@wordpress/block-editor 16.0.1-next.v.202607070741.0 → 16.2.0

package/src/components/block-inspector/useBlockInspectorAnimationSettings.js

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { useSelect } from '@wordpress/data';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
 
 export default function useBlockInspectorAnimationSettings( blockType ) {

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,14 +8,12 @@ import {
 	getSaveContent,
 	validateBlock,
 } from '@wordpress/blocks';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
+import { useNativeUndo } from '../../utils/native-undo';
 
 function BlockHTML( { clientId } ) {
 	const [ html, setHtml ] = useState( '' );
+	const nativeUndoRef = useNativeUndo();
 	const block = useSelect(
 		( select ) => select( blockEditorStore ).getBlock( clientId ),
 		[ clientId ]
@@ -83,6 +74,9 @@ function BlockHTML( { clientId } ) {
 			value={ html }
 			onBlur={ onChange }
 			onChange={ ( event ) => setHtml( event.target.value ) }
+			// The edits are local state until committed on blur, so undo
+			// and redo must remain the browser's own within the field.
+			ref={ nativeUndoRef }
 		/>
 	);
 }

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();
@@ -622,6 +648,7 @@ function BlockListBlockProvider( props ) {
 			const blockVisibility = attributes?.metadata?.blockVisibility;
 			const deviceType =
 				settings?.[ deviceTypeKey ]?.toLowerCase() || 'desktop';
+			const viewportSettings = settings?.__experimentalFeatures?.viewport;
 
 			const hasLightBlockWrapper = blockType?.apiVersion > 1;
 			const isMultiSelected = isBlockMultiSelected( clientId );
@@ -645,6 +672,7 @@ function BlockListBlockProvider( props ) {
 				bindableAttributes,
 				blockVisibility,
 				deviceType,
+				viewportSettings,
 				isMultiSelected,
 				blockEditingMode,
 				isEditingDisabled: blockEditingMode === 'disabled',
@@ -664,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 );
 
@@ -684,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,
@@ -736,9 +770,10 @@ function BlockListBlockProvider( props ) {
 					: false,
 				blockVisibility,
 				deviceType,
+				viewportSettings,
 			};
 		},
-		[ clientId, rootClientId ]
+		[ clientId, rootClientId, ghostBlock, ghostBlockWithoutAttributes ]
 	);
 
 	const defaultViewRef = useRefEffect( ( element ) => {
@@ -753,6 +788,7 @@ function BlockListBlockProvider( props ) {
 	const { isBlockCurrentlyHidden } = useBlockVisibility( {
 		blockVisibility: selectedProps?.blockVisibility,
 		deviceType: selectedProps?.deviceType,
+		viewportSettings: selectedProps?.viewportSettings,
 		view: defaultViewRef.current,
 	} );
 
@@ -817,10 +853,13 @@ function BlockListBlockProvider( props ) {
 		bindableAttributes,
 		blockVisibility,
 		deviceType,
+		viewportSettings,
 	} = selectedProps;
 
 	const privateContext = {
 		isPreviewMode,
+		ghostBlock,
+		rootClientId,
 		clientId,
 		className,
 		index,
@@ -856,6 +895,7 @@ function BlockListBlockProvider( props ) {
 		bindableAttributes,
 		blockVisibility,
 		deviceType,
+		viewportSettings,
 	};
 
 	if (

package/src/components/block-list/content.scss

@@ -347,8 +347,7 @@ _::-webkit-full-page-media, _:future, :root [data-has-multi-selection="true"] .b
 	}
 }
 
-// Hide the appender that sits at the end of block lists, when inside a nested block,
-// unless the block itself, or a parent, is selected.
+// Fade in the appender that sits at the end of block lists.
 .wp-block .block-list-appender .block-editor-inserter__toggle {
 	@media not ( prefers-reduced-motion ) {
 		animation: block-editor-inserter__toggle__fade-in-animation 0.1s ease;
@@ -356,15 +355,6 @@ _::-webkit-full-page-media, _:future, :root [data-has-multi-selection="true"] .b
 	}
 }
 
-.block-editor-block-list__block:not(.is-selected):not(.has-child-selected) .block-editor-default-block-appender {
-	display: none;
-
-	.block-editor-inserter__toggle {
-		opacity: 0;
-		transform: scale(0);
-	}
-}
-
 .block-editor-block-list__block .block-editor-block-list__block-html-textarea {
 	display: block;
 	margin: 0;

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

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import clsx from 'clsx';
-
-/**
- * WordPress dependencies
- */
 import {
 	AsyncModeProvider,
 	useSelect,
@@ -19,11 +12,7 @@ import {
 	useMemo,
 	useCallback,
 } from '@wordpress/element';
-import { getDefaultBlockName } from '@wordpress/blocks';
-
-/**
- * Internal dependencies
- */
+import { createBlock, getDefaultBlockName } from '@wordpress/blocks';
 import BlockListBlock from './block';
 import BlockListAppender from '../block-list-appender';
 import { useInBetweenInserter } from './use-in-between-inserter';
@@ -35,7 +24,6 @@ import {
 	BlockEditContextProvider,
 	DEFAULT_BLOCK_EDIT_CONTEXT,
 } from '../block-edit/context';
-import { useTypingObserver } from '../observe-typing';
 import { ZoomOutSeparator } from './zoom-out-separator';
 import { unlock } from '../../lock-unlock';
 
@@ -113,7 +101,6 @@ function Root( { className, ...settings } ) {
 			ref: useMergeRefs( [
 				useBlockSelectionClearer(),
 				useInBetweenInserter(),
-				useTypingObserver(),
 			] ),
 			className: clsx( 'is-root-container', className, {
 				'is-outline-mode': isOutlineMode,
@@ -191,6 +178,8 @@ function Items( {
 		isZoomOut,
 		selectedBlocks,
 		visibleBlocks,
+		ghostBlockName,
+		ghostBlockAttributes,
 		shouldRenderAppender,
 	} = useSelect(
 		( select ) => {
@@ -204,6 +193,7 @@ function Items( {
 				isSectionBlock,
 				isContainerInsertableToInContentOnlyMode,
 				getBlockName,
+				getBlockListSettings,
 				isZoomOut: _isZoomOut,
 				canInsertBlockType,
 			} = unlock( select( blockEditorStore ) );
@@ -218,6 +208,25 @@ function Items( {
 				};
 			}
 
+			// A block list without a custom appender renders a ghost of
+			// the container's default block while empty: a real block
+			// object rendered before it exists in the store, inserted on
+			// entry.
+			let _ghostBlockName;
+			let _ghostBlockAttributes;
+			if ( hasAppender && ! hasCustomAppender && ! _order.length ) {
+				const defaultBlock = ( rootClientId
+					? getBlockListSettings( rootClientId )?.defaultBlock
+					: undefined ) ?? { name: getDefaultBlockName() };
+				if (
+					defaultBlock.name &&
+					canInsertBlockType( defaultBlock.name, rootClientId )
+				) {
+					_ghostBlockName = defaultBlock.name;
+					_ghostBlockAttributes = defaultBlock.attributes;
+				}
+			}
+
 			const selectedBlockClientIds = getSelectedBlockClientIds();
 			const selectedBlockClientId = selectedBlockClientIds[ 0 ];
 			const showRootAppender =
@@ -236,21 +245,28 @@ function Items( {
 
 			const templateLock = getTemplateLock( rootClientId );
 
+			const appenderAllowed =
+				( ! isSectionBlock( rootClientId ) ||
+					isContainerInsertableToInContentOnlyMode(
+						getBlockName( selectedBlockClientId ),
+						rootClientId
+					) ) &&
+				getBlockEditingMode( rootClientId ) !== 'disabled' &&
+				( ! templateLock || templateLock === 'contentOnly' ) &&
+				hasAppender &&
+				! _isZoomOut();
+
 			return {
 				order: _order,
 				selectedBlocks: selectedBlockClientIds,
 				visibleBlocks: __unstableGetVisibleBlocks(),
 				isZoomOut: _isZoomOut(),
+				// The ghost is the block list's empty state: it renders
+				// whether or not the block is selected.
+				ghostBlockName: appenderAllowed ? _ghostBlockName : undefined,
+				ghostBlockAttributes: _ghostBlockAttributes,
 				shouldRenderAppender:
-					( ! isSectionBlock( rootClientId ) ||
-						isContainerInsertableToInContentOnlyMode(
-							getBlockName( selectedBlockClientId ),
-							rootClientId
-						) ) &&
-					getBlockEditingMode( rootClientId ) !== 'disabled' &&
-					( ! templateLock || templateLock === 'contentOnly' ) &&
-					hasAppender &&
-					! _isZoomOut() &&
+					appenderAllowed &&
 					( hasCustomAppender ||
 						hasSelectedRoot ||
 						showRootAppender ),
@@ -259,14 +275,29 @@ function Items( {
 		[ rootClientId, hasAppender, hasCustomAppender ]
 	);
 
+	// One ghost per empty period: regenerated when the list empties again
+	// or the default block changes, stable in between so the client ID,
+	// and with it the DOM, survives materialization.
+	const ghostBlock = useMemo(
+		() =>
+			ghostBlockName
+				? createBlock( ghostBlockName, ghostBlockAttributes )
+				: null,
+		[ ghostBlockName, ghostBlockAttributes ]
+	);
+	const showGhost = !! ghostBlock;
+
+	const items = showGhost ? [ ...order, ghostBlock.clientId ] : order;
+
 	return (
 		<LayoutProvider value={ layout }>
-			{ order.map( ( clientId ) => (
+			{ items.map( ( clientId ) => (
 				<AsyncModeProvider
 					key={ clientId }
 					value={
 						// Only provide data asynchronously if the block is
-						// not visible and not selected.
+						// not visible, not selected, and not the ghost.
+						clientId !== ghostBlock?.clientId &&
 						! visibleBlocks.has( clientId ) &&
 						! selectedBlocks.includes( clientId )
 					}
@@ -281,6 +312,11 @@ function Items( {
 					<BlockListBlock
 						rootClientId={ rootClientId }
 						clientId={ clientId }
+						ghostBlock={
+							clientId === ghostBlock?.clientId
+								? ghostBlock
+								: undefined
+						}
 					/>
 					{ isZoomOut && (
 						<ZoomOutSeparator
@@ -292,7 +328,7 @@ function Items( {
 				</AsyncModeProvider>
 			) ) }
 			{ order.length < 1 && placeholder }
-			{ shouldRenderAppender && (
+			{ shouldRenderAppender && ! showGhost && (
 				<BlockListAppender
 					tagName={ __experimentalAppenderTagName }
 					rootClientId={ rootClientId }

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

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { createContext, useContext } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import { getLayoutType } from '../../layouts';
 import { useSettings } from '../use-settings';
 

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

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { createContext } from '@wordpress/element';
 
 export const PrivateBlockContext = createContext( {} );

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

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { SVG, Path } from '@wordpress/components';
 import { isRTL } from '@wordpress/i18n';