prep build 10/19

docs/getting-started/devenv/get-started-with-create-block.md

@@ -0,0 +1,95 @@
+# Get started with create-block
+
+Custom blocks for the Block Editor in WordPress are typically registered using plugins and are defined through a specific set of files. The [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) package is an officially supported tool 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 [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts.md)) with no configuration required. 
+
+The package is designed to help developers quickly set up a block development environment following WordPress best practices.
+
+## Quick Start
+
+### Installation
+
+Start by ensuring you have Node.js and `npm` installed on your computer. Review the [Node.js development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/) guide if not.
+
+You can use `create-block` to scaffold a block just about anywhere and then [use `wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/) from the inside of the generated plugin folder. This will create a local WordPress development environment with your new block plugin installed and activated.
+
+If you have your own [local WordPress development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment) already set up, navigate to the `plugins/` folder using the terminal.
+
+Run the following command to scaffold an example block plugin:
+
+```bash
+npx @wordpress/create-block@latest todo-list
+cd todo-list
+```
+
+The `slug` provided (`todo-list`) defines the folder name for the scaffolded plugin and the internal block name. 
+
+Navigate to the Plugins page of our local WordPress installation and activate the "Todo List" plugin. The example block will then be available in the Editor. 
+
+### Basic usage
+
+The `create-block` assumes you will use modern JavaScript (ESNext and JSX) to build your block. This requires a build step to compile the code into a format that browsers can understand. Luckily, the `wp-scripts` package handles this process for you. Refer to the [Get started with wp-scripts](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts) for an introduction to this package. 
+
+ When `create-block` scaffolds the block, it installs `wp-scripts` and adds the most common scripts to the block's `package.json` file. By default, those include:
+
+```json
+{
+    "scripts": {
+		"build": "wp-scripts build",
+		"format": "wp-scripts format",
+		"lint:css": "wp-scripts lint-style",
+		"lint:js": "wp-scripts lint-js",
+		"packages-update": "wp-scripts packages-update",
+		"plugin-zip": "wp-scripts plugin-zip",
+		"start": "wp-scripts start"
+	}
+}
+```
+
+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.
+
+When working on your block, use the `npm run start` command. This will start a development server and automatically rebuild the block whenever any code change is detected.
+
+When you are ready to deploy your block, use the `npm run build` command. This optimizes your code and makes it production-ready.
+
+See the `wp-scripts` [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for more details about each available script.
+
+## Alternate implementations
+
+### Interactive mode
+
+For developers who prefer a more guided experience, the `create-block package` provides an interactive mode. Instead of manually specifying all options upfront, like the `slug` in the above example, this mode will prompt you for inputs step-by-step.
+
+To use this mode, run the command:
+
+```bash
+npx @wordpress/create-block@latest
+```
+
+Follow the prompts to configure your block settings interactively.
+
+### Quick start mode using options
+
+If you're already familiar with the `create-block` [options](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#options) and want a more streamlined setup, you can use quick start mode. This allows you to pass specific options directly in the command line, eliminating the need for interactive prompts.
+
+For instance, to quickly create a block named "my-block" with a namespace of "my-plugin" that is a Dynamic block, use this command:
+
+```bash
+npx @wordpress/create-block@latest --namespace="my-plugin" --slug="my-block" --variant="dynamic"
+```
+
+### Using templates
+
+The `create-block` package also supports the use of templates, enabling you to create blocks based on predefined configurations and structures. This is especially useful when you have a preferred block structure or when you're building multiple blocks with similar configurations.
+
+To use a template, specify the `--template` option followed by the template name or path:
+```bash
+npx @wordpress/create-block --template="my-custom-template"
+```
+
+Templates must be set up in advance so the `create-block` package knows where to find them. Learn more in the `create-block` [documentation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#template), and review the [External Project Templates](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/) guide.
+
+## Additional resources
+
+- [Using the create-block tool](https://learn.wordpress.org/tutorial/using-the-create-block-tool/) (Learn WordPress tutorial)
+- [@wordpress/create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) (Official documentation)
+- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) (Official documentation)

docs/getting-started/devenv/get-started-with-wp-env.md

@@ -4,13 +4,15 @@ The [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) package (`wp-
 
 Before following this guide, install [Node.js development tools](/docs/getting-started/devenv#node-js-development-tools) if you have not already done so.
 
+![wp-env basics diagram](https://developer.wordpress.org/files/2023/10/wp-env-diagram.png)
+
 ## Quick start
 
 1. Download, install, and start [Docker Desktop](https://www.docker.com/products/docker-desktop) following the instructions for your operating system.
 2. Run `npm -g install @wordpress/env` in the terminal to install `wp-env` globally.
 3. In the terminal, navigate to an existing plugin directory, theme directory, or a new working directory.
 4. Run `wp-env start` in the terminal to start the local WordPress environment.
-5. After the script runs, navigate to `http://localhost:8888/wp-admin/` and log into the WordPress dashboard using username `admin` and password `password`.
+5. After the script runs, navigate to <code>http://localhost:8888/wp-admin</code> and log into the WordPress dashboard using username `admin` and password `password`.
 
 ## Set up Docker Desktop
 
@@ -42,7 +44,7 @@ Next, navigate to an existing plugin directory, theme directory, or a new workin
 wp-env start
 ```
 
-Once the script completes, you can access the local environment at: `http://localhost:8888`. Log into the WordPress dashboard using username `admin` and password `password`.
+Once the script completes, you can access the local environment at: <code>http://localhost:8888</code>. Log into the WordPress dashboard using username `admin` and password `password`.
 
 <div class="callout callout-tip">
     Some projects, like Gutenberg, include their own specific <code>wp-env</code> configurations, and the documentation might prompt you to run <code>npm run start wp-env</code> instead.
@@ -131,10 +133,11 @@ export DOCKER_HOST=tcp://127.0.0.1:2376
 wp-env start
 ```
 
-Your environment should now be set up at `http://localhost:8888/`.
+Your environment should now be set up at <code>http://localhost:8888</code>.
 
 ## Additional resources
 
--   [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) (Official documentation)
--   [Docker Desktop](https://docs.docker.com/desktop) (Official documentation)
--   [Quick and easy local WordPress development with wp-env](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/) (WordPress Developer Blog)
+- [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) (Official documentation)
+- [Docker Desktop](https://docs.docker.com/desktop) (Official documentation)
+- [Quick and easy local WordPress development with wp-env](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/) (WordPress Developer Blog)
+- [`wp-env` Basics diagram](https://excalidraw.com/#json=8Tp55B-R6Z6-pNGtmenU6,_DeBR1IBxuHNIKPTVEaseA) (Excalidraw)

docs/getting-started/devenv/get-started-with-wp-scripts.md

@@ -0,0 +1,138 @@
+# Get started with wp-scripts
+
+The [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) package, commonly referred to as `wp-scripts`, is a set of configuration files and scripts that primarily aims to standardize and simplify the development process of WordPress projects that require a JavaScript build step.
+
+A JavaScript build step refers to the process of transforming, bundling, and optimizing JavaScript source code and related assets into a format suitable for production environments. These build steps often take modern JavaScript (ESNext and JSX) and convert it to a version compatible with most browsers. They can also bundle multiple files into one, minify the code to reduce file size and perform various other tasks to optimize the code.
+
+You will typically be working with ESNext and JSX when building for the Block Editor, and most examples in the Block Editor Handbook are written in these syntaxes. Learning how to set up a build step is essential. However, configuring the necessary tools like [webpack](https://webpack.js.org/), [Babel](https://babeljs.io/), and [ESLint](https://eslint.org/) can become complex. This is where `wp-scripts` comes in. 
+
+Here are a few things that `wp-scripts` can do: 
+
+- **Compilation:** Converts modern JavaScript (ESNext and JSX) into code compatible with most browsers, using Babel.
+- **Bundling:** Uses webpack to combine multiple JavaScript files into a single bundle for better performance.
+- **Code Linting:** Provides configurations for ESLint to help ensure code quality and conformity to coding standards.
+- **Code Formatting:** Incorporates Prettier for automated code styling to maintain consistent code formatting across projects.
+- **Sass Compilation:** Converts Sass (.scss or .sass) files to standard CSS.
+- **Code Minification:** Reduces the size of the JavaScript code for production to ensure faster page loads.
+
+The package abstracts away much of the initial setup, configuration, and boilerplate code associated with JavaScript development for modern WordPress. You can then focus on building blocks and Block Editor extensions.
+
+## 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.
+</div>
+
+### Installation
+
+Ensure you have Node.js and `npm` installed on your computer. Review the [Node.js development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/) guide if not. 
+
+Then, create a project folder and ensure it contains a `package.json` file, a `build` folder, and an `src` folder. The `src` folder should also include an `index.js` file. 
+
+If you have not created a `package.json` file before, navigate to the project folder in the terminal and run the `npm init` command. An interactive prompt will walk you through the steps. Configure as you like, but when it asks for the "entry point", enter `build/index.js`.
+
+Of course, there are many ways to set up a project using `wp-scripts`, but this is the recommended approach used throughout the Block Editor Handbook.
+
+Finally, install the `wp-scripts` package as a development dependency by running the command:
+
+```bash
+npm install @wordpress/scripts --save-dev
+```
+
+Once the installation is complete, your project folder should look like this:
+
+```bash
+example-project-folder/
+├── build/
+├── node_modules/ (autogenerated)
+├── src/
+│   └── index.js
+├── package-lock.json (autogenerated)
+└── package.json
+```
+
+### Basic usage
+
+Once installed, you can run the predefined scripts provided with `wp-scripts` by referencing them in the scripts section of your `package.json` file. Here’s an example:
+
+```json
+{
+    "scripts": {
+        "start": "wp-scripts start",
+        "build": "wp-scripts build"
+    }
+}
+```
+
+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.
+
+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). 
+
+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. 
+
+```php
+/**
+ * Enqueue Editor assets.
+ */
+function example_project_enqueue_editor_assets() {
+    $asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
+
+    wp_enqueue_script(
+        'example-editor-scripts',
+        plugins_url( 'build/index.js', __FILE__ ),
+        $asset_file['dependencies'],
+        $asset_file['version']
+    );
+}
+add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );
+```
+
+## 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.
+
+### Maintaining code quality
+
+To help developers improve the quality of their code, `wp-scripts` comes pre-configured with tools like ESLint and Prettier. ESLint ensures your JavaScript adheres to best practices and the [WordPress coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/), while Prettier automatically formats your code. The available scripts include: 
+
+```json
+{
+    "scripts": {
+        "format": "wp-scripts format",
+        "lint:css": "wp-scripts lint-style",
+        "lint:js": "wp-scripts lint-js",
+    }
+}
+```
+
+Regularly linting and formatting your code ensures it's functional, clear, and maintainable for yourself and other developers.
+
+### Running Tests
+
+Beyond just writing code, verifying its functionality is crucial. `wp-scripts` includes [Jest](https://jestjs.io/), a JavaScript testing framework, and both end-to-end and unit testing scripts:
+
+```json
+{
+    "scripts": {
+        "test:e2e": "wp-scripts test-e2e",
+        "test:unit": "wp-scripts test-unit-js"
+    }
+}
+```
+
+Unit tests validate individual units of code, such as functions, ensuring they work as intended, while end-to-end (E2E) tests evaluate the entire project by simulating real-world user scenarios to ensure all parts of the system work seamlessly together.
+
+### Advanced configurations 
+
+While `wp-scripts` provides a solid default configuration, there might be cases where you need more specialized setups. The good news is `wp-scripts` is highly adaptable. For example, you can extend and override the default webpack configuration, allowing you to add loaders and plugins or modify almost any part of the build process. This flexibility ensures that as your project grows or its requirements change, `wp-scripts` can be tailored to your evolving needs.
+
+See the `wp-scripts` [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for all configuration options.
+
+## Additional resources
+
+- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) (Official documentation)
+- [How webpack and WordPress packages interact](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/) (WordPress Developer Blog)

docs/manifest.json

@@ -29,6 +29,18 @@
 		"markdown_source": "../docs/getting-started/devenv/get-started-with-wp-env.md",
 		"parent": "devenv"
 	},
+	{
+		"title": "Get started with wp-scripts",
+		"slug": "get-started-with-wp-scripts",
+		"markdown_source": "../docs/getting-started/devenv/get-started-with-wp-scripts.md",
+		"parent": "devenv"
+	},
+	{
+		"title": "Get started with create-block",
+		"slug": "get-started-with-create-block",
+		"markdown_source": "../docs/getting-started/devenv/get-started-with-create-block.md",
+		"parent": "devenv"
+	},
 	{
 		"title": "Create a Block Tutorial",
 		"slug": "create-block",

docs/toc.json

@@ -11,6 +11,12 @@
 					},
 					{
 						"docs/getting-started/devenv/get-started-with-wp-env.md": []
+					},
+					{
+						"docs/getting-started/devenv/get-started-with-wp-scripts.md": []
+					},
+					{
+						"docs/getting-started/devenv/get-started-with-create-block.md": []
 					}
 				]
 			},

lib/experimental/interactivity-api/class-wp-directive-context.php

@@ -65,9 +65,10 @@ public function get_context() {
 	 * @return void
 	 */
 	public function set_context( $context ) {
-		if ( $context ) {
-			array_push( $this->stack, array_replace_recursive( $this->get_context(), $context ) );
-		}
+		array_push(
+			$this->stack,
+			array_replace_recursive( $this->get_context(), $context )
+		);
 	}
 
 	/**

lib/experimental/interactivity-api/directives/wp-context.php

@@ -25,8 +25,8 @@ function gutenberg_interactivity_process_wp_context( $tags, $context ) {
 
 	$new_context = json_decode( $value, true );
 	if ( null === $new_context ) {
-		// Invalid JSON defined in the directive.
-		return;
+		// If the JSON is not valid, we still add an empty array to the stack.
+		$new_context = array();
 	}
 
 	$context->set_context( $new_context );