@wordpress/block-editor 16.1.0 → 17.0.0

package/src/components/inner-blocks/stories/index.story.jsx

@@ -0,0 +1,246 @@
+import {
+	createBlock,
+	getBlockType,
+	registerBlockType,
+} from '@wordpress/blocks';
+import { createContext, useContext, useMemo } from '@wordpress/element';
+import InnerBlocks from '../';
+import BlockList from '../../block-list';
+import { useBlockProps } from '../../block-list/use-block-props';
+import { ExperimentalBlockEditorProvider } from '../../provider';
+
+// `InnerBlocks` only renders within a block, so the story args are passed down
+// to the block type registered below through a context rather than rendered by
+// the story directly.
+const ArgsContext = createContext( {} );
+
+const CONTAINER_BLOCK = 'storybook/inner-blocks-container';
+const TEXT_BLOCK = 'storybook/example-text';
+const MEDIA_BLOCK = 'storybook/example-media';
+const CHILD_BLOCKS = [
+	[ TEXT_BLOCK, 'Example Text', 'text' ],
+	[ MEDIA_BLOCK, 'Example Media', 'media' ],
+];
+
+// The inner blocks appender is only rendered while the block holding the inner
+// blocks is selected, so the container is selected from the start and its
+// client ID is hardcoded instead of using the generated one.
+const CONTAINER_CLIENT_ID = 'inner-blocks-container';
+const SELECTION = {
+	selectionStart: { clientId: CONTAINER_CLIENT_ID },
+	selectionEnd: { clientId: CONTAINER_CLIENT_ID },
+};
+
+function ContainerEdit() {
+	const args = useContext( ArgsContext );
+	const blockProps = useBlockProps();
+
+	return (
+		<div { ...blockProps }>
+			<InnerBlocks { ...args } />
+		</div>
+	);
+}
+
+function ChildEdit( { name } ) {
+	const blockProps = useBlockProps();
+	const { title } = getBlockType( name );
+
+	return <p { ...blockProps }>{ title }</p>;
+}
+
+// Minimal block types, so that the story doesn't depend on the block library.
+// They are registered when the story renders rather than when this file loads,
+// so that they don't leak into the registry shared with the other stories.
+function useContainerBlock() {
+	return useMemo( () => {
+		CHILD_BLOCKS.forEach( ( [ name, title, category ] ) => {
+			if ( ! getBlockType( name ) ) {
+				registerBlockType( name, {
+					apiVersion: 3,
+					title,
+					category,
+					edit: ChildEdit,
+					save: () => null,
+				} );
+			}
+		} );
+
+		if ( ! getBlockType( CONTAINER_BLOCK ) ) {
+			registerBlockType( CONTAINER_BLOCK, {
+				apiVersion: 3,
+				title: 'Example Container',
+				category: 'design',
+				// The container is only meant to host the inner blocks area,
+				// so it is kept out of the inserter itself.
+				supports: { inserter: false },
+				edit: ContainerEdit,
+				save: () => null,
+			} );
+		}
+
+		return [
+			{
+				...createBlock( CONTAINER_BLOCK ),
+				clientId: CONTAINER_CLIENT_ID,
+			},
+		];
+	}, [] );
+}
+
+// Marks out the inner blocks area, so that it is easier to tell which part of
+// the block list the props apply to.
+const storyStyles = `
+	.inner-blocks-story .wp-block[data-type="${ CONTAINER_BLOCK }"] {
+		border: 1px dashed #949494;
+		padding: 16px;
+	}
+`;
+
+// The rendered story is a block editor hosting the example block below, so the
+// generated snippet would only show that scaffolding. This is how a block
+// renders the inner blocks area that the controls act on instead.
+const sourceCode = `registerBlockType( 'my-plugin/my-block', {
+	edit() {
+		const blockProps = useBlockProps();
+
+		return (
+			<div { ...blockProps }>
+				<InnerBlocks
+					allowedBlocks={ [ 'core/image', 'core/paragraph' ] }
+					orientation="vertical"
+					renderAppender={ InnerBlocks.ButtonBlockAppender }
+				/>
+			</div>
+		);
+	},
+
+	save() {
+		const blockProps = useBlockProps.save();
+
+		return (
+			<div { ...blockProps }>
+				<InnerBlocks.Content />
+			</div>
+		);
+	},
+} );`;
+
+const meta = {
+	title: 'BlockEditor/InnerBlocks',
+	component: InnerBlocks,
+	parameters: {
+		docs: {
+			canvas: { sourceState: 'shown' },
+			description: {
+				component:
+					'InnerBlocks is a component which allows a single block to have multiple blocks as children. It is rendered by a block `edit` implementation, and pairs with `InnerBlocks.Content` in the `save` implementation, which is replaced by the content of the nested blocks.',
+			},
+			source: { code: sourceCode },
+		},
+	},
+	argTypes: {
+		allowedBlocks: {
+			control: { type: 'select' },
+			options: [ 'all', 'none', 'text block only' ],
+			mapping: {
+				all: true,
+				none: false,
+				'text block only': [ TEXT_BLOCK ],
+			},
+			description:
+				'The block types that can be inserted. `true` allows every block type, `false` allows none, and an array limits insertion to the listed block types.',
+			table: {
+				type: { summary: 'boolean | string[]' },
+				defaultValue: { summary: 'true' },
+			},
+		},
+		orientation: {
+			control: { type: 'select' },
+			options: [ 'vertical', 'horizontal' ],
+			description:
+				'Whether inner blocks are shown horizontally or vertically. It does not style the inner blocks, but it orients the block movers and makes drag and drop behave accordingly.',
+			table: {
+				type: { summary: "'horizontal' | 'vertical'" },
+				defaultValue: { summary: "'vertical'" },
+			},
+		},
+		templateLock: {
+			control: { type: 'select' },
+			options: [ false, 'all', 'insert', 'contentOnly' ],
+			description:
+				"Locks the inner blocks area. `'all'` prevents all operations, `'insert'` prevents inserting and removing blocks but allows moving them, `'contentOnly'` prevents all operations and cannot be overridden by children, and `false` opts out of a lock applied by a parent. When unset, the lock of the parent inner blocks area is used.",
+			table: {
+				type: { summary: "boolean | 'all' | 'insert' | 'contentOnly'" },
+			},
+		},
+		renderAppender: {
+			control: { type: 'select' },
+			options: [ 'default', 'button', 'none' ],
+			mapping: {
+				default: undefined,
+				button: InnerBlocks.ButtonBlockAppender,
+				none: false,
+			},
+			description:
+				'The component shown as the trailing appender of the inner blocks list. `InnerBlocks.ButtonBlockAppender` and `InnerBlocks.DefaultBlockAppender` are exposed for convenience, and any valid component can be passed. `false` renders no appender, and when unset the default appender is shown.',
+			table: {
+				type: { summary: 'Component | false' },
+			},
+		},
+		defaultBlock: {
+			control: { type: 'object' },
+			description:
+				'The block type inserted by default, in the form `{ name, attributes }`.',
+			table: {
+				type: { summary: 'Object' },
+			},
+		},
+		directInsert: {
+			control: { type: 'boolean' },
+			description:
+				'Whether the appender inserts `defaultBlock` directly, skipping the inserter dropdown and any registered inserter variations of that block type.',
+			table: {
+				type: { summary: 'boolean' },
+			},
+		},
+		prioritizedInserterBlocks: {
+			control: { type: 'object' },
+			description:
+				'The block types shown first in the block inserter, as an array of `{blockName}/{variationName}` strings, where the variation name is optional.',
+			table: {
+				type: { summary: 'string[]' },
+			},
+		},
+		placeholder: {
+			control: false,
+			description:
+				'An element rendered in front of the appender, which can be used to represent an example state before any block is inserted.',
+			table: {
+				type: { summary: 'Element' },
+			},
+		},
+	},
+};
+
+export default meta;
+
+export const Default = {
+	render: function Template( args ) {
+		const blocks = useContainerBlock();
+
+		return (
+			<ArgsContext.Provider value={ args }>
+				<ExperimentalBlockEditorProvider
+					value={ blocks }
+					selection={ SELECTION }
+				>
+					<style>{ storyStyles }</style>
+					<div className="inner-blocks-story">
+						<BlockList />
+					</div>
+				</ExperimentalBlockEditorProvider>
+			</ArgsContext.Provider>
+		);
+	},
+};

