Merge branch 'trunk' into experiment/modules-and-import-maps-api-requ…

…ired-server-dependency-graph

docs/getting-started/fundamentals/README.md

@@ -0,0 +1,11 @@
+# Fundamentals of Block Development
+
+This section provides an introduction to the most important concepts in Block Development.
+
+In this section, you will learn:
+
+1. [**File structure of a block**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block) - The purpose of each one of the types of files available for a block, the relationships between them, and their role in the output of the block.
+1. [**`block.json`**](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json) - How a block is defined using its `block.json` metadata and some relevant properties of this file.
+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/registration-of-a-block) - How to set proper attributes to the block's markup wrapper.
+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-json.md

@@ -0,0 +1,115 @@
+# block.json
+
+The `block.json` file simplifies the processs of defining and registering a block by using the same block's definition in JSON format to register the block in both the server and the client.
+
+[![Open block.json diagram in excalidraw](https://developer.wordpress.org/files/2023/11/block-json.png)](https://excalidraw.com/#json=v1GrIkGsYGKv8P14irBy6,Yy0vl8q7DTTL2VsH5Ww27A "Open block.json diagram in excalidraw")
+
+<div class="callout callout-tip">
+Click <a href="https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd">here</a> to see a full block example and check <a href="https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-supports-6aa4dd/src/block.json">its <code>block.json</code></a>
+</div>
+
+Besides simplifying a block's registration, using a `block.json` has [several benefits](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file), including improved performance and development.
+
+At [**Metadata in block.json**](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) you can find a detailed explanation of all the properties you can set in a `block.json` for a block. With these properties you can define things such as:
+
+- Basic metadata of the block
+- Files for the block's behavior, style, or output
+- Data Storage in the Block
+- Setting UI panels for the block
+
+## Basic metadata of the block
+
+Through properties of the `block.json`, we can define how the block will be uniquely identified, how it can be found, and the info displayed for the block in the Block Editor. Some of these properties are:
+
+- `apiVersion`: the version of [the API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/) used by the block (current version is 2).
+- `name`:  a unique identifier for a block, including a namespace.
+- `title`:  a display title for a block.
+- `category`:  a block category for the block in the Inserter panel.
+- `icon`:  a [Dashicon](https://developer.wordpress.org/resource/dashicons) slug or a custom SVG icon.
+- `description`:  a short description visible in the block inspector.
+- `keywords`: to locate the block in the inserter.
+- `textdomain`: the plugin text-domain (important for things such as translations).
+
+## Files for the block's behavior, output, or style 
+
+The `editorScript` and `editorStyle` properties allow defining Javascript and CSS files to be enqueued and loaded **only in the editor**.
+
+The `script` and `style` properties allow the definition of Javascript and CSS files to be enqueued and loaded **in both the editor and the front end**.
+
+The `viewScript` property allow us to define the Javascript file or files to be enqueued and loaded **only in the front end**.
+
+All these properties (`editorScript`, `editorStyle`, `script` `style`,`viewScript`) accept as a value a path for the file, a handle registered with `wp_register_script` or `wp_register_style`, or an array with a mix of both. Paths values in `block.json` are prefixed with `file:`.
+
+The `render` property ([introduced on WordPress 6.1](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/)) sets the path of a `.php` template file that will render the markup returned to the front end. This only method will be used to return the markup for the block on request only if `$render_callback` function has not been passed to the `register_block_type` function.
+
+## Data Storage in the Block with `attributes`
+
+The [`attributes` property](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) allows a block to declare "variables" that store data or content for the block.
+
+_Example: Attributes as defined in block.json_
+```json
+"attributes": {
+	"fallbackCurrentYear": {
+		"type": "string"
+	},
+	"showStartingYear": {
+		"type": "boolean"
+	},
+	"startingYear": {
+		"type": "string"
+	}
+},
+```
+By default `attributes` are serialized and stored in the block's delimiter but this [can be configured](https://developer.wordpress.org/news/2023/09/understanding-block-attributes/).
+
+_Example: Atributes stored in the Markup representation of the block_
+```html
+<!-- wp:block-development-examples/copyright-date-block-09aac3 {"fallbackCurrentYear":"2023","showStartingYear":true,"startingYear":"2020"} -->
+<p class="wp-block-block-development-examples-copyright-date-block-09aac3">© 2020–2023</p>
+<!-- /wp:block-development-examples/copyright-date-block-09aac3 -->x
+```
+
+These attributes are passed to the React component `Edit`(to display in the Block Editor) and the `save` function (to return the markup saved to the DB) of the block, and to any server-side render definition for the block (see `render` prop above). 
+
+The `Edit` component receives exclusively the capability of updating the attributes via the `setAttributes` function.
+
+_See how the attributes are passed to the [`Edit` component](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/edit.js), [the `save` function](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/save.js) and [the `render.php`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php) in this [full block example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3) of the  code above_
+
+<div class="callout callout-info">
+Check the <a href="https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/"> <code>attributes</code> </a> reference page for full info about the Attributes API. 
+</div>
+
+[![Open Attributes diagram in excalidraw](https://developer.wordpress.org/files/2023/11/attributes.png)](https://excalidraw.com/#json=pSgCZy8q9GbH7r0oz2fL1,MFCLd6ddQHqi_UqNp5ZSgg "Open Attributes diagram in excalidraw")
+
+
+## Enable UI settings panels for the block with `supports`
+
+The `supports` property allows a block to declare support for certain features, enabling users to customize specific settings (like colors or margins) from the Settings Sidebar.
+
+_Example: Supports as defined in block.json_
+
+```json
+"supports": {
+	"color": {
+		"text": true,
+		"link": true,
+		"background": true
+	}
+}
+```
+
+The use of `supports` 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.
+
+_Example: Supports custom settings stored in the Markup representation of the block_
+
+```html
+<!-- wp:block-development-examples/block-supports-6aa4dd {"backgroundColor":"contrast","textColor":"accent-4"} -->
+<p class="wp-block-block-development-examples-block-supports-6aa4dd has-accent-4-color has-contrast-background-color has-text-color has-background">Hello World</p>
+<!-- /wp:block-development-examples/block-supports-6aa4dd -->
+```
+
+_See the [full block example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd) of the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-supports-6aa4dd/src/block.json)_
+
+<div class="callout callout-info">
+Check the <a href="https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/"> <code>supports</code> </a> reference page for full info about the Supports API. 
+</div>

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

@@ -0,0 +1,114 @@
+# The block wrapper
+
+Each block's markup is wrapped by a container HTML tag that needs to have the proper attributes to fully work in the Block Editor and to reflect the proper block's style settings when rendered in the Block Editor and the front end. As developers, we have full control over the block's markup, and WordPress provides the tools to add the attributes that need to exist on the wrapper to our block's markup.
+
+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
+</div>
+
+A block can have three sets of markup defined, each one of them with a specific target and purpose:
+
+- The one for the **Block Editor**, defined through a `edit` React component passed to `registerBlockType` when registering the block in the client. 
+- The one used to **save the block in the DB**, defined through a `save` function passed to `registerBlockType` when registering the block in the client. 
+    - This markup will be returned to the front end on request if no dynamic render has been defined for the block.
+- 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` or the `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 React component `edit` and the `save` function, 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
+
+The `useBlockProps()` hook available on the `@wordpress/block-editor` allows passing the required attributes for the Block Editor to the `edit` block's outer wrapper. 
+
+Among other things, the `useBlockProps()` hook takes care of including in this wrapper:
+- An `id` for the block's markup 
+- Some accesibility and `data-` attributes
+- Classes and inline styles reflecting custom settings, which include by default:
+    - The `wp-block` class 
+    - A class that contains the name of the block with its namespace
+
+For example, for the following piece of code of a block's registration in the client...
+
+```js
+const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
+
+registerBlockType( ..., {
+	edit: Edit
+} );
+```
+_(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/src/index.js) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda))_
+
+...the markup of the block in the Block Editor could look like this:
+```html
+<p 
+    tabindex="0" 
+    id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
+    role="document" 
+    aria-label="Block: Minimal Gutenberg Block ca6eda" 
+    data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe" 
+    data-type="block-development-examples/minimal-block-ca6eda" 
+    data-title="Minimal Gutenberg Block ca6eda" 
+    class="
+        block-editor-block-list__block 
+        wp-block 
+        is-selected 
+        wp-block-block-development-examples-minimal-block-ca6eda
+    "
+>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.
+
+
+## The Save component's markup
+
+When saving the markup in the DB, it’s important to add the block props returned by `useBlockProps.save()` to the wrapper element of your block. `useBlockProps.save()` ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API.
+
+For example, for the following piece of code of a block's registration in the client that defines the markup desired for the DB (and returned to the front end by default)...
+
+```js
+const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
+const save = () => <p { ...useBlockProps.save() }>Hello World - Frontend</p>;
+
+registerBlockType( ..., {
+	edit: Edit,
+	save,
+} );
+```
+
+_(see the [code above](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/src/index.js) in [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda))_
+
+
+...the markup of the block in the front end could look like this:
+```html
+<p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – Frontend</p>
+```
+
+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.
+
+```html
+<p class="
+    wp-block-block-development-examples-block-supports-6aa4dd 
+    has-accent-4-color 
+    has-contrast-background-color 
+    has-text-color 
+    has-background
+">Hello World</p>
+```
+
+_(check the [example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd) that generated the HTML above in the front end)_
+
+## The server-side render markup
+
+Any markup in the server-side render definition for the block can use the [`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) to generate the string of attributes required to reflect the block settings. function (see [example](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php#L31)). 
+
+```php
+<p <?php echo get_block_wrapper_attributes(); ?>>
+	<?php esc_html_e( 'Block with Dynamic Rendering – hello!!!', '01-block-dynamic' ); ?>
+</p>
+```

docs/getting-started/fundamentals-block-development/file-structure-of-a-block.md → docs/getting-started/fundamentals/file-structure-of-a-block.md

@@ -1,8 +1,8 @@
 # File structure of a block
 
-It is recommended to **register blocks within plugins** to ensure they stay available when a theme gets switched. With the `create-block` tool you can quickly scaffold the structure of the files required to create a plugin that registers a block. 
+It is recommended to **register blocks within plugins** to ensure they stay available when a theme gets switched. With the [`create-block` tool](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) you can quickly scaffold the structure of the files required to create a plugin that registers a block. 
 
-The files generated by this tool are a good reference of the files that can be involved in the definition and registration of a block.
+The files generated by `create-block` are a good reference of the files that can be involved in the definition and registration of a block.
 
 [![Open File Structure of a Block Diagram in excalidraw](https://developer.wordpress.org/files/2023/11/file-structure-block.png)](https://excalidraw.com/#json=YYpeR-kY1ZMhFKVZxGhMi,mVZewfwNAh_oL-7bj4gmdw "Open File Structure of a Block Diagram in excalidraw")
 
@@ -47,7 +47,7 @@ The `edit.js` commonly gets used to contain the React component that gets used i
 
 ### `save.js`
 
-The `save.js` is similar to the `edit.js` file in that it exports a single React component. This component generates the static HTML markup that gets saved to the Database. 
+The `save.js` exports the function that returns the static HTML markup that gets saved to the Database. 
 
 ### `style.(css|scss|sass)`