Merge branch 'trunk' into refactor/flex-to-typescript

bin/api-docs/are-api-docs-unstaged.js

@@ -35,7 +35,7 @@ const getUnstagedReadmes = () =>
 				'\n',
 				'Some API docs may be out of date:',
 				unstagedReadmes.toString(),
-				'Either stage them or continue with --no-verify.',
+				'Either build and stage them with npm run api-docs:blocks or continue with --no-verify.',
 				'\n'
 			)
 		);

bin/packages/build.js

@@ -116,7 +116,9 @@ function createStyleEntryTransform() {
 
 			packages.add( packageName );
 			const entries = await glob(
-				path.resolve( PACKAGES_DIR, packageName, 'src/*.scss' )
+				path
+					.resolve( PACKAGES_DIR, packageName, 'src/*.scss' )
+					.replace( /\\/g, '/' )
 			);
 
 			// Account for the specific case where block styles in

docs/contributors/code/release.md

@@ -36,7 +36,7 @@ This will trigger a GitHub Actions (GHA) workflow that bumps the plugin version,
 
 #### View the release draft
 
-As soon as the workflow has finished, you'll find the release draft under https://github.com/WordPress/gutenberg/releases. The draft is pre-populated with changelog entries based on previous release candidates for this version, and any changes that have since been cherry-picked to the release branch. Thus, when releasing the first stable version of a series, make sure to delete any RC version headers (that are only there for your information) and to move the more recent changes to the correct section (see below).
+As soon as the workflow has finished, you'll find the release draft under [https://github.com/WordPress/gutenberg/releases](https://github.com/WordPress/gutenberg/releases). The draft is pre-populated with changelog entries based on previous release candidates for this version, and any changes that have since been cherry-picked to the release branch. Thus, when releasing the first stable version of a series, make sure to delete any RC version headers (that are only there for your information) and to move the more recent changes to the correct section (see below).
 
 The changelog draft will be at least partially pre-organized (based on GitHub label) into sections and within those into "features". Take some time to read the generated notes and then edit them to ensure legibility and accuracy.
 
@@ -158,7 +158,7 @@ Once you have the stable release branch in order and the correct Milestone assig
 
 Go to Gutenberg's GitHub repository's Actions tab, and locate the ["Build Gutenberg Plugin Zip" action](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml). You should now _carefully_ choose the next action based on information about the current Plugin release version:
 
-_If_ the previous release version was **stable** (`X.Y.Z` - e.g. `12.5.0`, `12.5.1` .etc) leave the the `Use workflow from` field as `trunk` and then specify `stable` in the text input field. The workflow will automatically create a point release, with z incremented (`x.y.(z+1)`) as required.
+_If_ the previous release version was **stable** (`X.Y.Z` - e.g. `12.5.0`, `12.5.1` .etc) leave the `Use workflow from` field as `trunk` and then specify `stable` in the text input field. The workflow will automatically create a point release, with z incremented (`x.y.(z+1)`) as required.
 
 _If_ however, the previous release was an **RC** (e.g. `X.Y.0-rc.1`) you will need to _manually_ select the _stable version's release branch_ (e.g. `12.5.0`) when creating the release. Failure to do this will cause the workflow to release the next major _stable_ version (e.g. `12.6.0`) which is not what you want.
 

docs/explanations/architecture/key-concepts.md

@@ -41,7 +41,7 @@ Given a block type, a block variation is a predefined set of its initial attribu
 
 ## Reusable Blocks
 
-A reusable blocks is a block (or multiple blocks) that can be inserted and edited globally at once. If a reusable block is edited in one place, those changes are reflected across all posts and pages that that block is used. Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page.
+A reusable blocks is a block (or multiple blocks) that can be inserted and edited globally at once. If a reusable block is edited in one place, those changes are reflected across all posts and pages that block is used. Examples of reusable blocks include a block consisting of a heading whose content and a custom color that would be appear on multiple pages of the site and sidebar widgets that would appear on every page.
 
 Any edits to a reusable block will appear on every other use of that block, saving time from having to make the same edit on different posts.
 

docs/manifest.json

@@ -1872,9 +1872,9 @@
 		"parent": "data"
 	},
 	{
-		"title": "Block Types Data",
-		"slug": "data-core-blocks",
-		"markdown_source": "../docs/reference-guides/data/data-core-blocks.md",
+		"title": "Block directory",
+		"slug": "data-core-block-directory",
+		"markdown_source": "../docs/reference-guides/data/data-core-block-directory.md",
 		"parent": "data"
 	},
 	{
@@ -1884,9 +1884,15 @@
 		"parent": "data"
 	},
 	{
-		"title": "The Post Editor’s Data",
-		"slug": "data-core-editor",
-		"markdown_source": "../docs/reference-guides/data/data-core-editor.md",
+		"title": "Block Types Data",
+		"slug": "data-core-blocks",
+		"markdown_source": "../docs/reference-guides/data/data-core-blocks.md",
+		"parent": "data"
+	},
+	{
+		"title": "Customize Widgets",
+		"slug": "data-core-customize-widgets",
+		"markdown_source": "../docs/reference-guides/data/data-core-customize-widgets.md",
 		"parent": "data"
 	},
 	{
@@ -1895,6 +1901,30 @@
 		"markdown_source": "../docs/reference-guides/data/data-core-edit-post.md",
 		"parent": "data"
 	},
