Merge branch 'trunk' into 55224/block-editor/block-patterns-list

WordPress · Nov 22, 2023 · 8fa80a5 · 8fa80a5
2 parents 5b27fa6 + c5ac490
commit 8fa80a5
Show file tree

Hide file tree

Showing 387 changed files with 3,567 additions and 2,938 deletions.
diff --git a/changelog.txt b/changelog.txt
diff --git a/docs/README.md b/docs/README.md
@@ -59,7 +59,7 @@ This handbook should be considered the canonical resource for all things related
 - [**Learn WordPress**](https://learn.wordpress.org/) - The WordPress hub for learning resources where you can find courses like [Introduction to Block Development: Build your first custom block](https://learn.wordpress.org/course/introduction-to-block-development-build-your-first-custom-block/), [Converting a Shortcode to a Block](https://learn.wordpress.org/course/converting-a-shortcode-to-a-block/) or [Using the WordPress Data Layer](https://learn.wordpress.org/course/using-the-wordpress-data-layer/)
 - [**WordPress.tv**](https://wordpress.tv/) - A hub of WordPress-related videos (from talks at WordCamps to recordings of online workshops) curated and moderated by the WordPress.org community. You’re sure to find something to aid your learning about [block development](https://wordpress.tv/?s=block%20development&sort=newest) or the [block-editor](https://wordpress.tv/?s=block%20editor&sort=relevance) here.
 - [**Gutenberg repository**](https://github.com/WordPress/gutenberg/) - Development of the block editor project is carried out in this GitHub repository. It contains the code of interesting packages such as [`block-library`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src) (core blocks) or [`components`](https://github.com/WordPress/gutenberg/tree/trunk/packages/components) (common UI elements). _The [gutenberg-examples](https://github.com/WordPress/gutenberg-examples) repository is another useful reference._
-
+- [**End User Documentation**](https://wordpress.org/documentation/) - Documentation site targeted to the end user (not developers) where you can also find documentation about the [Block Editor](https://wordpress.org/documentation/category/block-editor/) and [working with blocks](https://wordpress.org/documentation/article/work-with-blocks/).
 
 ## Are you in the right place?
 
@@ -70,4 +70,4 @@ This handbook should be considered the canonical resource for all things related
 - [/apis](https://developer.wordpress.org/apis) - Common APIs Handbook
 - [/advanced-administration](https://developer.wordpress.org/advanced-administration) - WP Advanced Administration Handbook
 - [/rest-api](https://developer.wordpress.org/rest-api/) - REST API Handbook
-- [/coding-standards](https://developer.wordpress.org/coding-standards) - Best practices for WordPress developers
+- [/coding-standards](https://developer.wordpress.org/coding-standards) - Best practices for WordPress developers
diff --git a/docs/contributors/versions-in-wordpress.md b/docs/contributors/versions-in-wordpress.md
@@ -6,6 +6,7 @@ If anything looks incorrect here, please bring it up in #core-editor in [WordPre
 
 | Gutenberg Versions | WordPress Version |
 | ------------------ | ----------------- |
+| 16.2-16.7          | 6.4.1             |
 | 16.2-16.7          | 6.4               |
 | 15.2-16.1          | 6.3.1             |
 | 15.2-16.1          | 6.3               |

diff --git a/docs/getting-started/devenv/get-started-with-wp-scripts.md b/docs/getting-started/devenv/get-started-with-wp-scripts.md
@@ -20,7 +20,7 @@ The package abstracts away much of the initial setup, configuration, and boilerp
 ## Quick start
 
 <div class="callout callout-tip">
-    If you want to build a custom block, the <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/"><code>@wordpress/create-block</code></a> package allows you 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 <code>wp-scripts</code>) with no configuration required. Refer to <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/">Get started with <code>create-block</code></a> for more details.
+    If you use <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/"><code>@wordpress/create-block</code></a> package to scaffold the structure of files needed to create and register a block, you'll also get a modern JavaScript build setup (using <code>wp-scripts</code>) with no configuration required, so you don't need to worry about installing <code>wp-scripts</code> or enqueuing assets. Refer to <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/">Get started with <code>create-block</code></a> for more details.
 </div>
 
 ### Installation
@@ -64,15 +64,25 @@ Once installed, you can run the predefined scripts provided with `wp-scripts` by
 }
 ```
 
-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. See the [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for all options.
+These scripts can then be run using the command `npm run {script name}`. 
+
+### The build process with `wp-scripts`
+
+The two scripts you will use most often are `start` and `build` since they handle the build step. See the [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for all options.
 
 When working on your project, use the `npm run start` command. This will start a development server and automatically rebuild the project whenever any change is detected. Note that the compiled code in `build/index.js` will not be optimized.
 
 When you are ready to deploy your project, use the `npm run build` command. This optimizes your code and makes it production-ready.
 
-After the build finishes, you will see the compiled JavaScript file created at `build/index.js`. A `build/index.asset.php` file will also be created, which contains an array of dependencies and a version number (for cache busting). 
+After the build finishes, you will see the compiled JavaScript file created at `build/index.js`. 
+
+A `build/index.asset.php` file will also be created in the build process, which contains an array of dependencies and a version number (for cache busting). Please, note that to register a block without this `wp-scripts` build process you'll need to manually create `*.asset.php` dependencies files (see [example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-no-build-e621a6)).
 
-Enqueue the file in the Editor using PHP as you would any other JavaScript file. You can refer to the [Enqueueing assets in the Editor](https://developer.wordpress.org/block-editor/how-to-guides/enqueueing-assets-in-the-editor/) guide for more information, but here's a typical implementation. 
+### Enqueuing assets
+
+If you register a block via `register_block_type` the scripts defined in `block.json` will be automatically enqueued (see [example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda))
+
+To manually enqueue files in the editor, in any other context, you can refer to the [Enqueueing assets in the Editor](https://developer.wordpress.org/block-editor/how-to-guides/enqueueing-assets-in-the-editor/) guide for more information, but here's a typical implementation. 
 
 ```php
 /**
@@ -91,6 +101,8 @@ function example_project_enqueue_editor_assets() {
 add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );
 ```
 
+Here's [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8) of manually enqueuing files in the editor.
+
 ## Next steps
 
 While `start` and `build` will be the two most used scripts, several other useful tools come with `wp-scripts` that are worth exploring. Here's a look at a few.

diff --git a/docs/getting-started/quick-start-guide.md b/docs/getting-started/quick-start-guide.md
@@ -16,7 +16,7 @@ Next, use the [`@wordpress/create-block`](https://developer.wordpress.org/block-
 Choose the folder where you want to create the plugin, and then execute the following command in the terminal from within that folder:
 
 ```sh
-npx @wordpress/create-block copyright-date-block --template create-block-tutorial-template
+npx @wordpress/create-block copyright-date-block --template @wordpress/create-block-tutorial-template
 ```
 
 The `slug` provided (`copyright-date-block`) defines the folder name for the scaffolded plugin and the internal block name.
@@ -41,4 +41,4 @@ When you are finished making changes, run the `npm run build` command. This opti
 
 - [Get started with create-block](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/)
 - [Get started with wp-scripts](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/)
-- [Get started with wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
+- [Get started with wp-env](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)
diff --git a/docs/how-to-guides/block-tutorial/README.md b/docs/how-to-guides/block-tutorial/README.md
@@ -2,9 +2,9 @@
 
 The purpose of this tutorial is to step through the fundamentals of creating a new block type. Beginning with the simplest possible example, each new section will incrementally build upon the last to include more of the common functionality you could expect to need when implementing your own block types.
 
-To follow along with this tutorial, you can download the [accompanying WordPress plugin](https://github.com/WordPress/gutenberg-examples) which includes all of the examples for you to try on your own site. At each step along the way, experiment by modifying the examples with your own ideas, and observe the effects they have on the block's behavior.
+To follow along with this tutorial, you can download the [accompanying WordPress plugin](https://github.com/WordPress/block-development-examples) which includes all of the examples for you to try on your own site. At each step along the way, experiment by modifying the examples with your own ideas, and observe the effects they have on the block's behavior.
 
-> To find the latest version of the .zip file go to the repo's [releases page](https://github.com/WordPress/gutenberg-examples/releases) and look in the latest release under 'Assets'.
+> To find the latest version of the .zip file go to the repo's [releases page](https://github.com/WordPress/block-development-examples/releases) and look in the latest release under 'Assets'.
 
 Code snippets are provided in two formats "JSX" and "Plain". JSX refers to JavaScript code that uses JSX syntax which requires a build step. Plain refers to "classic" JavaScript that does not require building. You can change between them using tabs found above each code example. Using JSX, does require you to run [the JavaScript build step](/docs/how-to-guides/javascript/js-build-setup/) to compile your code to a browser compatible format.
 

diff --git a/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md b/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md
@@ -18,9 +18,6 @@ The first method shows adding the style inline. This transforms the defined styl
 
 The `useBlockProps` React hook is used to set and apply properties on the block's wrapper element. The following example shows how:
 
-{% codetabs %}
-{% JSX %}
-
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
 import { useBlockProps } from '@wordpress/block-editor';
@@ -55,49 +52,6 @@ registerBlockType( 'gutenberg-examples/example-02-stylesheets', {
 } );
 ```
 
-{% Plain %}
-
-```js
-( function ( blocks, React, blockEditor ) {
-	var el = React.createElement;
-
-	blocks.registerBlockType( 'gutenberg-examples/example-02-stylesheets', {
-		edit: function ( props ) {
-			const greenBackground = {
-				backgroundColor: '#090',
-				color: '#fff',
-				padding: '20px',
-			};
-			const blockProps = blockEditor.useBlockProps( {
-				style: greenBackground,
-			} );
-			return el(
-				'p',
-				blockProps,
-				'Hello World (from the editor, in green).'
-			);
-		},
-		save: function () {
-			const redBackground = {
-				backgroundColor: '#090',
-				color: '#fff',
-				padding: '20px',
-			};
-			const blockProps = blockEditor.useBlockProps.save( {
-				style: redBackground,
-			} );
-			return el(
-				'p',
-				blockProps,
-				'Hello World (from the frontend, in red).'
-			);
-		},
-	} );
-} )( window.wp.blocks, window.React, window.wp.blockEditor );
-```
-
-{% end %}
-
 ## Method 2: Block classname
 
 The inline style works well for a small amount of CSS to apply. If you have much more than the above you will likely find that it is easier to manage with them in a separate stylesheet file.
@@ -106,9 +60,6 @@ The `useBlockProps` hooks includes the classname for the block automatically, it
 
 For example the block name: `gutenberg-examples/example-02-stylesheets` would get the classname: `wp-block-gutenberg-examples-example-02-stylesheets`. It might be a bit long but best to avoid conflicts with other blocks.
 
-{% codetabs %}
-{% JSX %}
-
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
 import { useBlockProps } from '@wordpress/block-editor';
@@ -131,66 +82,15 @@ registerBlockType( 'gutenberg-examples/example-02-stylesheets', {
 } );
 ```
 
-{% Plain %}
-
-```js
-( function ( blocks, React, blockEditor ) {
-	var el = React.createElement;
-
-	blocks.registerBlockType( 'gutenberg-examples/example-02-stylesheets', {
-		edit: function ( props ) {
-			var blockProps = blockEditor.useBlockProps();
-			return el(
-				'p',
-				blockProps,
-				'Hello World (from the editor, in green).'
-			);
-		},
-		save: function () {
-			var blockProps = blockEditor.useBlockProps.save();
-			return el(
-				'p',
-				blockProps,
-				'Hello World (from the frontend, in red).'
-			);
-		},
-	} );
-} )( window.wp.blocks, window.React, window.wp.blockEditor );
-```
-
-{% end %}
-
 ### Build or add dependency
 
 In order to include the blockEditor as a dependency, make sure to run the build step, or update the asset php file.
 
-{% codetabs %}
-{% JSX %}
-
 Build the scripts and update the asset file which is used to keep track of dependencies and the build version.
 ```bash
 npm run build
 ```
 
-{% Plain %}
-
-Edit the asset file to include the block-editor dependency for the scripts.
-
-```php
-<?php return
-	array( 'dependencies' =>
-		array(
-			'react',
-			'wp-blocks',
-			'wp-block-editor',
-			'wp-polyfill'
-		),
-		'version' => '0.1'
-	);
-```
-
-{% end %}
-
 ### Enqueue stylesheets
 
 Like scripts, you can enqueue your block's styles using the `block.json` file.
@@ -199,7 +99,7 @@ Use the `editorStyle` property to a CSS file you want to load in the editor view
 
 It is worth noting that, if the editor content is iframed, both of these will
 load in the iframe. `editorStyle` will also load outside the iframe, so it can
-be used for editor content as well as UI. 
+be used for editor content as well as UI.
 
 For example:
 
@@ -249,4 +149,4 @@ The files will automatically be enqueued when specified in the block.json.
 
 This guide showed a couple of different ways to apply styles to your block, by either inline or in its own style sheet. Both of these methods use the `useBlockProps` hook, see the [block wrapper reference documentation](/docs/reference-guides/block-api/block-edit-save.md#block-wrapper-props) for additional details.
 
-See the complete [example-02-stylesheets](https://github.com/WordPress/gutenberg-examples/tree/trunk/blocks-non-jsx/02-stylesheets) code in the [gutenberg-examples repository](https://github.com/WordPress/gutenberg-examples).
+See the complete [stylesheets-79a4c3](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/stylesheets-79a4c3) code in the [block-development-examples repository](https://github.com/WordPress/block-development-examples).
diff --git a/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md b/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md
@@ -10,9 +10,6 @@ When the user selects a block, a number of control buttons may be shown in a too
 
 You can also customize the toolbar to include controls specific to your block type. If the return value of your block type's `edit` function includes a `BlockControls` element, those controls will be shown in the selected block's toolbar.
 
-{% codetabs %}
-{% JSX %}
-
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
 
@@ -92,95 +89,6 @@ registerBlockType( 'gutenberg-examples/example-04-controls-esnext', {
 } );
 ```
 
-{% Plain %}
-
-```js
-( function ( blocks, blockEditor, React ) {
-	var el = React.createElement;
-	var RichText = blockEditor.RichText;
-	var AlignmentToolbar = blockEditor.AlignmentToolbar;
-	var BlockControls = blockEditor.BlockControls;
-	var useBlockProps = blockEditor.useBlockProps;
-
-	blocks.registerBlockType( 'gutenberg-examples/example-04-controls', {
-		title: 'Example: Controls',
-		icon: 'universal-access-alt',
-		category: 'design',
-
-		attributes: {
-			content: {
-				type: 'string',
-				source: 'html',
-				selector: 'p',
-			},
-			alignment: {
-				type: 'string',
-				default: 'none',
-			},
-		},
-		example: {
-			attributes: {
-				content: 'Hello World',
-				alignment: 'right',
-			},
-		},
-		edit: function ( props ) {
-			var content = props.attributes.content;
-			var alignment = props.attributes.alignment;
-
-			function onChangeContent( newContent ) {
-				props.setAttributes( { content: newContent } );
-			}
-
-			function onChangeAlignment( newAlignment ) {
-				props.setAttributes( {
-					alignment:
-						newAlignment === undefined ? 'none' : newAlignment,
-				} );
-			}
-
-			return el(
-				'div',
-				useBlockProps(),
-				el(
-					BlockControls,
-					{ key: 'controls' },
-					el( AlignmentToolbar, {
-						value: alignment,
-						onChange: onChangeAlignment,
-					} )
-				),
-				el( RichText, {
-					key: 'richtext',
-					tagName: 'p',
-					style: { textAlign: alignment },
-					onChange: onChangeContent,
-					value: content,
-				} )
-			);
-		},
-
-		save: function ( props ) {
-			var blockProps = useBlockProps.save();
-
-			return el(
-				'div',
-				blockProps,
-				el( RichText.Content, {
-					tagName: 'p',
-					className:
-						'gutenberg-examples-align-' +
-						props.attributes.alignment,
-					value: props.attributes.content,
-				} )
-			);
-		},
-	} );
-} )( window.wp.blocks, window.wp.blockEditor, window.React );
-```
-
-{% end %}
-
 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