Merge changes published in the Gutenberg plugin "release/13.5" branch

WordPress · Jun 15, 2022 · e829160 · e829160
1 parent a3e0b62
commit e829160
Show file tree

Hide file tree

Showing 875 changed files with 17,364 additions and 14,830 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -78,8 +78,32 @@ module.exports = {
 					},
 					{
 						name: 'lodash',
-						importNames: [ 'memoize' ],
-						message: 'Please use `memize` instead.',
+						importNames: [
+							'concat',
+							'defaultTo',
+							'differenceWith',
+							'dropRight',
+							'each',
+							'findIndex',
+							'isArray',
+							'isFinite',
+							'isFunction',
+							'isObjectLike',
+							'isUndefined',
+							'memoize',
+							'negate',
+							'noop',
+							'random',
+							'reverse',
+							'stubFalse',
+							'stubTrue',
+							'sum',
+							'sumBy',
+							'take',
+							'trim',
+						],
+						message:
+							'This Lodash method is not recommended. Please use native functionality instead. If using `memoize`, please use `memize` instead.',
 					},
 					{
 						name: 'reakit',

diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -3,3 +3,6 @@
 
 # ESLint updates.
 f63053cace3c02e284f00918e1854284c85b9132
+
+# Prettier upgrade to 2.6.2.
+33d84b036592a5bf31af05b7710f3b2b14163dc4
diff --git a/bin/check-latest-npm.js b/bin/check-latest-npm.js
@@ -69,15 +69,16 @@ async function getLatestNPMVersion() {
 				/** @type {NodeJS.ErrnoException} */ ( error ).code ===
 				'ENOTFOUND'
 			) {
-				error = new Error( `Could not contact the npm registry to determine latest version.
+				error =
+					new Error( `Could not contact the npm registry to determine latest version.
 
 This could be due to an intermittent outage of the service, or because you are not connected to the internet.
 
 Because it is important that \`package-lock.json\` files only be committed while running the latest version of npm, this commit has been blocked.
 
 If you are certain of your changes and desire to commit anyways, you should either connect to the internet or bypass commit verification using ${ yellow(
-					'git commit --no-verify'
-				) } .` );
+						'git commit --no-verify'
+					) } .` );
 			}
 
 			reject( error );

diff --git a/bin/packages/build.js b/bin/packages/build.js
@@ -69,9 +69,8 @@ function isFileImportedInStyleEntry( file, importStatements ) {
 function findStyleEntriesThatImportFile( file ) {
 	const entriesWithImport = stylesheetEntryPoints.reduce(
 		( acc, entryPoint ) => {
-			const styleEntryImportStatements = parseImportStatements(
-				entryPoint
-			);
+			const styleEntryImportStatements =
+				parseImportStatements( entryPoint );
 
 			if (
 				isFileImportedInStyleEntry( file, styleEntryImportStatements )
@@ -161,9 +160,10 @@ function createBlockJsonEntryTransform() {
 	return new Transform( {
 		objectMode: true,
 		async transform( file, encoding, callback ) {
-			const matches = /block-library[\/\\]src[\/\\](.*)[\/\\]block.json$/.exec(
-				file
-			);
+			const matches =
+				/block-library[\/\\]src[\/\\](.*)[\/\\]block.json$/.exec(
+					file
+				);
 			const blockName = matches ? matches[ 1 ] : undefined;
 
 			// Only block.json files in the block-library folder are subject to this transform.

diff --git a/bin/packages/validate-typescript-version.js b/bin/packages/validate-typescript-version.js
@@ -6,8 +6,8 @@ const tscDetectedVersion = require( 'typescript' ).version;
 /**
  * Internal dependencies
  */
-const tscDependencyVersion = require( '../../package.json' ).devDependencies
-	.typescript;
+const tscDependencyVersion =
+	require( '../../package.json' ).devDependencies.typescript;
 
 if ( tscDependencyVersion !== tscDetectedVersion ) {
 	console.error(

diff --git a/changelog.txt b/changelog.txt
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
@@ -214,4 +214,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-stlyesheets](https://github.com/WordPress/gutenberg-examples/tree/trunk/02-stylesheets) code in the [gutenberg-examples repository](https://github.com/WordPress/gutenberg-examples).
+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).
diff --git a/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md b/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md
@@ -133,9 +133,36 @@ Add the following to `block.js`
 
 {% end %}
 
-NOTE: If using the JSX version, you need to run `npm run build` and it will create the JavaScript file that is loaded in the editor at `build/index.js`
+### Step 4: Build or add dependency
 
-### Step 4: Confirm
+In order to register the block, an asset php file is required in the same directory as the directory used in `register_block_type()` and must begin with the script's filename.
+
+{% codetabs %}
+{% JSX %}
+
+Build the scripts and asset file which is used to keep track of dependencies and the build version.
+```bash
+npm run build
+```
+
+{% Plain %}
+
+Create the asset file to load the dependencies for the scripts. The name of this file should be the name of the js file then .asset.php. For this example, create `block.asset.php` with the following:
+
+```php
+<?php return
+	array( 'dependencies' =>
+		array(
+			'wp-blocks',
+			'wp-element',
+			'wp-polyfill'
+		),
+		'version' => '0.1'
+	);
+```
+
+
+### Step 5: Confirm
 
 Open your editor and try adding your new block. It will show in the inserter using the `title`.
 When inserted you will see the `Hello World (from the editor)` message.

diff --git a/docs/how-to-guides/feature-flags.md b/docs/how-to-guides/feature-flags.md
@@ -1,16 +1,18 @@
 # Feature Flags
 
-Often in the Gutenberg project, there's a need to control whether the code we write is shipped to WordPress core, or whether certain more experimental features are only active in the plugin.
-
-Often this is handled using a 'feature flag'.
+'Feature flags' are variables that allow you to prevent specific code in the Gutenberg project from being shipped to WordPress core, and to run certain experimental features only in the plugin.
 
 ## Introducing `process.env.IS_GUTENBERG_PLUGIN`
 
-The `process.env.IS_GUTENBERG_PLUGIN` is an environment variable that represents whether code is currently executing within the plugin. When the codebase is built for the plugin, this variable will be set to `true`. When building for core, it will be set to `false` or `undefined`.
+The `process.env.IS_GUTENBERG_PLUGIN` is an environment variable whose value 'flags' whether code is running within the Gutenberg plugin. 
+
+When the codebase is built for the plugin, this variable will be set to `true`. When building for WordPress core, it will be set to `false` or `undefined`.
 
 ## Basic Use
 
-A plugin only function or constant should be exported using the following ternary syntax:
+### Exporting features
+
+A plugin-only function or constant should be exported using the following ternary syntax:
 
 ```js
 function myPluginOnlyFeature() {
@@ -21,9 +23,11 @@ export const pluginOnlyFeature =
 	process.env.IS_GUTENBERG_PLUGIN ? myPluginOnlyFeature : undefined;
 ```
 
-In non-plugin environments the `phaseTwoFeature` export will be `undefined`.
+In the above example, the `pluginOnlyFeature` export will be `undefined` in non-plugin environments such as WordPress core.
 
-If you're attempting to import and call a plugin only feature, be sure to wrap the call to the function in an if statement to avoid an error:
+### Importing features
+
+If you're attempting to import and call a plugin-only feature, be sure to wrap the function call in an `if` statement to avoid an error:
 
 ```js
 import { pluginOnlyFeature } from '@wordpress/foo';
@@ -33,68 +37,68 @@ if ( process.env.IS_GUTENBERG_PLUGIN ) {
 }
 ```
 
-### How it works
+## How it works
 
-During the webpack build, any instances of `process.env.IS_GUTENBERG_PLUGIN` will be replaced using webpack's define plugin (https://webpack.js.org/plugins/define-plugin/).
+During the webpack build, instances of `process.env.IS_GUTENBERG_PLUGIN` will be replaced using webpack's [define plugin](https://webpack.js.org/plugins/define-plugin/).
 
-If you write the following code:
+For example, in the following code –
 
 ```js
 if ( process.env.IS_GUTENBERG_PLUGIN ) {
 	pluginOnlyFeature();
 }
 ```
 
-When building the codebase for the plugin the variable will be replaced with the boolean `true`:
+– the variable `process.env.IS_GUTENBERG_PLUGIN` will be replaced with the boolean `true` during the plugin-only build:
 
 ```js
-if ( true ) {
+if ( true ) { // Wepack has replaced `process.env.IS_GUTENBERG_PLUGIN` with `true`
 	pluginOnlyFeature();
 }
 ```
 
-Any code within the body of the if statement will be executed because of this truthyness.
+This ensures that code within the body of the `if` statement will always be executed.
 
-For core, the `process.env.IS_GUTENBERG_PLUGIN` variable is replaced with `undefined`, so the built code will look like:
+In WordPress core, the `process.env.IS_GUTENBERG_PLUGIN` variable is replaced with `undefined`. The built code looks like this:
 
 ```js
-if ( undefined ) {
+if ( undefined ) { // Wepack has replaced `process.env.IS_GUTENBERG_PLUGIN` with `undefined`
 	pluginOnlyFeature();
 }
 ```
 
-`undefined` evaluates to `false` so the plugin only feature will not be executed within core.
+`undefined` evaluates to `false` so the plugin-only feature will not be executed.
 
 ### Dead Code Elimination
 
-When building code for production, webpack 'minifies' code (https://en.wikipedia.org/wiki/Minification_(programming)), removing the amount of unnecessary JavaScript as much as possible. One of the steps involves something known as 'dead code elimination'.
+For production builds, webpack ['minifies'](https://en.wikipedia.org/wiki/Minification_(programming)) the code, removing as much unnecessary JavaScript as it can. 
 
-When the following code is encountered, webpack determines that the surrounding `if`statement is unnecessary:
+One of the steps involves something known as 'dead code elimination'. For example, when the following code is encountered, webpack determines that the surrounding `if` statement is unnecessary:
 
 ```js
 if ( true ) {
 	pluginOnlyFeature();
 }
 ```
 
-The condition will always evaluates to `true`, so can be removed leaving just the code in the body:
+The condition will always evaluate to `true`, so webpack removes it, leaving behind the code that was in the body:
 
 ```js
-pluginOnlyFeature();
+pluginOnlyFeature(); // The `if` condition block has been removed. Only the body remains.
 ```
 
-Similarly when building for core, the condition in the following `if` statement always resolves to false:
+Similarly, when building for WordPress core, the condition in the following `if` statement always resolves to false:
 
 ```js
 if ( undefined ) {
 	pluginOnlyFeature();
 }
 ```
 
-The minification process will remove the entire `if` statement including the body, ensuring plugin only code is not included in the built JavaScript intended for core.
+In this case, the minification process will remove the entire `if` statement including the body, ensuring plugin-only code is not included in WordPress core build.
 
 ## FAQ
 
 #### Why shouldn't I assign the result of an expression involving `IS_GUTENBERG_PLUGIN` to a variable, e.g. `const isMyFeatureActive = process.env.IS_GUTENBERG_PLUGIN === 2`?
 
-The aim here is to avoid introducing any complexity that could result in webpack's minifier not being able to eliminate dead code. See the [Dead Code Elimination](#dead-code-elimination) section for further details.
+Introducing complexity may prevent webpack's minifier from identifying and therefore eliminating dead code. Therefore it is recommended to use the examples in this document to ensure your feature flag functions as intended. For further details, see the [Dead Code Elimination](#dead-code-elimination) section.
diff --git a/docs/reference-guides/core-blocks.md b/docs/reference-guides/core-blocks.md
@@ -563,7 +563,7 @@ Displays the next or previous post link that is adjacent to the current post. ([
 
 -	**Name:** core/post-navigation-link
 -	**Category:** theme
--	**Supports:** typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
+-	**Supports:** color (background, link, text), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
 -	**Attributes:** label, linkLabel, showTitle, textAlign, type
 
 ## Post Template
Original file line number	Diff line number	Diff line change
Expand Up		@@ -214,4 +214,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-stlyesheets](https://github.com/WordPress/gutenberg-examples/tree/trunk/02-stylesheets) code in the [gutenberg-examples repository](https://github.com/WordPress/gutenberg-examples).
		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).