@wordpress/block-editor 16.2.0 → 17.0.0

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.js).
+
+## 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

@@ -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,7 +97,7 @@ function StyleStateInspectorSlots( {
 	isSectionBlock,
 	selectedBlockStyleState,
 } ) {
-	const borderPanelLabel = useBorderPanelLabel( { blockName } );
+	const borderPanelLabel = useBorderPanelLabel( { clientId } );
 	const showLayoutControls =
 		hasViewportBlockStyleState( selectedBlockStyleState ) &&
 		! hasPseudoBlockStyleState( selectedBlockStyleState );
@@ -298,7 +298,6 @@ function BlockInspector() {
 					<InspectorControlsTabs tabs={ availableTabs } />
 				) : (
 					<StyleInspectorSlots
-						blockName={ renderedBlockName }
 						showAdvancedControls={ false }
 						showPositionControls={ false }
 						showBindingsControls={ false }
@@ -501,7 +500,6 @@ const BlockInspectorSingleBlock = ( {
 			<BlockInspectorPreTabsSlot />
 			{ isEditingStyleState && (
 				<StyleStateInspectorSlots
-					blockName={ blockName }
 					clientId={ renderedBlockClientId }
 					contentClientIds={ contentClientIds }
 					isSectionBlock={ isSectionBlock }
@@ -530,7 +528,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.js

@@ -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 }
+				/>
+			) ) }
+		</>
+	);
+}

package/src/components/block-list/block.js

@@ -771,6 +771,11 @@ function BlockListBlockProvider( props ) {
 				blockVisibility,
 				deviceType,
 				viewportSettings,
+				supportsSplitting: hasBlockSupport(
+					blockName,
+					'splitting',
+					false
+				),
 			};
 		},
 		[ clientId, rootClientId, ghostBlock, ghostBlockWithoutAttributes ]
@@ -854,6 +859,7 @@ function BlockListBlockProvider( props ) {
 		blockVisibility,
 		deviceType,
 		viewportSettings,
+		supportsSplitting,
 	} = selectedProps;
 
 	const privateContext = {
@@ -896,6 +902,7 @@ function BlockListBlockProvider( props ) {
 		blockVisibility,
 		deviceType,
 		viewportSettings,
+		supportsSplitting,
 	};
 
 	if (

package/src/components/block-list/index.js

@@ -55,7 +55,13 @@ function Root( { className, ...settings } ) {
 		} = getSettings();
 		return {
 			isOutlineMode: outlineMode && ! isTyping(),
-			isFocusMode: focusMode || hasBlockSpotlight(),
+			/*
+			 * Spotlight fades everything but the block being worked on, which
+			 * has nothing to offer a canvas that cannot be edited — a preview
+			 * would just render most of its content faded out.
+			 */
+			isFocusMode:
+				! _isPreviewMode && ( focusMode || hasBlockSpotlight() ),
 			isPreviewMode: _isPreviewMode,
 			editedContentOnlySection: getEditedContentOnlySection(),
 		};

package/src/components/block-list/use-block-props/use-focus-first-element.js

@@ -50,6 +50,11 @@ export function useFocusFirstElement( { clientId, initialPosition } ) {
 			return;
 		}
 
+		if ( initialPosition === true ) {
+			ref.current.focus();
+			return;
+		}
+
 		// Find all tabbables within node.
 		const textInputs = focus.tabbable
 			.find( ref.current )

package/src/components/block-list/use-block-props/use-selected-block-event-handlers.js

@@ -28,7 +28,6 @@ export function useEventHandlers( { clientId, isSelected } ) {
 		getBlock,
 	} = unlock( useSelect( blockEditorStore ) );
 	const {
-		insertAfterBlock,
 		removeBlock,
 		resetZoomLevel,
 		startDraggingBlocks,
@@ -66,13 +65,13 @@ export function useEventHandlers( { clientId, isSelected } ) {
 					return;
 				}
 
-				event.preventDefault();
-
-				if ( keyCode === ENTER && isZoomOut() ) {
-					resetZoomLevel();
-				} else if ( keyCode === ENTER ) {
-					insertAfterBlock( clientId );
+				if ( keyCode === ENTER ) {
+					if ( isZoomOut() ) {
+						event.preventDefault();
+						resetZoomLevel();
+					}
 				} else {
+					event.preventDefault();
 					removeBlock( clientId );
 				}
 			}
@@ -327,7 +326,6 @@ export function useEventHandlers( { clientId, isSelected } ) {
 			getBlock,
 			isReusableBlock,
 			isTemplatePart,
-			insertAfterBlock,
 			removeBlock,
 			isZoomOut,
 			resetZoomLevel,