Merge branch 'trunk' into fix/41866-color-reset-dropdown

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/8015.md

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

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>

lib/compat/wordpress-6.8/blocks.php

@@ -170,7 +170,7 @@ function gutenberg_apply_block_hooks_to_post_content( $content ) {
  * @return WP_REST_Response The response object.
  */
 function gutenberg_insert_hooked_blocks_into_rest_response( $response, $post ) {
-	if ( empty( $response->data['content']['raw'] ) || empty( $response->data['content']['rendered'] ) ) {
+	if ( empty( $response->data['content']['raw'] ) ) {
 		return $response;
 	}
 
@@ -185,6 +185,8 @@ function gutenberg_insert_hooked_blocks_into_rest_response( $response, $post ) {
 
 	if ( 'wp_navigation' === $post->post_type ) {
 		$wrapper_block_type = 'core/navigation';
+	} elseif ( 'wp_block' === $post->post_type ) {
+		$wrapper_block_type = 'core/block';
 	} else {
 		$wrapper_block_type = 'core/post-content';
 	}
@@ -206,6 +208,11 @@ function gutenberg_insert_hooked_blocks_into_rest_response( $response, $post ) {
 
 	$response->data['content']['raw'] = $content;
 
+	// If the rendered content was previously empty, we leave it like that.
+	if ( empty( $response->data['content']['rendered'] ) ) {
+		return $response;
+	}
+
 	// No need to inject hooked blocks twice.
 	$priority = has_filter( 'the_content', 'apply_block_hooks_to_content' );
 	if ( false !== $priority ) {
@@ -224,6 +231,7 @@ function gutenberg_insert_hooked_blocks_into_rest_response( $response, $post ) {
 }
 add_filter( 'rest_prepare_page', 'gutenberg_insert_hooked_blocks_into_rest_response', 10, 2 );
 add_filter( 'rest_prepare_post', 'gutenberg_insert_hooked_blocks_into_rest_response', 10, 2 );
+add_filter( 'rest_prepare_wp_block', 'gutenberg_insert_hooked_blocks_into_rest_response', 10, 2 );
 
 /**
  * Updates the wp_postmeta with the list of ignored hooked blocks
@@ -272,6 +280,8 @@ function gutenberg_update_ignored_hooked_blocks_postmeta( $post ) {
 
 	if ( 'wp_navigation' === $post->post_type ) {
 		$wrapper_block_type = 'core/navigation';
+	} elseif ( 'wp_block' === $post->post_type ) {
+		$wrapper_block_type = 'core/block';
 	} else {
 		$wrapper_block_type = 'core/post-content';
 	}
@@ -311,3 +321,4 @@ function gutenberg_update_ignored_hooked_blocks_postmeta( $post ) {
 }
 add_filter( 'rest_pre_insert_page', 'gutenberg_update_ignored_hooked_blocks_postmeta' );
 add_filter( 'rest_pre_insert_post', 'gutenberg_update_ignored_hooked_blocks_postmeta' );
+add_filter( 'rest_pre_insert_wp_block', 'gutenberg_update_ignored_hooked_blocks_postmeta' );

packages/block-editor/README.md

@@ -713,10 +713,50 @@ Undocumented declaration.
 
 ### PlainText
 
+Render an auto-growing textarea allow users to fill any textual content.
+
 _Related_
 
 -   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/plain-text/README.md>
 
+_Usage_
+
+```jsx
+import { registerBlockType } from '@wordpress/blocks';
+import { PlainText } from '@wordpress/block-editor';
+
+registerBlockType( 'my-plugin/example-block', {
+	// ...
+
+	attributes: {
+		content: {
+			type: 'string',
+		},
+	},
+
+	edit( { className, attributes, setAttributes } ) {
+		return (
+			<PlainText
+				className={ className }
+				value={ attributes.content }
+				onChange={ ( content ) => setAttributes( { content } ) }
+			/>
+		);
+	},
+} );
+```
+
+_Parameters_
+
+-   _props_ `Object`: Component props.
+-   _props.value_ `string`: String value of the textarea.
+-   _props.onChange_ `Function`: Function called when the text value changes.
+-   _props.ref_ `[Object]`: The component forwards the `ref` property to the `TextareaAutosize` component.
+
+_Returns_
+
+-   `Element`: Plain text component
+
 ### privateApis
 
 Private @wordpress/block-editor APIs.

packages/block-editor/src/components/plain-text/README.md

@@ -6,11 +6,11 @@ Render an auto-growing textarea allow users to fill any textual content.
 
 ### `value: string`
 
-_Required._ String value of the textarea
+_Required._ String value of the textarea.
 
 ### `onChange( value: string ): Function`
 
-_Required._ Called when the value changes.
+_Required._ Function called when the text value changes.
 
 You can also pass any extra prop to the textarea rendered by this component.
 

packages/block-editor/src/components/plain-text/index.js

@@ -15,7 +15,41 @@ import { forwardRef } from '@wordpress/element';
 import EditableText from '../editable-text';
 
 /**
+ * Render an auto-growing textarea allow users to fill any textual content.
+ *
  * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/plain-text/README.md
+ *
+ * @example
+ * ```jsx
+ * import { registerBlockType } from '@wordpress/blocks';
+ * import { PlainText } from '@wordpress/block-editor';
+ *
+ * registerBlockType( 'my-plugin/example-block', {
+ *   // ...
+ *
+ *   attributes: {
+ *     content: {
+ *       type: 'string',
+ *     },
+ *   },
+ *
+ *   edit( { className, attributes, setAttributes } ) {
+ *     return (
+ *       <PlainText
+ *         className={ className }
+ *         value={ attributes.content }
+ *         onChange={ ( content ) => setAttributes( { content } ) }
+ *       />
+ *     );
+ *   },
+ * } );
+ * ````
+ *
+ * @param {Object}   props          Component props.
+ * @param {string}   props.value    String value of the textarea.
+ * @param {Function} props.onChange Function called when the text value changes.
+ * @param {Object}   [props.ref]    The component forwards the `ref` property to the `TextareaAutosize` component.
+ * @return {Element} Plain text component
  */
 const PlainText = forwardRef( ( { __experimentalVersion, ...props }, ref ) => {
 	if ( __experimentalVersion === 2 ) {

packages/block-editor/src/components/plain-text/stories/index.story.js

@@ -0,0 +1,75 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import PlainText from '..';
+
+const meta = {
+	title: 'BlockEditor/PlainText',
+	component: PlainText,
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'PlainText renders an auto-growing textarea that allows users to enter any textual content.',
+			},
+		},
+	},
+	argTypes: {
+		value: {
+			control: {
+				type: null,
+			},
+			table: {
+				type: {
+					summary: 'string',
+				},
+			},
+			description: 'String value of the textarea.',
+		},
+		onChange: {
+			action: 'onChange',
+			control: {
+				type: null,
+			},
+			table: {
+				type: {
+					summary: 'function',
+				},
+			},
+			description: 'Function called when the text value changes.',
+		},
+		className: {
+			control: 'text',
+			table: {
+				type: {
+					summary: 'string',
+				},
+			},
+			description: 'Additional class name for the PlainText.',
+		},
+	},
+};
+
+export default meta;
+
+export const Default = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] = useState();
+		return (
+			<PlainText
+				{ ...args }
+				onChange={ ( ...changeArgs ) => {
+					onChange( ...changeArgs );
+					setValue( ...changeArgs );
+				} }
+				value={ value }
+			/>
+		);
+	},
+};

packages/block-editor/src/components/text-decoration-control/README.md

@@ -28,7 +28,6 @@ Then, you can use the component in your block editor UI:
 ### `value`
 
 -   **Type:** `String`
--   **Default:** `none`
 -   **Options:** `none`, `underline`, `line-through`
 
 The current value of the Text Decoration setting. You may only choose from the `Options` listed above.