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

.eslintignore

@@ -6,7 +6,6 @@ node_modules
 packages/block-serialization-spec-parser/parser.js
 packages/e2e-tests/plugins
 packages/react-native-editor/bundle
-playground/dist
 vendor
 wordpress
 !.*.js

.eslintrc.js

@@ -121,10 +121,6 @@ module.exports = {
 					'Avoid truthy checks on length property rendering, as zero length is rendered verbatim.',
 			},
 		],
-		// Temporarily converted to warning until all errors are resolved.
-		// See https://github.com/WordPress/gutenberg/pull/22771 for the eslint-plugin-jsdoc update.
-		'jsdoc/check-param-names': 'warn',
-		'jsdoc/require-param': 'warn',
 	},
 	overrides: [
 		{

.github/workflows/storybook-pages.yml

@@ -42,4 +42,4 @@ jobs:
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./playground/dist
+        publish_dir: ./storybook/build

.gitignore

@@ -14,7 +14,6 @@ yarn.lock
 /wordpress
 /artifacts
 
-playground/dist
 .cache
 *.tsbuildinfo
 

.wp-env.json

@@ -3,7 +3,7 @@
 	"plugins": [
 		"."
 	],
-	"themes": [ "WordPress/theme-experiments/twentytwentyone-blocks" ],
+	"themes": [ "WordPress/theme-experiments/tt1-blocks" ],
 	"env": {
 		"tests": {
 			"mappings": {

bin/build-plugin-zip.sh

@@ -111,8 +111,11 @@ mv gutenberg.tmp.php gutenberg.php
 
 build_files=$(
 	ls build/*/*.{js,css,asset.php} \
-	build/block-library/blocks/*.php build/block-library/blocks/*/block.json \
-	build/edit-widgets/blocks/*.php build/edit-widgets/blocks/*/block.json \
+	build/block-library/blocks/*.php \
+	build/block-library/blocks/*/block.json \
+	build/block-library/blocks/*/*.css \
+	build/edit-widgets/blocks/*.php \
+	build/edit-widgets/blocks/*/block.json \
 )
 
 

bin/plugin/commands/performance.js

@@ -205,8 +205,8 @@ async function runTestSuite( testSuite, performanceTestDirectory ) {
 /**
  * Runs the performances tests on an array of branches and output the result.
  *
- * @param {WPPerformanceCommandOptions} options Command options.
  * @param {string[]}                    branches Branches to compare
+ * @param {WPPerformanceCommandOptions} options Command options.
  */
 async function runPerformanceTests( branches, options ) {
 	// The default value doesn't work because commander provides an array.

bin/plugin/commands/release.js

@@ -6,6 +6,7 @@ const fs = require( 'fs' );
 const semver = require( 'semver' );
 const Octokit = require( '@octokit/rest' );
 const { sprintf } = require( 'sprintf-js' );
+const os = require( 'os' );
 
 /**
  * Internal dependencies
@@ -518,13 +519,27 @@ async function runUpdateTrunkContentStep(
 			newReadmeFileContent.replace( STABLE_TAG_PLACEHOLDER, stableTag )
 		);
 
+		let xargsOpts = '';
+		if ( os.platform === 'linux' ) {
+			// When xargs receives no arguments, it behaves differently in macOS and linux:
+			// - macOS: doesn't run
+			// - linux: run without arguments
+			//
+			// In linux, the -r option teaches xargs not to run if it receives no arguments.
+			xargsOpts = '-r';
+		}
+
 		// Commit the content changes
 		runShellScript(
-			"svn st | grep '^?' | awk '{print $2}' | xargs svn add",
+			"svn st | grep '^?' | awk '{print $2}' | xargs " +
+				xargsOpts +
+				' svn add',
 			svnWorkingDirectoryPath
 		);
 		runShellScript(
-			"svn st | grep '^!' | awk '{print $2}' | xargs svn rm",
+			"svn st | grep '^!' | awk '{print $2}' | xargs " +
+				xargsOpts +
+				' svn rm',
 			svnWorkingDirectoryPath
 		);
 		await askForConfirmation(

docs/contributors/release.md

@@ -199,9 +199,9 @@ You'll need to use Subversion to publish the plugin to WordPress.org.
 6. Add new files/remove deleted files from the repository:
 ```bash
 # Add new files:
-svn st | grep '^\?' | awk '{print $2}' | xargs svn add
+svn st | grep '^\?' | awk '{print $2}' | xargs svn add # add the -r option to xargs if you use a linux-based OS
 # Delete old files:
-svn st | grep '^!' | awk '{print $2}' | xargs svn rm
+svn st | grep '^!' | awk '{print $2}' | xargs svn rm # add the -r option to xargs if you use a linux-based OS
 ```
 7. Commit the new version:
 ```bash

docs/contributors/testing-overview.md

@@ -355,9 +355,8 @@ It's tempting to snapshot deep renders, but that makes for huge snapshots. Addit
 Sometimes we need to mock refs for some stories which use them. Check the following documents to learn more:
 
 -   Why we need to use [Mocking Refs for Snapshot Testing](https://reactjs.org/blog/2016/11/16/react-v15.4.0.html#mocking-refs-for-snapshot-testing) with React.
--   [Using createNodeMock to mock refs](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core#using-createnodemock-to-mock-refs) with StoryShots.
 
-In that case, you might see test failures and `TypeError` reported by Jest in the lines which try to access a property from `ref.current`. If this happens, search for `initStoryshots` method call, which contains all necessary configurations to adjust.
+In that case, you might see test failures and `TypeError` reported by Jest in the lines which try to access a property from `ref.current`.
 
 ### Debugging Jest unit tests
 

docs/designers-developers/developers/block-api/block-registration.md

@@ -222,7 +222,7 @@ example: {
 
 #### variations (optional)
 
-- **Type:** `Object[]`
+-   **Type:** `Object[]`
 
 Similarly to how the block's style variations can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted.
 
@@ -256,19 +256,20 @@ variations: [
 
 An object describing a variation defined for the block type can contain the following fields:
 
-- `name` (type `string`) – The unique and machine-readable name.
-- `title` (type `string`) – A human-readable variation title.
-- `description` (optional, type `string`) – A detailed variation description.
-- `icon` (optional, type `string` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type.
-- `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`.
-- `attributes` (optional, type `Object`) – Values that override block attributes.
-- `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks.
-- `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type.
-- `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options:
-	- `inserter` - Block Variation is shown on the inserter.
-	- `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block.
-	- `transform` - Block Variation will be shown in the component for Block Variations transformations.
-- `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching.
+-   `name` (type `string`) – The unique and machine-readable name.
+-   `title` (type `string`) – A human-readable variation title.
+-   `description` (optional, type `string`) – A detailed variation description.
+-   `icon` (optional, type `string` | `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type.
+-   `isDefault` (optional, type `boolean`) – Indicates whether the current variation is the default one. Defaults to `false`.
+-   `attributes` (optional, type `Object`) – Values that override block attributes.
+-   `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks.
+-   `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type.
+-   `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options:
+    -   `inserter` - Block Variation is shown on the inserter.
+    -   `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block.
+    -   `transform` - Block Variation will be shown in the component for Block Variations transformations.
+-   `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching.
+-   `isActive` (optional, type `Function`) - A function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value.
 
 It's also possible to override the default block style variation using the `className` attribute when defining block variations.
 
@@ -278,15 +279,17 @@ variations: [
 		name: 'blue',
 		title: __( 'Blue Quote' ),
 		isDefault: true,
-		attributes: { className: 'is-style-blue-quote' },
+		attributes: { color: 'blue', className: 'is-style-blue-quote' },
 		icon: 'format-quote',
+		isActive: ( blockAttributes, variationAttributes ) =>
+			blockAttributes.color === variationAttributes.color
 	},
 ],
 ```
 
 #### supports (optional)
 
--   ***Type:*** `Object`
+-   **_Type:_** `Object`
 
 Supports contains as set of options to control features used in the editor. See the [the supports documentation](/docs/designers-developers/developers/block-api/block-supports.md) for more details.
 

docs/designers-developers/developers/block-api/block-supports.md

@@ -338,24 +338,6 @@ supports: {
 }
 ```
 
-When the block declares support for a specific spacing property, the attributes definition is extended to include some attributes.
+When the block declares support for a specific spacing property, the attributes definition is extended to include the `style` attribute.
 
-- `style`: attribute of `object` type with no default assigned. This is added when `padding` support is declared. It stores the custom values set by the user. The block can apply a default style by specifying its own `style` attribute with a default e.g.:
-
-```js
-attributes: {
-    style: {
-        type: 'object',
-        default: {
-            spacing: {
-                padding: {
-                    top: 'value',
-                    right: 'value',
-                    bottom: 'value',
-                    left: 'value'
-                }
-            }
-        }
-    }
-}
-```
+- `style`: attribute of `object` type with no default assigned. This is added when `padding` support is declared. It stores the custom values set by the user.

docs/designers-developers/developers/block-api/block-templates.md

@@ -1,6 +1,6 @@
 # Templates
 
-A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow to specify a default initial state for an editor session.
+A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow specifying a default initial state for an editor session.
 
 The scope of templates include:
 
@@ -110,6 +110,8 @@ add_action( 'init', 'myplugin_register_template' );
 - `all` — prevents all operations. It is not possible to insert new blocks, move existing blocks, or delete blocks.
 - `insert` — prevents inserting or removing blocks, but allows moving existing blocks.
 
+Lock settings can be inherited by InnerBlocks. If `templateLock` is not set in an InnerBlocks area, the locking of the parent InnerBlocks area is used. If the block is a top level block, the locking configuration of the current post type is used.
+
 ## Nested Templates
 
 Container blocks like the columns blocks also support templates. This is achieved by assigning a nested template to the block.

docs/designers-developers/developers/data/data-core-block-editor.md

@@ -344,6 +344,40 @@ _Returns_
 
 -   `?string`: Client ID of block selection start.
 
+<a name="getBlockTransformItems" href="#getBlockTransformItems">#</a> **getBlockTransformItems**
+
+Determines the items that appear in the available block transforms list.
+
+Each item object contains what's necessary to display a menu item in the
+transform list and handle its selection.
+
+The 'frecency' property is a heuristic (<https://en.wikipedia.org/wiki/Frecency>)
+that combines block usage frequenty and recency.
+
+Items are returned ordered descendingly by their 'frecency'.
+
+_Parameters_
+
+-   _state_ `Object`: Editor state.
+-   _rootClientId_ `?string`: Optional root client ID of block list.
+
+_Returns_
+
+-   `Array<WPEditorTransformItem>`: Items that appear in inserter.
+
+_Type Definition_
+
+-   _WPEditorTransformItem_ `Object`
+
+_Properties_
+
+-   _id_ `string`: Unique identifier for the item.
+-   _name_ `string`: The type of block to create.
+-   _title_ `string`: Title of the item, as it appears in the inserter.
+-   _icon_ `string`: Dashicon for the item, as it appears in the inserter.
+-   _isDisabled_ `boolean`: Whether or not the user should be prevented from inserting this item.
+-   _frecency_ `number`: Heuristic that combines frequency and recency.
+
 <a name="getClientIdsOfDescendants" href="#getClientIdsOfDescendants">#</a> **getClientIdsOfDescendants**
 
 Returns an array containing the clientIds of all descendants

docs/designers-developers/developers/data/data-core-editor.md

@@ -568,18 +568,11 @@ _Related_
 
 <a name="getStateBeforeOptimisticTransaction" href="#getStateBeforeOptimisticTransaction">#</a> **getStateBeforeOptimisticTransaction**
 
+> **Deprecated** since Gutenberg 9.7.0.
+
 Returns state object prior to a specified optimist transaction ID, or `null`
 if the transaction corresponding to the given ID cannot be found.
 
-_Parameters_
-
--   _state_ `Object`: Current global application state.
--   _transactionId_ `Object`: Optimist transaction ID.
-
-_Returns_
-
--   `Object`: Global application state prior to transaction.
-
 <a name="getSuggestedPostFormat" href="#getSuggestedPostFormat">#</a> **getSuggestedPostFormat**
 
 Returns a suggested post format for the current post, inferred only if there
@@ -696,18 +689,11 @@ _Related_
 
 <a name="inSomeHistory" href="#inSomeHistory">#</a> **inSomeHistory**
 
+> **Deprecated** since Gutenberg 9.7.0.
+
 Returns true if an optimistic transaction is pending commit, for which the
 before state satisfies the given predicate function.
 
-_Parameters_
-
--   _state_ `Object`: Editor state.
--   _predicate_ `Function`: Function given state, returning true if match.
-
-_Returns_
-
--   `boolean`: Whether predicate matches for some history.
-
 <a name="isAncestorMultiSelected" href="#isAncestorMultiSelected">#</a> **isAncestorMultiSelected**
 
 _Related_
@@ -1490,13 +1476,11 @@ Undocumented declaration.
 
 <a name="updatePost" href="#updatePost">#</a> **updatePost**
 
+> **Deprecated** since Gutenberg 9.7.0.
+
 Returns an action object used in signalling that a patch of updates for the
 latest version of the post have been received.
 
-_Parameters_
-
--   _edits_ `Object`: Updated post fields.
-
 _Returns_
 
 -   `Object`: Action object.

docs/designers-developers/developers/data/data-core.md

@@ -612,7 +612,8 @@ _Parameters_
 -   _name_ `string`: Name of the received entity.
 -   _records_ `(Array|Object)`: Records received.
 -   _query_ `?Object`: Query Object.
--   _invalidateCache_ `?boolean`: Should invalidate query caches
+-   _invalidateCache_ `?boolean`: Should invalidate query caches.
+-   _edits_ `?Object`: Edits to reset.
 
 _Returns_
 

docs/manifest.json

@@ -1805,6 +1805,12 @@
 		"markdown_source": "../packages/shortcode/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/stylelint-config",
+		"slug": "packages-stylelint-config",
+		"markdown_source": "../packages/stylelint-config/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/token-list",
 		"slug": "packages-token-list",

gutenberg.php

@@ -5,7 +5,7 @@
  * Description: Printing since 1440. This is the development plugin for the new block editor in core.
  * Requires at least: 5.3
  * Requires PHP: 5.6
- * Version: 9.6.0-rc.1
+ * Version: 9.7.0-rc.1
  * Author: Gutenberg Team
  * Text Domain: gutenberg
  *