Merge branch 'trunk' into 68028/fix-spacing-issue

.eslintrc.js

@@ -137,6 +137,11 @@ const restrictedSyntax = [
 		message:
 			'Avoid truthy checks on length property rendering, as zero length is rendered verbatim.',
 	},
+	{
+		selector:
+			'CallExpression[callee.name=/^(__|_x|_n|_nx)$/] > Literal[value=/^toggle\\b/i]',
+		message: "Avoid using the verb 'Toggle' in translatable strings",
+	},
 ];
 
 /** `no-restricted-syntax` rules for components. */

.github/workflows/sync-assets-to-plugin-repo.yml

@@ -0,0 +1,48 @@
+name: Sync Gutenberg plugin assets to WordPress.org plugin repo
+
+on:
+    push:
+        branches:
+            - trunk
+        paths:
+            - assets/**
+
+jobs:
+    sync-assets:
+        name: Sync assets to WordPress.org plugin repo
+        runs-on: ubuntu-latest
+        environment: wp.org plugin
+        env:
+            PLUGIN_REPO_URL: 'https://plugins.svn.wordpress.org/gutenberg'
+            SVN_USERNAME: ${{ secrets.SVN_USERNAME }}
+            SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }}
+
+        steps:
+            - name: Check out Gutenberg assets folder from WP.org plugin repo
+              run: |
+                  svn checkout "$PLUGIN_REPO_URL/assets" \
+                  --username "$SVN_USERNAME" --password "$SVN_PASSWORD"
+
+            - name: Delete everything
+              run: find assets -type f -not -path 'assets/.svn/*' -delete
+
+            - name: Checkout assets from current release
+              uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+              with:
+                  sparse-checkout: |
+                      assets
+                  show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
+                  path: git
+
+            - name: Copy files from git checkout to svn working copy
+              run: cp -R git/assets/* assets
+
+            - name: Commit the updated assets
+              working-directory: ./assets
+              run: |
+                  svn st | awk '/^?/ {print $2}' | xargs -r svn add
+                  svn st | awk '/^!/ {print $2}' | xargs -r svn rm
+                  svn commit . \
+                    -m "Sync assets for commit $GITHUB_SHA" \
+                    --no-auth-cache --non-interactive  --username "$SVN_USERNAME" --password "$SVN_PASSWORD" \
+                    --config-option=servers:global:http-timeout=600

assets/README.md

@@ -0,0 +1,7 @@
+## Gutenberg Plugin Assets
+
+The contents of this directory are synced from the [`assets/` directory in the Gutenberg repository on GitHub](https://github.com/WordPress/gutenberg/tree/trunk/assets) to the [`assets/` directory of the Gutenberg WordPress.org plugin repository](https://plugins.trac.wordpress.org/browser/gutenberg/assets). **Any changes committed directly to the plugin repository on WordPress.org will be overwritten.**
+
+The sync is performed by a [GitHub Actions workflow](https://github.com/WordPress/gutenberg/actions/workflows/sync-assets-to-plugin-repo.yml) that is triggered whenever a file in this directory is changed.
+
+Since that workflow requires access to WP.org plugin repository credentials, it needs to be approved manually by a member of the Gutenberg Core team. If you don't have the necessary permissions, please ask someone in [#core-editor](https://wordpress.slack.com/archives/C02QB2JS7).

backport-changelog/6.8/7865.md

@@ -1,3 +1,4 @@
 https://github.com/WordPress/wordpress-develop/pull/7865
 
-* https://github.com/WordPress/gutenberg/pull/66851
+* https://github.com/WordPress/gutenberg/pull/66851
+* https://github.com/WordPress/gutenberg/pull/68174

backport-changelog/6.8/8014.md

@@ -0,0 +1,3 @@
+https://github.com/WordPress/wordpress-develop/pull/8014
+
+* https://github.com/WordPress/gutenberg/pull/66479

backport-changelog/6.8/8015.md

@@ -0,0 +1,3 @@
+https://github.com/WordPress/wordpress-develop/pull/8015
+
+* https://github.com/WordPress/gutenberg/pull/68058

backport-changelog/6.8/8031.md

@@ -0,0 +1,4 @@
+https://github.com/WordPress/wordpress-develop/pull/8031
+
+* https://github.com/WordPress/gutenberg/pull/66675
+* https://github.com/WordPress/gutenberg/pull/68243

backport-changelog/6.8/8032.md

@@ -0,0 +1,3 @@
+https://github.com/WordPress/wordpress-develop/pull/8032
+
+* https://github.com/WordPress/gutenberg/pull/68003

bin/api-docs/gen-components-docs/markdown/index.mjs

@@ -8,14 +8,27 @@ import json2md from 'json2md';
  */
 import { generateMarkdownPropsJson } from './props.mjs';
 
