@wordpress/block-editor 16.0.1-next.v.202607070741.0 → 16.2.0

package/src/components/writing-flow/use-editable-root-event-handlers.js

@@ -0,0 +1,259 @@
+import { useSelect } from '@wordpress/data';
+import { useRefEffect } from '@wordpress/compose';
+import { useContext } from '@wordpress/element';
+import { store as blockEditorStore } from '../../store';
+import { getBlockClientId, getSelectionEditableElement } from '../../utils/dom';
+import { BlockRefs } from '../provider/block-refs-provider';
+
+// The React `on*` props the host bridges, mapped to their DOM event type. Only
+// editing events are redirected under `editableRoot` (the wrapper becomes the
+// editing host, so keyboard, input and composition events target it instead of
+// the block); pointer and other events still reach the block and need no
+// bridging. React prop names don't map to DOM types by lowercasing in general
+// (onChange is `input`, onDoubleClick is `dblclick`), so the mapping is
+// explicit, which also locks the bridged surface to events React actually fires.
+const SUPPORTED_EVENTS = {
+	onKeyDown: 'keydown',
+	onKeyUp: 'keyup',
+	onBeforeInput: 'beforeinput',
+	onInput: 'input',
+	onCompositionStart: 'compositionstart',
+	onCompositionUpdate: 'compositionupdate',
+	onCompositionEnd: 'compositionend',
+};
+
+// The DOM event types the host listens for. Fixed, so the host attaches these
+// listeners once rather than tracking which types are in use.
+const EVENT_TYPES = Object.values( SUPPORTED_EVENTS );
+
+/**
+ * Collects the supported `on*` event handlers from a set of props, e.g. a
+ * block's merged `wrapperProps`, keyed by DOM event type. Used by the block to
+ * register them (see `useRegisterBlockEventHandlers`).
+ *
+ * @param {Object} props Props to read handlers from.
+ *
+ * @return {Object|undefined} The handlers by event type, or undefined when
+ *                            there are none.
+ */
+export function getEventHandlers( props ) {
+	let handlers;
+
+	for ( const name in SUPPORTED_EVENTS ) {
+		if ( typeof props[ name ] === 'function' ) {
+			handlers = handlers || {};
+			handlers[ SUPPORTED_EVENTS[ name ] ] = props[ name ];
+		}
+	}
+
+	return handlers;
+}
+
+// The native properties React copies onto its SyntheticEvent for each event
+// type (the *EventInterface tables in react-dom), so the wrapper exposes exactly
+// what a React handler would see and nothing more. Values are copied straight
+// from the native event; React's normalizers only paper over browsers we don't
+// support, and anything omitted stays reachable through `nativeEvent`, as in
+// React (e.g. `getTargetRanges` on a `beforeinput`).
+const EVENT_INTERFACE = [
+	'eventPhase',
+	'bubbles',
+	'cancelable',
+	'timeStamp',
+	'defaultPrevented',
+	'isTrusted',
+];
+const KEYBOARD_EVENT_INTERFACE = [
+	...EVENT_INTERFACE,
+	'view',
+	'detail',
+	'key',
+	'code',
+	'location',
+	'ctrlKey',
+	'shiftKey',
+	'altKey',
+	'metaKey',
+	'repeat',
+	'locale',
+	'getModifierState',
+	'charCode',
+	'keyCode',
+	'which',
+];
+const INPUT_EVENT_INTERFACE = [ ...EVENT_INTERFACE, 'data' ];
+const EVENT_INTERFACES = {
+	keydown: KEYBOARD_EVENT_INTERFACE,
+	keyup: KEYBOARD_EVENT_INTERFACE,
+	beforeinput: INPUT_EVENT_INTERFACE,
+	input: INPUT_EVENT_INTERFACE,
+	compositionstart: INPUT_EVENT_INTERFACE,
+	compositionupdate: INPUT_EVENT_INTERFACE,
+	compositionend: INPUT_EVENT_INTERFACE,
+};
+
+/**
+ * Builds a React `SyntheticEvent`-like object for an extension handler, which
+ * expects one. It mirrors what react-dom does: a plain object wrapping the real
+ * native event, eagerly copying the same interface properties React exposes for
+ * the event type, so a handler sees exactly React's surface and nothing more.
+ *
+ * `preventDefault` and `stopPropagation` forward to the native event, so they
+ * behave as through React; `stopPropagation` also flags the walk through block
+ * ancestors to stop. `target` is the editable inside the block rather than the
+ * real target (the editing host above it), and `currentTarget` is reassigned as
+ * the event bubbles from block to block.
+ *
+ * @param {Event}       nativeEvent The event to wrap.
+ * @param {HTMLElement} target      The element to report as the target.
+ *
+ * @return {Object} The synthetic event.
+ */
+function createBlockSyntheticEvent( nativeEvent, target ) {
+	let propagationStopped = false;
+
+	const syntheticEvent = {
+		nativeEvent,
+		type: nativeEvent.type,
+		target,
+		currentTarget: null,
+		preventDefault() {
+			nativeEvent.preventDefault();
+			syntheticEvent.defaultPrevented = true;
+		},
+		isDefaultPrevented() {
+			return syntheticEvent.defaultPrevented;
+		},
+		stopPropagation() {
+			nativeEvent.stopPropagation();
+			propagationStopped = true;
+		},
+		isPropagationStopped() {
+			return propagationStopped;
+		},
+		// The modern event system doesn't pool, so persistence is a no-op.
+		persist() {},
+		isPersistent() {
+			return true;
+		},
+	};
+
+	for ( const property of EVENT_INTERFACES[ nativeEvent.type ] ) {
+		const value = nativeEvent[ property ];
+		syntheticEvent[ property ] =
+			typeof value === 'function' ? value.bind( nativeEvent ) : value;
+	}
+
+	return syntheticEvent;
+}
+
+/**
+ * Backwards compatibility for block event handlers under `editableRoot`.
+ *
+ * When a block supports `editableRoot`, the writing flow wrapper is the
+ * contentEditable editing host, so keyboard, input and composition events
+ * target the wrapper instead of the block. React `on*` handlers a third party
+ * added to a block through `wrapperProps` (e.g. via an `editor.BlockListBlock`
+ * filter) are on the block element, below the target, so they stop firing.
+ *
+ * The block registers those handlers (see `useBlockProps`), and this hook
+ * calls them from the host: it resolves the block that owns the selection and
+ * every block ancestor, and invokes each registered handler with a synthetic
+ * event, innermost first, like a bubbling event. The listeners are attached
+ * where React attaches its own (the portal container, the iframe's document
+ * element), so a block's handler runs and its `preventDefault` /
+ * `stopPropagation` behave as they would through React, without editableRoot.
+ *
+ * This does not cover handlers a filter puts on its own wrapping element rather
+ * than the block's `wrapperProps`; the block element is the supported event
+ * surface. It can be removed once input handling is lifted to the host.
+ */
+export default function useEditableRootEventHandlers() {
+	const { hasMultiSelection, getBlockParents } =
+		useSelect( blockEditorStore );
+	const { refsMap, eventHandlers } = useContext( BlockRefs );
+	return useRefEffect(
+		( node ) => {
+			function onEvent( event ) {
+				// Only act on real events targeting the host itself, while it
+				// is the editing host for a single block and some block has a
+				// handler to call.
+				if (
+					! eventHandlers.size ||
+					event.target !== node ||
+					! event.isTrusted ||
+					node.contentEditable !== 'true' ||
+					hasMultiSelection()
+				) {
+					return;
+				}
+
+				const selection = node.ownerDocument.defaultView.getSelection();
+
+				if ( ! selection.rangeCount ) {
+					return;
+				}
+
+				const editable = getSelectionEditableElement( selection, node );
+				const clientId = getBlockClientId( editable );
+
+				if ( ! clientId ) {
+					return;
+				}
+
+				// Call the handler on the block that owns the selection and each
+				// of its block ancestors, innermost first, like a bubbling
+				// event. The hierarchy comes from the store rather than the DOM,
+				// and one synthetic event, wrapping the real event, is reused
+				// for the whole chain, its currentTarget moved from block to
+				// block. The element is only resolved for blocks with a handler.
+				const clientIds = [
+					clientId,
+					...getBlockParents( clientId, true ),
+				];
+
+				let syntheticEvent;
+				for ( const ancestorClientId of clientIds ) {
+					const handler =
+						eventHandlers.get( ancestorClientId )?.current?.[
+							event.type
+						];
+					const element = handler && refsMap.get( ancestorClientId );
+
+					if ( ! element ) {
+						continue;
+					}
+
+					if ( ! syntheticEvent ) {
+						syntheticEvent = createBlockSyntheticEvent(
+							event,
+							editable
+						);
+					}
+
+					syntheticEvent.currentTarget = element;
+					handler( syntheticEvent );
+
+					if ( syntheticEvent.isPropagationStopped() ) {
+						break;
+					}
+				}
+			}
+
+			// Attach where React attaches its own event system: the portal
+			// container, which for the iframed canvas is the document element
+			// (see `preparePortalMount` in react-dom). Listening at the same
+			// node, non-capture, means a block's handler runs in the bubbling
+			// phase after core, and its stopPropagation stops at the same point
+			// React's would, as its `on*` handler would without editableRoot.
+			const root = node.ownerDocument.documentElement;
+			const unsubscribers = EVENT_TYPES.map( ( type ) => {
+				root.addEventListener( type, onEvent );
+				return () => root.removeEventListener( type, onEvent );
+			} );
+			return () =>
+				unsubscribers.forEach( ( unsubscribe ) => unsubscribe() );
+		},
+		[ hasMultiSelection, getBlockParents, refsMap, eventHandlers ]
+	);
+}

