@wordpress/block-editor 16.1.0 → 17.0.0

package/src/components/block-keyboard-shortcuts/index.js

@@ -0,0 +1,256 @@
+import { useCallback, useEffect, useRef } from '@wordpress/element';
+import { useSelect, useDispatch } from '@wordpress/data';
+import {
+	useShortcut,
+	store as keyboardShortcutsStore,
+} from '@wordpress/keyboard-shortcuts';
+import { store as blocksStore, switchToBlockType } from '@wordpress/blocks';
+import warning from '@wordpress/warning';
+import { store as blockEditorStore } from '../../store';
+import { unlock } from '../../lock-unlock';
+
+/**
+ * Returns every keyboard shortcut declared by a registered block type, through
+ * either a block variation or a block transform.
+ *
+ * @return {Array} Declared shortcuts, each paired with the block change it makes.
+ */
+function useDeclaredBlockShortcuts() {
+	return useSelect(
+		( select ) =>
+			unlock( select( blocksStore ) ).getBlockKeyboardShortcuts(),
+		[]
+	);
+}
+
+/**
+ * Returns a callback applying a block-declared shortcut to the selected block.
+ *
+ * The callback reports whether the shortcut was relevant to the current
+ * selection, which is not the same as whether the block changed: a shortcut
+ * that resolves to the block's current state is still handled, so that the key
+ * combination is swallowed rather than typed into the block.
+ *
+ * @return {Function} Callback receiving a declared shortcut.
+ */
+function useApplyBlockShortcut() {
+	const {
+		getBlock,
+		getBlockName,
+		getBlockAttributes,
+		getBlockEditingMode,
+		getSelectedBlockClientId,
+	} = useSelect( blockEditorStore );
+	const { getBlockVariations, getActiveBlockVariation } =
+		useSelect( blocksStore );
+	const { replaceBlocks, updateBlockAttributes } =
+		useDispatch( blockEditorStore );
+
+	return useCallback(
+		( { targetBlockName, blockNames, variationName } ) => {
+			const clientId = getSelectedBlockClientId();
+			if ( ! clientId ) {
+				return false;
+			}
+
+			// Transforming a block is a structural change, so it is only
+			// allowed where the block is fully editable.
+			if ( getBlockEditingMode( clientId ) !== 'default' ) {
+				return false;
+			}
+
+			const blockName = getBlockName( clientId );
+			if ( ! blockNames.includes( blockName ) ) {
+				return false;
+			}
+
+			const variation = variationName
+				? getBlockVariations( targetBlockName )?.find(
+						( { name } ) => name === variationName
+				  )
+				: undefined;
+
+			// The block is already of the target type, so there is nothing to
+			// transform. Applying the variation's attributes is all that is
+			// left to do.
+			if ( blockName === targetBlockName ) {
+				if ( ! variation?.attributes ) {
+					return false;
+				}
+				const activeVariation = getActiveBlockVariation(
+					targetBlockName,
+					getBlockAttributes( clientId )
+				);
+				if ( activeVariation?.name !== variationName ) {
+					updateBlockAttributes( clientId, variation.attributes );
+				}
+				return true;
+			}
+
+			const block = getBlock( clientId );
+			if ( ! block ) {
+				return false;
+			}
+
+			// Prefer a transform declared for this specific variation, and
+			// fall back to transforming to the block type and applying the
+			// variation's attributes on top.
+			let blocks = variation
+				? switchToBlockType( block, targetBlockName, variation.name )
+				: null;
+
+			if ( ! blocks ) {
+				blocks = switchToBlockType( block, targetBlockName );
+
+				if ( blocks && variation?.attributes ) {
+					blocks = blocks.map( ( newBlock ) =>
+						newBlock.name === targetBlockName
+							? {
+									...newBlock,
+									attributes: {
+										...newBlock.attributes,
+										...variation.attributes,
+									},
+							  }
+							: newBlock
+					);
+				}
+			}
+
+			if ( ! blocks ) {
+				return false;
+			}
+
+			replaceBlocks( clientId, blocks );
+			return true;
+		},
+		[
+			getBlock,
+			getBlockName,
+			getBlockAttributes,
+			getBlockEditingMode,
+			getSelectedBlockClientId,
+			getBlockVariations,
+			getActiveBlockVariation,
+			replaceBlocks,
+			updateBlockAttributes,
+		]
+	);
+}
+
+function BlockShortcut( { entry, apply } ) {
+	useShortcut( entry.name, ( event ) => {
+		// Another handler already acted on this event: either a shortcut
+		// claiming the same key combination, or this same shortcut mounted
+		// twice because block editor providers can be nested.
+		if ( event.defaultPrevented ) {
+			return;
+		}
+
+		if ( apply( entry ) ) {
+			event.preventDefault();
+		}
+	} );
+
+	return null;
+}
+
+function BlockShortcutsRegister( { shortcuts } ) {
+	const { registerShortcut, unregisterShortcut } = useDispatch(
+		keyboardShortcutsStore
+	);
+	// Shortcuts registered by a previous run, keyed by name, so that those
+	// belonging to a block type that has since been unregistered can be
+	// removed. Registration deliberately outlives this component: providers can
+	// be nested, and unmounting one of them must not take the shortcuts away
+	// from the others.
+	const registeredRef = useRef( new Map() );
+
+	useEffect( () => {
+		const registered = new Map();
+		const combinations = new Map();
+
+		for ( const shortcut of shortcuts ) {
+			const config = {
+				name: shortcut.name,
+				category: 'block',
+				description: shortcut.description,
+				keyCombination: shortcut.keyCombination,
+				aliases: shortcut.aliases,
+			};
+			const serialized = JSON.stringify( config );
+
+			// One shortcut is declared once per block change it can make, so
+			// the same name legitimately appears more than once: the heading
+			// level shortcuts are declared both on the variation, for a
+			// heading, and on the transform that produces one from a
+			// paragraph. Only declarations that disagree are a mistake, since
+			// the store keys shortcuts by name and the last one registered
+			// would decide what the others are matched against.
+			const previous = registered.get( shortcut.name );
+			if ( previous !== undefined ) {
+				if ( previous !== serialized ) {
+					warning(
+						`Block keyboard shortcut "${ shortcut.name }" is declared more than once with different settings.`
+					);
+				}
+				continue;
+			}
+
+			// Handlers are matched by key combination rather than by name, so
+			// two shortcuts claiming the same one both run on the same event,
+			// in registration order, and the first that applies takes it.
+			const { modifier, character } = shortcut.keyCombination;
+			const combination = `${ modifier ?? '' }+${ character }`;
+			if ( combinations.has( combination ) ) {
+				warning(
+					`Block keyboard shortcut "${
+						shortcut.name
+					}" uses the same key combination as "${ combinations.get(
+						combination
+					) }".`
+				);
+			}
+			combinations.set( combination, shortcut.name );
+
+			registerShortcut( config );
+			registered.set( shortcut.name, serialized );
+		}
+
+		for ( const name of registeredRef.current.keys() ) {
+			if ( ! registered.has( name ) ) {
+				unregisterShortcut( name );
+			}
+		}
+
+		registeredRef.current = registered;
+	}, [ shortcuts, registerShortcut, unregisterShortcut ] );
+
+	return null;
+}
+
+/**
+ * Registers and handles the keyboard shortcuts that blocks declare on their
+ * variations and transforms, applying them to the selected block.
+ *
+ * @return {Element} Element.
+ */
+export default function BlockKeyboardShortcuts() {
+	const shortcuts = useDeclaredBlockShortcuts();
+	const apply = useApplyBlockShortcut();
+
+	return (
+		<>
+			<BlockShortcutsRegister shortcuts={ shortcuts } />
+			{ shortcuts.map( ( entry, index ) => (
+				<BlockShortcut
+					// Shortcut names are not guaranteed to be unique across
+					// blocks, so the index keeps the list stable.
+					key={ `${ entry.name }-${ index }` }
+					entry={ entry }
+					apply={ apply }
+				/>
+			) ) }
+		</>
+	);
+}