+/**
+ * If the string is contentful, ensure that it ends with a single newline.
+ * Otherwise normalize to `undefined`.
+ *
+ * @param {string} [str]
+ */
+function normalizeTrailingNewline( str ) {
+	if ( ! str?.trim() ) {
+		return undefined;
+	}
+	return str.replace( /\n*$/, '\n' );
+}
+
 export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 	const mainDocsJson = [
 		{ h1: typeDocs.displayName },
 		'<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->',
 		{
 			p: `<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-${ typeDocs.displayName.toLowerCase() }--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>`,
 		},
-		typeDocs.description,
+		normalizeTrailingNewline( typeDocs.description ),
 		...generateMarkdownPropsJson( typeDocs.props ),
 	];
 
@@ -26,7 +39,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 					{
 						h3: subcomponentTypeDoc.displayName,
 					},
-					subcomponentTypeDoc.description,
+					normalizeTrailingNewline( subcomponentTypeDoc.description ),
 					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
 						headingLevel: 4,
 					} ),

bin/plugin/lib/utils.js

@@ -2,7 +2,7 @@
  * External dependencies
  */
 // @ts-ignore
-const inquirer = require( 'inquirer' );
+const { confirm } = require( '@inquirer/prompts' );
 const fs = require( 'fs' );
 const childProcess = require( 'child_process' );
 const { v4: uuid } = require( 'uuid' );
