@wordpress/block-editor 11.6.0 → 11.8.0

package/src/components/list-view/appender.js

@@ -0,0 +1,101 @@
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { speak } from '@wordpress/a11y';
+import { useSelect } from '@wordpress/data';
+import { forwardRef, useState, useEffect } from '@wordpress/element';
+import { __, sprintf } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { store as blockEditorStore } from '../../store';
+import useBlockDisplayTitle from '../block-title/use-block-display-title';
+import Inserter from '../inserter';
+
+export const Appender = forwardRef(
+	( { nestingLevel, blockCount, clientId, ...props }, ref ) => {
+		const [ insertedBlock, setInsertedBlock ] = useState( null );
+
+		const instanceId = useInstanceId( Appender );
+		const { hideInserter } = useSelect(
+			( select ) => {
+				const { getTemplateLock, __unstableGetEditorMode } =
+					select( blockEditorStore );
+
+				return {
+					hideInserter:
+						!! getTemplateLock( clientId ) ||
+						__unstableGetEditorMode() === 'zoom-out',
+				};
+			},
+			[ clientId ]
+		);
+
+		const blockTitle = useBlockDisplayTitle( {
+			clientId,
+			context: 'list-view',
+		} );
+
+		const insertedBlockTitle = useBlockDisplayTitle( {
+			clientId: insertedBlock?.clientId,
+			context: 'list-view',
+		} );
+
+		useEffect( () => {
+			if ( ! insertedBlockTitle?.length ) {
+				return;
+			}
+
+			speak(
+				sprintf(
+					// translators: %s: name of block being inserted (i.e. Paragraph, Image, Group etc)
+					__( '%s block inserted' ),
+					insertedBlockTitle
+				),
+				'assertive'
+			);
+		}, [ insertedBlockTitle ] );
+
+		if ( hideInserter ) {
+			return null;
+		}
+
+		const descriptionId = `list-view-appender__${ instanceId }`;
+		const description = sprintf(
+			/* translators: 1: The name of the block. 2: The numerical position of the block. 3: The level of nesting for the block. */
+			__( 'Append to %1$s block at position %2$d, Level %3$d' ),
+			blockTitle,
+			blockCount + 1,
+			nestingLevel
+		);
+
+		return (
+			<div className="list-view-appender">
+				<Inserter
+					ref={ ref }
+					rootClientId={ clientId }
+					position="bottom right"
+					isAppender
+					selectBlockOnInsert={ false }
+					shouldDirectInsert={ false }
+					__experimentalIsQuick
+					{ ...props }
+					toggleProps={ { 'aria-describedby': descriptionId } }
+					onSelectOrClose={ ( maybeInsertedBlock ) => {
+						if ( maybeInsertedBlock?.clientId ) {
+							setInsertedBlock( maybeInsertedBlock );
+						}
+					} }
+				/>
+				<div
+					className="list-view-appender__description"
+					id={ descriptionId }
+				>
+					{ description }
+				</div>
+			</div>
+		);
+	}
+);

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

@@ -33,7 +33,6 @@ import {
 	BlockMoverDownButton,
 } from '../block-mover/button';
 import ListViewBlockContents from './block-contents';
-import BlockSettingsDropdown from '../block-settings-menu/block-settings-dropdown';
 import { useListViewContext } from './context';
 import { getBlockPositionDescription } from './utils';
 import { store as blockEditorStore } from '../../store';