package/src/components/writing-flow/use-editable-root.js

@@ -0,0 +1,105 @@
+import { useRegistry, useSelect } from '@wordpress/data';
+import { useRefEffect } from '@wordpress/compose';
+import { store as blockEditorStore } from '../../store';
+import { setContentEditableWrapper } from './utils';
+import { getBlockClientId, getSelectionEditableElement } from '../../utils/dom';
+import { unlock } from '../../lock-unlock';
+
+/**
+ * Keeps the writing flow wrapper contentEditable while the selected block
+ * supports `editableRoot`, so the native selection can extend across blocks.
+ * While the wrapper is editable it must also hold focus: a nested editable
+ * element cannot retain focus once an ancestor becomes an editing host (the
+ * first DOM mutation moves focus to the host, inconsistently across
+ * browsers).
+ */
+export default function useEditableRoot() {
+	const registry = useRegistry();
+	const enabled = useSelect( ( select ) => {
+		const { getSelectedBlockClientId, canHostEditableRoot, isZoomOut } =
+			unlock( select( blockEditorStore ) );
+		return (
+			! isZoomOut() && canHostEditableRoot( getSelectedBlockClientId() )
+		);
+	}, [] );
+
+	return useRefEffect(
+		( node ) => {
+			if ( ! enabled ) {
+				return;
+			}
+
+			const {
+				getSelectedBlockClientId,
+				hasMultiSelection,
+				isMultiSelecting,
+			} = registry.select( blockEditorStore );
+
+			// Focus is moved separately below, only when an editable
+			// element belonging to the selected block holds it.
+			if ( ! setContentEditableWrapper( node, true, { focus: false } ) ) {
+				return;
+			}
+
+			// Move focus from the block's editable element to the wrapper,
+			// but only when an editable element belonging to the selected
+			// block has focus. Never steal focus from other regions (e.g.
+			// List View), UI elements (e.g. buttons), or other editables
+			// within the wrapper (e.g. the post title). The selection is
+			// preserved. If the selection is still outside the focused
+			// element, a mousedown just focused it and the browser has not
+			// placed the caret yet; moving focus now would cancel the
+			// pending caret placement. The selection observer moves focus
+			// once the selection lands.
+			const { activeElement } = node.ownerDocument;
+			const selection = node.ownerDocument.defaultView.getSelection();
+			if (
+				activeElement !== node &&
+				activeElement?.isContentEditable &&
+				node.contains( activeElement ) &&
+				getBlockClientId( activeElement ) ===
+					getSelectedBlockClientId() &&
+				selection.anchorNode &&
+				activeElement.contains( selection.anchorNode )
+			) {
+				node.focus();
+			}
+
+			return () => {
+				// A multi-selection owns the wrapper as its editing host
+				// now: the host and its textbox semantics remain, and the
+				// selection observer disables both together when the
+				// selection collapses. Removing the attributes here would
+				// strip the accessible name off the focused editing host at
+				// the moment cross-block editing begins.
+				if ( hasMultiSelection() || isMultiSelecting() ) {
+					return;
+				}
+
+				setContentEditableWrapper( node, false );
+
+				// If the wrapper held focus, return focus to the editable
+				// element containing the selection, which is focusable
+				// again now that the wrapper is no longer an editing host.
+				// Only do so if that element belongs to the selected block:
+				// when the selection moved to another block through the
+				// store, the stale DOM selection must not reclaim block
+				// selection through its focus handler.
+				if ( node.ownerDocument.activeElement === node ) {
+					const editable = getSelectionEditableElement(
+						node.ownerDocument.defaultView.getSelection(),
+						node
+					);
+					if (
+						editable &&
+						getBlockClientId( editable ) ===
+							getSelectedBlockClientId()
+					) {
+						editable.focus();
+					}
+				}
+			};
+		},
+		[ enabled, registry ]
+	);
+}

