Merge branch 'trunk' into update/cover-background-label

.github/workflows/publish-npm-packages.yml

@@ -53,6 +53,9 @@ jobs:
               with:
                   path: publish
                   ref: wp/${{ github.event.inputs.wp_version }}
+                  # We need to ensure that Lerna can read the commit created during the previous npm publishing.
+                  # Lerna assumes that all packages need publishing if it can't access the necessary information.
+                  fetch-depth: 999
                   token: ${{ secrets.GUTENBERG_TOKEN }}
                   show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
 

bin/plugin/commands/packages.js

@@ -83,24 +83,14 @@ async function checkoutNpmReleaseBranch( {
 	/*
 	 * Create the release branch.
 	 *
-	 * Note that we are grabbing an arbitrary depth of commits
-	 * during the fetch. When `lerna` attempts to determine if
-	 * a package needs an update, it looks at `git` history,
-	 * and if we have pruned that history it will pre-emptively
-	 * publish when it doesn't need to.
-	 *
-	 * We could set a different arbitrary depth if this isn't
-	 * long enough or if it's excessive. We could also try and
-	 * find a way to more specifically fetch what we expect to
-	 * change. For example, if we knew we'll be performing
-	 * updates every two weeks, we might be conservative and
-	 * use `--shallow-since=4.weeks.ago`.
-	 *
-	 * At the time of writing, a depth of 100 pulls in all
-	 * `trunk` commits from within the past week.
+	 * Note that we are grabbing an arbitrary depth of commits (999) during the fetch.
+	 * When Lerna attempts to determine if a package needs an update, it looks at
+	 * `git` history to find the commit created during the previous npm publishing.
+	 * Lerna assumes that all packages need publishing if it can't access
+	 * the necessary information.
 	 */
 	await SimpleGit( gitWorkingDirectoryPath )
-		.fetch( 'origin', npmReleaseBranch, [ '--depth=100' ] )
+		.fetch( 'origin', npmReleaseBranch, [ '--depth=999' ] )
 		.checkout( npmReleaseBranch );
 	log(
 		'>> The local npm release branch ' +

docs/getting-started/devenv/get-started-with-create-block.md

@@ -0,0 +1,95 @@
+# Get started with create-block
+
+Custom blocks for the Block Editor in WordPress are typically registered using plugins and are defined through a specific set of files. The [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) package is an officially supported tool to scaffold the structure of files needed to create and register a block. It generates all the necessary code to start a project and integrates a modern JavaScript build setup (using [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts.md)) with no configuration required. 
+
+The package is designed to help developers quickly set up a block development environment following WordPress best practices.
+
+## Quick Start
+
+### Installation
+
+Start by ensuring you have Node.js and `npm` installed on your computer. Review the [Node.js development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/) guide if not.
+
+You can use `create-block` to scaffold a block just about anywhere and then [use `wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/) from the inside of the generated plugin folder. This will create a local WordPress development environment with your new block plugin installed and activated.
+
+If you have your own [local WordPress development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment) already set up, navigate to the `plugins/` folder using the terminal.
+
+Run the following command to scaffold an example block plugin:
+
+```bash
+npx @wordpress/create-block@latest todo-list
+cd todo-list
+```
+
+The `slug` provided (`todo-list`) defines the folder name for the scaffolded plugin and the internal block name. 
+
+Navigate to the Plugins page of our local WordPress installation and activate the "Todo List" plugin. The example block will then be available in the Editor. 
+
+### Basic usage
+
+The `create-block` assumes you will use modern JavaScript (ESNext and JSX) to build your block. This requires a build step to compile the code into a format that browsers can understand. Luckily, the `wp-scripts` package handles this process for you. Refer to the [Get started with wp-scripts](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts) for an introduction to this package. 
+
+ When `create-block` scaffolds the block, it installs `wp-scripts` and adds the most common scripts to the block's `package.json` file. By default, those include:
+
+```json
+{
+    "scripts": {
+		"build": "wp-scripts build",
+		"format": "wp-scripts format",
+		"lint:css": "wp-scripts lint-style",
+		"lint:js": "wp-scripts lint-js",
+		"packages-update": "wp-scripts packages-update",
+		"plugin-zip": "wp-scripts plugin-zip",
+		"start": "wp-scripts start"
+	}
+}
+```
+
+These scripts can then be run using the command `npm run {script name}`. The two scripts you will use most often are `start` and `build` since they handle the build step.
+
+When working on your block, use the `npm run start` command. This will start a development server and automatically rebuild the block whenever any code change is detected.
+
+When you are ready to deploy your block, use the `npm run build` command. This optimizes your code and makes it production-ready.
+
+See the `wp-scripts` [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for more details about each available script.
+
+## Alternate implementations
+
+### Interactive mode
+
+For developers who prefer a more guided experience, the `create-block package` provides an interactive mode. Instead of manually specifying all options upfront, like the `slug` in the above example, this mode will prompt you for inputs step-by-step.
+
+To use this mode, run the command:
+
+```bash
+npx @wordpress/create-block@latest
+```
+
+Follow the prompts to configure your block settings interactively.
+
+### Quick start mode using options
+
+If you're already familiar with the `create-block` [options](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#options) and want a more streamlined setup, you can use quick start mode. This allows you to pass specific options directly in the command line, eliminating the need for interactive prompts.
+
+For instance, to quickly create a block named "my-block" with a namespace of "my-plugin" that is a Dynamic block, use this command:
+
+```bash
+npx @wordpress/create-block@latest --namespace="my-plugin" --slug="my-block" --variant="dynamic"
+```
+
+### Using templates
+
+The `create-block` package also supports the use of templates, enabling you to create blocks based on predefined configurations and structures. This is especially useful when you have a preferred block structure or when you're building multiple blocks with similar configurations.
+
+To use a template, specify the `--template` option followed by the template name or path:
+```bash
+npx @wordpress/create-block --template="my-custom-template"
+```
+
+Templates must be set up in advance so the `create-block` package knows where to find them. Learn more in the `create-block` [documentation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#template), and review the [External Project Templates](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/) guide.
+
+## Additional resources
+
+- [Using the create-block tool](https://learn.wordpress.org/tutorial/using-the-create-block-tool/) (Learn WordPress tutorial)
+- [@wordpress/create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) (Official documentation)
+- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) (Official documentation)

docs/getting-started/devenv/get-started-with-wp-env.md

@@ -4,6 +4,8 @@ The [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) package (`wp-
 
 Before following this guide, install [Node.js development tools](/docs/getting-started/devenv#node-js-development-tools) if you have not already done so.
 
+![wp-env basics diagram](https://developer.wordpress.org/files/2023/10/wp-env-diagram.png)
+
 ## Quick start
 
 1. Download, install, and start [Docker Desktop](https://www.docker.com/products/docker-desktop) following the instructions for your operating system.
@@ -135,6 +137,7 @@ Your environment should now be set up at `http://localhost:8888/`.
 
 ## Additional resources
 
--   [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) (Official documentation)
--   [Docker Desktop](https://docs.docker.com/desktop) (Official documentation)
--   [Quick and easy local WordPress development with wp-env](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/) (WordPress Developer Blog)
+- [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) (Official documentation)
+- [Docker Desktop](https://docs.docker.com/desktop) (Official documentation)
+- [Quick and easy local WordPress development with wp-env](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/) (WordPress Developer Blog)
+- [`wp-env` Basics diagram](https://excalidraw.com/#json=8Tp55B-R6Z6-pNGtmenU6,_DeBR1IBxuHNIKPTVEaseA) (Excalidraw)

docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md

@@ -69,7 +69,7 @@ registerBlockType( 'gutenberg-examples/example-06', {
 
 ## Allowed Blocks
 
-Using the `ALLOWED_BLOCKS` property, you can define the set of blocks allowed in your InnerBlock. This restricts the blocks that can be included only to those listed, all other blocks will not show in the inserter.
+Using the `allowedBlocks` property, you can define the set of blocks allowed in your InnerBlock. This restricts the blocks that can be included only to those listed, all other blocks will not show in the inserter.
 
 ```js
 const ALLOWED_BLOCKS = [ 'core/image', 'core/paragraph' ];
@@ -87,6 +87,16 @@ By default, `InnerBlocks` expects its blocks to be shown in a vertical list. A v
 
 Specifying this prop does not affect the layout of the inner blocks, but results in the block mover icons in the child blocks being displayed horizontally, and also ensures that drag and drop works correctly.
 
+## Default Block
+
+By default `InnerBlocks` opens a list of permitted blocks via `allowedBlocks` when the block appender is clicked. You can modify the default block and its attributes that are inserted when the initial block appender is clicked by using the `defaultBlock` property. For example:
+
+```js
+<InnerBlocks defaultBlock={['core/paragraph', {placeholder: "Lorem ipsum..."}]} directInsert />
+```
+
+By default this behavior is disabled until the `directInsert` prop is set to `true`. This allows you to specify conditions for when the default block should or should not be inserted.
+
 ## Template
 
 Use the template property to define a set of blocks that prefill the InnerBlocks component when inserted. You can set attributes on the blocks to define their use. The example below shows a book review template using InnerBlocks component and setting placeholders values to show the block usage.

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

@@ -320,6 +320,7 @@ Note, however, that not all settings are relevant for all blocks. The settings s
 
 There's one special setting property, `appearanceTools`, which is a boolean and its default value is false. Themes can use this setting to enable the following ones:
 
+- background: backgroundImage
 - border: color, radius, style, width
 - color: link
 - dimensions: minHeight

docs/manifest.json

@@ -29,6 +29,12 @@
 		"markdown_source": "../docs/getting-started/devenv/get-started-with-wp-env.md",
 		"parent": "devenv"
 	},
+	{
+		"title": "Get started with create-block",
+		"slug": "get-started-with-create-block",
+		"markdown_source": "../docs/getting-started/devenv/get-started-with-create-block.md",
+		"parent": "devenv"
+	},
 	{
 		"title": "Create a Block Tutorial",
 		"slug": "create-block",

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

@@ -227,8 +227,7 @@ var withInspectorControls = wp.compose.createHigherOrderComponent( function (
 			)
 		);
 	};
-},
-'withInspectorControls' );
+}, 'withInspectorControls' );
 
 wp.hooks.addFilter(
 	'editor.BlockEdit',
@@ -239,6 +238,29 @@ wp.hooks.addFilter(
 
 {% end %}
 
+Note that as this hook is run for _all blocks_, consuming it has potential for performance regressions particularly around block selection metrics.
+
+To mitigate this, consider whether any work you perform can be altered to run only under certain conditions.
+
+For example, if you are adding components that only need to render when the block is _selected_, then you can use the block's "selected" state (`props.isSelected`) to conditionalize your rendering.
+
+```js
+const withInspectorControls = createHigherOrderComponent( ( BlockEdit ) => {
+	return ( props ) => {
+		return (
+			<>
+				<BlockEdit { ...props } />
+				{ props.isSelected && {
+					<InspectorControls>
+						<PanelBody>My custom control</PanelBody>
+					</InspectorControls>
+				}}
+			</>
+		);
+	};
+}, 'withInspectorControl' );
+```
+
 #### `editor.BlockListBlock`
 
 Used to modify the block's wrapper component containing the block's `edit` component and all toolbars. It receives the original `BlockListBlock` component and returns a new wrapped component.
@@ -288,8 +310,7 @@ var withClientIdClassName = wp.compose.createHigherOrderComponent( function (
 
 		return el( BlockListBlock, newProps );
 	};
-},
-'withClientIdClassName' );
+}, 'withClientIdClassName' );
 
 wp.hooks.addFilter(
 	'editor.BlockListBlock',

docs/toc.json

@@ -11,6 +11,9 @@
 					},
 					{
 						"docs/getting-started/devenv/get-started-with-wp-env.md": []
+					},
+					{
+						"docs/getting-started/devenv/get-started-with-create-block.md": []
 					}
 				]
 			},

lib/README.md

@@ -1,5 +1,7 @@
 # Gutenberg PHP
 
+This documentation is intended for developers who are contributing to the PHP code in the Gutenberg plugin, and pertains to files in the `lib` directory.
+
 The Gutenberg plugin is continuously enhancing existing features and creating new ones. Some features, once considered stable and useful, are merged into Core (the WordPress source code) during a WordPress release. Others remain in the plugin forever or are eventually removed as the minimum supported WordPress version changes.
 
 During a WordPress release, new features, bugfixes and other changes are "synced" between the Gutenberg plugin and WordPress Core. Consistent naming and directory structures make this process easier by preventing naming conflicts and compartmentalizing release-specific code.
@@ -100,6 +102,16 @@ Wrapping code in `class_exists()` and `function_exists()` is usually inappropria
 
 When to use which prefix is a judgement call, but the general rule is that if you're unsure, use the `gutenberg` prefix because it will less likely give rise to naming conflicts.
 
+#### When not to use plugin-specific prefixes/suffixes
+
+The above recommendations in relation to plugin-specific prefixes/suffixes are relevant only to files in the `lib` directory and only in the Gutenberg plugin.
+
+`Gutenberg` prefixes/suffixes _should not_ be used in Core PHP code. When synching `/lib` files to Core, plugin-specific prefixes/suffixes are generally replaced with their `WP_` or `wp_` equivalents manually.
+
+Accordingly, unless required to run plugin-only code, you should avoid using plugin-specific prefixes/suffixes in any block PHP code. Core blocks in the plugin are [published as NPM packages](https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/code/release.md#packages-releases-to-npm-and-wordpress-core-updates), which Core consumes as NPM dependencies.
+
+See [block naming conventions](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library#naming-convention-for-php-functions) for more information on block naming conventions.
+
 As always, get in touch with your fellow contributors if you're unsure.
 
 ### Documentation and annotations

lib/block-supports/behaviors.php

@@ -109,8 +109,8 @@ function gutenberg_render_behaviors_support_lightbox( $block_content, $block ) {
 	if ( isset( $block['attrs']['id'] ) ) {
 		$img_uploaded_src = wp_get_attachment_url( $block['attrs']['id'] );
 		$img_metadata     = wp_get_attachment_metadata( $block['attrs']['id'] );
-		$img_width        = $img_metadata['width'];
-		$img_height       = $img_metadata['height'];
+		$img_width        = $img_metadata['width'] ?? 'none';
+		$img_height       = $img_metadata['height'] ?? 'none';
 	} else {
 		$img_uploaded_src = $processor->get_attribute( 'src' );
 		$img_width        = 'none';

lib/compat/wordpress-6.5/block-patterns.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * Extends Core's wp-includes/block-patterns.php to add new media related
+ * pattern categories for WP 6.5.
+ *
+ * @package gutenberg
+ */
+
+/**
+ * Adds new pattern categories for better organization of media related patterns.
+ *
+ * Note: This should be removed when the minimum required WP version is >= 6.5.
+ *
+ * @return void
+ */
+function gutenberg_register_media_pattern_categories() {
+	// Register new categories.
+	register_block_pattern_category(
+		'videos',
+		array(
+			'label'       => _x( 'Videos', 'Block pattern category' ),
+			'description' => __( 'Different layouts containing videos.' ),
+		)
+	);
+	register_block_pattern_category(
+		'audio',
+		array(
+			'label'       => _x( 'Audio', 'Block pattern category' ),
+			'description' => __( 'Different layouts containing audio.' ),
+		)
+	);
+}
+add_action( 'init', 'gutenberg_register_media_pattern_categories' );

lib/experimental/interactivity-api/class-wp-directive-processor.php

@@ -20,7 +20,7 @@
  * available.  Please restrain from investing unnecessary time and effort trying
  * to improve this code.
  */
-class WP_Directive_Processor extends WP_HTML_Tag_Processor {
+class WP_Directive_Processor extends Gutenberg_HTML_Tag_Processor_6_4 {
 
 	/**
 	 * An array of root blocks.

lib/load.php

@@ -76,8 +76,8 @@ function gutenberg_is_experiment_enabled( $name ) {
 require __DIR__ . '/compat/plugin/edit-site-routes-backwards-compat.php';
 require __DIR__ . '/compat/plugin/footnotes.php';
 
+require __DIR__ . '/compat/wordpress-6.4/html-api/class-gutenberg-html-tag-processor-6-4.php';
 if ( ! class_exists( 'WP_HTML_Processor' ) ) {
-	require __DIR__ . '/compat/wordpress-6.4/html-api/class-gutenberg-html-tag-processor-6-4.php';
 	require __DIR__ . '/compat/wordpress-6.4/html-api/class-wp-html-active-formatting-elements.php';
 	require __DIR__ . '/compat/wordpress-6.4/html-api/class-wp-html-open-elements.php';
 	require __DIR__ . '/compat/wordpress-6.4/html-api/class-wp-html-processor-state.php';
@@ -103,6 +103,9 @@ function gutenberg_is_experiment_enabled( $name ) {
 require __DIR__ . '/compat/wordpress-6.4/script-loader.php';
 require __DIR__ . '/compat/wordpress-6.4/kses.php';
 
+// WordPress 6.5 compat.
+require __DIR__ . '/compat/wordpress-6.5/block-patterns.php';
+
 // Experimental features.
 require __DIR__ . '/experimental/block-editor-settings-mobile.php';
 require __DIR__ . '/experimental/blocks.php';

packages/block-editor/src/components/block-controls/hook.js

@@ -17,17 +17,20 @@ export default function useBlockControlsFill( group, shareWithChildBlocks ) {
 	const { clientId } = useBlockEditContext();
 	const isParentDisplayed = useSelect(
 		( select ) => {
+			if ( ! shareWithChildBlocks ) {
+				return false;
+			}
+
 			const { getBlockName, hasSelectedInnerBlock } =
 				select( blockEditorStore );
 			const { hasBlockSupport } = select( blocksStore );
+
 			return (
-				shareWithChildBlocks &&
 				hasBlockSupport(
 					getBlockName( clientId ),
 					'__experimentalExposeControlsToChildren',
 					false
-				) &&
-				hasSelectedInnerBlock( clientId )
+				) && hasSelectedInnerBlock( clientId )
 			);
 		},
 		[ shareWithChildBlocks, clientId ]