@@ -97,14 +97,19 @@ async function askForConfirmation(
 	isDefault = true,
 	abortMessage = 'Aborting.'
 ) {
-	const { isReady } = await inquirer.prompt( [
-		{
-			type: 'confirm',
-			name: 'isReady',
+	let isReady = false;
+	try {
+		isReady = await confirm( {
 			default: isDefault,
 			message,
-		},
-	] );
+		} );
+	} catch ( error ) {
+		if ( error instanceof Error && error.name === 'ExitPromptError' ) {
+			console.log( 'Cancelled.' );
+			process.exit( 1 );
+		}
+		throw error;
+	}
 
 	if ( ! isReady ) {
 		log( formats.error( '\n' + abortMessage ) );

docs/explanations/architecture/styles.md

@@ -37,10 +37,8 @@ The user may change the state of this block by applying different styles: a text
 After some user modifications to the block, the initial markup may become something like this:
 
 ```html
-<p
-	class="has-color has-green-color has-font-size has-small-font-size my-custom-class"
-	style="line-height: 1em"
-></p>
+<p class="has-color has-green-color has-font-size has-small-font-size my-custom-class"
+	style="line-height: 1em"></p>
 ```
 
 This is what we refer to as "user-provided block styles", also know as "local styles" or "serialized styles". Essentially, each tool (font size, color, etc) ends up adding some classes and/or inline styles to the block markup. The CSS styling for these classes is part of the block, global, or theme stylesheets.
@@ -125,7 +123,7 @@ The block supports API only serializes the font size value to the wrapper, resul
 
 This is an active area of work you can follow [in the tracking issue](https://github.com/WordPress/gutenberg/issues/38167). The linked proposal is exploring a different way to serialize the user changes: instead of each block support serializing its own data (for example, classes such as `has-small-font-size`, `has-green-color`) the idea is the block would get a single class instead (for example, `wp-style-UUID`) and the CSS styling for that class will be generated in the server by WordPress.
 
-While work continues in that proposal, there's an escape hatch, an experimental option block authors can use. Any block support can skip the serialization to HTML markup by using `skipSerialization`. For example:
+While work continues in that proposal, there's an escape hatch, an experimental option block authors can use. Any block support can skip the serialization to HTML markup by using `__experimentalSkipSerialization`. For example:
 
 ```json
 {
@@ -134,15 +132,15 @@ While work continues in that proposal, there's an escape hatch, an experimental
 	"supports": {
 		"typography": {
 			"fontSize": true,
-			"skipSerialization": true
+			"__experimentalSkipSerialization": true
 		}
 	}
 }
 ```
 
 This means that the typography block support will do all of the things (create a UI control, bind the block attribute to the control, etc) except serializing the user values into the HTML markup. The classes and inline styles will not be automatically applied to the wrapper and it is the block author's responsibility to implement this in the `edit`, `save`, and `render_callback` functions. See [this issue](https://github.com/WordPress/gutenberg/issues/28913) for examples of how it was done for some blocks provided by WordPress.
 
-Note that, if `skipSerialization` is enabled for a group (typography, color, spacing) it affects _all_ block supports within this group. In the example above _all_ the properties within the `typography` group will be affected (e.g. `fontSize`, `lineHeight`, `fontFamily` .etc).
+Note that, if `__experimentalSkipSerialization` is enabled for a group (typography, color, spacing) it affects _all_ block supports within this group. In the example above _all_ the properties within the `typography` group will be affected (e.g. `fontSize`, `lineHeight`, `fontFamily` .etc).
 
 To enable for a _single_ property only, you may use an array to declare which properties are to be skipped. In the example below, only `fontSize` will skip serialization, leaving other items within the `typography` group (e.g. `lineHeight`, `fontFamily` .etc) unaffected.
 
@@ -154,7 +152,7 @@ To enable for a _single_ property only, you may use an array to declare which pr
 		"typography": {
 			"fontSize": true,
 			"lineHeight": true,
-			"skipSerialization": [ "fontSize" ]
+			"__experimentalSkipSerialization": [ "fontSize" ]
 		}
 	}
 }
@@ -475,7 +473,7 @@ If blocks do this, they need to be registered in the server using the `block.jso
 
 Every chunk of styles can only use a single selector.
 
-This is particularly relevant if the block is using `skipSerialization` to serialize the different style properties to different nodes other than the wrapper. See "Current limitations of blocks supports" for more.
+This is particularly relevant if the block is using `__experimentalSkipSerialization` to serialize the different style properties to different nodes other than the wrapper. See "Current limitations of blocks supports" for more.
 
 #### 3. **Only a single property per block**
 

docs/getting-started/fundamentals/javascript-in-the-block-editor.md

@@ -26,7 +26,7 @@ The diagram below provides an overview of the build process when using the `wp-s
 
 - **Production Mode (`npm run build`):** In this mode, `wp-scripts` compiles your JavaScript, minifying the output to reduce file size and improve loading times in the browser. This is ideal for deploying your code to a live site.
 
-- **Development Mode (`npm run start`):** This mode is tailored for active development. It skips minification for easier debugging, generates source maps for better error tracking, and watches your source files for changes. When a change is detected, it automatically rebuilds the affected files, allowing you to see updates in real-time.
+- **Development Mode (`npm start`):** This mode is tailored for active development. It skips minification for easier debugging, generates source maps for better error tracking, and watches your source files for changes. When a change is detected, it automatically rebuilds the affected files, allowing you to see updates in real-time.
 
 The `wp-scripts` package also facilitates the use of JavaScript modules, allowing code distribution across multiple files and resulting in a streamlined bundle after the build process. The [block-development-example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8) GitHub repository provides some good examples.
 

docs/how-to-guides/themes/global-settings-and-styles.md

@@ -1053,16 +1053,16 @@ Pseudo selectors `:hover`, `:focus`, `:visited`, `:active`, `:link`, `:any-link`
 
 #### Variations
 
-A block can have a "style variation", as defined per the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the theme.json file. Styles for unregistered style variations will be ignored.
+A block can have a "style variation," as defined in the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the `theme.json` file. Styles for unregistered style variations will be ignored.
 
-Note that variations are a "block concept", they only exist bound to blocks. The `theme.json` specification respects that distinction by only allowing `variations` at the block-level but not at the top-level. It's also worth highlighting that only variations defined in the `block.json` file of the block are considered "registered": so far, the style variations added via `register_block_style` or in the client are ignored, see [this issue](https://github.com/WordPress/gutenberg/issues/49602) for more information.
+Note that variations are a "block concept"—they only exist when bound to blocks. The `theme.json` specification respects this distinction by only allowing `variations` at the block level, not the top level. It’s also worth highlighting that only variations defined in the `block.json` file of the block or via `register_block_style` on the server are considered "registered" for `theme.json` styling purposes.
 
 For example, this is how to provide styles for the existing `plain` variation for the `core/quote` block:
 
 ```json
 {
 	"version": 3,
-	"styles":{
+	"styles": {
 		"blocks": {
 			"core/quote": {
 				"variations": {
@@ -1078,14 +1078,107 @@ For example, this is how to provide styles for the existing `plain` variation fo
 }
 ```
 
-The resulting CSS output is this:
+The resulting CSS output is:
 
 ```css
 .wp-block-quote.is-style-plain {
 	background-color: red;
 }
 ```
 
+It is also possible for multiple block types to share the same variation styles. There are two recommended ways to define such shared styles:
+
+1. `theme.json` partial files
+2. programmatically, using `register_block_style`
+
+##### Variation Theme.json Partials
+
+Like theme style variation partials, those for block style variations reside within a theme's `/styles` directory. However, they are differentiated from theme style variations by the introduction of a top-level property called `blockTypes`. The `blockTypes` property is an array of block types for which the block style variation has been registered.
+
+Additionally, a `slug` property is available to provide consistency between the different sources that may define block style variations and to decouple the `slug` from the translatable `title` property.
+
+The following is an example of a `theme.json` partial that defines styles for the "Variation A" block style for the Group, Columns, and Media & Text block types:
+
+```json
+{
+	"$schema": "https://schemas.wp.org/trunk/theme.json",
+	"version": 3,
+	"title": "Variation A",
+	"slug": "variation-a",
+	"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
+	"styles": {
+		"color": {
+			"background": "#eed8d3",
+			"text": "#201819"
+		},
+		"elements": {
+			"heading": {
+				"color": {
+					"text": "#201819"
+				}
+			}
+		},
+		"blocks": {
+			"core/group": {
+				"color": {
+					"background": "#825f58",
+					"text": "#eed8d3"
+				},
+				"elements": {
+					"heading": {
+						"color": {
+							"text": "#eed8d3"
+						}
+					}
+				}
+			}
+		}
+	}
+}
+```
+
+##### Programmatically Registering Variation Styles
+
+As an alternative to `theme.json` partials, you can register variation styles at the same time as registering the variation itself through `register_block_style`. This is done by registering the block style for an array of block types while also passing a "style object" within the `style_data` option.
+
+The example below registers a "Green" variation for the Group and Columns blocks. Note that the style object passed via `style_data` follows the same shape as the `styles` property of a `theme.json` partial.
+
+```php
+register_block_style(
+    array( 'core/group', 'core/columns' ),
+    array(
+        'name'       => 'green',
+        'label'      => __( 'Green' ),
+        'style_data' => array(
+            'color'    => array(
+                'background' => '#4f6f52',
+                'text'       => '#d2e3c8',
+            ),
+            'blocks'   => array(
+                'core/group' => array(
+                    'color' => array(
+                        'background' => '#739072',
+                        'text'       => '#e3eedd',
+                    ),
+                ),
+            ),
+            'elements' => array(
+                'link'   => array(
+                    'color'  => array(
+                        'text' => '#ead196',
+                    ),
+                    ':hover' => array(
+                        'color' => array(
+                            'text' => '#ebd9b4',
+                        ),
+                    ),
+                ),
+            ),
+        ),
+    )
+);
+```
+
 ### customTemplates
 
 <div class="callout callout-alert">Supported in WordPress from version 5.9.</div>