package/src/components/writing-flow/use-home-end.js

@@ -0,0 +1,64 @@
+import { HOME, END } from '@wordpress/keycodes';
+import { useSelect } from '@wordpress/data';
+import { useRefEffect } from '@wordpress/compose';
+import { getSelectionEditableElement } from '../../utils/dom';
+import { store as blockEditorStore } from '../../store';
+
+/**
+ * Moves the caret to the start or end of the visual line for Home and End
+ * with `Selection.modify()`, because the browser's default caret movement
+ * cannot be relied on in two cases:
+ *
+ * - While the wrapper is the contentEditable editing host (a selected block
+ *   supports `editableRoot`), browsers don't perform the default caret
+ *   movement for Home and End.
+ * - Chromium on macOS maps Home and End to scroll commands, so it never
+ *   moves the caret in editable content on that platform, including nested
+ *   editable elements like the tab labels in the tab-list block.
+ */
+export default function useHomeEnd() {
+	const { hasMultiSelection } = useSelect( blockEditorStore );
+	return useRefEffect( ( node ) => {
+		function onKeyDown( event ) {
+			if ( event.defaultPrevented ) {
+				return;
+			}
+
+			if ( event.keyCode !== HOME && event.keyCode !== END ) {
+				return;
+			}
+
+			if ( event.metaKey || event.ctrlKey || event.altKey ) {
+				return;
+			}
+
+			// Only handle keys pressed in editable content, in both of the
+			// cases mentioned above: `event.target` is the focused element,
+			// and `isContentEditable` is true both for the wrapper as the
+			// editing host and for a nested editable element like a tab label.
+			// Anything else that takes focus like inputs and textareas keep
+			// default behavior.
+			if ( ! event.target.isContentEditable || hasMultiSelection() ) {
+				return;
+			}
+
+			const selection = node.ownerDocument.defaultView.getSelection();
+
+			if ( ! getSelectionEditableElement( selection, node ) ) {
+				return;
+			}
+
+			event.preventDefault();
+			selection.modify(
+				event.shiftKey ? 'extend' : 'move',
+				event.keyCode === HOME ? 'backward' : 'forward',
+				'lineboundary'
+			);
+		}
+
+		node.addEventListener( 'keydown', onKeyDown );
+		return () => {
+			node.removeEventListener( 'keydown', onKeyDown );
+		};
+	}, [] );
+}

