Merge branch 'trunk' into fixed-header-custom-scroll

.eslintrc.js

@@ -357,6 +357,26 @@ module.exports = {
 				'jsdoc/require-param': 'off',
 			},
 		},
+		{
+			files: [ 'packages/components/src/**' ],
+			excludedFiles: [ 'packages/components/src/utils/colors-values.js' ],
+			rules: {
+				'no-restricted-syntax': [
+					'error',
+					{
+						selector: 'Literal[value=/--wp-admin-theme-/]',
+						message:
+							'--wp-admin-theme-* variables do not support component theming. Use variables from the COLORS object in packages/components/src/utils/colors-values.js instead.',
+					},
+					{
+						selector:
+							'TemplateElement[value.cooked=/--wp-admin-theme-/]',
+						message:
+							'--wp-admin-theme-* variables do not support component theming. Use variables from the COLORS object in packages/components/src/utils/colors-values.js instead.',
+					},
+				],
+			},
+		},
 		{
 			files: [ 'packages/components/src/**' ],
 			excludedFiles: [ 'packages/components/src/**/@(test|stories)/**' ],

.github/CODEOWNERS

@@ -132,7 +132,7 @@
 /packages/report-flaky-tests                    @kevin940726
 
 # wp-env
-/packages/env                                   @noahtallen @ObliviousHarmony @t-hamano
+/packages/env                                   @ObliviousHarmony @t-hamano
 
 # PHP
 /lib                                            @spacedmonkey

bin/packages/build.js

@@ -1,3 +1,5 @@
+#!/usr/bin/env node
+
 /**
  * External dependencies
  */

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/contributors/documentation/README.md

@@ -4,7 +4,7 @@ A guide on how to get started contributing documentation to the Gutenberg projec
 
 ## Discussions
 
-The [Make WordPress Docs blog](https://make.wordpress.org/docs/) is the primary spot for the latest information around WordPress documentation: including announcements, product goals, meeting notes, meeting agendas, and more.
+The [Make WordPress Docs blog](https://make.wordpress.org/docs/) is the primary spot for the latest information around WordPress documentation, including announcements, product goals, meeting notes, meeting agendas, and more.
 
 Real-time discussions for documentation take place in the `#docs` channel in [Make WordPress Slack](https://make.wordpress.org/chat) (registration required). Weekly meetings for the Documentation team are on Tuesdays at 14:00UTC.
 
@@ -14,7 +14,7 @@ The Gutenberg project uses GitHub for managing code and tracking issues. The mai
 
 There are two major sets of documentation for the Gutenberg project:
 
-1. [User documentation](https://wordpress.org/documentation/article/wordpress-block-editor/) is information on how to use the Editor as an author publishing posts. For contributing to user docs, follow the docs blog, or ask in the #docs Slack channel, to understand the current priorities.
+1. [User documentation](https://wordpress.org/documentation/article/wordpress-block-editor/) is information on how to use the Editor as an author publishing posts. For contributing to user docs, follow the docs blog or ask in the #docs Slack channel to understand the current priorities.
 2. [Block editor handbook](https://developer.wordpress.org/block-editor/) is everything related to the Gutenberg project including: developing, extending, and—what you are reading right now—contributing specific to Gutenberg.
 
 The rest of this document covers contributing to the block editor handbook.
@@ -29,24 +29,24 @@ See [the Git Workflow](/docs/contributors/code/git-workflow.md) documentation fo
 
 ### Handbook structure
 
-The handbook is organized into four sections based on the functional types of documents. [The Documentation System](https://documentation.divio.com/) does a great job explaining the needs and functions of each type, but in short they are:
+The handbook is organized into four sections based on the functional types of documents. [The Documentation System](https://documentation.divio.com/) does a great job explaining the needs and functions of each type, but in short, they are:
 
 -   **Getting started tutorials** - full lessons that take learners step by step to complete an objective, for example the [create a block tutorial](/docs/getting-started/devenv/get-started-with-create-block.md).
--   **How to guides** - short lessons specific to completing a small specific task, for example [how to add a button to the block toolbar](/docs/how-to-guides/format-api.md).
+-   **How-to guides** - short lessons specific to completing a small specific task, for example [how to add a button to the block toolbar](/docs/how-to-guides/format-api.md).
 -   **Reference guides** - API documentation, purely functional descriptions,
 -   **Explanations** - longer documentation focused on learning, not a specific task.
 
 ### Templates
 
-A [how to guide template](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/contributors/documentation/how-to-guide-template.md) is available to provide a common structure to guides. If starting a new how to guide, copy the markdown from the template to get started.
+A [how-to guide template](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/contributors/documentation/how-to-guide-template.md) is available to provide a common structure to guides. If starting a new how-to guide, copy the markdown from the template to get started.
 
-The template is based on examples from The Good Docs Project, see their [template repository for additional examples](https://github.com/thegooddocsproject/templates) to help you create quality documentation.
+The template is based on examples from The Good Docs Project. See their [template repository](https://github.com/thegooddocsproject/templates) for additional examples to help you create quality documentation.
 
 ### Update a document
 
 To update an existing page:
 
-1. Check out the gutenberg repository.
+1. Check out the Gutenberg repository.
 2. Create a branch to work, for example `docs/update-contrib-guide`.
 3. Make the necessary changes to the existing document.
 4. Commit your changes.
@@ -57,16 +57,16 @@ To update an existing page:
 To add a new document requires a working JavaScript development environment to build the documentation, see the [JavaScript build setup documentation](/docs/how-to-guides/javascript/js-build-setup.md):
 
 1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs) folder, use lower-case, no spaces, if needed a dash separator, and `.md` extension.
-2. Add content, all documents require one and only H1 tag, using markdown notation.
-3. Add document entry to the [toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json) hierarchy, see existing entries for format.
+2. Add content using markdown notation. All documents require one and only `h1` tag.
+3. Add document entry to the [toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json) hierarchy. See existing entries for format.
 4. Run `npm run docs:build` to update `manifest.json`.
 5. Commit `manifest.json` with other files updated.
 
-If you forget to run, `npm run docs:build` your PR will fail the static analysis check, since the `manifest.json` file is an uncommitted local change that must be committed.
+If you forget to run, `npm run docs:build` your PR will fail the static analysis check since the `manifest.json` file is an uncommitted local change that must be committed.
 
 ### Documenting packages
 
-Package documentation is generated automatically by the documentation tool by pulling the contents of the README.md file located in the root of the package. Sometimes however, it is preferable to split the contents of the README out into smaller, easier to read portions.
+Package documentation is generated automatically by the documentation tool by pulling the contents of the README.md file located in the root of the package. Sometimes, however, it is preferable to split the contents of the README into smaller, easier-to-read portions.
 
 This can be accomplished by creating a `docs` directory in the package and adding `toc.json` file that contains references other markdown files also contained in the `docs` directory. The `toc.json` file should contain an array of pages to be added as sub-pages of the main README file. The formatting follows the [`manifest.json`](https://github.com/WordPress/gutenberg/blob/HEAD/docs/manifest.json) file that is generated automatically.
 
@@ -85,7 +85,7 @@ In order for these pages to be nested under the main package name, be sure to se
 
 ### Using links
 
-It's likely at some point you'll want to link to other internal documentation pages. It's worth emphasizing all documents can be browsed in different contexts:
+It's likely at some point, you'll want to link to other internal documentation pages. It's worth emphasizing all documents can be browsed in different contexts:
 
 -   Block editor handbook
 -   GitHub website
@@ -97,9 +97,9 @@ To create links that work in all contexts, you must use absolute path links with
 -   `/packages/*/README.md`
 -   `/packages/components/src/**/README.md`
 
-This way they will be properly handled in all three aforementioned contexts.
+This way, they will be properly handled in all three aforementioned contexts.
 
-Use the full directory and filename from the Gutenberg repository, not the published path; the Block Editor Handbook creates short URLs—you can see this in the tutorials section. Likewise, the `readme.md` portion is dropped in the handbook, but should be included in links.
+Use the full directory and filename from the Gutenberg repository, not the published path; the Block Editor Handbook creates short URLs—you can see this in the tutorials section. Likewise, the `readme.md` portion is dropped in the handbook but should be included in the links.
 
 An example, the link to this page is: `/docs/contributors/documentation/README.md`
 
@@ -128,15 +128,15 @@ Here is an example `codetabs` section:
     \{\% end \%\}
 ````
 
-The preferred format for code examples is JSX, this should be the default view. The example placed first in source will be shown as the default.
+The preferred format for code examples is JSX. This should be the default view. The example placed first in source will be shown as the default.
 
 **Note:** It is not required to include plain JavaScript code examples for every guide. The recommendation is to include plain code for beginner tutorials or short examples, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem are in JSX that requires a build process.
 
 ### Callout notices
 
 The Block Editor handbook supports the same [notice styles as other WordPress handbooks](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting). However, the shortcode implementation is not ideal with the different locations the block editor handbook documentation is published (npm, GitHub).
 
-The recommended way to implement in markdown is to use the raw HTML and`callout callout-LEVEL` classes. For example:
+The recommended way to implement in markdown is to use the raw HTML and `callout callout-LEVEL` classes. For example:
 
 ```html
 <div class="callout callout-info">This is an **info** callout.</div>
@@ -163,7 +163,7 @@ This is a **warning** callout.
 <div class="callout callout-warning">
 Note: In callout notices, links also need to be HTML `&lt;a href>&lt;/a>` notations. 
 The usual link transformation is not applied to links in callouts.
-For instance, to reach the Getting started > Create Block page the URL in GitHub is
+For instance, to reach the Getting started > Create Block page, the URL in GitHub is
 https://developer.wordpress.org/docs/getting-started/devenv/get-started-with-create-block.md
 and will have to be hardcoded for the endpoint in the Block Editor Handbook as 
 <a href="https://developer.wordpress.org/block-editor/getting-started/create-block/">https://developer.wordpress.org/block-editor/getting-started/create-block/</a> to link correctly in the handbook. 
@@ -181,12 +181,32 @@ An example config for using Visual Studio Code and the Prettier extensions:
 },
 ```
 
- <div class="callout callout-info">
- Note: depending on where you are viewing this document, the brackets may show as double, the proper format is just a single bracket.
+<div class="callout callout-info">
+Depending on where you are viewing this document, the brackets may show as double. The proper format is just a single bracket.
+</div>
+
+### Video embeds
+
+Videos in the Block Editor Handbook need to be hosted on the [WordPress YouTube channel](https://www.youtube.com/@WordPress) as unlisted videos. This process requires additional permissions. Reach out in the #marketing Slack channel for assistance.
+
+Once the video has been uploaded to YouTube, retrieve the video embed link. It should look something like this: 
+
+```
+https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog
+```
+
+Then, place the following code where you want the video to be embedded in the documentation. Update the embed link and video title accordingly.
+
+```html
+<iframe width="960" height="540" src="[Video embed link]" title="[Video title]" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="true"></iframe>
+```
+
+<div class="callout callout-info">
+Videos should have an aspect ratio of <code>16:9</code> and be filmed at the highest resolution possible.
 </div>
 
 ## Resources
 
--   [Copy Guidelines](/docs/contributors/documentation/copy-guide.md) for writing instructions, documentations, or other contributions to Gutenberg project.
+-   [Copy Guidelines](/docs/contributors/documentation/copy-guide.md) for writing instructions, documentation, or other contributions to the Gutenberg project.
 
 -   [Tone and Voice Guide](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/) from WordPress Documentation.

docs/getting-started/fundamentals/block-in-the-editor.md

@@ -3,6 +3,7 @@
 The Block Editor is a React Single Page Application (SPA) and every block in the editor is displayed through a React component defined in the `edit` property of the settings object used to [register the block on the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side). 
 
 The `props` object received by the block's `Edit` React component includes:
+
 - [`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes) - attributes object
 - [`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes) - method to update the attributes object
 - [`isSelected`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#isselected) - boolean that communicates whether the block is currently selected
@@ -14,18 +15,21 @@ The WordPress Gutenberg project uses <a href="https://wordpress.github.io/gutenb
 </div>
 
 Custom settings controls for the block in the Block Toolbar or the Settings Sidebar can also be defined through this `Edit` React component via built-in components such as:
+
 - [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md) 
 - [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls) 
 
 ## Built-in components
 
 The package [`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) includes a library of generic WordPress components to create common UI elements for the Block Editor and the WordPress dashboard. Some of the  most commonly used components from this package are:
+
 - [`TextControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-textcontrol--docs) 
 - [`Panel`](https://wordpress.github.io/gutenberg/?path=/docs/components-panel--docs)
 - [`ToggleControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-togglecontrol--docs)
 - [`ExternalLink`](https://wordpress.github.io/gutenberg/?path=/docs/components-externallink--docs)
 
 The package [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) includes a library of components and hooks for the Block Editor, including those to define custom settings controls for the block in the Editor. Some of the components most commonly used from this package are:
+
 - [`RichText`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md)
 - [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)
 - [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
@@ -37,13 +41,12 @@ The package <a href="https://developer.wordpress.org/block-editor/reference-guid
 </div>
 
 A good workflow when using a component for the Block Editor is:
+
 - Import the component from a WordPress package
 - Add the corresponding code for the component to your project in JSX format
 - Most built-in components will be used to set [block attributes](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#using-attributes-to-store-block-data), so define any necessary attributes in `block.json` and create event handlers to update those attributes with `setAttributes` in your component
 - If needed, adapt the code to be serialized and stored in the database
 
-
-
 ## Block Controls: Block Toolbar and Settings Sidebar
 
 To simplify block customization and ensure a consistent experience for users, there are a number of built-in UI patterns to help generate the editor preview. 
@@ -95,7 +98,6 @@ _See the [full block example](https://github.com/WordPress/block-development-exa
 
 Note that `BlockControls` is only visible when the block is currently selected and in visual editing mode. `BlockControls` are not shown when editing a block in HTML editing mode.
 
-
 ### Settings Sidebar
 
 The Settings Sidebar is used to display less-often-used settings or settings that require more screen space. The Settings Sidebar should be used for **block-level settings only**.