Merge remote-tracking branch 'origin/trunk' into update/node-to-18-x

docs/getting-started/fundamentals/README.md

@@ -9,4 +9,5 @@ In this section, you will learn:
 1. [**Registration of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block) - How a block is registered in both the server and the client.
 1. [**Block wrapper**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper) - How to set proper attributes to the block's markup wrapper.
 1. [**The block in the Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-in-the-editor) - The block as a React component loaded in the Block Editor and its possibilities.
+1. [**Markup representation of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block) - How blocks are represented in the DB or in templates.
 1. [**Javascript in the Block Editor**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor) - How to work with Javascript for the Block Editor.

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

@@ -5,7 +5,7 @@ Each block's markup is wrapped by a container HTML tag that needs to have the pr
 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
+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:
@@ -16,7 +16,7 @@ A block can have three sets of markup defined, each one of them with a specific
 - 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.
 
-For the [`edit` React component and the `save` function](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/), the block wrapper element should be a native DOM element (like `<div>`) or a React component that forwards any additional props to native DOM elements. Using a <Fragment> or <ServerSideRender> component, for instance, would be invalid.
+For the [`edit` React component and the `save` function](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/), the block wrapper element should be a native DOM element (like `<div>`) or a React component that forwards any additional props to native DOM elements. Using a `<Fragment>` or `<ServerSideRender>` component, for instance, would be invalid.
 
 
 ## The Edit component's markup
@@ -60,7 +60,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
 >Hello World - Block Editor</p>
 ```
 
-Any additional classes and attributes for the `Edit` component of the block should be passed as an argument of `useBlockProps` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/edit.js)). When you add `support` for any feature, they get added to the object returned by the `useBlockProps` hook.
+Any additional classes and attributes for the `Edit` component of the block should be passed as an argument of `useBlockProps` (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/edit.js)). When you add `supports` for any feature, they get added to the object returned by the `useBlockProps` hook.
 
 
 ## The Save component's markup
@@ -89,7 +89,7 @@ _(see the [code above](https://github.com/WordPress/block-development-examples/b
 
 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 `support` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.
+When you add `supports` for any feature, the proper classes get added to the object returned by the `useBlockProps.save()` hook.
 
 ```html
 <p class="

docs/getting-started/fundamentals/markup-representation-block.md

@@ -0,0 +1,44 @@
+# Markup representation of a block
+
+When stored, in the database (DB) or in templates as HTML files, blocks are represented using a [specific HTML grammar](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes), which is technically valid HTML based on HTML comments that act as explicit block delimiters 
+
+These are some of the rules for the markup used to represent a block:
+- All core block comments start with a prefix and the block name: `wp:blockname`
+- For custom blocks, `blockname` is `namespace/blockname`
+- The comment can be a single line, self-closing, or wrapper for HTML content.
+- Custom block settings and attributes are stored as a JSON object inside the block comment.
+
+_Example: Markup representation of an `image` core block_
+
+```
+<!-- wp:image -->
+<figure class="wp-block-image"><img src="source.jpg" alt="" /></figure>
+<!-- /wp:image -->
+```
+
+The [markup representation of a block is parsed for the Block Editor](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/) and the block's output for the front end:
+- In the editor, WordPress parses this block markup, captures its data and loads its `edit` version
+- In the front end, WordPress parses this block markup, captures its data and generates its final HTML markup
+
+Whenever a block is saved, the `save` function, defined when the [block is registered in the client](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side), is called to return the markup that will be saved into the database within the block delimiter's comment. If `save` is `null` (common case for blocks with dynamic rendering), only a single line block delimiter's comment is stored, along with any attributes
+
+The Post Editor checks that the markup created by the `save` function is identical to the block's markup saved to the database:
+- If there are any differences, the Post Editor trigger a **block validation error**.
+- Block validation errors usually happen when a block’s `save` function is updated to change the markup produced by the block.
+- A block developer can mitigate these issues by adding a [**block deprecation**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) to register the change in the block.
+
+The markup of a **block with dynamic rendering** is expected to change so the markup of these blocks is not saved to the database. What is saved in the DB as representation of the block, for blocks with dynamic rendering, is a single line of HTML consisting on just the block delimiter's comment (including block attributes values). That HTML is not subject to the Post Editor’s validation.
+
+_Example: Markup representation of a block with dynamic rendering (`save` = `null`) and attributes_
+
+
+```html
+<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->
+```
+
+## Additional Resources
+
+- [Data Flow and Data Format](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/)
+- [Static vs. dynamic blocks: What’s the difference?](https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/)
+- [Block deprecation – a tutorial](https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/)
+- [Introduction to Templates > Block markup](https://developer.wordpress.org/themes/templates/introduction-to-templates/#block-markup) | Theme Handbook 

docs/manifest.json

@@ -89,6 +89,12 @@
  "markdown_source": "../docs/getting-started/fundamentals/block-in-the-editor.md",
  "parent": "fundamentals"
  },
