Merge branch 'trunk' into font-library/fix-focus-loss

.eslintrc.js

@@ -406,5 +406,11 @@ module.exports = {
 				],
 			},
 		},
+		{
+			files: [ 'packages/interactivity*/src/**' ],
+			rules: {
+				'react/react-in-jsx-scope': 'error',
+			},
+		},
 	],
 };

docs/contributors/documentation/README.md

@@ -111,7 +111,7 @@ 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 `JSX` and `Plain` 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.
 
 Here is an example `codetabs` section:
 

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

@@ -6,7 +6,7 @@ A block typically inserts markup (HTML) into post content that you want to style
 
 ## Before you start
 
-You will need a basic block and WordPress development environment to implement the examples shown in this guide. See the [create a basic block](/docs/how-to-guides/block-tutorial/writing-your-first-block-type.md) or [block tutorial](/docs/getting-started/devenv/get-started-with-create-block.md) to get setup.
+You will need a basic block and WordPress development environment to implement the examples shown in this guide. See the [Quick Start Guide](/docs/getting-started/quick-start-guide.md) or [block tutorial](/docs/getting-started/tutorial.md) to get set up.
 
 ## Methods to add style
 

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

@@ -38,14 +38,16 @@ registerBlockType( 'gutenberg-examples/example-06', {
 
 ## Allowed blocks
 
-Using the `allowedBlocks` property, you can define the set of blocks allowed in your InnerBlock. This restricts the blocks that can be included only to those listed, all other blocks will not show in the inserter.
+Using the `allowedBlocks` prop, you can further limit, in addition to the `allowedBlocks` field in `block.json`, which blocks can be inserted as direct descendants of this block. It is useful to determine the list of allowed blocks dynamically, individually for each block. For example, determined by a block attribute:
 
 ```js
-const ALLOWED_BLOCKS = [ 'core/image', 'core/paragraph' ];
+const { allowedBlocks } = attributes;
 //...
-<InnerBlocks allowedBlocks={ ALLOWED_BLOCKS } />;
+<InnerBlocks allowedBlocks={ allowedBlocks } />;
 ```
 
+If the list of allowed blocks is always the same, prefer the [`allowedBlocks` block setting](#defining-a-children-block-relationship) instead.
+
 ## Orientation
 
 By default, `InnerBlocks` expects its blocks to be shown in a vertical list. A valid use-case is to style inner blocks to appear horizontally, for instance by adding CSS flex or grid properties to the inner blocks wrapper. When blocks are styled in such a way, the `orientation` prop can be set to indicate that a horizontal layout is being used:
@@ -109,12 +111,13 @@ add_action( 'init', function() {
 } );
 ```
 
-## Using parent and ancestor relationships in blocks
+## Using parent, ancestor and children relationships in blocks
 
-A common pattern for using InnerBlocks is to create a custom block that will be only be available if its parent block is inserted. This allows builders to establish a relationship between blocks, while limiting a nested block's discoverability. Currently, there are two relationships builders can use: `parent` and `ancestor`. The differences are:
+A common pattern for using InnerBlocks is to create a custom block that will only be available if its parent block is inserted. This allows builders to establish a relationship between blocks, while limiting a nested block's discoverability. There are three relationships that builders can use: `parent`, `ancestor` and `allowedBlocks`. The differences are:
 
 - If you assign a `parent` then you’re stating that the nested block can only be used and inserted as a __direct descendant of the parent__.
 - If you assign an `ancestor` then you’re stating that the nested block can only be used and inserted as a __descendent of the parent__.
+- If you assign the `allowedBlocks` then you’re stating a relationship in the opposite direction, i.e., which blocks can be used and inserted as __direct descendants of this block__.
 
 The key difference between `parent` and `ancestor` is `parent` has finer specificity, while an `ancestor` has greater flexibility in its nested hierarchy.
 
@@ -150,6 +153,23 @@ When defining a descendent block, use the `ancestor` block setting. This prevent
 }
 ```
 
+### Defining a children block relationship
+
+An example of this is the Navigation block, which is assigned the `allowedBlocks` block setting. This makes only a certain subset of block types to be available as direct descendants of the Navigation block. See [Navigation code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/navigation).
+
+The `allowedBlocks` setting can be extended by builders of custom blocks. The custom block can hook into the `blocks.registerBlockType` filter and add itself to the available children of the Navigation.
+
+When defining a set of possible descendant blocks, use the `allowedBlocks` block setting. This limits what blocks are showing in the inserter when inserting a new child block.
+
+```json
+{
+	"title": "Navigation",
+	"name": "core/navigation",
+	"allowedBlocks": [ "core/navigation-link", "core/search", "core/social-links", "core/page-list", "core/spacer" ],
+	// ...
+}
+```
+
 ## Using a React hook
 
 You can use a react hook called `useInnerBlocksProps` instead of the `InnerBlocks` component. This hook allows you to take more control over the markup of inner blocks areas.