Revert/block support stabilization

backport-changelog/6.8/7069.md

@@ -3,4 +3,3 @@ https://github.com/WordPress/wordpress-develop/pull/7069
 * https://github.com/WordPress/gutenberg/pull/63401
 * https://github.com/WordPress/gutenberg/pull/66918
 * https://github.com/WordPress/gutenberg/pull/67018
-* https://github.com/WordPress/gutenberg/pull/67552

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

@@ -71,10 +71,6 @@ function gutenberg_stabilize_experimental_block_supports( $args ) {
 		}
 
 		$stabilize_config = function ( $unstable_config, $stable_support_key ) use ( $experimental_support_properties, $common_experimental_properties ) {
-			if ( ! is_array( $unstable_config ) ) {
-				return $unstable_config;
-			}
-
 			$stable_config = array();
 			foreach ( $unstable_config as $key => $value ) {
 				// Get stable key from support-specific map, common properties map, or keep original.
@@ -120,23 +116,18 @@ function gutenberg_stabilize_experimental_block_supports( $args ) {
 				( $key_positions[ $support ] ?? PHP_INT_MAX ) <
 				( $key_positions[ $stable_support_key ] ?? PHP_INT_MAX );
 
-			/*
-			 * To merge the alternative support config effectively, it also needs to be
-			 * stabilized before merging to keep stabilized and experimental flags in
-			 * sync.
-			 */
-			$args['supports'][ $stable_support_key ] = $stabilize_config( $args['supports'][ $stable_support_key ], $stable_support_key );
-			// Prevents reprocessing this support as it was stabilized above.
-			$done[ $stable_support_key ] = true;
-
-			if ( is_array( $stable_config ) && is_array( $args['supports'][ $stable_support_key ] ) ) {
-				$stable_config = $experimental_first
-					? array_merge( $stable_config, $args['supports'][ $stable_support_key ] )
-					: array_merge( $args['supports'][ $stable_support_key ], $stable_config );
-			} else {
-				$stable_config = $experimental_first
+				if ( is_array( $args['supports'][ $stable_support_key ] ) ) {
+					/*
+					 * To merge the alternative support config effectively, it also needs to be
+					 * stabilized before merging to keep stabilized and experimental flags in
+					 * sync.
+					 */
+					$args['supports'][ $stable_support_key ] = $stabilize_config( $args['supports'][ $stable_support_key ], $stable_support_key );
+					$stable_config                           = $experimental_first
 					? $args['supports'][ $stable_support_key ]
 					: $stable_config;
+					// Prevents reprocessing this support as it was merged above.
+					$done[ $stable_support_key ] = true;
 			}
 		}
 

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/inserter/category-tabs/index.js

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

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.