package/src/components/inner-blocks/test/index.js

@@ -1,8 +1,4 @@
 /* eslint-disable testing-library/render-result-naming-convention */
-
-/**
- * WordPress dependencies
- */
 import {
 	createBlock,
 	getBlockTypes,
@@ -12,10 +8,6 @@ import {
 	unregisterBlockType,
 } from '@wordpress/blocks';
 import { renderToString } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import InnerBlocks from '../';
 
 describe( 'InnerBlocks', () => {

package/src/components/inner-blocks/use-block-context.js

@@ -1,12 +1,5 @@
-/**
- * WordPress dependencies
- */
 import { store as blocksStore } from '@wordpress/blocks';
 import { useSelect } from '@wordpress/data';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
 
 /**

package/src/components/inner-blocks/use-inner-block-template-sync.js

@@ -1,18 +1,8 @@
-/**
- * External dependencies
- */
 import fastDeepEqual from 'fast-deep-equal/es6/index.js';
-
-/**
- * WordPress dependencies
- */
 import { useRef, useLayoutEffect } from '@wordpress/element';
 import { useRegistry } from '@wordpress/data';
-import { synchronizeBlocksWithTemplate } from '@wordpress/blocks';
-
-/**
- * Internal dependencies
- */
+import { getBlockType, synchronizeBlocksWithTemplate } from '@wordpress/blocks';
+import deprecated from '@wordpress/deprecated';
 import { store as blockEditorStore } from '../../store';
 
 /**
@@ -23,7 +13,8 @@ import { store as blockEditorStore } from '../../store';
  * then we replace the inner blocks with the correct value after synchronizing it with the template.
  *
  * @param {string}  clientId                       The block client ID.
- * @param {Object}  template                       The template to match.
+ * @param {Object}  template                       A template to apply in place of the one
+ *                                                 declared in the block type settings.
  * @param {string}  templateLock                   The template lock state for the inner blocks. For
  *                                                 example, if the template lock is set to "all",
  *                                                 then the inner blocks will stay in sync with the
@@ -40,6 +31,26 @@ export default function useInnerBlockTemplateSync(
 	templateLock,
 	templateInsertUpdatesSelection
 ) {
+	if ( template !== undefined ) {
+		deprecated(
+			'The template prop of InnerBlocks and useInnerBlocksProps',
+			{
+				since: '7.2',
+				alternative: 'a `template` declared in the block type settings',
+			}
+		);
+	}
+	if ( templateInsertUpdatesSelection !== undefined ) {
+		deprecated(
+			'The templateInsertUpdatesSelection prop of InnerBlocks and useInnerBlocksProps',
+			{
+				since: '7.2',
+				alternative:
+					'`templateInsertUpdatesSelection` declared in the block type settings',
+			}
+		);
+	}
+
 	// Instead of adding a useSelect mapping here, please add to the useSelect
 	// mapping in InnerBlocks! Every subscription impacts performance.
 	const registry = useRegistry();
@@ -51,6 +62,7 @@ export default function useInnerBlockTemplateSync(
 		let isCancelled = false;
 
 		const {
+			getBlockName,
 			getBlocks,
 			getSelectedBlocksInitialCaretPosition,
 			isBlockSelected,
@@ -67,27 +79,39 @@ export default function useInnerBlockTemplateSync(
 				return;
 			}
 
+			// A template declared in block type settings serves as the
+			// default when no `template` prop is passed, along with whether
+			// applying it moves the selection.
+			let resolvedTemplate = template;
+			let resolvedUpdatesSelection = templateInsertUpdatesSelection;
+			if ( template === undefined ) {
+				const blockType = getBlockType( getBlockName( clientId ) );
+				resolvedTemplate = blockType?.template;
+				resolvedUpdatesSelection =
+					blockType?.templateInsertUpdatesSelection;
+			}
+
+			const currentInnerBlocks = getBlocks( clientId );
+			const hasAppliedTemplate = fastDeepEqual(
+				resolvedTemplate,
+				existingTemplateRef.current
+			);
+
 			// Only synchronize innerBlocks with template if innerBlocks are empty
 			// or a locking "all" or "contentOnly" exists directly on the block.
-			const currentInnerBlocks = getBlocks( clientId );
 			const shouldApplyTemplate =
 				currentInnerBlocks.length === 0 ||
 				templateLock === 'all' ||
 				templateLock === 'contentOnly';
 
-			const hasTemplateChanged = ! fastDeepEqual(
-				template,
-				existingTemplateRef.current
-			);
-
-			if ( ! shouldApplyTemplate || ! hasTemplateChanged ) {
+			if ( ! shouldApplyTemplate || hasAppliedTemplate ) {
 				return;
 			}
 
-			existingTemplateRef.current = template;
+			existingTemplateRef.current = resolvedTemplate;
 			const nextBlocks = synchronizeBlocksWithTemplate(
 				currentInnerBlocks,
-				template
+				resolvedTemplate
 			);
 
 			if ( ! fastDeepEqual( nextBlocks, currentInnerBlocks ) ) {
@@ -98,7 +122,7 @@ export default function useInnerBlockTemplateSync(
 					clientId,
 					nextBlocks,
 					currentInnerBlocks.length === 0 &&
-						templateInsertUpdatesSelection &&
+						resolvedUpdatesSelection &&
 						nextBlocks.length !== 0 &&
 						isBlockSelected( clientId ),
 					// This ensures the "initialPosition" doesn't change when applying the template

package/src/components/inner-blocks/use-nested-settings-update.js

@@ -1,14 +1,7 @@
-/**
- * WordPress dependencies
- */
 import { useLayoutEffect, useState } from '@wordpress/element';
 import { useRegistry } from '@wordpress/data';
 import deprecated from '@wordpress/deprecated';
 import { isShallowEqual } from '@wordpress/is-shallow-equal';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
 import { getLayoutType } from '../../layouts';
 

package/src/components/inner-content/index.js

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import {
 	createPortal,
 	useLayoutEffect,
@@ -10,10 +7,6 @@ import {
 } from '@wordpress/element';
 import { AsyncModeProvider, useSelect } from '@wordpress/data';
 import { safeHTML } from '@wordpress/dom';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
 import BlockListBlock from '../block-list/block';
 import { LayoutProvider } from '../block-list/layout';

package/src/components/inner-content/test/index.js

@@ -1,20 +1,9 @@
-/**
- * External dependencies
- */
 import { render } from '@testing-library/react';
-
-/**
- * WordPress dependencies
- */
 import {
 	createBlock,
 	registerBlockType,
 	unregisterBlockType,
 } from '@wordpress/blocks';
-
-/**
- * Internal dependencies
- */
 import InnerContent from '../';
 import { BlockEditorProvider } from '../../provider';
 

package/src/components/inserter/block-patterns-explorer/index.js

@@ -1,13 +1,7 @@
-/**
- * WordPress dependencies
- */
 import { Modal } from '@wordpress/components';
+import { Tabs } from '@wordpress/ui';
 import { useState } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-
-/**
- * Internal dependencies
- */
 import PatternExplorerSidebar from './pattern-explorer-sidebar';
 import PatternList from './pattern-list';
 import { usePatternCategories } from '../block-patterns-tab/use-pattern-categories';
@@ -21,22 +15,34 @@ function PatternsExplorer( { initialCategory, rootClientId, onModalClose } ) {
 	const patternCategories = usePatternCategories( rootClientId );
 
 	return (
-		<div className="block-editor-block-patterns-explorer">
+		<Tabs.Root
+			className="block-editor-block-patterns-explorer"
+			orientation="vertical"
+			value={ selectedCategory }
+			onValueChange={ setSelectedCategory }
+		>
 			<PatternExplorerSidebar
-				selectedCategory={ selectedCategory }
 				patternCategories={ patternCategories }
-				onClickCategory={ setSelectedCategory }
 				searchValue={ searchValue }
 				setSearchValue={ setSearchValue }
 			/>
-			<PatternList
-				searchValue={ searchValue }
-				selectedCategory={ selectedCategory }
-				patternCategories={ patternCategories }
-				rootClientId={ rootClientId }
-				onModalClose={ onModalClose }
-			/>
-		</div>
+			{ patternCategories.map( ( { name } ) => (
+				<Tabs.Panel
+					key={ name }
+					value={ name }
+					tabIndex={ -1 }
+					className="block-editor-block-patterns-explorer__panel"
+				>
+					<PatternList
+						searchValue={ searchValue }
+						selectedCategory={ name }
+						patternCategories={ patternCategories }
+						rootClientId={ rootClientId }
+						onModalClose={ onModalClose }
+					/>
+				</Tabs.Panel>
+			) ) }
+		</Tabs.Root>
 	);
 }
 

package/src/components/inserter/block-patterns-explorer/pattern-explorer-sidebar.js

@@ -1,73 +1,32 @@
-/**
- * WordPress dependencies
- */
-import { Button, SearchControl } from '@wordpress/components';
+import { SearchControl } from '@wordpress/components';
+import { Stack, Tabs } from '@wordpress/ui';
 import { __ } from '@wordpress/i18n';
 
-function PatternCategoriesList( {
-	selectedCategory,
+function PatternExplorerSidebar( {
 	patternCategories,
-	onClickCategory,
+	searchValue,
+	setSearchValue,
 } ) {
-	const baseClassName = 'block-editor-block-patterns-explorer__sidebar';
-	return (
-		<div className={ `${ baseClassName }__categories-list` }>
-			{ patternCategories.map( ( { name, label } ) => {
-				return (
-					<Button
-						__next40pxDefaultSize
-						key={ name }
-						label={ label }
-						className={ `${ baseClassName }__categories-list__item` }
-						isPressed={ selectedCategory === name }
-						onClick={ () => {
-							onClickCategory( name );
-						} }
-					>
-						{ label }
-					</Button>
-				);
-			} ) }
-		</div>
-	);
-}
-
-function PatternsExplorerSearch( { searchValue, setSearchValue } ) {
-	const baseClassName = 'block-editor-block-patterns-explorer__search';
 	return (
-		<div className={ baseClassName }>
+		<Stack
+			direction="column"
+			gap="lg"
+			className="block-editor-block-patterns-explorer__sidebar"
+		>
 			<SearchControl
 				onChange={ setSearchValue }
 				value={ searchValue }
 				label={ __( 'Search' ) }
 				placeholder={ __( 'Search' ) }
 			/>
-		</div>
-	);
-}
-
-function PatternExplorerSidebar( {
-	selectedCategory,
-	patternCategories,
-	onClickCategory,
-	searchValue,
-	setSearchValue,
-} ) {
-	const baseClassName = 'block-editor-block-patterns-explorer__sidebar';
-	return (
-		<div className={ baseClassName }>
-			<PatternsExplorerSearch
-				searchValue={ searchValue }
-				setSearchValue={ setSearchValue }
-			/>
-			{ ! searchValue && (
-				<PatternCategoriesList
-					selectedCategory={ selectedCategory }
-					patternCategories={ patternCategories }
-					onClickCategory={ onClickCategory }
-				/>
-			) }
-		</div>
+			<Tabs.List>
+				{ patternCategories.map( ( { name, label } ) => (
+					<Tabs.Tab key={ name } value={ name }>
+						{ label }
+					</Tabs.Tab>
+				) ) }
+			</Tabs.List>
+		</Stack>
 	);
 }