@wordpress/block-editor 16.2.0 → 17.0.2-next.v.202608281122.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/block-editor",
-	"version": "16.2.0",
+	"version": "17.0.2-next.v.202608281122.0",
 	"description": "Generic block editor.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -60,48 +60,45 @@
 	],
 	"dependencies": {
 		"@react-spring/web": "^9.4.5",
-		"@wordpress/a11y": "^4.53.0",
-		"@wordpress/base-styles": "^12.1.0",
-		"@wordpress/blob": "^4.53.0",
-		"@wordpress/block-serialization-default-parser": "^5.53.0",
-		"@wordpress/blocks": "^15.26.0",
-		"@wordpress/commands": "^1.53.0",
-		"@wordpress/components": "^39.0.0",
-		"@wordpress/compose": "^8.6.0",
-		"@wordpress/data": "^10.53.0",
-		"@wordpress/dataviews": "^18.0.0",
-		"@wordpress/date": "^5.53.0",
-		"@wordpress/deprecated": "^4.53.0",
-		"@wordpress/dom": "^4.53.0",
-		"@wordpress/element": "^8.5.0",
-		"@wordpress/escape-html": "^3.53.0",
-		"@wordpress/global-styles-engine": "^1.20.0",
-		"@wordpress/hooks": "^4.53.0",
-		"@wordpress/html-entities": "^4.53.0",
-		"@wordpress/i18n": "^6.26.0",
-		"@wordpress/icons": "^15.4.0",
-		"@wordpress/image-cropper": "^1.17.0",
-		"@wordpress/interactivity": "^6.53.0",
-		"@wordpress/is-shallow-equal": "^5.53.0",
-		"@wordpress/kebab-case": "^1.0.0",
-		"@wordpress/keyboard-shortcuts": "^5.53.0",
-		"@wordpress/keycodes": "^4.53.0",
-		"@wordpress/notices": "^5.53.0",
-		"@wordpress/preferences": "^4.53.0",
-		"@wordpress/priority-queue": "^3.53.0",
-		"@wordpress/private-apis": "^1.53.0",
-		"@wordpress/rich-text": "^7.53.0",
-		"@wordpress/style-engine": "^2.53.0",
-		"@wordpress/token-list": "^3.53.0",
-		"@wordpress/ui": "^0.20.0",
-		"@wordpress/upload-media": "^0.38.0",
-		"@wordpress/url": "^4.53.0",
-		"@wordpress/warning": "^3.53.0",
-		"@wordpress/wordcount": "^4.53.0",
+		"@wordpress/a11y": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/base-styles": "^13.0.1-next.v.202608281122.0",
+		"@wordpress/blob": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/block-serialization-default-parser": "^5.54.1-next.v.202608281122.0",
+		"@wordpress/blocks": "^16.0.1-next.v.202608281122.0",
+		"@wordpress/commands": "^1.54.2-next.v.202608281122.0",
+		"@wordpress/components": "^40.1.1-next.v.202608281122.0",
+		"@wordpress/compose": "^8.7.2-next.v.202608281122.0",
+		"@wordpress/data": "^10.54.2-next.v.202608281122.0",
+		"@wordpress/dataviews": "^18.1.2-next.v.202608281122.0",
+		"@wordpress/date": "^5.54.1-next.v.202608281122.0",
+		"@wordpress/deprecated": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/dom": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/element": "^8.6.2-next.v.202608281122.0",
+		"@wordpress/global-styles-engine": "^1.21.1-next.v.202608281122.0",
+		"@wordpress/hooks": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/html-entities": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/i18n": "^6.27.1-next.v.202608281122.0",
+		"@wordpress/icons": "^15.5.1-next.v.202608281122.0",
+		"@wordpress/image-cropper": "^1.18.2-next.v.202608281122.0",
+		"@wordpress/interactivity": "^6.54.1-next.v.202608281122.0",
+		"@wordpress/is-shallow-equal": "^5.54.1-next.v.202608281122.0",
+		"@wordpress/kebab-case": "^1.1.1-next.v.202608281122.0",
+		"@wordpress/keyboard-shortcuts": "^5.54.1-next.v.202608281122.0",
+		"@wordpress/keycodes": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/notices": "^5.54.1-next.v.202608281122.0",
+		"@wordpress/preferences": "^4.54.2-next.v.202608281122.0",
+		"@wordpress/priority-queue": "^3.54.1-next.v.202608281122.0",
+		"@wordpress/private-apis": "^1.54.1-next.v.202608281122.0",
+		"@wordpress/rich-text": "^7.54.1-next.v.202608281122.0",
+		"@wordpress/style-engine": "^2.54.1-next.v.202608281122.0",
+		"@wordpress/token-list": "^3.54.1-next.v.202608281122.0",
+		"@wordpress/ui": "^0.22.1-next.v.202608281122.0",
+		"@wordpress/upload-media": "^0.39.2-next.v.202608281122.0",
+		"@wordpress/url": "^4.54.1-next.v.202608281122.0",
+		"@wordpress/warning": "^3.54.1-next.v.202608281122.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.9.3",
-		"deepmerge": "^4.3.1",
 		"diff": "^8.0.3",
 		"fast-deep-equal": "^3.1.3",
 		"parsel-js": "^1.1.2",
@@ -113,14 +110,14 @@
 		"remove-accents": "^0.5.0"
 	},
 	"devDependencies": {
-		"@ariakit/test": "^0.7.2",
+		"@ariakit/test": "^0.7.4",
 		"@testing-library/dom": "^10.4.1",
 		"@testing-library/react": "^16.3.2",
 		"@testing-library/user-event": "^14.6.1",
 		"@types/postcss-prefix-selector": "^1.16.3",
-		"@wordpress/block-library": "^10.4.0",
+		"@wordpress/block-library": "^10.5.2-next.v.202608281122.0",
 		"deep-freeze": "^0.0.1",
-		"storybook": "^10.4.3"
+		"storybook": "^10.5.3"
 	},
 	"peerDependencies": {
 		"@types/react": "^18 || ^19",
@@ -135,5 +132,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "989764d42ff93e33684aaf0b96a5b7f3d9bbff52"
+	"gitHead": "de479d415171765f7b573c81aeec5334ff506a12"
 }

