Merge branch 'trunk' of https://github.com/WordPress/gutenberg into t…

…ry/interactivity-lazy-hydration

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,
 					} ),

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/block-supports/block-style-variations.php

@@ -211,10 +211,10 @@ function gutenberg_render_block_style_variation_support_styles( $parsed_block )
  * block attributes in the `render_block_data` filter gets applied to the
  * block's markup.
  *
- * @see gutenberg_render_block_style_variation_support_styles
- *
  * @since 6.6.0
  *
+ * @see gutenberg_render_block_style_variation_support_styles
+ *
  * @param  string $block_content Rendered block content.
  * @param  array  $block         Block object.
  *

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/block-tools/style.scss

@@ -78,6 +78,7 @@
 		color: $white;
 		padding: 0;
 
+		// TODO: Consider passing size="small" to the Inserter toggle instead.
 		// Special dimensions for this button.
 		min-width: $button-size-small;
 		height: $button-size-small;

packages/block-editor/src/components/default-block-appender/content.scss

@@ -42,6 +42,7 @@
 		color: $white;
 		padding: 0;
 
+		// TODO: Consider passing size="small" to the Inserter toggle instead.
 		// Special dimensions for this button.
 		min-width: $button-size-small;
 		height: $button-size-small;

packages/block-editor/src/components/inserter/block-patterns-explorer/index.js

@@ -14,9 +14,8 @@ import { usePatternCategories } from '../block-patterns-tab/use-pattern-categori
 
 function PatternsExplorer( { initialCategory, rootClientId } ) {
 	const [ searchValue, setSearchValue ] = useState( '' );
-	const [ selectedCategory, setSelectedCategory ] = useState(
-		initialCategory?.name
-	);
+	const [ selectedCategory, setSelectedCategory ] =
+		useState( initialCategory );
 
 	const patternCategories = usePatternCategories( rootClientId );
 

packages/block-editor/src/components/inserter/block-patterns-tab/index.js

@@ -70,7 +70,9 @@ function BlockPatternsTab( {
 			) }
 			{ showPatternsExplorer && (
 				<PatternsExplorerModal
-					initialCategory={ selectedCategory || categories[ 0 ] }
+					initialCategory={
+						selectedCategory?.name || categories[ 0 ]?.name
+					}
 					patternCategories={ categories }
 					onModalClose={ () => setShowPatternsExplorer( false ) }
 					rootClientId={ rootClientId }

packages/block-editor/src/components/inserter/block-patterns-tab/pattern-category-previews.js

@@ -69,19 +69,19 @@ export function PatternCategoryPreviews( {
 					return false;
 				}
 
-				if ( category.name === allPatternsCategory.name ) {
+				if ( category.name === allPatternsCategory?.name ) {
 					return true;
 				}
 
 				if (
-					category.name === myPatternsCategory.name &&
+					category.name === myPatternsCategory?.name &&
 					pattern.type === INSERTER_PATTERN_TYPES.user
 				) {
 					return true;
 				}
 
 				if (
-					category.name === starterPatternsCategory.name &&
+					category.name === starterPatternsCategory?.name &&
 					pattern.blockTypes?.includes( 'core/post-content' )
 				) {
 					return true;
@@ -149,7 +149,7 @@ export function PatternCategoryPreviews( {
 							level={ 4 }
 							as="div"
 						>
-							{ category.label }
+							{ category?.label }
 						</Heading>
 					</FlexBlock>
 					<PatternsFilter

packages/block-editor/src/components/inserter/block-patterns-tab/patterns-filter.js

@@ -25,7 +25,7 @@ import {
 const getShouldDisableSyncFilter = ( sourceFilter ) =>
 	sourceFilter !== 'all' && sourceFilter !== 'user';
 const getShouldHideSourcesFilter = ( category ) => {
-	return category.name === myPatternsCategory.name;
+	return category?.name === myPatternsCategory.name;
 };
 
 const PATTERN_SOURCE_MENU_OPTIONS = [
@@ -60,7 +60,7 @@ export function PatternsFilter( {
 	// the user may be confused when switching to another category if the haven't explicity set
 	// this filter themselves.
 	const currentPatternSourceFilter =
-		category.name === myPatternsCategory.name
+		category?.name === myPatternsCategory.name
 			? INSERTER_PATTERN_TYPES.user
 			: patternSourceFilter;
 

packages/block-editor/src/components/inserter/category-tabs/index.js

@@ -64,9 +64,10 @@ function CategoryTabs( {
 					<Tabs.Tab
 						key={ category.name }
 						tabId={ category.name }
-						aria-label={ category.label }
 						aria-current={
-							category === selectedCategory ? 'true' : undefined
+							category.name === selectedCategory?.name
+								? 'true'
+								: undefined
 						}
 					>
 						{ category.label }

packages/block-editor/src/components/inserter/index.js

@@ -60,6 +60,7 @@ const defaultRenderToggle = ( {
 
 	return (
 		<Wrapper
+			__next40pxDefaultSize={ toggleProps.as ? undefined : true }
 			icon={ plus }
 			label={ label }
 			tooltipPosition="bottom"

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.