diff --git a/packages/block-editor/src/components/list-view/README.md b/packages/block-editor/src/components/list-view/README.md index 25fb7b61ac6c0..da0a255d1ac97 100644 --- a/packages/block-editor/src/components/list-view/README.md +++ b/packages/block-editor/src/components/list-view/README.md @@ -2,6 +2,8 @@ The ListView component provides an overview of the hierarchical structure of all blocks in the editor. The blocks are presented vertically one below the other. +By providing the `rootClientId` prop you can restrict the blocks that are shown to only children of the block with that client id. + Blocks that have child blocks (such as group or column blocks) are presented with the parent at the top and the nested children below. In addition to presenting the structure of the blocks in the editor, the ListView component lets users navigate to each block by clicking on its line in the hierarchy tree. Multiple blocks at the same level of nesting can be selected by holding down the `SHIFT` key and clicking blocks within the list. diff --git a/packages/block-editor/src/components/list-view/index.js b/packages/block-editor/src/components/list-view/index.js index aff471e18fa1a..6e627a5b8b1d6 100644 --- a/packages/block-editor/src/components/list-view/index.js +++ b/packages/block-editor/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, @@ -56,11 +57,12 @@ export const BLOCK_LIST_ITEM_HEIGHT = 36; * * @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 {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 ListViewComponent( @@ -71,11 +73,23 @@ function ListViewComponent( 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 ) => { @@ -219,6 +233,7 @@ function ListViewComponent( { { ...props } showAppender={ false } blockSettingsMenu={ BlockSettingsDropdown } + rootClientId={ null } /> ); } ); diff --git a/packages/block-editor/src/components/list-view/use-list-view-client-ids.js b/packages/block-editor/src/components/list-view/use-list-view-client-ids.js index 5dafa765f16ea..1d874f21f6a46 100644 --- a/packages/block-editor/src/components/list-view/use-list-view-client-ids.js +++ b/packages/block-editor/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 ] ); }