package/src/components/background-image-control/README.md

@@ -0,0 +1,122 @@
+# Background Image Control
+
+The `BackgroundImageControl` component provides an interface for selecting, positioning, and configuring background images in the WordPress block editor.
+
+_Note:_ This is an internal component. It is not exported from `@wordpress/block-editor` and is not part of the public API; it is rendered by the Global Styles [background panel](../global-styles/background-panel.jsx).
+
+## Features
+
+-   Upload or select a background image from the media library.
+-   Adjust background position using a focal point picker.
+-   Toggle background repeat and attachment properties.
+-   Set background size (cover, contain, auto, or custom units).
+-   Remove or replace the background image.
+-   Drag and drop image uploads.
+
+## Development guidelines
+
+### Usage
+
+Renders the background image controls, to be used within a `ToolsPanelItem` in the block inspector.
+
+```jsx
+import { useState } from 'react';
+import {
+	__experimentalToolsPanel as ToolsPanel,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+} from '@wordpress/components';
+import BackgroundImageControl from '../background-image-control';
+
+const MyBackgroundImageControl = () => {
+	const [ style, setStyle ] = useState( {} );
+	return (
+		<ToolsPanel label={ 'Background' } panelId="my-panel">
+			<ToolsPanelItem
+				label={ 'Image' }
+				panelId="my-panel"
+				isShownByDefault
+				hasValue={ () => !! style?.background?.backgroundImage }
+				onDeselect={ () => setStyle( {} ) }
+			>
+				<BackgroundImageControl
+					value={ style }
+					onChange={ setStyle }
+					settings={ {
+						background: {
+							backgroundImage: true,
+							backgroundSize: true,
+						},
+					} }
+				/>
+			</ToolsPanelItem>
+		</ToolsPanel>
+	);
+};
+```
+
+### Props
+
+#### `value`
+
+-   **Type:** `Object`
+
+The style object the controls read from and write to. Background values live under the `background` key, for example `{ background: { backgroundImage: { url, id, title }, backgroundSize: 'cover' } }`.
+
+#### `onChange`
+
+-   **Type:** `Function`
+
+A callback that receives the updated style object whenever a background property changes.
+
+#### `inheritedValue`
+
+-   **Type:** `Object`
+-   **Default:** the `value` prop
+
+A style object with the values inherited from global styles, used as the fallback when `value` has none. `ref` pointers within it are resolved before use.
+
+#### `settings`
+
+-   **Type:** `Object`
+
+The theme settings object. The background size, position, and repeat controls are only rendered when at least one of `settings.background.backgroundSize`, `settings.background.backgroundPosition`, or `settings.background.backgroundRepeat` is enabled.
+
+#### `defaultValues`
+
+-   **Type:** `Object`
+-   **Default:** `{}`
+
+Default values for the background properties, used as placeholders when nothing is set.
+
+#### `showInheritanceLabelIndicators`
+
+-   **Type:** `Boolean`
+-   **Default:** whether global styles inheritance is enabled
+
+Whether to show the inherited-value label treatment, including the local-override affordance on the reset control.
+
+## Utility functions
+
+### `coordsToBackgroundPosition( value )`
+
+Converts `FocalPointPicker` x/y values to a CSS `background-position` value.
+
+```js
+coordsToBackgroundPosition( { x: 0.5, y: 0.5 } ); // '50% 50%'
+coordsToBackgroundPosition( { x: 0.5 } ); // '50% 50%' — a missing coord falls back to 0.5
+coordsToBackgroundPosition( undefined ); // undefined
+```
+
+### `backgroundPositionToCoords( value )`
+
+Converts a CSS `background-position` value to `FocalPointPicker` coordinates.
+
+```js
+backgroundPositionToCoords( '50% 50%' ); // { x: 0.5, y: 0.5 }
+backgroundPositionToCoords( '50%' ); // { x: 0.5, y: 0.5 } — y falls back to x
+backgroundPositionToCoords( undefined ); // { x: undefined, y: undefined }
+```
+
+## Related components
+
+Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a [`BlockEditorProvider`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/provider/README.md) in the components tree.

