Stabilize defaultBlock, directInsert API's and getDirectInsertBlock s…

…elector (#52083)
WordPress · Jul 13, 2023 · 0b3fb0b · 0b3fb0b · github-actions · Jul 13, 2023
1 parent 800cd8c
commit 0b3fb0b
Show file tree

Hide file tree

Showing 12 changed files with 107 additions and 21 deletions.
diff --git 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<string>`: 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -2267,15 +2267,15 @@ export const __experimentalGetAllowedBlocks = createSelector(
  * @property {?Object}        attributes       Attributes to pass to the newly created block.
  * @property {?Array<string>} 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,
 		}
 	);