Merge branch 'trunk' into docs/add-video-embed-documentation

docs/contributors/code/back-merging-to-wp-core.md

@@ -0,0 +1,31 @@
+# Back-merging code to WordPress Core
+
+For major releases of the WordPress software, Gutenberg features need to be merged into WordPress Core. Typically this involves taking changes made in `.php` files within the Gutenberg repository and making the equivalent updates in the WP Core codebase.
+
+## Files/Directories
+
+Changes to files within the following files/directories will typically require back-merging to WP Core:
+
+-   `lib/`
+-   `phpunit/`
+
+## Ignored directories/files
+
+The following directories/files do _not_ require back-merging to WP Core:
+
+-   `lib/load.php` - Plugin specific code.
+-   `lib/experiments-page.php` - experiments are Plugin specific.
+-   `packages/block-library` - this is handled automatically during the packages sync process.
+-   `packages/e2e-tests/plugins` - PHP files related to e2e tests only. Mostly fixture data generators.
+-   `phpunit/blocks` - the code is maintained in Gutenberg so the test should be as well.
+
+Please note this list is not exhaustive.
+
+## Pull Request Criteria
+
+In general, all PHP code committed to the Gutenberg repository since the date of the final Gutenberg release that was included in [the _last_ stable WP Core release](https://developer.wordpress.org/block-editor/contributors/versions-in-wordpress/) should be considered for back merging to WP Core.
+
+There are however certain exceptions to that rule. PRs with the following criteria do _not_ require back-merging to WP Core:
+
+-   Does not contain changes to PHP code.
+-   Has label `Backport from WordPress Core` - this code is already in WP Core.

docs/getting-started/fundamentals/block-wrapper.md

@@ -2,16 +2,16 @@
 
 Each block's markup is wrapped by a container HTML tag that needs to have the proper attributes to fully work in the Block Editor and to reflect the proper block's style settings when rendered in the Block Editor and the front end. As developers, we have full control over the block's markup, and WordPress provides the tools to add the attributes that need to exist on the wrapper to our block's markup.
 
-Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`. 
+Ensuring proper attributes to the block wrapper is especially important when using custom styling or features like `supports`.
 
 <div class="callout callout-info">
 The use of <code>supports</code> generates a set of properties that need to be manually added to the wrapping element of the block so they're properly stored as part of the block data.
 </div>
 
 A block can have three sets of markup defined, each one of them with a specific target and purpose:
 
-- The one for the **Block Editor**, defined through a `edit` React component passed to [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#registerblocktype) when registering the block in the client. 
-- The one used to **save the block in the DB**, defined through a `save` function passed to `registerBlockType` when registering the block in the client. 
+- The one for the **Block Editor**, defined through a `edit` React component passed to [`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#registerblocktype) when registering the block in the client.
+- The one used to **save the block in the DB**, defined through a `save` function passed to `registerBlockType` when registering the block in the client.
     - This markup will be returned to the front end on request if no dynamic render has been defined for the block.
 - The one used to **dynamically render the markup of the block** returned to the front end on request, defined through the `render_callback` on [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) or the [`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render) PHP file in `block.json`
     - If defined, this server-side generated markup will be returned to the front end, ignoring the markup stored in DB.
@@ -21,13 +21,13 @@ For the [`edit` React component and the `save` function](https://developer.wordp
 
 ## The Edit component's markup
 
-The [`useBlockProps()`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops) hook available on the [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor) allows passing the required attributes for the Block Editor to the `edit` block's outer wrapper. 
+The [`useBlockProps()`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops) hook available on the [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor) allows passing the required attributes for the Block Editor to the `edit` block's outer wrapper.
 
 Among other things, the `useBlockProps()` hook takes care of including in this wrapper:
-- An `id` for the block's markup 
-- Some accesibility and `data-` attributes
+- An `id` for the block's markup
+- Some accessibility and `data-` attributes
 - Classes and inline styles reflecting custom settings, which include by default:
-    - The `wp-block` class 
+    - The `wp-block` class
     - A class that contains the name of the block with its namespace
 
 For example, for the following piece of code of a block's registration in the client...
@@ -43,18 +43,18 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
 
 ...the markup of the block in the Block Editor could look like this:
 ```html
-<p 
-    tabindex="0" 
-    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
-    role="document" 
-    aria-label="Block: Minimal Gutenberg Block ca6eda" 
-    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
-    data-type="block-development-examples/minimal-block-ca6eda" 
-    data-title="Minimal Gutenberg Block ca6eda" 
+<p
+    tabindex="0"
+    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe"
+    role="document"
+    aria-label="Block: Minimal Gutenberg Block ca6eda"
+    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe"
+    data-type="block-development-examples/minimal-block-ca6eda"
+    data-title="Minimal Gutenberg Block ca6eda"
     class="
-        block-editor-block-list__block 
-        wp-block 
-        is-selected 
+        block-editor-block-list__block
+        wp-block
+        is-selected
         wp-block-block-development-examples-minimal-block-ca6eda
     "
 >Hello World - Block Editor</p>
@@ -87,16 +87,16 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
 <p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – Frontend</p>
 ```
 
-Any additional classes and attributes for the `save` function of the block should be passed as an argument of `useBlockProps.save()` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)). 
+Any additional classes and attributes for the `save` function of the block should be passed as an argument of `useBlockProps.save()` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)).
 
 When you add `supports` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.
 
 ```html
 <p class="
-    wp-block-block-development-examples-block-supports-6aa4dd 
-    has-accent-4-color 
-    has-contrast-background-color 
-    has-text-color 
+    wp-block-block-development-examples-block-supports-6aa4dd
+    has-accent-4-color
+    has-contrast-background-color
+    has-text-color
     has-background
 ">Hello World</p>
 ```
@@ -105,10 +105,10 @@ _(check the [example](https://github.com/WordPress/block-development-examples/tr
 
 ## The server-side render markup
 
-Any markup in the server-side render definition for the block can use the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) function to generate the string of attributes required to reflect the block settings (see [example](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)). 
+Any markup in the server-side render definition for the block can use the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) function to generate the string of attributes required to reflect the block settings (see [example](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)).
 
 ```php
 <p <?php echo get_block_wrapper_attributes(); ?>>
 	<?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', 'block-development-examples' ); ?>
 </p>
-```
+```

docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md

@@ -208,13 +208,13 @@ export const withBookQueryControls = ( BlockEdit ) => ( props ) => {
 	// function to handle that.
 	return isMyBooksVariation( props ) ? (
 		<>
-			<BlockEdit { ...props } />
+			<BlockEdit key="edit" { ...props } />
 			<InspectorControls>
 				<BookAuthorSelector /> { /** Our custom component */ }
 			</InspectorControls>
 		</>
 	) : (
-		<BlockEdit { ...props } />
+		<BlockEdit key="edit" { ...props } />
 	);
 };
 

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

@@ -233,6 +233,7 @@ The settings section has the following structure:
 		},
 		"custom": {},
 		"dimensions": {
+			"aspectRatio": false,
 			"minHeight": false,
 		},
 		"layout": {
@@ -773,6 +774,7 @@ Each block declares which style properties it exposes via the [block supports me
 			"text": "value"
 		},
 		"dimensions": {
+			"aspectRatio": "value",
 			"minHeight": "value"
 		},
 		"filter": {

docs/how-to-guides/themes/theme-support.md

@@ -472,7 +472,7 @@ Use this setting to enable the following Global Styles settings:
 - color: link
 - spacing: blockGap, margin, padding
 - typography: lineHeight
-- dimensions: minHeight
+- dimensions: aspectRatio, minHeight
 - position: sticky
 
 ```php

docs/manifest.json

@@ -1673,6 +1673,12 @@
 		"markdown_source": "../packages/icons/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/interactivity-router",
+		"slug": "packages-interactivity-router",
+		"markdown_source": "../packages/interactivity-router/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/interactivity",
 		"slug": "packages-interactivity",

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

@@ -442,19 +442,21 @@ This value signals that a block supports some of the CSS style properties relate
 ```js
 supports: {
     dimensions: {
+        aspectRatio: true // Enable aspect ratio control.
         minHeight: true // Enable min height control.
     }
 }
 ```
 
 When a block declares support for a specific dimensions property, its attributes definition is extended to include the `style` attribute.
 
-- `style`: attribute of `object` type with no default assigned. This is added when `minHeight` support is declared. It stores the custom values set by the user, e.g.:
+- `style`: attribute of `object` type with no default assigned. This is added when `aspectRatio` or `minHeight` support is declared. It stores the custom values set by the user, e.g.:
 
 ```js
 attributes: {
     style: {
         dimensions: {
+            aspectRatio: "16/9",
             minHeight: "50vh"
         }
     }

docs/reference-guides/core-blocks.md

@@ -42,7 +42,7 @@ Create and save content to reuse across your site. Update the pattern, and the c
 -	**Name:** core/block
 -	**Category:** reusable
 -	**Supports:** ~~customClassName~~, ~~html~~, ~~inserter~~, ~~renaming~~
--	**Attributes:** ref
+-	**Attributes:** overrides, ref
 
 ## Button
 
@@ -238,7 +238,7 @@ Add an image or video with a text overlay. ([Source](https://github.com/WordPres
 
 -	**Name:** core/cover
 -	**Category:** media
--	**Supports:** align, anchor, color (heading, text, ~~background~~, ~~enableContrastChecker~~), layout (~~allowJustification~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
+-	**Supports:** align, anchor, color (heading, text, ~~background~~, ~~enableContrastChecker~~), dimensions (aspectRatio), layout (~~allowJustification~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
 -	**Attributes:** allowedBlocks, alt, backgroundType, contentPosition, customGradient, customOverlayColor, dimRatio, focalPoint, gradient, hasParallax, id, isDark, isRepeated, isUserOverlayColor, minHeight, minHeightUnit, overlayColor, tagName, templateLock, url, useFeaturedImage
 
 ## Details
@@ -341,7 +341,7 @@ Gather blocks in a layout container. ([Source](https://github.com/WordPress/gute
 
 -	**Name:** core/group
 -	**Category:** design
--	**Supports:** align (full, wide), anchor, ariaLabel, background (backgroundImage, backgroundSize), color (background, button, gradients, heading, link, text), dimensions (minHeight), layout (allowSizingOnChildren), position (sticky), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
+-	**Supports:** align (full, wide), anchor, ariaLabel, background (backgroundImage, backgroundSize), color (background, button, gradients, heading, link, text), dimensions (aspectRatio, minHeight), layout (allowSizingOnChildren), position (sticky), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~
 -	**Attributes:** allowedBlocks, tagName, templateLock
 
 ## Heading

docs/reference-guides/data/data-core-block-editor.md

@@ -409,6 +409,19 @@ _Returns_
 
 -   `WPBlock[]`: Block objects.
 
+### getBlocksByName
+
+Returns all blocks that match a blockName. Results include nested blocks.
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+-   _blockName_ `?string`: Optional block name, if not specified, returns an empty array.
+
+_Returns_
+
+-   `Array`: Array of clientIds of blocks with name equal to blockName.
+
 ### getBlockSelectionEnd
 
 Returns the current block selection end. This value may be null, and it may represent either a singular block selection or multi-selection end. A selection is singular if its start and end match.

docs/reference-guides/data/data-core-notices.md

@@ -277,7 +277,7 @@ export const ExampleComponent = () => {
 	const notices = useSelect( ( select ) =>
 		select( noticesStore ).getNotices()
 	);
-	const { removeNotices } = useDispatch( noticesStore );
+	const { removeAllNotices } = useDispatch( noticesStore );
 	return (
 		<>
 			<ul>

docs/reference-guides/filters/block-filters.md

@@ -19,11 +19,11 @@ _Example_:
 ```php
 <?php
 
-function filter_metadata_registration( $metadata ) {
+function wpdocs_filter_metadata_registration( $metadata ) {
 	$metadata['apiVersion'] = 1;
 	return $metadata;
 };
-add_filter( 'block_type_metadata', 'filter_metadata_registration' );
+add_filter( 'block_type_metadata', 'wpdocs_filter_metadata_registration' );
 
 register_block_type( __DIR__ );
 ```
@@ -40,11 +40,11 @@ The filter takes two params:
 _Example:_
 
 ```php
-function filter_metadata_registration( $settings, $metadata ) {
+function wpdocs_filter_metadata_registration( $settings, $metadata ) {
 	$settings['api_version'] = $metadata['apiVersion'] + 1;
 	return $settings;
 };
-add_filter( 'block_type_metadata_settings', 'filter_metadata_registration', 10, 2 );
+add_filter( 'block_type_metadata_settings', 'wpdocs_filter_metadata_registration', 10, 2 );
 
 register_block_type( __DIR__ );
 ```
@@ -189,7 +189,7 @@ const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
 	return ( props ) => {
 		return (
 			<>
-				<BlockEdit { ...props } />
+				<BlockEdit key="edit" { ...props } />
 				<InspectorControls>
 					<PanelBody>My custom control</PanelBody>
 				</InspectorControls>
@@ -352,14 +352,14 @@ On the server, you can filter the list of blocks shown in the inserter using the
 <?php
 // my-plugin.php
 
-function filter_allowed_block_types_when_post_provided( $allowed_block_types, $editor_context ) {
+function wpdocs_filter_allowed_block_types_when_post_provided( $allowed_block_types, $editor_context ) {
 	if ( ! empty( $editor_context->post ) ) {
 		return array( 'core/paragraph', 'core/heading' );
 	}
 	return $allowed_block_types;
 }
 
-add_filter( 'allowed_block_types_all', 'filter_allowed_block_types_when_post_provided', 10, 2 );
+add_filter( 'allowed_block_types_all', 'wpdocs_filter_allowed_block_types_when_post_provided', 10, 2 );
 ```
 
 ## Managing block categories
@@ -374,7 +374,7 @@ It is possible to filter the list of default block categories using the `block_c
 <?php
 // my-plugin.php
 
-function filter_block_categories_when_post_provided( $block_categories, $editor_context ) {
+function wpdocs_filter_block_categories_when_post_provided( $block_categories, $editor_context ) {
 	if ( ! empty( $editor_context->post ) ) {
 		array_push(
 			$block_categories,
@@ -388,7 +388,7 @@ function filter_block_categories_when_post_provided( $block_categories, $editor_
 	return $block_categories;
 }
 
-add_filter( 'block_categories_all', 'filter_block_categories_when_post_provided', 10, 2 );
+add_filter( 'block_categories_all', 'wpdocs_filter_block_categories_when_post_provided', 10, 2 );
 ```
 
 ### `wp.blocks.updateCategory`

docs/reference-guides/filters/editor-filters.md

@@ -84,14 +84,14 @@ _Example:_
 <?php
 // my-plugin.php
 
-function filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) {
+function wpdocs_filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) {
 	if ( ! empty( $editor_context->post ) ) {
 		$editor_settings['maxUploadFileSize'] = 12345;
 	}
 	return $editor_settings;
 }
 
-add_filter( 'block_editor_settings_all', 'filter_block_editor_settings_when_post_provided', 10, 2 );
+add_filter( 'block_editor_settings_all', 'wpdocs_filter_block_editor_settings_when_post_provided', 10, 2 );
 ```
 
 #### `block_editor_rest_api_preload_paths`
@@ -104,14 +104,14 @@ _Example:_
 <?php
 // my-plugin.php
 
-function filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) {
+function wpdocs_filter_block_editor_rest_api_preload_paths_when_post_provided( $preload_paths, $editor_context ) {
 	if ( ! empty( $editor_context->post ) ) {
 		array_push( $preload_paths, array( '/wp/v2/blocks', 'OPTIONS' ) );
 	}
 	return $preload_paths;
 }
 
-add_filter( 'block_editor_rest_api_preload_paths', 'filter_block_editor_rest_api_preload_paths_when_post_provided', 10, 2 );
+add_filter( 'block_editor_rest_api_preload_paths', 'wpdocs_filter_block_editor_rest_api_preload_paths_when_post_provided', 10, 2 );
 ```
 
 ### Available default editor settings

docs/reference-guides/filters/global-styles-filters.md

@@ -14,7 +14,7 @@ _Example:_
 This is how to pass a new color palette for the theme and disable the text color UI:
 
 ```php
-function filter_theme_json_theme( $theme_json ){
+function wpdocs_filter_theme_json_theme( $theme_json ){
 	$new_data = array(
 		'version'  => 2,
 		'settings' => array(
@@ -38,5 +38,5 @@ function filter_theme_json_theme( $theme_json ){
 
 	return $theme_json->update_with( $new_data );
 }
-add_filter( 'wp_theme_json_data_theme', 'filter_theme_json_theme' );
+add_filter( 'wp_theme_json_data_theme', 'wpdocs_filter_theme_json_theme' );
 ```