package/src/components/block-edit-visually-button/README.md

@@ -0,0 +1,39 @@
+# Block Edit Visually Button
+
+`BlockEditVisuallyButton` renders the toolbar button that takes a block out of the HTML editor and back to the visual editor. It is the toolbar counterpart of the "Edit as HTML" / "Edit visually" item that [`BlockSettingsMenu`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-settings-menu/README.md) renders, and it exists so that a block being edited as HTML always offers a visible way back without opening the settings menu.
+
+_Note:_ This component is internal to the block editor and is not exported from `@wordpress/block-editor`. It is rendered by [`BlockToolbar`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-toolbar/README.md); it is documented here for contributors working on the block toolbar rather than as public API.
+
+## Development guidelines
+
+The button renders only when a single block is selected and that block's mode is `html`, so it is safe to render unconditionally alongside the rest of the toolbar: with a multi-block selection, or with a block in visual mode, it returns `null`. Clicking it dispatches `toggleBlockMode` for the selected block, which flips the mode back to `visual`.
+
+Note that the two entry points are not gated the same way. The settings menu item is only rendered for a valid block that supports `html` editing while the `codeEditingEnabled` setting is on, whereas this button checks the block's mode alone. Whatever put the block into HTML mode, the toolbar button is there to bring it back.
+
+### Usage
+
+```jsx
+import { ToolbarGroup } from '@wordpress/components';
+
+function MyBlockToolbar( { clientIds } ) {
+	return (
+		<div className="my-block-toolbar">
+			<ToolbarGroup>{ /* Block controls. */ }</ToolbarGroup>
+			<BlockEditVisuallyButton clientIds={ clientIds } />
+		</div>
+	);
+}
+```
+
+### Props
+
+#### `clientIds`
+
+-   **Type:** `Array`
+-   **Required:** Yes
+
+The client IDs of the currently selected blocks. The button renders only when the array contains exactly one client ID, since editing visually applies to a single block.
+
+## Related components
+
+Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a [`BlockEditorProvider`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/provider/README.md) in the components tree.

package/src/components/block-editing-mode/README.md

