Merge changes published in the Gutenberg plugin "release/21.1" branch

Author: gutenbergplugin

.github/workflows/unit-test.yml

@@ -211,7 +211,7 @@ jobs:
             # dependency versions are installed and cached.
             ##
             - name: Set up PHP
-              uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
+              uses: shivammathur/setup-php@0f7f1d08e3e32076e51cae65eb0b0c871405b16e # v2.34.1
               with:
                   php-version: '${{ matrix.php }}'
                   ini-file: development
@@ -226,7 +226,7 @@ jobs:
             # Since Composer dependencies are installed using `composer update` and no lock file is in version control,
             # passing a custom cache suffix ensures that the cache is flushed at least once per week.
             - name: Install Composer dependencies
-              uses: ramsey/composer-install@a2636af0004d1c0499ffca16ac0b4cc94df70565 # v3.1.0
+              uses: ramsey/composer-install@3cf229dc2919194e9e36783941438d17239e8520 # v3.1.1
               with:
                   custom-cache-suffix: $(/bin/date -u --date='last Mon' "+%F")
 
@@ -311,7 +311,7 @@ jobs:
                   persist-credentials: false
 
             - name: Set up PHP
-              uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
+              uses: shivammathur/setup-php@0f7f1d08e3e32076e51cae65eb0b0c871405b16e # v2.34.1
               with:
                   php-version: '7.4'
                   coverage: none
@@ -332,7 +332,7 @@ jobs:
             # Since Composer dependencies are installed using `composer update` and no lock file is in version control,
             # passing a custom cache suffix ensures that the cache is flushed at least once per week.
             - name: Install Composer dependencies
-              uses: ramsey/composer-install@a2636af0004d1c0499ffca16ac0b4cc94df70565 # v3.1.0
+              uses: ramsey/composer-install@3cf229dc2919194e9e36783941438d17239e8520 # v3.1.1
               with:
                   custom-cache-suffix: ${{ steps.get-date.outputs.date }}
 

changelog.txt

@@ -355,7 +355,7 @@ privateValidateBlocks( blocks, true );
 #### Private React component properties
 
 To add a private argument to a stable component you'll need
-to prepare a stable and an private version of that component.
+to prepare a stable and a private version of that component.
 Then, export the stable function and `lock()` the unstable function
 inside it:
 

docs/contributors/code/coding-guidelines.md

@@ -85,7 +85,7 @@ The following snippet explains how the Gutenberg repository is structured omitti
     │   PHP Source code of the Gutenberg plugin.
     │
     ├── lib/compact/wordpress-x.x
-    │   PHP code that was include in WordPress ont the WordPrexx X.X version.
+    │   PHP code that was include in WordPress ont the WordPress X.X version.
     │   It is kept to ensure plugin compatibility with older WordPress versions.
     │
     ├── packages

docs/contributors/folder-structure.md