package/src/components/writing-flow/use-input.js

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { useSelect, useDispatch } from '@wordpress/data';
 import { useRefEffect } from '@wordpress/compose';
 import { ENTER, BACKSPACE, DELETE } from '@wordpress/keycodes';
@@ -11,11 +8,9 @@ import {
 	getBlockTransforms,
 	findTransform,
 } from '@wordpress/blocks';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
+import { setContentEditableWrapper } from './utils';
+import { getSelectionEditableElement } from '../../utils/dom';
 
 /**
  * Handles input for selections across blocks.
@@ -45,10 +40,25 @@ export default function useInput() {
 
 	return useRefEffect( ( node ) => {
 		function onBeforeInput( event ) {
-			// If writing flow is editable, NEVER allow the browser to alter the
-			// DOM. This will cause React errors (and the DOM should only be
-			// altered in a controlled fashion).
-			if ( node.contentEditable === 'true' ) {
+			// If writing flow is editable, never allow the browser to alter
+			// the DOM outside of an editable element within a block. This
+			// will cause React errors (and the DOM should only be altered in
+			// a controlled fashion). The wrapper can be contentEditable with
+			// a single selection when the selected block supports
+			// `editableRoot`; in that case edits within the block's editable
+			// element are handled by its rich text instance.
+			if ( node.contentEditable !== 'true' ) {
+				return;
+			}
+
+			if ( hasMultiSelection() ) {
+				event.preventDefault();
+				return;
+			}
+
+			const selection = node.ownerDocument.defaultView.getSelection();
+
+			if ( ! getSelectionEditableElement( selection, node ) ) {
 				event.preventDefault();
 			}
 		}
@@ -127,7 +137,7 @@ export default function useInput() {
 			}
 
 			if ( event.keyCode === ENTER ) {
-				node.contentEditable = false;
+				setContentEditableWrapper( node, false );
 				event.preventDefault();
 				if ( __unstableIsFullySelected() ) {
 					replaceBlocks(
@@ -141,7 +151,7 @@ export default function useInput() {
 				event.keyCode === BACKSPACE ||
 				event.keyCode === DELETE
 			) {
-				node.contentEditable = false;
+				setContentEditableWrapper( node, false );
 				event.preventDefault();
 				if ( __unstableIsFullySelected() ) {
 					removeBlocks( getSelectedBlockClientIds() );
@@ -156,7 +166,7 @@ export default function useInput() {
 				event.key.length === 1 &&
 				! ( event.metaKey || event.ctrlKey )
 			) {
-				node.contentEditable = false;
+				setContentEditableWrapper( node, false );
 				if ( __unstableIsSelectionMergeable() ) {
 					__unstableDeleteSelection( event.keyCode === DELETE );
 				} else {
@@ -176,7 +186,7 @@ export default function useInput() {
 				return;
 			}
 
-			node.contentEditable = false;
+			setContentEditableWrapper( node, false );
 
 			if ( __unstableIsSelectionMergeable() ) {
 				__unstableDeleteSelection();

package/src/components/writing-flow/use-multi-selection.js

@@ -1,13 +1,7 @@
-/**
- * WordPress dependencies
- */
 import { useRefEffect } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