+	{
+		"title": "Edit Site",
+		"slug": "data-core-edit-site",
+		"markdown_source": "../docs/reference-guides/data/data-core-edit-site.md",
+		"parent": "data"
+	},
+	{
+		"title": "Edit Widgets",
+		"slug": "data-core-edit-widgets",
+		"markdown_source": "../docs/reference-guides/data/data-core-edit-widgets.md",
+		"parent": "data"
+	},
+	{
+		"title": "The Post Editor’s Data",
+		"slug": "data-core-editor",
+		"markdown_source": "../docs/reference-guides/data/data-core-editor.md",
+		"parent": "data"
+	},
+	{
+		"title": "The Keyboard Shortcuts Data",
+		"slug": "data-core-keyboard-shortcuts",
+		"markdown_source": "../docs/reference-guides/data/data-core-keyboard-shortcuts.md",
+		"parent": "data"
+	},
 	{
 		"title": "Notices Data",
 		"slug": "data-core-notices",
@@ -1907,6 +1937,24 @@
 		"markdown_source": "../docs/reference-guides/data/data-core-nux.md",
 		"parent": "data"
 	},
+	{
+		"title": "Preferences",
+		"slug": "data-core-preferences",
+		"markdown_source": "../docs/reference-guides/data/data-core-preferences.md",
+		"parent": "data"
+	},
+	{
+		"title": "Reusable blocks",
+		"slug": "data-core-reusable-blocks",
+		"markdown_source": "../docs/reference-guides/data/data-core-reusable-blocks.md",
+		"parent": "data"
+	},
+	{
+		"title": "Rich Text",
+		"slug": "data-core-rich-text",
+		"markdown_source": "../docs/reference-guides/data/data-core-rich-text.md",
+		"parent": "data"
+	},
 	{
 		"title": "The Viewport Data",
 		"slug": "data-core-viewport",

docs/reference-guides/README.md

@@ -52,10 +52,18 @@
 
 -   [**core**: WordPress Core Data](/docs/reference-guides/data/data-core.md)
     -   [**core/annotations**: Annotations](/docs/reference-guides/data/data-core-annotations.md)
-    -   [**core/blocks**: Block Types Data](/docs/reference-guides/data/data-core-blocks.md)
+    -   [**core/block-directory**: Block directory](/docs/reference-guides/data/data-core-block-directory.md)
     -   [**core/block-editor**: The Block Editor’s Data](/docs/reference-guides/data/data-core-block-editor.md)
-    -   [**core/editor**: The Post Editor’s Data](/docs/reference-guides/data/data-core-editor.md)
+    -   [**core/blocks**: Block Types Data](/docs/reference-guides/data/data-core-blocks.md)
+    -   [**core/customize-widgets**: Customize Widgets](/docs/reference-guides/data/data-core-customize-widgets.md)
     -   [**core/edit-post**: The Editor’s UI Data](/docs/reference-guides/data/data-core-edit-post.md)
+    -   [**core/edit-site**: Edit Site](/docs/reference-guides/data/data-core-edit-site.md)
+    -   [**core/edit-widgets**: Edit Widgets](/docs/reference-guides/data/data-core-edit-widgets.md)
+    -   [**core/editor**: The Post Editor’s Data](/docs/reference-guides/data/data-core-editor.md)
+    -   [**core/keyboard-shortcuts**: The Keyboard Shortcuts Data](/docs/reference-guides/data/data-core-keyboard-shortcuts.md)
     -   [**core/notices**: Notices Data](/docs/reference-guides/data/data-core-notices.md)
     -   [**core/nux**: The NUX (New User Experience) Data](/docs/reference-guides/data/data-core-nux.md)
+    -   [**core/preferences**: Preferences](/docs/reference-guides/data/data-core-preferences.md)
+    -   [**core/reusable-blocks**: Reusable blocks](/docs/reference-guides/data/data-core-reusable-blocks.md)
+    -   [**core/rich-text**: Rich Text](/docs/reference-guides/data/data-core-rich-text.md)
     -   [**core/viewport**: The Viewport Data](/docs/reference-guides/data/data-core-viewport.md)

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

@@ -40,6 +40,15 @@ Starting in WordPress 5.8 release, we encourage using the `block.json` metadata
 			"message": "This is a notice!"
 		}
 	},