+ {
+ "title": "Markup representation of a block",
+ "slug": "markup-representation-block",
+ "markdown_source": "../docs/getting-started/fundamentals/markup-representation-block.md",
+ "parent": "fundamentals"
+ },
  {
  "title": "Working with Javascript for the Block Editor",
  "slug": "javascript-in-the-block-editor",

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

@@ -116,7 +116,7 @@ wp.hooks.addFilter(
 );
 ```
 
-#### `blocks.getSaveContent.extraProps`
+### `blocks.getSaveContent.extraProps`
 
 A filter that applies to all blocks returning a WP Element in the `save` function. This filter is used to add extra props to the root element of the `save` function. For example: to add a className, an id, or any valid prop for this element.
 
@@ -229,7 +229,7 @@ const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
 }, 'withMyPluginControls' );
 ```
 
-#### `editor.BlockListBlock`
+### `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.
 

docs/toc.json

@@ -39,6 +39,9 @@
  {
  "docs/getting-started/fundamentals/block-in-the-editor.md": []
  },
+ {
+ "docs/getting-started/fundamentals/markup-representation-block.md": []
+ },
  {
  "docs/getting-started/fundamentals/javascript-in-the-block-editor.md": []
  }

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.3
  * Requires PHP: 7.0
- * Version: 17.3.0-rc.1
+ * Version: 17.3.0
  * Author: Gutenberg Team
  * Text Domain: gutenberg
  *

lib/class-wp-theme-json-resolver-gutenberg.php

@@ -322,9 +322,6 @@ public static function get_theme_data( $deprecated = array(), $options = array()
  }
  $theme_support_data['settings']['color']['defaultGradients'] = $default_gradients;
 
- // Classic themes without a theme.json don't support global duotone.
- $theme_support_data['settings']['color']['defaultDuotone'] = false;
-
  // Allow themes to enable all border settings via theme_support.
  if ( current_theme_supports( 'border' ) ) {
  $theme_support_data['settings']['border']['color'] = true;

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

@@ -31,3 +31,49 @@ function gutenberg_register_media_pattern_categories() {
  );
 }
 add_action( 'init', 'gutenberg_register_media_pattern_categories' );
+
+/**
+ * Adds a new taxonomy for organizing user created patterns.
+ *
+ * @see https://github.com/WordPress/gutenberg/pull/53163
+ *
+ * @return void
+ */
+function gutenberg_register_taxonomy_patterns() {
+ $args = array(
+ 'public' => false,
+ 'publicly_queryable' => false,
+ 'hierarchical' => false,
+ 'labels' => array(
+ 'name' => _x( 'Pattern Categories', 'taxonomy general name' ),
+ 'singular_name' => _x( 'Pattern Category', 'taxonomy singular name' ),
+ 'add_new_item' => __( 'Add New Category' ),
+ 'add_or_remove_items' => __( 'Add or remove pattern categories' ),
+ 'back_to_items' => __( '← Go to pattern categories' ),
+ 'choose_from_most_used' => __( 'Choose from the most used pattern categories' ),
+ 'edit_item' => __( 'Edit Pattern Category' ),
+ 'item_link' => __( 'Pattern Category Link' ),
+ 'item_link_description' => __( 'A link to a pattern category.' ),
+ 'items_list' => __( 'Pattern Categories list' ),
+ 'items_list_navigation' => __( 'Pattern Categories list navigation' ),
+ 'new_item_name' => __( 'New Pattern Category Name' ),
+ 'no_terms' => __( 'No pattern categories' ),
+ 'not_found' => __( 'No pattern categories found.' ),
+ 'popular_items' => __( 'Popular Pattern Categories' ),
+ 'search_items' => __( 'Search Pattern Categories' ),
+ 'separate_items_with_commas' => __( 'Separate pattern categories with commas' ),
+ 'update_item' => __( 'Update Pattern Category' ),
+ 'view_item' => __( 'View Pattern Category' ),
+ ),
+ 'query_var' => false,
+ 'rewrite' => false,
+ 'show_ui' => true,
+ '_builtin' => true,
+ 'show_in_nav_menus' => false,
+ 'show_in_rest' => true,
+ 'show_admin_column' => true,
+ 'show_tagcloud' => false,
+ );
+ register_taxonomy( 'wp_pattern_category', array( 'wp_block' ), $args );
+}
+add_action( 'init', 'gutenberg_register_taxonomy_patterns' );