+import { setContentEditableWrapper } from './utils';
 
 function selector( select ) {
 	const {
@@ -73,11 +67,9 @@ export default function useMultiSelection() {
 			// all content editable. We can't rely on using the store and
 			// React because re-rending happens too slowly. We need to be
 			// able to select across instances immediately.
-			node.contentEditable = true;
-
 			// For some browsers, like Safari, it is important that focus
 			// happens BEFORE selection removal.
-			node.focus();
+			setContentEditableWrapper( node, true );
 
 			defaultView.getSelection().removeAllRanges();
 		},

package/src/components/writing-flow/use-preview-mode-nav.js

@@ -1,13 +1,6 @@
-/**
- * WordPress dependencies
- */
 import { useRefEffect } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
 import { TAB, UP, DOWN, LEFT, RIGHT } from '@wordpress/keycodes';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
 
 /**

package/src/components/writing-flow/use-select-all.js

@@ -1,16 +1,13 @@
-/**
- * WordPress dependencies
- */
 import { isEntirelySelected } from '@wordpress/dom';
 import { useSelect, useDispatch } from '@wordpress/data';
 import { __unstableUseShortcutEventMatch as useShortcutEventMatch } from '@wordpress/keyboard-shortcuts';
 import { useRefEffect } from '@wordpress/compose';
-
-/**
- * Internal dependencies
- */
 import { store as blockEditorStore } from '../../store';
-import { isInsideRootBlock, getBlockClientId } from '../../utils/dom';
+import {
+	isInsideRootBlock,
+	getBlockClientId,
+	getSelectionEditableElement,
+} from '../../utils/dom';
 
 export default function useSelectAll() {
 	const { getBlockOrder, getSelectedBlockClientIds, getBlockRootClientId } =
@@ -25,17 +22,43 @@ export default function useSelectAll() {
 			}
 
 			const selectedClientIds = getSelectedBlockClientIds();
+			const { ownerDocument } = node;
+			const selection = ownerDocument.defaultView.getSelection();
+			// When the wrapper is contentEditable and holds focus (the
+			// selected block supports `editableRoot`), the event targets the
+			// wrapper; resolve the editable element containing the selection.
+			const editable =
+				( event.target === node &&
+					getSelectionEditableElement( selection, node ) ) ||
+				event.target;
 
 			if (
 				selectedClientIds.length < 2 &&
-				! isEntirelySelected( event.target )
+				! isEntirelySelected( editable )
 			) {
+				// While the wrapper is contentEditable, the browser default
+				// would select the entire canvas. Select the contents of the
+				// editable element instead, like the default does when the
+				// element itself holds focus.
+				if ( event.target === node && editable !== node ) {
+					event.preventDefault();
+					const range = ownerDocument.createRange();
+					range.selectNodeContents( editable );
+					selection.removeAllRanges();
+					selection.addRange( range );
+					// The native `selectionchange` event is asynchronous;
+					// dispatch it synchronously so that listeners depending
+					// on it (e.g. the rich text internal record sync) run
+					// before any event following this one.
+					ownerDocument.dispatchEvent(
+						new Event( 'selectionchange' )
+					);
+				}
 				return;
 			}
 
 			event.preventDefault();
 
-			const { ownerDocument } = event.target;
 			const [ firstSelectedClientId ] = selectedClientIds;
 			const activeClientId = getBlockClientId(
 				ownerDocument.activeElement