@@ -0,0 +1,72 @@
+# Block Editing Mode
+
+`useBlockEditingMode` is a hook that reads, and optionally sets, the editing mode of a block. The mode restricts the user interface that is displayed for editing that block.
+
+The mode can be set to one of the following values:
+
+-   `'disabled'`: Prevents editing the block entirely, i.e., it cannot be selected.
+-   `'contentOnly'`: Hides all non-content UI, such as auxiliary controls in the toolbar, block movers, and block settings.
+-   `'default'`: Allows editing the block as normal.
+
+Modes don't cascade to inner blocks, with one exception: a block set to `'disabled'` also disables its inner blocks, unless an inner block has its own mode explicitly set.
+
+If called outside of a block context, the mode is set on the editor root, which follows the same rule, so `'disabled'` applies to every block, while `'contentOnly'` does not.
+
+A mode can also be derived rather than set by the block itself. Under a `templateLock: 'contentOnly'` ancestor, a block without an explicitly set mode is derived as `'contentOnly'` if it is a content block (it has an attribute with `role: 'content'`, or `supports.contentRole`), and as `'disabled'` otherwise. An explicitly set mode wins over these derived modes. See the [block locking guide](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/block-locking/) for more on locking.
+
+## Development guidelines
+
+### Usage
+
+Called without an argument, the hook returns the current mode for the block. This is the most common use, and lets a block hide controls when editing is restricted:
+
+```jsx
+import {
+	BlockControls,
+	useBlockEditingMode,
+	useBlockProps,
+} from '@wordpress/block-editor';
+
+function MyBlock( { attributes, setAttributes } ) {
+	const blockEditingMode = useBlockEditingMode();
+	return (
+		<>
+			{ blockEditingMode === 'default' && (
+				<BlockControls group="block">
+					<MyToolbarControl />
+				</BlockControls>
+			) }
+			<div { ...useBlockProps() }></div>
+		</>
+	);
+}
+```
+
+Passing a mode sets it for the block:
+
+```jsx
+import {
+	useBlockEditingMode,
+	useBlockProps,
+} from '@wordpress/block-editor';
+
+function MyBlock( { attributes, setAttributes } ) {
+	useBlockEditingMode( 'disabled' );
+	return <div { ...useBlockProps() }></div>;
+}
+```
+
+### Parameters
+
+#### `mode`
+
+-   **Type:** `String`
+-   **Default:** `undefined`
+
+The editing mode to set for the block. One of `'disabled'`, `'contentOnly'`, or `'default'`. If `undefined`, the current editing mode remains unchanged.
+
+### Return
+
+-   **Type:** `String`
+
+The current editing mode for the block.

package/src/components/block-inspector/{index.js → index.jsx}

