From 0b3fb0bc5514025ed2f48a2403c35f30f2dfd5a5 Mon Sep 17 00:00:00 2001 From: Seth Rubenstein Date: Thu, 13 Jul 2023 10:17:59 -0400 Subject: [PATCH] Stabilize defaultBlock, directInsert API's and getDirectInsertBlock selector (#52083) --- .../data/data-core-block-editor.md | 23 ++++++++++++ .../src/components/inner-blocks/README.md | 10 +++++ .../src/components/inner-blocks/index.js | 4 ++ .../components/inner-blocks/index.native.js | 4 ++ .../use-nested-settings-update.js | 37 ++++++++++++++++--- .../src/components/inserter/index.js | 5 +-- packages/block-editor/src/store/selectors.js | 25 +++++++++++-- packages/block-library/src/buttons/edit.js | 4 +- .../block-library/src/navigation-link/edit.js | 4 +- .../src/navigation-submenu/edit.js | 4 +- .../src/navigation/edit/inner-blocks.js | 4 +- .../navigation/edit/unsaved-inner-blocks.js | 4 +- 12 files changed, 107 insertions(+), 21 deletions(-) diff --git a/docs/reference-guides/data/data-core-block-editor.md b/docs/reference-guides/data/data-core-block-editor.md index 67dbc48ccf29d8..fd29b1c6e1388c 100644 --- a/docs/reference-guides/data/data-core-block-editor.md +++ b/docs/reference-guides/data/data-core-block-editor.md @@ -485,6 +485,29 @@ _Returns_ - `Array`: ids of top-level and descendant blocks. +### getDirectInsertBlock + +Returns the block to be directly inserted by the block appender. + +_Parameters_ + +- _state_ `Object`: Editor state. +- _rootClientId_ `?string`: Optional root client ID of block list. + +_Returns_ + +- `?WPDirectInsertBlock`: The block type to be directly inserted. + +_Type Definition_ + +- _WPDirectInsertBlock_ `Object` + +_Properties_ + +- _name_ `string`: The type of block. +- _attributes_ `?Object`: Attributes to pass to the newly created block. +- _attributesToCopy_ `?Array`: Attributes to be copied from adjecent blocks when inserted. + ### getDraggedBlockClientIds Returns the client ids of any blocks being directly dragged. diff --git a/packages/block-editor/src/components/inner-blocks/README.md b/packages/block-editor/src/components/inner-blocks/README.md index 5ecd9c90898210..0f5d303b8c7917 100644 --- a/packages/block-editor/src/components/inner-blocks/README.md +++ b/packages/block-editor/src/components/inner-blocks/README.md @@ -185,3 +185,13 @@ For example, a button block, deeply nested in several levels of block `X` that u - **Type:** `Array` - **Default:** - `undefined`. Determines which block types should be shown in the block inserter. For example, when inserting a block within the Navigation block we specify `core/navigation-link` and `core/navigation-link/page` as these are the most commonly used inner blocks. `prioritizedInserterBlocks` takes an array of the form {blockName}/{variationName}, where {variationName} is optional. + +### `defaultBlock` + +- **Type:** `Array` +- **Default:** - `undefined`. Determines which block type should be inserted by default and any attributes that should be set by default when the block is inserted. Takes an array in the form of `[ blockname, {blockAttributes} ]`. + +### `directInsert` + +- **Type:** `Boolean` +- **Default:** - `undefined`. Determines whether the default block should be inserted directly into the InnerBlocks area by the block appender. diff --git a/packages/block-editor/src/components/inner-blocks/index.js b/packages/block-editor/src/components/inner-blocks/index.js index e1513b9008374c..9e0e4f19cfc7ea 100644 --- a/packages/block-editor/src/components/inner-blocks/index.js +++ b/packages/block-editor/src/components/inner-blocks/index.js @@ -46,6 +46,8 @@ function UncontrolledInnerBlocks( props ) { clientId, allowedBlocks, prioritizedInserterBlocks, + defaultBlock, + directInsert, __experimentalDefaultBlock, __experimentalDirectInsert, template, @@ -64,6 +66,8 @@ function UncontrolledInnerBlocks( props ) { clientId, allowedBlocks, prioritizedInserterBlocks, + defaultBlock, + directInsert, __experimentalDefaultBlock, __experimentalDirectInsert, templateLock, diff --git a/packages/block-editor/src/components/inner-blocks/index.native.js b/packages/block-editor/src/components/inner-blocks/index.native.js index 8af05521e9f036..f07dcf4fc53053 100644 --- a/packages/block-editor/src/components/inner-blocks/index.native.js +++ b/packages/block-editor/src/components/inner-blocks/index.native.js @@ -73,6 +73,8 @@ function UncontrolledInnerBlocks( props ) { clientId, allowedBlocks, prioritizedInserterBlocks, + defaultBlock, + directInsert, __experimentalDefaultBlock, __experimentalDirectInsert, template, @@ -103,6 +105,8 @@ function UncontrolledInnerBlocks( props ) { clientId, allowedBlocks, prioritizedInserterBlocks, + defaultBlock, + directInsert, __experimentalDefaultBlock, __experimentalDirectInsert, templateLock, diff --git a/packages/block-editor/src/components/inner-blocks/use-nested-settings-update.js b/packages/block-editor/src/components/inner-blocks/use-nested-settings-update.js index 633d6b2701ed65..44f99428a31bf8 100644 --- a/packages/block-editor/src/components/inner-blocks/use-nested-settings-update.js +++ b/packages/block-editor/src/components/inner-blocks/use-nested-settings-update.js @@ -3,6 +3,7 @@ */ import { useLayoutEffect, useMemo } from '@wordpress/element'; import { useSelect, useDispatch, useRegistry } from '@wordpress/data'; +import deprecated from '@wordpress/deprecated'; /** * Internal dependencies @@ -25,9 +26,13 @@ const pendingSettingsUpdates = new WeakMap(); * @param {string[]} allowedBlocks An array of block names which are permitted * in inner blocks. * @param {string[]} prioritizedInserterBlocks Block names and/or block variations to be prioritized in the inserter, in the format {blockName}/{variationName}. - * @param {?WPDirectInsertBlock} __experimentalDefaultBlock The default block to insert: [ blockName, { blockAttributes } ]. - * @param {?Function|boolean} __experimentalDirectInsert If a default block should be inserted directly by the - * appender. + * @param {?WPDirectInsertBlock} defaultBlock The default block to insert: [ blockName, { blockAttributes } ]. + * @param {?Function|boolean} directInsert If a default block should be inserted directly by the appender. + * + * @param {?WPDirectInsertBlock} __experimentalDefaultBlock A deprecated prop for the default block to insert: [ blockName, { blockAttributes } ]. Use `defaultBlock` instead. + * + * @param {?Function|boolean} __experimentalDirectInsert A deprecated prop for whether a default block should be inserted directly by the appender. Use `directInsert` instead. + * * @param {string} [templateLock] The template lock specified for the inner * blocks component. (e.g. "all") * @param {boolean} captureToolbars Whether or children toolbars should be shown @@ -41,6 +46,8 @@ export default function useNestedSettingsUpdate( clientId, allowedBlocks, prioritizedInserterBlocks, + defaultBlock, + directInsert, __experimentalDefaultBlock, __experimentalDirectInsert, templateLock, @@ -108,11 +115,29 @@ export default function useNestedSettingsUpdate( } if ( __experimentalDefaultBlock !== undefined ) { - newSettings.__experimentalDefaultBlock = __experimentalDefaultBlock; + deprecated( '__experimentalDefaultBlock', { + alternative: 'defaultBlock', + since: '6.3', + version: '6.4', + } ); + newSettings.defaultBlock = __experimentalDefaultBlock; + } + + if ( defaultBlock !== undefined ) { + newSettings.defaultBlock = defaultBlock; } if ( __experimentalDirectInsert !== undefined ) { - newSettings.__experimentalDirectInsert = __experimentalDirectInsert; + deprecated( '__experimentalDirectInsert', { + alternative: 'directInsert', + since: '6.3', + version: '6.4', + } ); + newSettings.directInsert = __experimentalDirectInsert; + } + + if ( directInsert !== undefined ) { + newSettings.directInsert = directInsert; } // Batch updates to block list settings to avoid triggering cascading renders @@ -144,6 +169,8 @@ export default function useNestedSettingsUpdate( _allowedBlocks, _prioritizedInserterBlocks, _templateLock, + defaultBlock, + directInsert, __experimentalDefaultBlock, __experimentalDirectInsert, captureToolbars, diff --git a/packages/block-editor/src/components/inserter/index.js b/packages/block-editor/src/components/inserter/index.js index 9c24497e5a9078..8e2972fbe2bf5e 100644 --- a/packages/block-editor/src/components/inserter/index.js +++ b/packages/block-editor/src/components/inserter/index.js @@ -231,7 +231,7 @@ export const ComposedPrivateInserter = compose( [ getBlockRootClientId, hasInserterItems, getAllowedBlocks, - __experimentalGetDirectInsertBlock, + getDirectInsertBlock, getSettings, } = select( blockEditorStore ); @@ -243,8 +243,7 @@ export const ComposedPrivateInserter = compose( [ const allowedBlocks = getAllowedBlocks( rootClientId ); const directInsertBlock = - shouldDirectInsert && - __experimentalGetDirectInsertBlock( rootClientId ); + shouldDirectInsert && getDirectInsertBlock( rootClientId ); const settings = getSettings(); diff --git a/packages/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index c7115445ec8cc4..3aaec39a986ccd 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -2267,15 +2267,15 @@ export const __experimentalGetAllowedBlocks = createSelector( * @property {?Object} attributes Attributes to pass to the newly created block. * @property {?Array} attributesToCopy Attributes to be copied from adjecent blocks when inserted. */ -export const __experimentalGetDirectInsertBlock = createSelector( +export const getDirectInsertBlock = createSelector( ( state, rootClientId = null ) => { if ( ! rootClientId ) { return; } const defaultBlock = - state.blockListSettings[ rootClientId ]?.__experimentalDefaultBlock; + state.blockListSettings[ rootClientId ]?.defaultBlock; const directInsert = - state.blockListSettings[ rootClientId ]?.__experimentalDirectInsert; + state.blockListSettings[ rootClientId ]?.directInsert; if ( ! defaultBlock || ! directInsert ) { return; } @@ -2292,6 +2292,25 @@ export const __experimentalGetDirectInsertBlock = createSelector( ] ); +export const __experimentalGetDirectInsertBlock = createSelector( + ( state, rootClientId = null ) => { + deprecated( + 'wp.data.select( "core/block-editor" ).__experimentalGetDirectInsertBlock', + { + alternative: + 'wp.data.select( "core/block-editor" ).getDirectInsertBlock', + since: '6.3', + version: '6.4', + } + ); + return getDirectInsertBlock( state, rootClientId ); + }, + ( state, rootClientId ) => [ + state.blockListSettings[ rootClientId ], + state.blocks.tree.get( rootClientId ), + ] +); + const checkAllowListRecursive = ( blocks, allowedBlockTypes ) => { if ( typeof allowedBlockTypes === 'boolean' ) { return allowedBlockTypes; diff --git a/packages/block-library/src/buttons/edit.js b/packages/block-library/src/buttons/edit.js index 78be70ed9dc354..c901655dd42631 100644 --- a/packages/block-library/src/buttons/edit.js +++ b/packages/block-library/src/buttons/edit.js @@ -51,8 +51,8 @@ function ButtonsEdit( { attributes, className } ) { const innerBlocksProps = useInnerBlocksProps( blockProps, { allowedBlocks: ALLOWED_BLOCKS, - __experimentalDefaultBlock: DEFAULT_BLOCK, - __experimentalDirectInsert: true, + defaultBlock: DEFAULT_BLOCK, + directInsert: true, template: [ [ buttonBlockName, diff --git a/packages/block-library/src/navigation-link/edit.js b/packages/block-library/src/navigation-link/edit.js index 96d6f16926a669..d0d739575963a0 100644 --- a/packages/block-library/src/navigation-link/edit.js +++ b/packages/block-library/src/navigation-link/edit.js @@ -372,8 +372,8 @@ export default function NavigationLinkEdit( { }, { allowedBlocks: ALLOWED_BLOCKS, - __experimentalDefaultBlock: DEFAULT_BLOCK, - __experimentalDirectInsert: true, + defaultBlock: DEFAULT_BLOCK, + directInsert: true, renderAppender: false, } ); diff --git a/packages/block-library/src/navigation-submenu/edit.js b/packages/block-library/src/navigation-submenu/edit.js index 7707a6442111e5..ad907a0cb92cbb 100644 --- a/packages/block-library/src/navigation-submenu/edit.js +++ b/packages/block-library/src/navigation-submenu/edit.js @@ -320,8 +320,8 @@ export default function NavigationSubmenuEdit( { getNavigationChildBlockProps( innerBlocksColors ); const innerBlocksProps = useInnerBlocksProps( navigationChildBlockProps, { allowedBlocks, - __experimentalDefaultBlock: DEFAULT_BLOCK, - __experimentalDirectInsert: true, + defaultBlock: DEFAULT_BLOCK, + directInsert: true, // Ensure block toolbar is not too far removed from item // being edited. diff --git a/packages/block-library/src/navigation/edit/inner-blocks.js b/packages/block-library/src/navigation/edit/inner-blocks.js index 669703f002dbb2..373acd1f52dfa8 100644 --- a/packages/block-library/src/navigation/edit/inner-blocks.js +++ b/packages/block-library/src/navigation/edit/inner-blocks.js @@ -98,8 +98,8 @@ export default function NavigationInnerBlocks( { onChange, allowedBlocks: ALLOWED_BLOCKS, prioritizedInserterBlocks: PRIORITIZED_INSERTER_BLOCKS, - __experimentalDefaultBlock: DEFAULT_BLOCK, - __experimentalDirectInsert: shouldDirectInsert, + defaultBlock: DEFAULT_BLOCK, + directInsert: shouldDirectInsert, orientation, templateLock, diff --git a/packages/block-library/src/navigation/edit/unsaved-inner-blocks.js b/packages/block-library/src/navigation/edit/unsaved-inner-blocks.js index 52f6d8134042de..e2ad08c2a99ab1 100644 --- a/packages/block-library/src/navigation/edit/unsaved-inner-blocks.js +++ b/packages/block-library/src/navigation/edit/unsaved-inner-blocks.js @@ -68,8 +68,8 @@ export default function UnsavedInnerBlocks( { { renderAppender: hasSelection ? undefined : false, allowedBlocks: ALLOWED_BLOCKS, - __experimentalDefaultBlock: DEFAULT_BLOCK, - __experimentalDirectInsert: shouldDirectInsert, + defaultBlock: DEFAULT_BLOCK, + directInsert: shouldDirectInsert, } );