Docs: Switch code distinction to JSX & Plain (#37348)

* Replace ESNext vs ES5 with JSX and Plain.

The distinction between JavaScript examples shown in code is not really
between the JavaScript syntax, ESNext and ES5, since we dropped IE11
support; but between code that requires a build due to JSX and Plain
JavaScript that does not require a build.

* Remove ES5 code examples, only need one

The code examples are duplicated with the basic differences being
destructuring and function definitions, no JSX code used.

With the dropping of IE11 support, the minimum targeted browser supports
the ES6 code that is being used, so we don't need both examples.

* Apply suggestions from code review

Thanks Ryan for the additions, they all look good 👍

Co-authored-by: Ryan Welcher <[email protected]>

Co-authored-by: Ryan Welcher <[email protected]>

docs/contributors/documentation/README.md

@@ -88,26 +88,26 @@ An example, the link to this page is: `/docs/contributors/documentation/README.m
 
 The code example in markdown should be wrapped in three tick marks \`\`\` and should additionally include a language specifier. See this [GitHub documentation around fenced code blocks](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks).
 
-A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `ESNext` and `ES5` code samples. For example, [on this block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md).
+A unique feature to the Gutenberg documentation is the `codetabs` toggle, this allows two versions of code to be shown at once. This is used for showing both `JSX` and `Plain` code samples. For example, [on this block tutorial page](/docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md).
 
 Here is an example `codetabs` section:
 
 ````md
- {% codetabs %}
- {% ESNext %}
+ \{\% codetabs \%\}
+ \{\% JSX \%\}
  ```js
-  // ESNext code here
+ // JSX code here
  ```
- {% ES5 %}
+ \{\% Plain \%\}
  ```js
-  // ES5 code here
+ // Plain code here
  ```
- {% end %}
+ \{\% end \%\}
 ````
 
-The preferred format for code examples is ESNext, this should be the default view. The example placed first in source will be shown as the default.
+The preferred format for code examples is JSX, this should be the default view. The example placed first in source will be shown as the default.
 
-**Note:** it is not required to include ES5 code examples. The guidance is to include `ES5` code for beginner tutorials, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem is in ESNext.
+**Note:** It is not required to include plain JavaScript code examples for every guide. The recommendation is to include plain code for beginner tutorials or short examples, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem are in JSX that requires a build process.
 
 ### Callout notices
 

docs/how-to-guides/block-tutorial/README.md

@@ -4,6 +4,6 @@ The purpose of this tutorial is to step through the fundamentals of creating a n
 
 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.
 
-Code snippets are provided in two formats "ES5" and "ESNext". ES5 refers to "classic" JavaScript (ECMAScript 5), while ESNext refers to the next versions of the language standard, plus JSX syntax. You can change between them using tabs found above each code example. Using ESNext, 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.
+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.
 
-Note that it is not required to use ESNext to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with ESNext, developers find it is easier to read and write, thus most code examples you'll find use the ESNext syntax.
+Note that it is not required to use JSX to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with JSX and the build step, many developers tend to find it is easier to read and write, thus most code examples you'll find use the JSX syntax.

docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md

@@ -5,7 +5,7 @@ In the [previous section](/docs/how-to-guides/block-tutorial/writing-your-first-
 The editor will automatically generate a class name for each block type to simplify styling. It can be accessed from the object argument passed to the edit and save functions. In this section, we will create a stylesheet to use that class name.
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
@@ -38,7 +38,7 @@ registerBlockType( 'gutenberg-examples/example-02-stylesheets', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, element, blockEditor ) {

docs/how-to-guides/block-tutorial/block-controls-toolbar-and-sidebar.md

@@ -11,7 +11,7 @@ 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 %}
-{% ESNext %}
+{% JSX %}
 
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
@@ -92,7 +92,7 @@ registerBlockType( 'gutenberg-examples/example-04-controls-esnext', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, blockEditor, element ) {

docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md

@@ -18,7 +18,7 @@ Block attributes can be used for any content or setting you want to save for tha
 The following code example shows how to create a dynamic block that shows only the last post as a link.
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
@@ -52,7 +52,7 @@ registerBlockType( 'gutenberg-examples/example-dynamic', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, element, data, blockEditor ) {
@@ -155,7 +155,7 @@ Gutenberg 2.8 added the [`<ServerSideRender>`](/packages/server-side-render/READ
 _Server-side render is meant as a fallback; client-side rendering in JavaScript is always preferred (client rendering is faster and allows better editor manipulation)._
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
@@ -182,7 +182,7 @@ registerBlockType( 'gutenberg-examples/example-dynamic', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, element, serverSideRender, blockEditor ) {
@@ -219,4 +219,4 @@ registerBlockType( 'gutenberg-examples/example-dynamic', {
 
 {% end %}
 
-Note that this code uses the `wp-server-side-render` package but not `wp-data`. Make sure to update the dependencies in the PHP code. You can use wp-scripts and ESNext setup for auto dependencies (see the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples/tree/HEAD/01-basic-esnext) for PHP code setup).
+Note that this code uses the `wp-server-side-render` package but not `wp-data`. Make sure to update the dependencies in the PHP code. You can use wp-scripts to automatically build dependencies (see the [gutenberg-examples repo](https://github.com/WordPress/gutenberg-examples/tree/HEAD/01-basic-esnext) for PHP code setup).

docs/how-to-guides/block-tutorial/introducing-attributes-and-editable-fields.md

@@ -53,7 +53,7 @@ Because `RichText` allows for nested nodes, you'll most often use it in conjunct
 Here is the complete block definition for Example 03.
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
@@ -108,7 +108,7 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, blockEditor, element ) {

docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md

@@ -7,7 +7,7 @@ Note: A single block can only contain one `InnerBlock` component.
 Here is the basic InnerBlocks usage.
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 import { registerBlockType } from '@wordpress/blocks';
@@ -38,7 +38,7 @@ registerBlockType( 'gutenberg-examples/example-06', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, element, blockEditor ) {
@@ -92,7 +92,7 @@ Specifying this prop does not affect the layout of the inner blocks, but results
 Use the template property to define a set of blocks that prefill the InnerBlocks component when inserted. You can set attributes on the blocks to define their use. The example below shows a book review template using InnerBlocks component and setting placeholders values to show the block usage.
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 const MY_TEMPLATE = [
@@ -113,7 +113,7 @@ const MY_TEMPLATE = [
  },
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 const MY_TEMPLATE = [

docs/how-to-guides/block-tutorial/writing-your-first-block-type.md

@@ -38,7 +38,7 @@ add_action( 'init', 'gutenberg_examples_01_register_block' );
 
 Note the above example, shows using the [wp-scripts build step](/docs/how-to-guides/javascript/js-build-setup/) that automatically sets dependencies and versions the file.
 
-If you were using the ES5 code, you would specify `array( 'wp-blocks', 'wp-element' )` as the dependency array. See the [example 01](https://github.com/WordPress/gutenberg-examples/blob/HEAD/01-basic/index.php) in Gutenberg Examples repository for full syntax.
+If you were using the plain code, you would specify `array( 'wp-blocks', 'wp-element' )` as the dependency array. See the [example 01](https://github.com/WordPress/gutenberg-examples/blob/HEAD/01-basic/index.php) in Gutenberg Examples repository for full syntax.
 
 - **`wp-blocks`** includes block type registration and related functions
 - **`wp-element`** includes the [WordPress Element abstraction](/packages/element/README.md) for describing the structure of your blocks
@@ -48,7 +48,7 @@ If you were using the ES5 code, you would specify `array( 'wp-blocks', 'wp-eleme
 With the script enqueued, let's look at the implementation of the block itself:
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```jsx
 import { registerBlockType } from '@wordpress/blocks';
@@ -85,7 +85,7 @@ registerBlockType( 'gutenberg-examples/example-01-basic-esnext', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( blocks, element, blockEditor ) {

docs/how-to-guides/internationalization.md

@@ -38,7 +38,7 @@ add_action( 'init', 'myguten_block_init' );
 In your code, you can include the i18n functions. The most common function is **\_\_** (a double underscore) which provides translation of a simple string. Here is a basic block example:
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 import { __ } from '@wordpress/i18n';
@@ -64,7 +64,7 @@ registerBlockType( 'myguten/simple', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 const { __ } = wp.i18n;

docs/how-to-guides/javascript/versions-and-building.md

@@ -1,15 +1,14 @@
 # JavaScript Versions and Build Step
 
-The Block Editor Handbook shows JavaScript examples in two syntaxes: ES5 and ESNext. These are version names for the JavaScript language standard definitions. You may also see elsewhere the names ES6, or ECMAScript 2015 mentioned. See the [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript) Wikipedia article for all the details.
+The Block Editor Handbook shows JavaScript examples in two syntaxes: JSX and Plain.
 
-ES5 code is compatible with WordPress's minimum [target for browser support](https://make.wordpress.org/core/handbook/best-practices/browser-support/).
+Plain refers to JavaScript code compatible with WordPress's minimum [target for browser support](https://make.wordpress.org/core/handbook/best-practices/browser-support/) without requiring a transpilation step. This step is commonly referred to as a build process.
 
-"ESNext" doesn't refer to a specific version of JavaScript, but is "dynamic" and refers to the next language definitions, whatever they might be. Because some browsers won't support these features yet (because they're new or proposed), an extra build step is required to transform the code to a syntax that works in all browsers. Webpack and babel are the tools that perform this transformation step.
+"JSX" doesn't refer to a specific version of JavaScript, but refers to the latest language definition plus
+[JSX syntax](https://reactjs.org/docs/introducing-jsx.html), a syntax that blends HTML and JavaScript. JSX makes it easier to read and write markup code, but does require a build step to transpile into code compatible with browers. Webpack and babel are the tools that perform this transpilation step.
 
-Additionally, the ESNext code examples in the handbook include [JSX syntax](https://reactjs.org/docs/introducing-jsx.html), a syntax that blends HTML and JavaScript. JSX makes it easier to read and write markup code, but does require a build step to transform into compatible code.
+For simplicity, the JavaScript tutorial uses the Plain definition, without JSX. This code can run straight in your browser and does not require an additional build step. In many cases, it is perfectly fine to follow the same approach for simple plugins or experimenting. As your codebase grows in complexity it might be a good idea to switch to JSX. You will find the majority of code and documentation across the block editor uses JSX.
 
-For simplicity, the JavaScript tutorial uses the ES5 definition, without JSX. This code can run straight in your browser and does not require an additional build step. In many cases, it is perfectly fine to follow the same approach for simple plugins or experimenting. As your codebase grows in complexity it might be a good idea to switch to ESNext. You will find the majority of code and documentation across the block editor uses ESNext.
+See the [JavaScript Build Setup documentation](/docs/how-to-guides/javascript/js-build-setup.md) for setting up a development environment using JSX syntax.
 
-See the [JavaScript Build Setup documentation](/docs/how-to-guides/javascript/js-build-setup.md) for setting up a development environment using ESNext syntax.
-
-See the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and ESNext.
+See the [ESNext syntax documentation](/docs/how-to-guides/javascript/esnext-js.md) for explanation and examples about common code differences between standard JavaScript and more modern approaches.

docs/how-to-guides/metabox/meta-block-3-add.md

@@ -9,7 +9,7 @@ The hook `useEntityProp` can be used by the blocks to get or change meta values.
 Add this code to your JavaScript file (this tutorial will call the file `myguten.js`):
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 import { registerBlockType } from '@wordpress/blocks';
@@ -54,7 +54,7 @@ registerBlockType( 'myguten/meta-block', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 ( function ( wp ) {

docs/how-to-guides/platform/custom-block-editor/README.md

@@ -12,8 +12,6 @@ To follow along with this tutorial, you can [download the accompanying WordPress
 
 ## Code Syntax
 
-Code snippets are provided in "ESNext". ESNext refers to the next versions of the language standard, plus JSX syntax.
-
-Note that it is not required to use ESNext to create blocks or extend the editor, you can use classic JavaScript. However, once familiar with ESNext, developers find it is easier to read and write, thus most code examples you'll find use the ESNext syntax.
+Code snippets are provided using JSX syntax. Note it is not required to use JSX to create blocks or extend the editor, you can use plain JavaScript. However, once familiar with JSX, many developers tend find it is easier to read and write, thus most code examples you'll find use that syntax.
 
 - [Start custom block editor tutorial](/docs/reference-guides/platform/custom-block-editor/tutorial.md)

docs/reference-guides/block-api/block-attributes.md

@@ -361,7 +361,7 @@ Attributes may be obtained from a post's meta rather than from the block's repre
 From here, meta attributes can be read and written by a block using the same interface as any attribute:
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 edit( { attributes, setAttributes } ) {
@@ -373,7 +373,7 @@ edit( { attributes, setAttributes } ) {
 },
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 edit: function( props ) {

docs/reference-guides/block-api/block-deprecation.md

@@ -15,27 +15,13 @@ For blocks with multiple deprecations, it may be easier to save each deprecation
 
 ### Example:
 
-{% codetabs %}
-{% ESNext %}
-
 ```js
 const v1 = {};
 const v2 = {};
 const v3 = {};
 const deprecated = [ v3, v2, v1 ];
 ```
 
-{% ES5 %}
-
-```js
-var v1 = {};
-var v2 = {};
-var v3 = {};
-var deprecated = [ v3, v2, v1 ];
-```
-
-{% end %}
-
 It is also recommended to keep [fixtures](https://github.com/WordPress/gutenberg/blob/HEAD/test/integration/fixtures/blocks/README.md) which contain the different versions of the block content to allow you to easily test that new deprecations and migrations are working across all previous versions of the block.
 
 Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form:
@@ -51,7 +37,7 @@ It's important to note that `attributes`, `supports`, and `save` are not automat
 ### Example:
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 const { registerBlockType } = wp.blocks;
@@ -83,7 +69,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 var el = wp.element.createElement,
@@ -127,7 +113,7 @@ Sometimes, you need to update the attributes set to rename or modify old attribu
 ### Example:
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 const { registerBlockType } = wp.blocks;
@@ -169,7 +155,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 var el = wp.element.createElement,
@@ -224,7 +210,7 @@ E.g: a block wants to migrate a title attribute to a paragraph innerBlock.
 ### Example:
 
 {% codetabs %}
-{% ESNext %}
+{% JSX %}
 
 ```js
 const { registerBlockType } = wp.blocks;
@@ -268,7 +254,7 @@ registerBlockType( 'gutenberg/block-with-deprecated-version', {
 } );
 ```
 
-{% ES5 %}
+{% Plain %}
 
 ```js
 var el = wp.element.createElement,