+	"variations": [
+		{
+			"name": "example",
+			"title": "Example",
+			"attributes": {
+				"message": "This is an example!"
+			},
+		}
+	]
 	"editorScript": "file:./build/index.js",
 	"script": "file:./build/script.js",
 	"viewScript": "file:./build/view.js",
@@ -421,6 +430,37 @@ It provides structured example data for the block. This data is used to construc
 
 See the [the example documentation](/docs/reference-guides/block-api/block-registration.md#example-optional) for more details.
 
+### Variations
+
+- Type: `object[]`
+- Optional
+- Localized: Yes (`title`, `description`, and `keywords` of each variation only)
+- Property: `variations`
+- Since: `WordPress 5.9.0`
+
+```json
+{
+	"variations": [
+		{
+			"name": "example",
+			"title": "Example",
+			"attributes": {
+				"level": 2,
+				"message": "This is an example!"
+			},
+			"scope": [ "block" ],
+			"isActive": [ "level" ]
+		}
+	]
+}
+```
+
+Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality. Each block variation is differentiated from the others by setting some initial attributes or inner blocks. Then at the time when a block is inserted these attributes and/or inner blocks are applied.
+
+_Note: In JavaScript you can provide a function for the `isActive` property, and a React element for the `icon`. In the `block.json` file both only support strings_
+
+See the [the variations documentation](/docs/reference-guides/block-api/block-variations.md) for more details.
+
 ### Editor Script
 
 -   Type: `WPDefinedAsset` ([learn more](#wpdefinedasset))

docs/reference-guides/core-blocks.md

@@ -177,7 +177,7 @@ An advanced block that allows displaying post comments using different visual co
 -	**Name:** core/comments
 -	**Category:** theme
 -	**Supports:** align (full, wide), color (background, gradients, link, text), ~~html~~
--	**Attributes:** tagName
+-	**Attributes:** legacy, tagName
 
 ## Comments Pagination
 
@@ -485,15 +485,6 @@ This block is deprecated. Please use the Comments block instead. ([Source](https
 -	**Supports:** ~~html~~, ~~inserter~~
 -	**Attributes:** commentId
 
-## Post Comments (deprecated)
-
-This block is deprecated. Please use the Comments block instead. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-comments))
-
--	**Name:** core/post-comments
--	**Category:** theme
--	**Supports:** align (full, wide), color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~, ~~inserter~~
--	**Attributes:** textAlign
-
 ## Post Comments Count
 
 Display a post's comments count. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-comments-count))

docs/reference-guides/data/README.md

@@ -2,10 +2,18 @@
 
 -   [**core**: WordPress Core Data](/docs/reference-guides/data/data-core.md)
 -   [**core/annotations**: Annotations](/docs/reference-guides/data/data-core-annotations.md)
--   [**core/blocks**: Block Types Data](/docs/reference-guides/data/data-core-blocks.md)
+-   [**core/block-directory**: Block directory](/docs/reference-guides/data/data-core-block-directory.md)
 -   [**core/block-editor**: The Block Editor’s Data](/docs/reference-guides/data/data-core-block-editor.md)
--   [**core/editor**: The Post Editor’s Data](/docs/reference-guides/data/data-core-editor.md)
+-   [**core/blocks**: Block Types Data](/docs/reference-guides/data/data-core-blocks.md)
+-   [**core/customize-widgets**: Customize Widgets](/docs/reference-guides/data/data-core-customize-widgets.md)
 -   [**core/edit-post**: The Editor’s UI Data](/docs/reference-guides/data/data-core-edit-post.md)
+-   [**core/edit-site**: Edit Site](/docs/reference-guides/data/data-core-edit-site.md)
+-   [**core/edit-widgets**: Edit Widgets](/docs/reference-guides/data/data-core-edit-widgets.md)
+-   [**core/editor**: The Post Editor’s Data](/docs/reference-guides/data/data-core-editor.md)
+-   [**core/keyboard-shortcuts**: The Keyboard Shortcuts Data](/docs/reference-guides/data/data-core-keyboard-shortcuts.md)
 -   [**core/notices**: Notices Data](/docs/reference-guides/data/data-core-notices.md)
 -   [**core/nux**: The NUX (New User Experience) Data](/docs/reference-guides/data/data-core-nux.md)
+-   [**core/preferences**: Preferences](/docs/reference-guides/data/data-core-preferences.md)
+-   [**core/reusable-blocks**: Reusable blocks](/docs/reference-guides/data/data-core-reusable-blocks.md)
+-   [**core/rich-text**: Rich Text](/docs/reference-guides/data/data-core-rich-text.md)
 -   [**core/viewport**: The Viewport Data](/docs/reference-guides/data/data-core-viewport.md)