@@ -42,12 +42,12 @@ import {
 } from '../../hooks/block-style-state';
 
 function StyleInspectorSlots( {
-	blockName,
+	clientId,
 	showAdvancedControls = true,
 	showPositionControls = true,
 	showBindingsControls = true,
 } ) {
-	const borderPanelLabel = useBorderPanelLabel( { blockName } );
+	const borderPanelLabel = useBorderPanelLabel( { clientId } );
 	return (
 		<>
 			<InspectorControls.Slot />
@@ -97,8 +97,8 @@ function StyleStateInspectorSlots( {
 	isSectionBlock,
 	selectedBlockStyleState,
 } ) {
-	const borderPanelLabel = useBorderPanelLabel( { blockName } );
-	const showLayoutControls =
+	const borderPanelLabel = useBorderPanelLabel( { clientId } );
+	const isViewportStyleState =
 		hasViewportBlockStyleState( selectedBlockStyleState ) &&
 		! hasPseudoBlockStyleState( selectedBlockStyleState );
 	const showSectionStyleControls =
@@ -130,7 +130,7 @@ function StyleStateInspectorSlots( {
 						label={ __( 'Background' ) }
 						className="background-block-support-panel__inner-wrapper"
 					/>
-					{ showLayoutControls && (
+					{ isViewportStyleState && (
 						<InspectorControls.Slot
 							group="layout"
 							label={ __( 'Layout' ) }
@@ -151,6 +151,9 @@ function StyleStateInspectorSlots( {
 					/>
 				</>
 			) }
+			{ isViewportStyleState && (
+				<InspectorControls.Slot group="viewport" />
+			) }
 		</>
 	);
 }
@@ -298,7 +301,6 @@ function BlockInspector() {
 					<InspectorControlsTabs tabs={ availableTabs } />
 				) : (
 					<StyleInspectorSlots
-						blockName={ renderedBlockName }
 						showAdvancedControls={ false }
 						showPositionControls={ false }
 						showBindingsControls={ false }
@@ -501,7 +503,6 @@ const BlockInspectorSingleBlock = ( {
 			<BlockInspectorPreTabsSlot />
 			{ isEditingStyleState && (
 				<StyleStateInspectorSlots
-					blockName={ blockName }
 					clientId={ renderedBlockClientId }
 					contentClientIds={ contentClientIds }
 					isSectionBlock={ isSectionBlock }
@@ -530,7 +531,9 @@ const BlockInspectorSingleBlock = ( {
 					<InspectorControls.Slot group="list" ref={ listViewRef } />
 					<ListViewContentPopover listViewRef={ listViewRef } />
 					{ ! isSectionBlock && (
-						<StyleInspectorSlots blockName={ blockName } />
+						<StyleInspectorSlots
+							clientId={ renderedBlockClientId }
+						/>
 					) }
 				</>
 			) }

package/src/components/block-keyboard-shortcuts/index.jsx

@@ -0,0 +1,256 @@
+import { useCallback, useEffect, useRef } from '@wordpress/element';
+import { useSelect, useDispatch } from '@wordpress/data';
+import {
+	useShortcut,
+	store as keyboardShortcutsStore,
+} from '@wordpress/keyboard-shortcuts';
+import { store as blocksStore, switchToBlockType } from '@wordpress/blocks';
+import warning from '@wordpress/warning';
+import { store as blockEditorStore } from '../../store';
+import { unlock } from '../../lock-unlock';
+
+/**
+ * Returns every keyboard shortcut declared by a registered block type, through
+ * either a block variation or a block transform.
+ *
+ * @return {Array} Declared shortcuts, each paired with the block change it makes.
+ */
+function useDeclaredBlockShortcuts() {
+	return useSelect(
+		( select ) =>
+			unlock( select( blocksStore ) ).getBlockKeyboardShortcuts(),
+		[]
+	);
+}
+
+/**
+ * Returns a callback applying a block-declared shortcut to the selected block.
+ *
+ * The callback reports whether the shortcut was relevant to the current
+ * selection, which is not the same as whether the block changed: a shortcut
+ * that resolves to the block's current state is still handled, so that the key
+ * combination is swallowed rather than typed into the block.
+ *
+ * @return {Function} Callback receiving a declared shortcut.
+ */
+function useApplyBlockShortcut() {
+	const {
+		getBlock,
+		getBlockName,
+		getBlockAttributes,
+		getBlockEditingMode,
+		getSelectedBlockClientId,
+	} = useSelect( blockEditorStore );
+	const { getBlockVariations, getActiveBlockVariation } =
+		useSelect( blocksStore );
+	const { replaceBlocks, updateBlockAttributes } =
+		useDispatch( blockEditorStore );
+
+	return useCallback(
+		( { targetBlockName, blockNames, variationName } ) => {
+			const clientId = getSelectedBlockClientId();
+			if ( ! clientId ) {
+				return false;
+			}
+
+			// Transforming a block is a structural change, so it is only
+			// allowed where the block is fully editable.
+			if ( getBlockEditingMode( clientId ) !== 'default' ) {
+				return false;
+			}
+
+			const blockName = getBlockName( clientId );
+			if ( ! blockNames.includes( blockName ) ) {
+				return false;
+			}
+
+			const variation = variationName
+				? getBlockVariations( targetBlockName )?.find(
+						( { name } ) => name === variationName
+				  )
+				: undefined;
+
+			// The block is already of the target type, so there is nothing to
+			// transform. Applying the variation's attributes is all that is
+			// left to do.
+			if ( blockName === targetBlockName ) {
+				if ( ! variation?.attributes ) {
+					return false;
+				}
+				const activeVariation = getActiveBlockVariation(
+					targetBlockName,
+					getBlockAttributes( clientId )
+				);
+				if ( activeVariation?.name !== variationName ) {
+					updateBlockAttributes( clientId, variation.attributes );
+				}
+				return true;
+			}
+
+			const block = getBlock( clientId );
+			if ( ! block ) {
+				return false;
+			}
+
+			// Prefer a transform declared for this specific variation, and
+			// fall back to transforming to the block type and applying the
+			// variation's attributes on top.
+			let blocks = variation
+				? switchToBlockType( block, targetBlockName, variation.name )
+				: null;
+
+			if ( ! blocks ) {
+				blocks = switchToBlockType( block, targetBlockName );
+
+				if ( blocks && variation?.attributes ) {
+					blocks = blocks.map( ( newBlock ) =>
+						newBlock.name === targetBlockName
+							? {
+									...newBlock,
+									attributes: {
+										...newBlock.attributes,
+										...variation.attributes,
+									},
+							  }
+							: newBlock
+					);
+				}
+			}
+
+			if ( ! blocks ) {
+				return false;
+			}
+
+			replaceBlocks( clientId, blocks );
+			return true;
+		},
+		[
+			getBlock,
+			getBlockName,
+			getBlockAttributes,
+			getBlockEditingMode,
+			getSelectedBlockClientId,
+			getBlockVariations,
+			getActiveBlockVariation,
+			replaceBlocks,
+			updateBlockAttributes,
+		]
+	);
+}
+
+function BlockShortcut( { entry, apply } ) {
+	useShortcut( entry.name, ( event ) => {
+		// Another handler already acted on this event: either a shortcut
+		// claiming the same key combination, or this same shortcut mounted
+		// twice because block editor providers can be nested.
+		if ( event.defaultPrevented ) {
+			return;
+		}
+
+		if ( apply( entry ) ) {
+			event.preventDefault();
+		}
+	} );
+
+	return null;
+}
+
+function BlockShortcutsRegister( { shortcuts } ) {
+	const { registerShortcut, unregisterShortcut } = useDispatch(
+		keyboardShortcutsStore
+	);
+	// Shortcuts registered by a previous run, keyed by name, so that those
+	// belonging to a block type that has since been unregistered can be
+	// removed. Registration deliberately outlives this component: providers can
+	// be nested, and unmounting one of them must not take the shortcuts away
+	// from the others.
+	const registeredRef = useRef( new Map() );
+
+	useEffect( () => {
+		const registered = new Map();
+		const combinations = new Map();
+
+		for ( const shortcut of shortcuts ) {
+			const config = {
+				name: shortcut.name,
+				category: 'block',
+				description: shortcut.description,
+				keyCombination: shortcut.keyCombination,
+				aliases: shortcut.aliases,
+			};
+			const serialized = JSON.stringify( config );
+
+			// One shortcut is declared once per block change it can make, so
+			// the same name legitimately appears more than once: the heading
+			// level shortcuts are declared both on the variation, for a
+			// heading, and on the transform that produces one from a
+			// paragraph. Only declarations that disagree are a mistake, since
+			// the store keys shortcuts by name and the last one registered
+			// would decide what the others are matched against.
+			const previous = registered.get( shortcut.name );
+			if ( previous !== undefined ) {
+				if ( previous !== serialized ) {
+					warning(
+						`Block keyboard shortcut "${ shortcut.name }" is declared more than once with different settings.`
+					);
+				}
+				continue;
+			}
+
+			// Handlers are matched by key combination rather than by name, so
+			// two shortcuts claiming the same one both run on the same event,
+			// in registration order, and the first that applies takes it.
+			const { modifier, character } = shortcut.keyCombination;
+			const combination = `${ modifier ?? '' }+${ character }`;
+			if ( combinations.has( combination ) ) {
+				warning(
+					`Block keyboard shortcut "${
+						shortcut.name
+					}" uses the same key combination as "${ combinations.get(
+						combination
+					) }".`
+				);
+			}
+			combinations.set( combination, shortcut.name );
+
+			registerShortcut( config );
+			registered.set( shortcut.name, serialized );
+		}
+
+		for ( const name of registeredRef.current.keys() ) {
+			if ( ! registered.has( name ) ) {
+				unregisterShortcut( name );
+			}
+		}
+
+		registeredRef.current = registered;
+	}, [ shortcuts, registerShortcut, unregisterShortcut ] );
+
+	return null;
+}
+
+/**
+ * Registers and handles the keyboard shortcuts that blocks declare on their
+ * variations and transforms, applying them to the selected block.
+ *
+ * @return {Element} Element.
+ */
+export default function BlockKeyboardShortcuts() {
+	const shortcuts = useDeclaredBlockShortcuts();
+	const apply = useApplyBlockShortcut();
+
+	return (
+		<>
+			<BlockShortcutsRegister shortcuts={ shortcuts } />
+			{ shortcuts.map( ( entry, index ) => (
+				<BlockShortcut
+					// Shortcut names are not guaranteed to be unique across
+					// blocks, so the index keeps the list stable.
+					key={ `${ entry.name }-${ index }` }
+					entry={ entry }
+					apply={ apply }
+				/>
+			) ) }
+		</>
+	);
+}