package/src/components/block-list/README.md

@@ -0,0 +1,98 @@
+# Block List
+
+The `BlockList` component is responsible for rendering a list of blocks within the WordPress block editor. It manages the layout, interactions, and UI behaviors for blocks within the editor interface, such as selection handling, focus management, and appender display.
+
+## Development guidelines
+
+`BlockList` is primarily used internally by the editor, but it is exported for consumers building their own block editor UI. It handles:
+
+-   **Block rendering:** Displays a list of blocks based on the provided `rootClientId`.
+-   **Selection and focus handling:** Manages block selection, focus state, and block visibility.
+-   **Zoom-out mode:** Provides UI behavior for zooming out from nested block structures.
+-   **Block editing mode integration:** Supports different block editing modes, including content-only editing and disabled states.
+-   **Block appender support:** Displays an appender UI when appropriate, allowing users to insert new blocks.
+
+To render the inner blocks of a specific block instead, prefer `useInnerBlocksProps` from the `InnerBlocks` component, which wires up the correct context for nested block lists.
+
+### Usage
+
+`BlockList` must be rendered within a `BlockEditorProvider`, and is usually placed inside a `BlockCanvas` so that the blocks render in the editor's writing flow.
+
+```jsx
+import { useState } from 'react';
+import {
+	BlockCanvas,
+	BlockEditorProvider,
+	BlockList,
+} from '@wordpress/block-editor';
+
+function MyEditor() {
+	const [ blocks, setBlocks ] = useState( [] );
+
+	return (
+		<BlockEditorProvider
+			value={ blocks }
+			onInput={ setBlocks }
+			onChange={ setBlocks }
+		>
+			<BlockCanvas height="400px">
+				<BlockList className="my-editor-block-list" />
+			</BlockCanvas>
+		</BlockEditorProvider>
+	);
+}
+```
+
+### Props
+
+#### `className`
+
+-   **Type:** `String`
+-   **Required:** No
+
+Additional class name applied to the block list's root container.
+
+#### `rootClientId`
+
+-   **Type:** `String`
+-   **Required:** No
+
+The client ID of the root block whose inner blocks will be rendered. If omitted, the top-level blocks are rendered.
+
+#### `placeholder`
+
+-   **Type:** `ReactNode`
+-   **Required:** No
+
+Content displayed in place of the blocks when the list is empty.
+
+#### `renderAppender`
+
+-   **Type:** `Function|false`
+-   **Required:** No
+
+A function rendering a custom appender, the UI used to insert new blocks at the end of the list. Pass `false` to suppress the appender entirely. When omitted, the standard block appender is rendered where appropriate.
+
+#### `layout`
+
+-   **Type:** `Object`
+-   **Required:** No
+-   **Default:** `{ type: 'default' }`
+
+The layout configuration applied to the blocks, affecting their positioning and arrangement.
+
+#### `__experimentalAppenderTagName`
+
+-   **Type:** `String`
+-   **Required:** No
+-   **Default:** `'div'`
+
+The tag name used for the appender element.
+
+_Note:_ This prop is experimental and may be removed or changed without notice.
+
+## Related components
+
+-   `BlockListBlock` - Renders individual blocks within the `BlockList`.
+-   `BlockListAppender` - Provides UI for adding new blocks.
+-   `useInnerBlocksProps` - Hook for managing inner blocks and their props.

