Make useBlockEditingMode() public (#52094)

* Make useBlockEditingMode() public

* Remove unnecessary unlock()s

docs/reference-guides/data/data-core-block-editor.md

@@ -209,6 +209,35 @@ _Returns_
 
 -   `number`: Number of blocks in the post.
 
+### getBlockEditingMode
+
+Returns the block editing mode for a given block.
+
+The mode can be one of three options:
+
+-   `'disabled'`: Prevents editing the block entirely, i.e. it cannot be selected.
+-   `'contentOnly'`: Hides all non-content UI, e.g. auxiliary controls in the toolbar, the block movers, block settings.
+-   `'default'`: Allows editing the block as normal.
+
+Blocks can set a mode using the `useBlockEditingMode` hook.
+
+The mode is inherited by all of the block's inner blocks, unless they have their own mode.
+
+A template lock can also set a mode. If the template lock is `'contentOnly'`, the block's mode is overridden to `'contentOnly'` if the block has a content role attribute, or `'disabled'` otherwise.
+
+_Related_
+
+-   useBlockEditingMode
+
+_Parameters_
+
+-   _state_ `Object`: Global application state.
+-   _clientId_ `string`: The block client ID, or `''` for the root container.
+
+_Returns_
+
+-   `BlockEditingMode`: The block editing mode. One of `'disabled'`, `'contentOnly'`, or `'default'`.
+
 ### getBlockHierarchyRootClientId
 
 Given a block client ID, returns the root of the hierarchy from which the block is nested, return the block itself for root level blocks.
@@ -1554,6 +1583,23 @@ _Parameters_
 -   _clientId_ `string`: Block client ID.
 -   _fallbackToParent_ `boolean`: If true, select the first parent if there is no previous block.
 
+### setBlockEditingMode
+
+Sets the block editing mode for a given block.
+
+_Related_
+
+-   useBlockEditingMode
+
+_Parameters_
+
+-   _clientId_ `string`: The block client ID, or `''` for the root container.
+-   _mode_ `BlockEditingMode`: The block editing mode. One of `'disabled'`, `'contentOnly'`, or `'default'`.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### setBlockMovingClientId
 
 Action that enables or disables the block moving mode.
@@ -1711,6 +1757,22 @@ _Returns_
 
 -   `Object`: Action object.
 
+### unsetBlockEditingMode
+
+Clears the block editing mode for a given block.
+
+_Related_
+
+-   useBlockEditingMode
+
+_Parameters_
+
+-   _clientId_ `string`: The block client ID, or `''` for the root container.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### updateBlock
 
 Action that updates the block with the specified client ID.

packages/block-editor/README.md

@@ -811,6 +811,40 @@ _Returns_
 
 -   `Object`: Block edit context
 
+### useBlockEditingMode
+
+Allows a block to restrict the user interface that is displayed for editing that block and its inner blocks.
+
+_Usage_
+
+```js
+function MyBlock( { attributes, setAttributes } ) {
+	useBlockEditingMode( 'disabled' );
+	return <div { ...useBlockProps() }></div>;
+}
+```
+
+`mode` can be one of three options:
+
+-   `'disabled'`: Prevents editing the block entirely, i.e. it cannot be
+    selected.
+-   `'contentOnly'`: Hides all non-content UI, e.g. auxiliary controls in the
+    toolbar, the block movers, block settings.
+-   `'default'`: Allows editing the block as normal.
+
+The mode is inherited by all of the block's inner blocks, unless they have
+their own mode.
+
+If called outside of a block context, the mode is applied to all blocks.
+
+_Parameters_
+
+-   _mode_ `?BlockEditingMode`: The editing mode to apply. If undefined, the current editing mode is not changed.
+
+_Returns_
+
+-   `BlockEditingMode`: The current editing mode.
+
 ### useBlockProps
 
 This hook is used to lightly mark an element as a block element. The element should be the outermost element of a block. Call this hook and pass the returned props to the element to mark as a block. If you define a ref for the element, it is important to pass the ref to this hook, which the hook in turn will pass to the component through the props it returns. Optionally, you can also pass any other props through this hook, and they will be merged and returned.

packages/block-editor/src/components/block-editing-mode/index.js

@@ -8,7 +8,6 @@ import { useContext, useEffect } from '@wordpress/element';
  * Internal dependencies
  */
 import { store as blockEditorStore } from '../../store';
-import { unlock } from '../../lock-unlock';
 import { BlockListBlockContext } from '../block-list/block-list-block-context';
 
 /**
@@ -49,14 +48,11 @@ export function useBlockEditingMode( mode ) {
 	const { clientId = '' } = useContext( BlockListBlockContext ) ?? {};
 	const blockEditingMode = useSelect(
 		( select ) =>
-			unlock( select( blockEditorStore ) ).getBlockEditingMode(
-				clientId
-			),
+			select( blockEditorStore ).getBlockEditingMode( clientId ),
 		[ clientId ]
 	);
-	const { setBlockEditingMode, unsetBlockEditingMode } = unlock(
-		useDispatch( blockEditorStore )
-	);
+	const { setBlockEditingMode, unsetBlockEditingMode } =
+		useDispatch( blockEditorStore );
 	useEffect( () => {
 		if ( mode ) {
 			setBlockEditingMode( clientId, mode );

packages/block-editor/src/components/block-inspector/index.js

@@ -30,7 +30,6 @@ import PositionControls from '../inspector-controls-tabs/position-controls-panel
 import useBlockInspectorAnimationSettings from './useBlockInspectorAnimationSettings';
 import BlockInfo from '../block-info-slot-fill';
 import BlockQuickNavigation from '../block-quick-navigation';
-import { unlock } from '../../lock-unlock';
 
 function BlockInspectorLockedBlocks( { topLevelLockedBlock } ) {
 	const contentClientIds = useSelect(
@@ -39,7 +38,7 @@ function BlockInspectorLockedBlocks( { topLevelLockedBlock } ) {
 				getClientIdsOfDescendants,
 				getBlockName,
 				getBlockEditingMode,
-			} = unlock( select( blockEditorStore ) );
+			} = select( blockEditorStore );
 			return getClientIdsOfDescendants( [ topLevelLockedBlock ] ).filter(
 				( clientId ) =>
 					getBlockName( clientId ) !== 'core/list-item' &&

packages/block-editor/src/components/block-list-appender/index.js

@@ -15,7 +15,6 @@ import { getDefaultBlockName } from '@wordpress/blocks';
 import DefaultBlockAppender from '../default-block-appender';
 import ButtonBlockAppender from '../button-block-appender';
 import { store as blockEditorStore } from '../../store';
-import { unlock } from '../../lock-unlock';
 
 function DefaultAppender( { rootClientId } ) {
 	const canInsertDefaultBlock = useSelect( ( select ) =>
@@ -48,7 +47,7 @@ function useAppender( rootClientId, CustomAppender ) {
 				getSelectedBlockClientId,
 				__unstableGetEditorMode,
 				getBlockEditingMode,
-			} = unlock( select( blockEditorStore ) );
+			} = select( blockEditorStore );
 
 			if ( CustomAppender === false ) {
 				return false;

packages/block-editor/src/components/block-list/block.js

@@ -37,7 +37,6 @@ import BlockHtml from './block-html';
 import { useBlockProps } from './use-block-props';
 import { store as blockEditorStore } from '../../store';
 import { useLayout } from './layout';
-import { unlock } from '../../lock-unlock';
 import { BlockListBlockContext } from './block-list-block-context';
 
 /**
@@ -102,7 +101,7 @@ function BlockListBlock( {
 				getSettings,
 				__unstableGetTemporarilyEditingAsBlocks,
 				getBlockEditingMode,
-			} = unlock( select( blockEditorStore ) );
+			} = select( blockEditorStore );
 			return {
 				themeSupportsLayout: getSettings().supportsLayout,
 				isTemporarilyEditingAsBlocks:

packages/block-editor/src/components/block-list/use-in-between-inserter.js

@@ -11,7 +11,6 @@ import { isRTL } from '@wordpress/i18n';
  */
 import { store as blockEditorStore } from '../../store';
 import { InsertionPointOpenRef } from '../block-tools/insertion-point';
-import { unlock } from '../../lock-unlock';
 
 export function useInBetweenInserter() {
 	const openRef = useContext( InsertionPointOpenRef );
@@ -29,7 +28,7 @@ export function useInBetweenInserter() {
 		getTemplateLock,
 		__unstableIsWithinBlockOverlay,
 		getBlockEditingMode,
-	} = unlock( useSelect( blockEditorStore ) );
+	} = useSelect( blockEditorStore );
 	const { showInsertionPoint, hideInsertionPoint } =
 		useDispatch( blockEditorStore );
 

packages/block-editor/src/components/block-parent-selector/index.js

@@ -14,7 +14,6 @@ import useBlockDisplayInformation from '../use-block-display-information';
 import BlockIcon from '../block-icon';
 import { useShowHoveredOrFocusedGestures } from '../block-toolbar/utils';
 import { store as blockEditorStore } from '../../store';
-import { unlock } from '../../lock-unlock';
 
 /**
  * Block parent selector component, displaying the hierarchy of the
@@ -30,7 +29,7 @@ export default function BlockParentSelector() {
 			getBlockParents,
 			getSelectedBlockClientId,
 			getBlockEditingMode,
-		} = unlock( select( blockEditorStore ) );
+		} = select( blockEditorStore );
 		const { hasBlockSupport } = select( blocksStore );
 		const selectedBlockClientId = getSelectedBlockClientId();
 		const parents = getBlockParents( selectedBlockClientId );

packages/block-editor/src/components/block-toolbar/index.js

@@ -32,7 +32,6 @@ import BlockEditVisuallyButton from '../block-edit-visually-button';
 import { useShowHoveredOrFocusedGestures } from './utils';
 import { store as blockEditorStore } from '../../store';
 import __unstableBlockNameContext from './block-name-context';
-import { unlock } from '../../lock-unlock';
 
 const BlockToolbar = ( { hideDragHandle } ) => {
 	const { blockClientIds, blockType, isValid, isVisual, blockEditingMode } =
@@ -44,7 +43,7 @@ const BlockToolbar = ( { hideDragHandle } ) => {
 				isBlockValid,
 				getBlockRootClientId,
 				getBlockEditingMode,
-			} = unlock( select( blockEditorStore ) );
+			} = select( blockEditorStore );
 			const selectedBlockClientIds = getSelectedBlockClientIds();
 			const selectedBlockClientId = selectedBlockClientIds[ 0 ];
 			const blockRootClientId = getBlockRootClientId(

packages/block-editor/src/components/block-tools/block-contextual-toolbar.js

@@ -24,7 +24,6 @@ import { useViewportMatch } from '@wordpress/compose';
 import NavigableToolbar from '../navigable-toolbar';
 import BlockToolbar from '../block-toolbar';
 import { store as blockEditorStore } from '../../store';
-import { unlock } from '../../lock-unlock';
 import { useHasAnyBlockControls } from '../block-controls/use-has-block-controls';
 
 function BlockContextualToolbar( { focusOnMount, isFixed, ...props } ) {
@@ -45,7 +44,7 @@ function BlockContextualToolbar( { focusOnMount, isFixed, ...props } ) {
 			getBlockParents,
 			getSelectedBlockClientIds,
 			getBlockEditingMode,
-		} = unlock( select( blockEditorStore ) );
+		} = select( blockEditorStore );
 		const { getBlockType } = select( blocksStore );
 		const selectedBlockClientIds = getSelectedBlockClientIds();
 		const _selectedBlockClientId = selectedBlockClientIds[ 0 ];

packages/block-editor/src/components/index.js

@@ -158,6 +158,7 @@ export {
 export { default as __experimentalBlockPatternsList } from './block-patterns-list';
 export { default as __experimentalPublishDateTimePicker } from './publish-date-time-picker';
 export { default as __experimentalInspectorPopoverHeader } from './inspector-popover-header';
+export { useBlockEditingMode } from './block-editing-mode';
 
 /*
  * State Related Components

packages/block-editor/src/components/list-view/block.js

@@ -39,7 +39,6 @@ import { getBlockPositionDescription } from './utils';
 import { store as blockEditorStore } from '../../store';
 import useBlockDisplayInformation from '../use-block-display-information';
 import { useBlockLock } from '../block-lock';
-import { unlock } from '../../lock-unlock';
 import AriaReferencedText from './aria-referenced-text';
 
 function ListViewBlock( {
@@ -84,9 +83,7 @@ function ListViewBlock( {
 	);
 	const blockEditingMode = useSelect(
 		( select ) =>
-			unlock( select( blockEditorStore ) ).getBlockEditingMode(
-				clientId
-			),
+			select( blockEditorStore ).getBlockEditingMode( clientId ),
 		[ clientId ]
 	);
 

packages/block-editor/src/components/use-block-drop-zone/index.js

@@ -19,7 +19,6 @@ import {
 	isPointContainedByRect,
 } from '../../utils/math';
 import { store as blockEditorStore } from '../../store';
-import { unlock } from '../../lock-unlock';
 
 /** @typedef {import('../../utils/math').WPPoint} WPPoint */
 /** @typedef {import('../use-on-block-drop/types').WPDropOperation} WPDropOperation */
@@ -155,7 +154,7 @@ export default function useBlockDropZone( {
 				__unstableIsWithinBlockOverlay,
 				__unstableHasActiveBlockOverlayActive,
 				getBlockEditingMode,
-			} = unlock( select( blockEditorStore ) );
+			} = select( blockEditorStore );
 			const blockEditingMode = getBlockEditingMode( targetRootClientId );
 			return (
 				blockEditingMode !== 'default' ||

packages/block-editor/src/private-apis.js

@@ -12,7 +12,6 @@ import { PrivateListView } from './components/list-view';
 import BlockInfo from './components/block-info-slot-fill';
 import { useShouldContextualToolbarShow } from './utils/use-should-contextual-toolbar-show';
 import { cleanEmptyObject } from './hooks/utils';
-import { useBlockEditingMode } from './components/block-editing-mode';
 import BlockQuickNavigation from './components/block-quick-navigation';
 import { LayoutStyle } from './components/block-list/layout';
 import { BlockRemovalWarningModal } from './components/block-removal-warning-modal';
@@ -40,7 +39,6 @@ lock( privateApis, {
 	BlockInfo,
 	useShouldContextualToolbarShow,
 	cleanEmptyObject,
-	useBlockEditingMode,
 	BlockQuickNavigation,
 	LayoutStyle,
 	BlockRemovalWarningModal,

packages/block-editor/src/store/actions.js

@@ -1878,3 +1878,42 @@ export const registerInserterMediaCategory =
 			},
 		} );
 	};
+
+/**
+ * @typedef {import('../components/block-editing-mode').BlockEditingMode} BlockEditingMode
+ */
+
+/**
+ * Sets the block editing mode for a given block.
+ *
+ * @see useBlockEditingMode
+ *
+ * @param {string}           clientId The block client ID, or `''` for the root container.
+ * @param {BlockEditingMode} mode     The block editing mode. One of `'disabled'`,
+ *                                    `'contentOnly'`, or `'default'`.
+ *
+ * @return {Object} Action object.
+ */
+export function setBlockEditingMode( clientId = '', mode ) {
+	return {
+		type: 'SET_BLOCK_EDITING_MODE',
+		clientId,
+		mode,
+	};
+}
+
+/**
+ * Clears the block editing mode for a given block.
+ *
+ * @see useBlockEditingMode
+ *
+ * @param {string} clientId The block client ID, or `''` for the root container.
+ *
+ * @return {Object} Action object.
+ */
+export function unsetBlockEditingMode( clientId = '' ) {
+	return {
+		type: 'UNSET_BLOCK_EDITING_MODE',
+		clientId,
+	};
+}