@@ -461,3 +461,36 @@ _Example_: Example `default` values.
 	}
 }
 ```
+
+## Role
+
+The `role` property designates an attribute as being of a particular conceptual type. This property can be applied to any attribute to provide semantic meaning about how the attribute should be handled.
+
+Use `content` to designate the attribute as user-editable content. Blocks with attributes marked as `content` may be enabled for privileged editing in special circumstances such as content only locking.
+Use `local` to mark the attribute as temporary and non-persistable. Attributes marked as `local` are ignored by the Block Serializer and never saved to post content.
+
+_Example_: `content` role used by the paragraph block
+
+```js
+{
+    content: {
+        type: 'string',
+        source: 'html',
+        selector: 'p',
+        role: 'content',
+    }
+}
+```
+
+_Example_: `local` role used for temporary data.
+
+```js
+{
+    blob: {
+        type: 'string',
+        role: 'local',
+    }
+}
+```
+
+Learn more in the [WordPress 6.7 dev note](https://make.wordpress.org/core/2024/10/20/miscellaneous-block-editor-changes-in-wordpress-6-7/#stabilized-role-property-for-block-attributes).

docs/reference-guides/block-api/block-attributes.md

@@ -176,7 +176,7 @@ $template = array(
 		) ),
 		array( 'core/column', array(), array(
 			array( 'core/paragraph', array(
-				'placeholder' => 'Add a inner paragraph'
+				'placeholder' => 'Add an inner paragraph'
 			) ),
 		) ),
 	) )

docs/reference-guides/block-api/block-templates.md

@@ -271,7 +271,7 @@ A transformation of type `shortcode` is an object that takes the following param
 -   **type** _(string)_: the value `shortcode`.
 -   **tag** _(string|array)_: the shortcode tag or list of shortcode aliases this transform can work with.
 -   **transform** _(function, optional)_: a callback that receives the shortcode attributes as the first argument and the [WPShortcodeMatch](/packages/shortcode/README.md#next) as the second. It should return a block object or an array of block objects. When this parameter is defined, it will take precedence over the `attributes` parameter.
--   **attributes** _(object, optional)_: object representing where the block attributes should be sourced from, according to the attributes shape defined by the [block configuration object](./block-registration.md). If a particular attribute contains a `shortcode` key, it should be a function that receives the shortcode attributes as the first arguments and the [WPShortcodeMatch](/packages/shortcode/README.md#next) as second, and returns a value for the attribute that will be sourced in the block's comment.
+-   **attributes** _(object, optional)_: object representing where the block attributes should be sourced from, according to the attributes shape defined by the [block configuration object](/docs/reference-guides/block-api/block-registration.md). If a particular attribute contains a `shortcode` key, it should be a function that receives the shortcode attributes as the first arguments and the [WPShortcodeMatch](/packages/shortcode/README.md#next) as second, and returns a value for the attribute that will be sourced in the block's comment.
 -   **isMatch** _(function, optional)_: a callback that receives the shortcode attributes per the [Shortcode API](https://codex.wordpress.org/Shortcode_API) and should return a boolean. Returning `false` from this function will prevent the shortcode to be transformed into this block.
 -   **priority** _(number, optional)_: controls the priority with which a transform is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set.
 

docs/reference-guides/block-api/block-transforms.md

@@ -1042,6 +1042,27 @@ _Returns_
 
 Returns whether post saving is locked.
 
+_Usage_
+
+```jsx
+import { __ } from '@wordpress/i18n';
+import { store as editorStore } from '@wordpress/editor';
+import { useSelect } from '@wordpress/data';
+
+const ExampleComponent = () => {
+	const isSavingLocked = useSelect(
+		( select ) => select( editorStore ).isPostSavingLocked(),
+		[]
+	);
+
+	return isSavingLocked ? (
+		<p>{ __( 'Post saving is locked' ) }</p>
+	) : (
+		<p>{ __( 'Post saving is not locked' ) }</p>
+	);
+};
+```
+
 _Parameters_
 
 -   _state_ `Object`: Global application state.

docs/reference-guides/data/data-core-editor.md

@@ -73,7 +73,7 @@ const ExampleComponent = () => {
 			}
 		>
 			{ __(
-				'Generate an snackbar error notice with explicit dismiss button.'
+				'Generate a snackbar error notice with explicit dismiss button.'
 			) }
 		</Button>
 	);

docs/reference-guides/data/data-core-notices.md

@@ -175,7 +175,7 @@ store( 'myFruitPlugin', {
 
 The derived state, regardless of whether it derives from the global state, local context, or both, can also be processed on the server by the Server Directive Processing.
 
-_Please, visit the [Understanding global state, local context and derived state](./undestanding-global-state-local-context-and-derived-state.md) guide to learn more about how derived state works in the Interactivity API._
+_Please, visit the [Understanding global state, local context and derived state](/docs/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md) guide to learn more about how derived state works in the Interactivity API._
 
 ### Derived state that can be defined statically