package/src/components/block-list/block-crash-boundary.js

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { Component } from '@wordpress/element';
 
 class BlockCrashBoundary extends Component {

package/src/components/block-list/block-crash-warning.js

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { __ } from '@wordpress/i18n';
-
-/**
- * Internal dependencies
- */
 import Warning from '../warning';
 
 const warning = (

package/src/components/block-list/block-html.js

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import TextareaAutosize from 'react-autosize-textarea';
-
-/**
- * WordPress dependencies
- */
 import { useEffect, useMemo, useState } from '@wordpress/element';
 import { useSelect, useDispatch } from '@wordpress/data';
 import {
@@ -15,10 +8,6 @@ import {
 	getSaveContent,
 	validateBlock,
 } from '@wordpress/blocks';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
 import { useNativeUndo } from '../../utils/native-undo';
 

package/src/components/block-list/block-invalid-warning.js

@@ -1,15 +1,8 @@
-/**
- * WordPress dependencies
- */
 import { __, _x } from '@wordpress/i18n';
 import { Button, Modal } from '@wordpress/components';
 import { useState, useCallback, useMemo } from '@wordpress/element';
 import { createBlock, rawHandler } from '@wordpress/blocks';
 import { useDispatch, useSelect } from '@wordpress/data';
-
-/**
- * Internal dependencies
- */
 import Warning from '../warning';
 import BlockCompare from '../block-compare';
 import { store as blockEditorStore } from '../../store';

package/src/components/block-list/block.js

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import clsx from 'clsx';
-
-/**
- * WordPress dependencies
- */
 import { memo, RawHTML, useContext, useMemo } from '@wordpress/element';
 import {
 	getBlockType,
@@ -25,10 +18,6 @@ import { withFilters } from '@wordpress/components';
 import { withDispatch, useSelect } from '@wordpress/data';
 import { compose, useRefEffect } from '@wordpress/compose';
 import { safeHTML } from '@wordpress/dom';
-
-/**
- * Internal dependencies
- */
 import BlockEdit from '../block-edit';
 import BlockInvalidWarning from './block-invalid-warning';
 import BlockCrashWarning from './block-crash-warning';
@@ -357,7 +346,7 @@ const applyWithDispatch = withDispatch( ( dispatch, ownProps, registry ) => {
 
 				if (
 					blockOrder.length === 1 &&
-					isUnmodifiedBlock( getBlock( firstClientId ) )
+					isUnmodifiedBlock( getBlock( firstClientId ), 'content' )
 				) {
 					removeBlock( _clientId );
 				} else if ( isTextualWrapper ) {
@@ -404,7 +393,10 @@ const applyWithDispatch = withDispatch( ( dispatch, ownProps, registry ) => {
 
 						if (
 							! getBlockOrder( _clientId ).length &&
-							isUnmodifiedBlock( getBlock( _clientId ) )
+							isUnmodifiedBlock(
+								getBlock( _clientId ),
+								'content'
+							)
 						) {
 							removeBlock( _clientId, false );
 						}
@@ -464,7 +456,23 @@ const applyWithDispatch = withDispatch( ( dispatch, ownProps, registry ) => {
 					return;
 				}
 
-				if ( getBlockOrder( nextBlockClientId ).length ) {
+				// Forward deleting an unmodified default block should
+				// remove it and move into the next block, not pull the
+				// next block's first item out of it.
+				if ( isUnmodifiedDefaultBlock( getBlock( clientId ) ) ) {
+					// Select the first leaf block, so the caret starts at
+					// the beginning of the block's content rather than on
+					// a container's shell.
+					let firstLeafClientId = nextBlockClientId;
+					while ( getBlockOrder( firstLeafClientId ).length ) {
+						firstLeafClientId =
+							getBlockOrder( firstLeafClientId )[ 0 ];
+					}
+					registry.batch( () => {
+						removeBlock( clientId );
+						selectBlock( firstLeafClientId );
+					} );
+				} else if ( getBlockOrder( nextBlockClientId ).length ) {
 					moveFirstItemUp( nextBlockClientId, false );
 				} else {
 					mergeBlocks( clientId, nextBlockClientId );
@@ -558,7 +566,19 @@ BlockListBlock = compose(
 // context to pass the rest of the information to the filtered BlockListBlock
 // component, and useBlockProps.
 function BlockListBlockProvider( props ) {
-	const { clientId, rootClientId } = props;
+	const { clientId, rootClientId, ghostBlock } = props;
+	// Stable fallback so the selector returns referentially equal values.
+	const ghostBlockWithoutAttributes = useMemo(
+		() =>
+			ghostBlock
+				? {
+						clientId: ghostBlock.clientId,
+						name: ghostBlock.name,
+						isValid: true,
+				  }
+				: undefined,
+		[ ghostBlock ]
+	);
 	const selectedProps = useSelect(
 		( select ) => {
 			const {
@@ -594,7 +614,12 @@ function BlockListBlockProvider( props ) {
 				getSelectedBlocksInitialCaretPosition,
 			} = unlock( select( blockEditorStore ) );
 			const blockWithoutAttributes =
-				getBlockWithoutAttributes( clientId );
+				getBlockWithoutAttributes( clientId ) ??
+				// An appender ghost renders from its block object until it
+				// is inserted on entry; it is never selected before that.
+				( clientId === ghostBlockWithoutAttributes?.clientId
+					? ghostBlockWithoutAttributes
+					: undefined );
 
 			// This is a temporary fix.
 			// This function should never be called when a block is not
@@ -608,7 +633,8 @@ function BlockListBlockProvider( props ) {
 				hasBlockSupport: _hasBlockSupport,
 				getActiveBlockVariation,
 			} = select( blocksStore );
-			const attributes = getBlockAttributes( clientId );
+			const attributes =
+				getBlockAttributes( clientId ) ?? ghostBlock?.attributes;
 			const { name: blockName, isValid } = blockWithoutAttributes;
 			const blockType = getBlockType( blockName );
 			const settings = getSettings();
@@ -666,9 +692,17 @@ function BlockListBlockProvider( props ) {
 				clientId,
 				checkDeep
 			);
-			const sectionBlockClientId = _isSectionBlock( clientId )
+			const isSectionBlock = _isSectionBlock( clientId );
+			const sectionBlockClientId = isSectionBlock
 				? clientId
 				: getParentSectionBlock( clientId );
+			// Without a section block there is nothing for the deep check to
+			// match, and it walks the parents of every selected block to find
+			// that out.
+			const isSelectionWithinCurrentSection =
+				isBlockSelected( sectionBlockClientId ) ||
+				( !! sectionBlockClientId &&
+					hasSelectedInnerBlock( sectionBlockClientId, checkDeep ) );
 
 			const multiple = hasBlockSupport( blockName, 'multiple', true );
 
@@ -686,11 +720,9 @@ function BlockListBlockProvider( props ) {
 				mode: getBlockMode( clientId ),
 				isSelectionEnabled: isSelectionEnabled(),
 				isLocked: !! getTemplateLock( rootClientId ),
-				isSectionBlock: _isSectionBlock( clientId ),
+				isSectionBlock,
 				isWithinSectionBlock: !! sectionBlockClientId,
-				isSelectionWithinCurrentSection:
-					isBlockSelected( sectionBlockClientId ) ||
-					hasSelectedInnerBlock( sectionBlockClientId, checkDeep ),
+				isSelectionWithinCurrentSection,
 				blockType,
 				canRemove,
 				canMove,
@@ -739,9 +771,14 @@ function BlockListBlockProvider( props ) {
 				blockVisibility,
 				deviceType,
 				viewportSettings,
+				supportsSplitting: hasBlockSupport(
+					blockName,
+					'splitting',
+					false
+				),
 			};
 		},
-		[ clientId, rootClientId ]
+		[ clientId, rootClientId, ghostBlock, ghostBlockWithoutAttributes ]
 	);
 
 	const defaultViewRef = useRefEffect( ( element ) => {
@@ -822,10 +859,13 @@ function BlockListBlockProvider( props ) {
 		blockVisibility,
 		deviceType,
 		viewportSettings,
+		supportsSplitting,
 	} = selectedProps;
 
 	const privateContext = {
 		isPreviewMode,
+		ghostBlock,
+		rootClientId,
 		clientId,
 		className,
 		index,
@@ -862,6 +902,7 @@ function BlockListBlockProvider( props ) {
 		blockVisibility,
 		deviceType,
 		viewportSettings,
+		supportsSplitting,
 	};
 
 	if (