@wordpress/block-editor 16.0.0 → 16.1.0

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

@@ -13,8 +13,12 @@ import { getBlockClientId } from '../../utils/dom';
 
 export default function useClickSelection() {
 	const { selectBlock } = useDispatch( blockEditorStore );
-	const { isSelectionEnabled, getBlockSelectionStart, hasMultiSelection } =
-		useSelect( blockEditorStore );
+	const {
+		isSelectionEnabled,
+		getBlockSelectionStart,
+		getSelectionStart,
+		hasMultiSelection,
+	} = useSelect( blockEditorStore );
 	return useRefEffect(
 		( node ) => {
 			function onMouseDown( event ) {
@@ -31,7 +35,53 @@ export default function useClickSelection() {
 					// When selecting a single block in a document by holding the shift key,
 					// don't mark this action as multiselection.
 					if ( startClientId && startClientId !== clickedClientId ) {
-						setContentEditableWrapper( node, true );
+						// When the selected block has no text selection
+						// within it (e.g. an image or spacer), there is no
+						// native selection for the wrapper to adopt when it
+						// is focused, so Safari inserts a caret at the start
+						// of the wrapper and asynchronously reveals it,
+						// scrolling a scrolled-down viewport back up, which
+						// `preventScroll` does not cover. Leave focus alone
+						// in that case: the click moves it.
+						const { clientId, attributeKey } = getSelectionStart();
+						setContentEditableWrapper( node, true, {
+							focus: !! attributeKey,
+						} );
+
+						// The browser extends the selection from the native
+						// anchor. When a block is selected without a text
+						// selection within it, there is no native anchor,
+						// and browsers synthesize one at the nearest text
+						// instead, excluding the block itself. Give the
+						// browser the right anchor before it acts on the
+						// click: the near edge of the selected block, so the
+						// whole block ends up within the extended selection.
+						const { ownerDocument } = node;
+						const selection =
+							ownerDocument.defaultView.getSelection();
+						const blockElement =
+							! attributeKey &&
+							ownerDocument.getElementById(
+								`block-${ clientId }`
+							);
+
+						if (
+							blockElement &&
+							! (
+								selection.anchorNode &&
+								blockElement.contains( selection.anchorNode )
+							)
+						) {
+							const isForward =
+								// eslint-disable-next-line no-bitwise
+								blockElement.compareDocumentPosition(
+									event.target
+								) & node.DOCUMENT_POSITION_FOLLOWING;
+							selection.setPosition(
+								blockElement,
+								isForward ? 0 : blockElement.childNodes.length
+							);
+						}
 					}
 				} else if ( hasMultiSelection() ) {
 					// Allow user to escape out of a multi-selection to a
@@ -54,6 +104,7 @@ export default function useClickSelection() {
 			selectBlock,
 			isSelectionEnabled,
 			getBlockSelectionStart,
+			getSelectionStart,
 			hasMultiSelection,
 		]
 	);

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

@@ -0,0 +1,266 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { useRefEffect } from '@wordpress/compose';
+import { useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+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

@@ -3,7 +3,6 @@
  */
 import { useRegistry, useSelect } from '@wordpress/data';
 import { useRefEffect } from '@wordpress/compose';
-import { hasBlockSupport } from '@wordpress/blocks';
 
 /**
  * Internal dependencies
@@ -13,77 +12,6 @@ import { setContentEditableWrapper } from './utils';
 import { getBlockClientId, getSelectionEditableElement } from '../../utils/dom';
 import { unlock } from '../../lock-unlock';
 
-/**
- * Returns true when the writing flow wrapper can host editing for the given
- * block: it supports `editableRoot`, is edited visually in the default
- * editing mode, and has sibling blocks for a native selection to extend
- * into, all of them editable.
- *
- * @param {Object} select   Bound block editor store selectors.
- * @param {string} clientId Block client ID.
- *
- * @return {boolean} Whether an editing host can host the block.
- */
-export function canHostEditableRoot( select, clientId ) {
-	const {
-		getBlockName,
-		getBlockEditingMode,
-		getBlockMode,
-		getBlockRootClientId,
-		getBlockOrder,
-	} = select;
-
-	if (
-		! clientId ||
-		getBlockEditingMode( clientId ) !== 'default' ||
-		// Not when the block is edited as HTML: there is no rich text to
-		// host then, only a textarea, which the editing host would
-		// interfere with.
-		getBlockMode( clientId ) !== 'visual' ||
-		! hasBlockSupport( getBlockName( clientId ), 'editableRoot', false )
-	) {
-		return false;
-	}
-
-	// Only host when the block has sibling blocks for a native selection to
-	// extend into, all of them editable. A lone block (e.g. a single
-	// paragraph nested in an HTML block) is edited on its own element, and
-	// read-only siblings (e.g. pattern content without overrides enabled)
-	// must not become editable by inheriting from the host.
-	const siblings = getBlockOrder( getBlockRootClientId( clientId ) );
-	return (
-		siblings.length > 1 &&
-		siblings.every(
-			( siblingClientId ) =>
-				getBlockEditingMode( siblingClientId ) === 'default'
-		)
-	);
-}
-
-/**
- * Returns true when the writing flow wrapper should be contentEditable: the
- * selected block supports `editableRoot`.
- *
- * @return {boolean} Whether the wrapper should be editable.
- */
-export function useHasEditableRoot() {
-	return useSelect( ( select ) => {
-		const selectors = select( blockEditorStore );
-		return canHostEditableRoot(
-			selectors,
-			selectors.getSelectedBlockClientId()
-		);
-	}, [] );
-}
-
-/**
- * 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).
- */
 /**
  * Keeps the writing flow wrapper contentEditable while the selected block
  * supports `editableRoot`, so the native selection can extend across blocks.
@@ -94,11 +22,13 @@ export function useHasEditableRoot() {
  */
 export default function useEditableRoot() {
 	const registry = useRegistry();
-	const isZoomOut = useSelect(
-		( select ) => unlock( select( blockEditorStore ) ).isZoomOut(),
-		[]
-	);
-	const enabled = useHasEditableRoot() && ! isZoomOut;
+	const enabled = useSelect( ( select ) => {
+		const { getSelectedBlockClientId, canHostEditableRoot, isZoomOut } =
+			unlock( select( blockEditorStore ) );
+		return (
+			! isZoomOut() && canHostEditableRoot( getSelectedBlockClientId() )
+		);
+	}, [] );
 
 	return useRefEffect(
 		( node ) => {

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

@@ -12,10 +12,16 @@ import { getSelectionEditableElement } from '../../utils/dom';
 import { store as blockEditorStore } from '../../store';
 
 /**
- * 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. Perform the equivalent movement with
- * `Selection.modify()`.
+ * 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 );
@@ -33,11 +39,13 @@ export default function useHomeEnd() {
 				return;
 			}
 
-			if (
-				node.contentEditable !== 'true' ||
-				node.ownerDocument.activeElement !== node ||
-				hasMultiSelection()
-			) {
+			// 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;
 			}
 

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

@@ -14,8 +14,7 @@ import { isSelectionForward } from '@wordpress/dom';
  */
 import { store as blockEditorStore } from '../../store';
 import { getBlockClientId } from '../../utils/dom';
-import { canHostEditableRoot } from './use-editable-root';
-import { setContentEditableWrapper, setShiftClickInProgress } from './utils';
+import { setContentEditableWrapper } from './utils';
 import { unlock } from '../../lock-unlock';
 
 const { ownsSelection } = unlock( richTextPrivateApis );
@@ -102,9 +101,13 @@ function getRichTextElement( node ) {
  * Sets a multi-selection based on the native selection across blocks.
  */
 export default function useSelectionObserver() {
-	const { multiSelect, selectBlock, selectionChange } =
-		useDispatch( blockEditorStore );
-	const blockEditorSelectors = useSelect( blockEditorStore );
+	const {
+		multiSelect,
+		selectBlock,
+		selectionChange,
+		startMultiSelect,
+		stopMultiSelect,
+	} = useDispatch( blockEditorStore );
 	const {
 		getBlockParents,
 		getBlockSelectionStart,
@@ -112,7 +115,8 @@ export default function useSelectionObserver() {
 		getSelectionStart,
 		getSelectionEnd,
 		getSelectedBlockClientId,
-	} = blockEditorSelectors;
+		canHostEditableRoot,
+	} = unlock( useSelect( blockEditorStore ) );
 	return useRefEffect(
 		( node ) => {
 			const { ownerDocument } = node;
@@ -122,12 +126,18 @@ export default function useSelectionObserver() {
 
 			function onMouseDown( event ) {
 				isTripleClick = event.detail === 3;
-				setShiftClickInProgress( event.shiftKey );
+				// A shift+click makes a multi-selection: mark the gesture as
+				// in progress so the clicked block's focus handler does not
+				// select it (collapsing the native range being made), and so
+				// use-multi-selection does not clear the native selection.
+				// The selection is built on mouseup.
+				if ( event.shiftKey ) {
+					startMultiSelect();
+				}
 			}
 
 			function onKeyDown() {
 				isTripleClick = false;
-				setShiftClickInProgress( false );
 			}
 
 			function onSelectionChange( event ) {
@@ -174,10 +184,7 @@ export default function useSelectionObserver() {
 						// always move it), which must not re-enable the wrapper
 						// after another block has been selected.
 						collapsedClientId === getSelectedBlockClientId() &&
-						canHostEditableRoot(
-							blockEditorSelectors,
-							collapsedClientId
-						)
+						canHostEditableRoot( collapsedClientId )
 					) {
 						setContentEditableWrapper( node, true );
 
@@ -362,9 +369,19 @@ export default function useSelectionObserver() {
 					];
 					const depth = findDepth( startPath, endPath );
 
+					// If one path ends before they diverge, one block
+					// contains the other, so there are no sibling blocks
+					// to promote the selection to. Record the selection as
+					// is: it resolves to the outer block, which is treated
+					// as fully selected. See `getSelectionNestingAncestor`
+					// in the store.
+					const isAncestorDescendant =
+						depth >= startPath.length || depth >= endPath.length;
+
 					if (
-						startPath[ depth ] !== startClientId ||
-						endPath[ depth ] !== endClientId
+						! isAncestorDescendant &&
+						( startPath[ depth ] !== startClientId ||
+							endPath[ depth ] !== endClientId )
 					) {
 						multiSelect( startPath[ depth ], endPath[ depth ] );
 						return;
@@ -444,7 +461,7 @@ export default function useSelectionObserver() {
 			);
 			function onMouseUp( event ) {
 				onSelectionChange( event );
-				setShiftClickInProgress( false );
+				stopMultiSelect();
 			}
 
 			defaultView.addEventListener( 'mouseup', onMouseUp );

package/src/components/writing-flow/utils.js

@@ -118,29 +118,6 @@ function toPlainText( html ) {
 	return plainText.replace( /\n\n+/g, '\n\n' );
 }
 
-let shiftClickInProgress = false;
-
-/**
- * Tracks whether a shift+click gesture is in progress, from the shift held
- * mousedown until its mouseup. Maintained by the selection observer; read by
- * the block focus handler, since the focus event fired between the two
- * carries no modifier keys.
- *
- * @param {boolean} value Whether a shift+click gesture is in progress.
- */
-export function setShiftClickInProgress( value ) {
-	shiftClickInProgress = value;
-}
-
-/**
- * Returns whether a shift+click gesture is in progress.
- *
- * @return {boolean} Whether a shift+click gesture is in progress.
- */
-export function isShiftClickInProgress() {
-	return shiftClickInProgress;
-}
-
 /**
  * Makes the wrapper element an editing host, or stops it from being one. The
  * ARIA attributes travel with the editability: while the wrapper is the
@@ -194,7 +171,9 @@ export function setContentEditableWrapper(
 	node.setAttribute( 'aria-label', __( 'Editor canvas' ) );
 
 	if ( focus ) {
-		node.focus();
+		// Without preventScroll, focusing the wrapper scrolls the
+		// viewport to the top of the wrapper.
+		node.focus( { preventScroll: true } );
 	}
 
 	return true;