Merge branch 'trunk' into try/document-bar-for-style-book-and-revisions

.gitattributes

@@ -14,3 +14,6 @@
 
 # Directories with vendored code.
 packages/edit-site/lib/** linguist-vendored
+
+# The changelog.txt file is authored as markdown.
+changelog.txt linguist-language=Markdown

.prettierrc.js

@@ -1,3 +1,11 @@
 // Import the default config file and expose it in the project root.
 // Useful for editor integrations.
-module.exports = require( '@wordpress/prettier-config' );
+module.exports = {
+	...require( '@wordpress/prettier-config' ),
+	overrides: [
+		{
+			files: [ 'changelog.txt' ],
+			options: { parser: 'markdown' },
+		},
+	],
+};

backport-changelog/6.6/6841.md

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

backport-changelog/6.6/6854.md

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

backport-changelog/6.6/6864.md

@@ -0,0 +1,4 @@
+https://github.com/WordPress/wordpress-develop/pull/6864
+
+* https://github.com/WordPress/gutenberg/pull/62488
+* https://github.com/WordPress/gutenberg/pull/62696

backport-changelog/6.6/6873.md

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

bin/cherry-pick.mjs

@@ -6,6 +6,7 @@ import readline from 'readline';
 
 import { spawnSync } from 'node:child_process';
 
+const REPO = 'WordPress/gutenberg';
 const LABEL = process.argv[ 2 ] || 'Backport to WP Beta/RC';
 const BACKPORT_COMPLETED_LABEL = 'Backported to WP Core';
 const BRANCH = getCurrentBranch();
@@ -113,7 +114,7 @@ function cli( command, args, pipe = false ) {
  */
 async function fetchPRs() {
 	const { items } = await GitHubFetch(
-		`/search/issues?per_page=100&q=is:pr state:closed sort:updated label:"${ LABEL }" repo:WordPress/gutenberg`
+		`/search/issues?per_page=100&q=is:pr state:closed sort:updated label:"${ LABEL }" repo:${ REPO }`
 	);
 	const PRs = items
 		// eslint-disable-next-line camelcase
@@ -143,7 +144,7 @@ async function fetchPRs() {
 	const PRsWithMergeCommit = [];
 	for ( const PR of PRs ) {
 		const { merge_commit_sha: mergeCommitHash } = await GitHubFetch(
-			'/repos/WordPress/Gutenberg/pulls/' + PR.number
+			`/repos/${ REPO }/pulls/` + PR.number
 		);
 		PRsWithMergeCommit.push( {
 			...PR,
@@ -380,15 +381,17 @@ function reportSummaryNextSteps( successes, failures ) {
 function GHcommentAndRemoveLabel( pr ) {
 	const { number, cherryPickHash } = pr;
 	const comment = prComment( cherryPickHash );
+	const repo = [ '--repo', REPO ];
 	try {
-		cli( 'gh', [ 'pr', 'comment', number, '--body', comment ] );
-		cli( 'gh', [ 'pr', 'edit', number, '--remove-label', LABEL ] );
+		cli( 'gh', [ 'pr', 'comment', number, ...repo, '--body', comment ] );
+		cli( 'gh', [ 'pr', 'edit', number, ...repo, '--remove-label', LABEL ] );
 
 		if ( LABEL === 'Backport to WP Beta/RC' ) {
 			cli( 'gh', [
 				'pr',
 				'edit',
 				number,
+				...repo,
 				'--add-label',
 				BACKPORT_COMPLETED_LABEL,
 			] );
@@ -444,7 +447,7 @@ function reportFailure( { number, title, error, mergeCommitHash } ) {
  * @return {string} PR URL.
  */
 function prUrl( number ) {
-	return `https://github.com/WordPress/gutenberg/pull/${ number } `;
+	return `https://github.com/${ REPO }/pull/${ number } `;
 }
 
 /**

docs/contributors/code/coding-guidelines.md

@@ -758,7 +758,7 @@ When documenting an example, use the markdown <code>\`\`\`</code> code block to
 
 ### Documenting React components
 
-When possible, all components should be implemented as [function components](https://reactjs.org/docs/components-and-props.html#function-and-class-components), using [hooks](https://reactjs.org/docs/hooks-intro.html) for managing component lifecycle and state.
+When possible, all components should be implemented as [function components](https://reactjs.org/docs/components-and-props.html#function-and-class-components), using [hooks](https://react.dev/reference/react/hooks) for managing component lifecycle and state.
 
 Documenting a function component should be treated the same as any other function. The primary caveat in documenting a component is being aware that the function typically accepts only a single argument (the "props"), which may include many property members. Use the [dot syntax for parameter properties](https://jsdoc.app/tags-param.html#parameters-with-properties) to document individual prop types.
 

docs/getting-started/tutorial.md

@@ -33,7 +33,7 @@ If you don't have one or more of these items, the [Block Development Environment
 The first step in creating the Copyright Date Block is to scaffold the initial block structure using the [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) package.
 
 <div class="callout callout-info">
-	Review the <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/">Get started with create-block</a> documentation for an introduction to using this package.
+	Review the <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/">Get started with create-block</a> documentation for an introduction to using this package.
 </div>
 
 You can use `create-block` from just about any directory (folder) on your computer and then use `wp-env` to create a local WordPress development environment with your new block plugin installed and activated.

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

@@ -12,9 +12,14 @@ By registering your own block variation with some specific Query Loop block sett
 
 With the block variations API you can provide the default settings that make the most sense for your use-case.
 
+In order to have a Query Loop variation properly working, we'll need to:
+- Register the block variation for the `core/query` block with some default values
+- Define a layout for the block variation
+- Use the `namespace` attribute in the `isActive` block variation property
+
 Let's go on a journey, for example, of setting up a variation for a plugin which registers a `book` [custom post type](https://developer.wordpress.org/plugins/post-types/).
 
-### Offer sensible defaults
+### 1. Offer sensible defaults
 
 Your first step would be to create a variation which will be set up in such a way to provide a block variation which will display by default a list of books instead of blog posts. The full variation code will look something like this:
 
@@ -91,7 +96,9 @@ In this way, your block will show up just like any other block while the user is
 
 At this point, your custom variation will be virtually indistinguishable from a stand-alone block. Completely branded to your plugin, easy to discover and directly available to the user as a drop in.
 
-### Customize your variation layout
+However, your query loop variation won't work just yet — we still need to define a layout so that it can render properly.
+
+### 2. Customize your variation layout
 
 Please note that the Query Loop block supports `'block'` as a string in the `scope` property. In theory, that's to allow the variation to be picked up after inserting the block itself. Read more about the Block Variation Picker [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md).
 
@@ -125,7 +132,7 @@ In order for a variation to be connected to another Query Loop variation we need
 
 For example, if we have a Query Loop variation exposed to the inserter(`scope: ['inserter']`) with the name `products`, we can connect a scoped `block` variation by setting its `namespace` attribute to `['products']`. If the user selects this variation after having clicked `Start blank`, the namespace attribute will be overridden by the main inserter variation.
 
-### Making Gutenberg recognize your variation
+### 3. Making Gutenberg recognize your variation
 
 There is one slight problem you might have realized after implementing this variation: while it is transparent to the user as they are inserting it, Gutenberg will still recognize the variation as a Query Loop block at its core and so, after its insertion, it will show up as a Query Loop block in the tree view of the editor, for instance.
 

docs/reference-guides/core-blocks.md

@@ -902,7 +902,7 @@ Summarize your post with a list of headings. Add HTML anchors to Heading blocks
 
 -	**Name:** core/table-of-contents
 -	**Experimental:** true
--	**Category:** layout
+-	**Category:** design
 -	**Supports:** color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
 -	**Attributes:** headings, onlyIncludeCurrentPage
 

docs/reference-guides/interactivity-api/api-reference.md

@@ -73,8 +73,9 @@ The `wp-interactive` directive "activates" the interactivity for the DOM element
 </div>
 ```
 
-> **Note**
-> The use of `data-wp-interactive` is a requirement for the Interactivity API "engine" to work. In the following examples the `data-wp-interactive` has not been added for the sake of simplicity. Also, the `data-wp-interactive` directive will be injected automatically in the future.
+<div class="callout callout-info">
+  The use of <code>data-wp-interactive</code> is a requirement for the Interactivity API "engine" to work. In the following examples the <code>data-wp-interactive</code> has not been added for the sake of simplicity. Also, the <code>data-wp-interactive</code> directive will be injected automatically in the future.
+</div>
 
 ### `wp-context`
 
@@ -299,6 +300,10 @@ The returned value is used to change the inner content of the element: `<div>val
 
 ### `wp-on`
 
+<div class="callout callout-info">
+  Consider using the more performant <a href="#wp-on-async"><code>wp-on-async</code></a> instead if your directive code does not need synchronous access to the event object. If synchronous access is required, consider implementing an <a href="#async-actions"><code>async action</code></a> which yields to the main thread after calling the synchronous API.
+</div>
+
 This directive runs code on dispatched DOM events like `click` or `keyup`. The syntax is `data-wp-on--[event]` (like `data-wp-on--click` or `data-wp-on--keyup`).
 
 ```php
@@ -325,8 +330,17 @@ The `wp-on` directive is executed each time the associated event is triggered.
 
 The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored.
 
+### `wp-on-async`
+
+This directive is a more performant approach for `wp-on`. It immediately yields to main to avoid contributing to a long task, allowing other interactions that otherwise would be waiting on the main thread
+to run sooner. Use this async version whenever there is no need for synchronous access to the `event` object, in particular the methods `event.preventDefault()`, `event.stopPropagation()`, and `event.stopImmediatePropagation()`.
+
 ### `wp-on-window`
 
+<div class="callout callout-info">
+  Consider using the more performant <a href="#wp-on-async-window"><code>wp-on-async-window</code></a> instead if your directive code does not need synchronous access to the event object. If synchronous access is required, consider implementing an <a href="#async-actions"><code>async action</code></a> which yields to the main thread after calling the synchronous API.
+</div>
+
 This directive allows you to attach global window events like `resize`, `copy`, and `focus` and then execute a defined callback when those happen.
 
 [List of supported window events.](https://developer.mozilla.org/en-US/docs/Web/API/Window#events)
@@ -354,8 +368,16 @@ store( "myPlugin", {
 
 The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.
 
+### `wp-on-async-window`
+
+Similar to `wp-on-async`, this is an optimized version of `wp-on-window` that immediately yields to main to avoid contributing to a long task. Use this async version whenever there is no need for synchronous access to the `event` object, in particular the methods `event.preventDefault()`, `event.stopPropagation()`, and `event.stopImmediatePropagation()`. This event listener is also added as [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive).
+
 ### `wp-on-document`
 
+<div class="callout callout-info">
+  Consider using the more performant <a href="#wp-on-async-document"><code>wp-on-async-document</code></a> instead if your directive code does not need synchronous access to the event object. If synchronous access is required, consider implementing an <a href="#async-actions"><code>async action</code></a> which yields to the main thread after calling the synchronous API.
+</div>
+
 This directive allows you to attach global document events like `scroll`, `mousemove`, and `keydown` and then execute a defined callback when those happen.
 
 [List of supported document events.](https://developer.mozilla.org/en-US/docs/Web/API/Document#events)
@@ -383,6 +405,10 @@ store( "myPlugin", {
 
 The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.
 
+### `wp-on-async-document`
+
+Similar to `wp-on-async`, this is an optimized version of `wp-on-document` that immediately yields to main to avoid contributing to a long task. Use this async version whenever there is no need for synchronous access to the `event` object, in particular the methods `event.preventDefault()`, `event.stopPropagation()`, and `event.stopImmediatePropagation()`. This event listener is also added as [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive).
+
 ### `wp-watch`
 
 It runs a callback **when the node is created and runs it again when the state or context changes**.
@@ -737,7 +763,7 @@ const { state, actions } = store("myPlugin", {
 });
 ```
 
-##### Async actions
+<h5 id="async-actions">Async actions</h5>
 
 Async actions should use generators instead of async/await.
 
@@ -772,7 +798,7 @@ We need to be able to know when async actions start awaiting and resume operatio
 
 The store will work fine if it is written like this:
 ```js
-store("myPlugin", {
+const { state } = store("myPlugin", {
   state: {
     get isOpen() {
       return getContext().isOpen;
@@ -788,6 +814,28 @@ store("myPlugin", {
 });
 ```
 
+As mentioned above with [`wp-on`](#wp-on), [`wp-on-window`](#wp-on-window), and [`wp-on-document`](#wp-on-document), an async action should be used whenever the `async` versions of the aforementioned directives cannot be used due to the action requiring synchronous access to the `event` object. Synchronous access is reqired whenever the action needs to call `event.preventDefault()`, `event.stopPropagation()`, or `event.stopImmediatePropagation()`. To ensure that the action code does not contribute to a long task, you may manually yield to the main thread after calling the synchronous event API. For example:
+
+```js
+// Note: In WordPress 6.6 this splitTask function is exported by @wordpress/interactivity.
+function splitTask() {
+  return new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+}
+
+store("myPlugin", {
+  actions: {
+    handleClick: function* (event) {
+      event.preventDefault();
+      yield splitTask();
+      doTheWork();
+    },
+  },
+});
+```
+
+You may want to add multiple such `yield` points in your action if it is doing a lot of work.
 
 #### Side Effects
 
@@ -845,9 +893,9 @@ const { state } = store( "myPlugin", {
   }
 } );
 ```
-
-> **Note**
-> All `store()` calls with the same namespace return the same references, i.e., the same `state`, `actions`, etc., containing the result of merging all the store parts passed.
+<div class="callout callout-info">
+  All <code>store()</code> calls with the same namespace return the same references, i.e., the same <code>state</code>, <code>actions</code>, etc., containing the result of merging all the store parts passed.
+</div>
 
 - To access the context inside an action, derived state, or side effect, you can use the `getContext` function.
 - To access the reference, you can use the `getElement` function.

gutenberg.php

@@ -5,7 +5,7 @@
  * Description: Printing since 1440. This is the development plugin for the block editor, site editor, and other future WordPress core functionality.
  * Requires at least: 6.4
  * Requires PHP: 7.2
- * Version: 18.6.0-rc.1
+ * Version: 18.6.0
  * Author: Gutenberg Team
  * Text Domain: gutenberg
  *