@@ -135,7 +134,8 @@ function ListViewBlock( {
 		  )
 		: __( 'Options' );
 
-	const { isTreeGridMounted, expand, collapse } = useListViewContext();
+	const { isTreeGridMounted, expand, collapse, BlockSettingsMenu } =
+		useListViewContext();
 
 	const hasSiblings = siblingBlockCount > 0;
 	const hasRenderedMovers = showBlockMovers && hasSiblings;
@@ -248,6 +248,7 @@ function ListViewBlock( {
 			path={ path }
 			id={ `list-view-block-${ clientId }` }
 			data-block={ clientId }
+			data-expanded={ canExpand ? isExpanded : undefined }
 			isExpanded={ canExpand ? isExpanded : undefined }
 			aria-selected={ !! isSelected || forceSelectionContentLock }
 			ref={ rowRef }
@@ -321,14 +322,15 @@ function ListViewBlock( {
 				</>
 			) }
 
-			{ showBlockActions && (
+			{ showBlockActions && BlockSettingsMenu && (
 				<TreeGridCell
 					className={ listViewBlockSettingsClassName }
 					aria-selected={ !! isSelected || forceSelectionContentLock }
 				>
 					{ ( { ref, tabIndex, onFocus } ) => (
-						<BlockSettingsDropdown
+						<BlockSettingsMenu
 							clientIds={ dropdownClientIds }
+							block={ block }
 							icon={ moreVertical }
 							label={ settingsAriaLabel }
 							toggleProps={ {

package/src/components/list-view/branch.js

@@ -1,12 +1,17 @@
 /**
  * WordPress dependencies
  */
+import {
+	__experimentalTreeGridRow as TreeGridRow,
+	__experimentalTreeGridCell as TreeGridCell,
+} from '@wordpress/components';
 import { memo } from '@wordpress/element';
 import { AsyncModeProvider, useSelect } from '@wordpress/data';
 
 /**
  * Internal dependencies
  */
+import { Appender } from './appender';
 import ListViewBlock from './block';
 import { useListViewContext } from './context';
 import { isClientIdSelected } from './utils';
@@ -93,6 +98,7 @@ function ListViewBranch( props ) {
 		parentId,
 		shouldShowInnerBlocks = true,
 		isSyncedBranch = false,
+		showAppender: showAppenderProp = true,
 	} = props;
 
 	const parentBlockInformation = useBlockDisplayInformation( parentId );
@@ -120,8 +126,12 @@ function ListViewBranch( props ) {
 		return null;
 	}
 
+	// Only show the appender at the first level.
+	const showAppender = showAppenderProp && level === 1;
 	const filteredBlocks = blocks.filter( Boolean );
 	const blockCount = filteredBlocks.length;
+	// The appender means an extra row in List View, so add 1 to the row count.
+	const rowCount = showAppender ? blockCount + 1 : blockCount;
 	let nextPosition = listPosition;
 
 	return (
@@ -175,7 +185,7 @@ function ListViewBranch( props ) {
 								isDragged={ isDragged }
 								level={ level }
 								position={ position }
-								rowCount={ blockCount }
+								rowCount={ rowCount }
 								siblingBlockCount={ blockCount }
 								showBlockMovers={ showBlockMovers }
 								path={ updatedPath }
@@ -209,6 +219,25 @@ function ListViewBranch( props ) {
 					</AsyncModeProvider>
 				);
 			} ) }
+			{ showAppender && (
+				<TreeGridRow
+					level={ level }
+					setSize={ rowCount }
+					positionInSet={ rowCount }
+					isExpanded={ true }
+				>
+					<TreeGridCell>
+						{ ( treeGridCellProps ) => (
+							<Appender
+								clientId={ parentId }
+								nestingLevel={ level }
+								blockCount={ blockCount }
+								{ ...treeGridCellProps }
+							/>
+						) }
+					</TreeGridCell>
+				</TreeGridRow>
+			) }
 		</>
 	);
 }

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

@@ -7,6 +7,7 @@ import {
 } from '@wordpress/compose';
 import { __experimentalTreeGrid as TreeGrid } from '@wordpress/components';
 import { AsyncModeProvider, useSelect } from '@wordpress/data';
+import deprecated from '@wordpress/deprecated';
 import {
 	useCallback,
 	useEffect,
@@ -28,6 +29,7 @@ import useListViewClientIds from './use-list-view-client-ids';
 import useListViewDropZone from './use-list-view-drop-zone';
 import useListViewExpandSelectedItem from './use-list-view-expand-selected-item';
 import { store as blockEditorStore } from '../../store';
+import { BlockSettingsDropdown } from '../block-settings-menu/block-settings-dropdown';
 
 const expanded = ( state, action ) => {
 	if ( Array.isArray( action.clientIds ) ) {
@@ -47,22 +49,47 @@ const expanded = ( state, action ) => {
 
 export const BLOCK_LIST_ITEM_HEIGHT = 36;
 
+/** @typedef {import('react').ComponentType} ComponentType */
+/** @typedef {import('react').Ref<HTMLElement>} Ref */
+
 /**
  * Show a hierarchical list of blocks.
  *
- * @param {Object}  props                 Components props.
- * @param {string}  props.id              An HTML element id for the root element of ListView.
- * @param {Array}   props.blocks          Custom subset of block client IDs to be used instead of the default hierarchy.
- * @param {boolean} props.showBlockMovers Flag to enable block movers
- * @param {boolean} props.isExpanded      Flag to determine whether nested levels are expanded by default.
- * @param {Object}  ref                   Forwarded ref
+ * @param {Object}         props                   Components props.
+ * @param {string}         props.id                An HTML element id for the root element of ListView.
+ * @param {Array}          props.blocks            _deprecated_ Custom subset of block client IDs to be used instead of the default hierarchy.
+ * @param {?boolean}       props.showBlockMovers   Flag to enable block movers. Defaults to `false`.
+ * @param {?boolean}       props.isExpanded        Flag to determine whether nested levels are expanded by default. Defaults to `false`.
+ * @param {?boolean}       props.showAppender      Flag to show or hide the block appender. Defaults to `false`.
+ * @param {?ComponentType} props.blockSettingsMenu Optional more menu substitution. Defaults to the standard `BlockSettingsDropdown` component.
+ * @param {string}         props.rootClientId      The client id of the root block from which we determine the blocks to show in the list.
+ * @param {Ref}            ref                     Forwarded ref
  */
-function ListView(
-	{ id, blocks, showBlockMovers = false, isExpanded = false },
+function ListViewComponent(
+	{
+		id,
+		blocks,
+		showBlockMovers = false,
+		isExpanded = false,
+		showAppender = false,
+		blockSettingsMenu: BlockSettingsMenu = BlockSettingsDropdown,
+		rootClientId,
+	},
 	ref
 ) {
+	// This can be removed once we no longer need to support the blocks prop.
+	if ( blocks ) {
+		deprecated(
+			'`blocks` property in `wp.blockEditor.__experimentalListView`',
+			{
+				since: '6.3',
+				alternative: '`rootClientId` property',
+			}
+		);
+	}
+
 	const { clientIdsTree, draggedClientIds, selectedClientIds } =
-		useListViewClientIds( blocks );
+		useListViewClientIds( { blocks, rootClientId } );
 
 	const { visibleBlockCount, shouldShowInnerBlocks } = useSelect(
 		( select ) => {
@@ -170,8 +197,16 @@ function ListView(
 			expandedState,
 			expand,
 			collapse,
+			BlockSettingsMenu,
 		} ),
-		[ isMounted.current, draggedClientIds, expandedState, expand, collapse ]
+		[
+			isMounted.current,
+			draggedClientIds,
+			expandedState,
+			expand,
+			collapse,
+			BlockSettingsMenu,
+		]
 	);
 
 	// If there are no blocks to show, do not render the list view.
@@ -198,16 +233,30 @@ function ListView(
 				<ListViewContext.Provider value={ contextValue }>
 					<ListViewBranch
 						blocks={ clientIdsTree }
+						parentId={ rootClientId }
 						selectBlock={ selectEditorBlock }
 						showBlockMovers={ showBlockMovers }
 						fixedListWindow={ fixedListWindow }
 						selectedClientIds={ selectedClientIds }
 						isExpanded={ isExpanded }
 						shouldShowInnerBlocks={ shouldShowInnerBlocks }
+						showAppender={ showAppender }
 					/>
 				</ListViewContext.Provider>
 			</TreeGrid>
 		</AsyncModeProvider>
 	);
 }
-export default forwardRef( ListView );
+export const PrivateListView = forwardRef( ListViewComponent );
+
+export default forwardRef( ( props, ref ) => {
+	return (
+		<PrivateListView
+			ref={ ref }
+			{ ...props }
+			showAppender={ false }
+			blockSettingsMenu={ BlockSettingsDropdown }
+			rootClientId={ null }
+		/>
+	);
+} );

package/src/components/list-view/style.scss

@@ -400,7 +400,9 @@ $block-navigation-max-indent: 8;
 
 	.block-editor-list-view-drop-indicator__line {
 		background: var(--wp-admin-theme-color);
-		height: $border-width;
+		height: 6px;
+		border: 1px solid $white;
+		border-radius: 4px;
 	}
 }
 
@@ -410,3 +412,22 @@ $block-navigation-max-indent: 8;
 	height: 36px;
 }
 
+.list-view-appender .block-editor-inserter__toggle {
+	background-color: #1e1e1e;
+	color: #fff;
+	margin: $grid-unit-10 0 0 24px;
+	border-radius: 2px;
+	height: 24px;
+	min-width: 24px;
+	padding: 0;
+
+	&:hover,
+	&:focus {
+		background: var(--wp-admin-theme-color);
+		color: #fff;
+	}
+}
+
+.list-view-appender__description {
+	display: none;
+}

package/src/components/list-view/test/use-list-view-drop-zone.js

@@ -0,0 +1,188 @@
+/**
+ * Internal dependencies
+ */
+import { getListViewDropTarget } from '../use-list-view-drop-zone';
+
+describe( 'getListViewDropTarget', () => {
+	const blocksData = [
+		{
+			blockIndex: 0,
+			canInsertDraggedBlocksAsChild: true,
+			canInsertDraggedBlocksAsSibling: true,
+			clientId: 'block-1',
+			element: {
+				getBoundingClientRect: () => ( {
+					top: 50,
+					bottom: 100,
+					left: 10,
+					right: 100,
+					x: 10,
+					y: 50,
+					width: 90,
+					height: 50,
+				} ),
+			},
+			innerBlockCount: 1,
+			isDraggedBlock: false,
+			isExpanded: true,
+			rootClientId: '',
+		},
+		{
+			blockIndex: 0,
+			canInsertDraggedBlocksAsChild: true,
+			canInsertDraggedBlocksAsSibling: true,
+			clientId: 'block-2',
+			element: {
+				getBoundingClientRect: () => ( {
+					top: 100,
+					bottom: 150,
+					left: 10,
+					right: 100,
+					x: 10,
+					y: 100,
+					width: 90,
+					height: 50,
+				} ),
+			},
+			innerBlockCount: 0,
+			isDraggedBlock: false,
+			isExpanded: false,
+			rootClientId: 'block-1',
+		},
+		{
+			blockIndex: 1,
+			canInsertDraggedBlocksAsChild: true,
+			canInsertDraggedBlocksAsSibling: true,
+			clientId: 'block-3',
+			element: {
+				getBoundingClientRect: () => ( {
+					top: 150,
+					bottom: 150,
+					left: 10,
+					right: 100,
+					x: 10,
+					y: 150,
+					width: 90,
+					height: 50,
+				} ),
+			},
+			innerBlockCount: 0,
+			isDraggedBlock: false,
+			isExpanded: false,
+			rootClientId: '',
+		},
+	];
+
+	it( 'should return the correct target when dragging a block over the top half of the first block', () => {
+		const position = { x: 50, y: 70 };
+		const target = getListViewDropTarget( blocksData, position );
+
+		expect( target ).toEqual( {
+			blockIndex: 0,
+			clientId: 'block-1',
+			dropPosition: 'top',
+			rootClientId: '',
+		} );
+	} );
+
+	it( 'should nest when dragging a block over the bottom half of an expanded block', () => {
+		const position = { x: 50, y: 90 };
+		const target = getListViewDropTarget( blocksData, position );
+
+		expect( target ).toEqual( {
+			blockIndex: 0,
+			dropPosition: 'inside',
+			rootClientId: 'block-1',
+		} );
+	} );
+
+	it( 'should nest when dragging a block over the right side and bottom half of a collapsed block with children', () => {
+		const position = { x: 70, y: 90 };
+
+		const collapsedBlockData = [ ...blocksData ];
+
+		// Set the first block to be collapsed.
+		collapsedBlockData[ 0 ] = {
+			...collapsedBlockData[ 0 ],
+			isExpanded: false,
+		};
+
+		// Hide the first block's children.
+		collapsedBlockData.splice( 1, 1 );
+
+		const target = getListViewDropTarget( collapsedBlockData, position );
+
+		expect( target ).toEqual( {
+			blockIndex: 0,
+			dropPosition: 'inside',
+			rootClientId: 'block-1',
+		} );
+	} );
+
+	it( 'should drag below when dragging a block over the left side and bottom half of a collapsed block with children', () => {
+		const position = { x: 30, y: 90 };
+
+		const collapsedBlockData = [ ...blocksData ];
+
+		// Set the first block to be collapsed.
+		collapsedBlockData[ 0 ] = {
+			...collapsedBlockData[ 0 ],
+			isExpanded: false,
+		};
+
+		// Hide the first block's children.
+		collapsedBlockData.splice( 1, 1 );
+
+		const target = getListViewDropTarget( collapsedBlockData, position );
+
+		expect( target ).toEqual( {
+			blockIndex: 1,
+			clientId: 'block-1',
+			dropPosition: 'bottom',
+			rootClientId: '',
+		} );
+	} );
+
+	it( 'should drag below when attempting to nest but the dragged block is not allowed as a child', () => {
+		const position = { x: 70, y: 90 };
+
+		const childNotAllowedBlockData = [ ...blocksData ];
+
+		// Set the first block to not be allowed as a child.
+		childNotAllowedBlockData[ 0 ] = {
+			...childNotAllowedBlockData[ 0 ],
+			canInsertDraggedBlocksAsChild: false,
+		};
+
+		const target = getListViewDropTarget(
+			childNotAllowedBlockData,
+			position
+		);
+
+		expect( target ).toEqual( {
+			blockIndex: 1,
+			clientId: 'block-1',
+			dropPosition: 'bottom',
+			rootClientId: '',
+		} );
+	} );
+
+	it( 'should return undefined when the dragged block cannot be inserted as a sibling', () => {
+		const position = { x: 50, y: 70 };
+
+		const siblingNotAllowedBlockData = [ ...blocksData ];
+
+		// Set the first block to not be allowed as a sibling.
+		siblingNotAllowedBlockData[ 0 ] = {
+			...siblingNotAllowedBlockData[ 0 ],
+			canInsertDraggedBlocksAsSibling: false,
+		};
+
+		const target = getListViewDropTarget(
+			siblingNotAllowedBlockData,
+			position
+		);
+
+		expect( target ).toBeUndefined();
+	} );
+} );

package/src/components/list-view/use-list-view-client-ids.js

@@ -9,7 +9,7 @@ import { useSelect } from '@wordpress/data';
  */
 import { store as blockEditorStore } from '../../store';
 
-export default function useListViewClientIds( blocks ) {
+export default function useListViewClientIds( { blocks, rootClientId } ) {
 	return useSelect(
 		( select ) => {
 			const {
@@ -21,9 +21,11 @@ export default function useListViewClientIds( blocks ) {
 			return {
 				selectedClientIds: getSelectedBlockClientIds(),
 				draggedClientIds: getDraggedBlockClientIds(),
-				clientIdsTree: blocks ? blocks : __unstableGetClientIdsTree(),
+				clientIdsTree: blocks
+					? blocks
+					: __unstableGetClientIdsTree( rootClientId ),
 			};
 		},
-		[ blocks ]
+		[ blocks, rootClientId ]
 	);
 }

package/src/components/list-view/use-list-view-drop-zone.js

@@ -36,6 +36,7 @@ import { store as blockEditorStore } from '../../store';
  * @property {Element} element                         The DOM element representing the block.
  * @property {number}  innerBlockCount                 The number of inner blocks the block has.
  * @property {boolean} isDraggedBlock                  Whether the block is currently being dragged.
+ * @property {boolean} isExpanded                      Whether the block is expanded in the UI.
  * @property {boolean} canInsertDraggedBlocksAsSibling Whether the dragged block can be a sibling of this block.
  * @property {boolean} canInsertDraggedBlocksAsChild   Whether the dragged block can be a child of this block.
  */
@@ -78,7 +79,7 @@ const ALLOWED_DROP_EDGES = [ 'top', 'bottom' ];
  *
  * @return {WPListViewDropZoneTarget | undefined} An object containing data about the drop target.
  */
-function getListViewDropTarget( blocksData, position ) {
+export function getListViewDropTarget( blocksData, position ) {
 	let candidateEdge;
 	let candidateBlockData;
 	let candidateDistance;
@@ -146,12 +147,15 @@ function getListViewDropTarget( blocksData, position ) {
 
 	// If the user is dragging towards the bottom of the block check whether
 	// they might be trying to nest the block as a child.
-	// If the block already has inner blocks, this should always be treated
+	// If the block already has inner blocks, and is expanded, this should be treated
 	// as nesting since the next block in the tree will be the first child.
+	// However, if the block is collapsed, dragging beneath the block should
+	// still be allowed, as the next visible block in the tree will be a sibling.
 	if (
 		isDraggingBelow &&
 		candidateBlockData.canInsertDraggedBlocksAsChild &&
-		( candidateBlockData.innerBlockCount > 0 ||
+		( ( candidateBlockData.innerBlockCount > 0 &&
+			candidateBlockData.isExpanded ) ||
 			isNestingGesture( position, candidateRect ) )
 	) {
 		return {
@@ -208,10 +212,12 @@ export default function useListViewDropZone() {
 
 				const blocksData = blockElements.map( ( blockElement ) => {
 					const clientId = blockElement.dataset.block;
+					const isExpanded = blockElement.dataset.expanded === 'true';
 					const rootClientId = getBlockRootClientId( clientId );
 
 					return {
 						clientId,
+						isExpanded,
 						rootClientId,
 						blockIndex: getBlockIndex( clientId ),
 						element: blockElement,