@wordpress/block-editor 17.0.0 → 17.1.0

package/src/components/writing-flow/{use-tab-nav.js → use-tab-nav.jsx}

@@ -1,16 +1,37 @@
 import { focus, isFormElement } from '@wordpress/dom';
-import { TAB } from '@wordpress/keycodes';
+import { TAB, withIgnoreIMEEvents } from '@wordpress/keycodes';
+import { __ } from '@wordpress/i18n';
 import { useSelect, useDispatch } from '@wordpress/data';
-import { useRefEffect, useMergeRefs } from '@wordpress/compose';
+import { useRefEffect, useMergeRefs, useInstanceId } from '@wordpress/compose';
 import { useRef } from '@wordpress/element';
 import { store as blockEditorStore } from '../../store';
 import { isInSameBlock, isInsideRootBlock } from '../../utils/dom';
 import { unlock } from '../../lock-unlock';
 
+/**
+ * Spans the element over the canvas, so it is always at least partially in
+ * view and focussing it never scrolls the content. Fixed positioning would
+ * achieve that too, but makes Safari composite the scrollable canvas on a
+ * layer sized to the whole document instead of the visible pane.
+ */
+const PREVENT_SCROLL_ON_FOCUS = {
+	position: 'absolute',
+	inset: 0,
+	pointerEvents: 'none',
+	outline: 'none',
+};
+
+// Keys that move focus from the canvas stop into the canvas.
+const ENTRY_KEYS = [ 'Enter', ' ', 'F2', 'Escape' ];
+
 export default function useTabNav() {
 	const containerRef = /** @type {typeof useRef<HTMLElement>} */ ( useRef )();
 	const focusCaptureBeforeRef = useRef();
 	const focusCaptureAfterRef = useRef();
+	const hintId = useInstanceId(
+		useTabNav,
+		'block-editor-writing-flow__canvas-stop-hint'
+	);
 
 	const {
 		hasMultiSelection,
@@ -19,6 +40,7 @@ export default function useTabNav() {
 		getBlockOrder,
 		getLastFocus,
 		getSectionRootClientId,
+		getEditedContentOnlySection,
 		isZoomOut,
 	} = unlock( useSelect( blockEditorStore ) );
 	const { setLastFocus } = unlock( useDispatch( blockEditorStore ) );
@@ -27,16 +49,17 @@ export default function useTabNav() {
 	// capturing on the focus capture elements.
 	const noCaptureRef = useRef();
 
-	function onFocusCapture( event ) {
-		const canvasElement =
-			containerRef.current.ownerDocument === event.target.ownerDocument
-				? containerRef.current
-				: containerRef.current.ownerDocument.defaultView.frameElement;
+	// The canvas is a single stop in the page's tab order, and going in is
+	// an explicit action on it. Focus returns to the place it last left the
+	// canvas from.
+	function enterCanvas() {
+		// Focus the canvas window first. The stop is in the parent document,
+		// and when Firefox focuses an element in another document, it does
+		// not move window focus, so the caret would be restored but key
+		// presses would keep going to the parent page.
+		containerRef.current.ownerDocument.defaultView.focus();
 
-		// Do not capture incoming focus if set by us in WritingFlow.
-		if ( noCaptureRef.current ) {
-			noCaptureRef.current = null;
-		} else if ( hasMultiSelection() ) {
+		if ( hasMultiSelection() ) {
 			containerRef.current.focus();
 		} else if ( getSelectedBlockClientId() ) {
 			if ( getLastFocus()?.current ) {
@@ -68,36 +91,107 @@ export default function useTabNav() {
 					.focus();
 			} else {
 				// If we don't have any section root, focus the canvas.
-				canvasElement.focus();
+				containerRef.current.focus();
 			}
 		} else {
-			const isBefore =
-				// eslint-disable-next-line no-bitwise
-				event.target.compareDocumentPosition( canvasElement ) &
-				event.target.DOCUMENT_POSITION_FOLLOWING;
 			const tabbables = focus.tabbable.find( containerRef.current );
 			if ( tabbables.length ) {
-				const next = isBefore
-					? tabbables[ 0 ]
-					: tabbables[ tabbables.length - 1 ];
-				next.focus();
+				tabbables[ 0 ].focus();
+			} else {
+				// Nothing in the canvas is tabbable. Entering still enters:
+				// keys go to the canvas, and a block can be selected with
+				// the arrow keys or a click.
+				containerRef.current.focus();
 			}
 		}
 	}
 
+	function onStopKeyDown( event ) {
+		if (
+			event.defaultPrevented ||
+			event.ctrlKey ||
+			event.metaKey ||
+			event.altKey
+		) {
+			return;
+		}
+
+		const { key } = event;
+
+		if ( ! event.shiftKey && ENTRY_KEYS.includes( key ) ) {
+			event.preventDefault();
+			enterCanvas();
+			return;
+		}
+
+		// Shift+Tab leaves the canvas on its own, because the stop is the
+		// first element before it. Plain Tab would move into the content,
+		// so move focus to the first tabbable element past the canvas.
+		if ( key === 'Tab' && ! event.shiftKey ) {
+			event.preventDefault();
+			focus.tabbable.findNext( focusCaptureAfterRef.current )?.focus();
+		}
+	}
+
+	// Focus arriving on the stop engages the canvas right away, like a
+	// text field that starts editing when focused. Only Escape parks
+	// focus on the stop, giving Tab traction again: from a parked stop,
+	// Tab moves to the interface around the canvas, not the content.
+	function onStopFocus() {
+		if ( noCaptureRef.current ) {
+			noCaptureRef.current = null;
+			return;
+		}
+		enterCanvas();
+	}
+
 	const before = (
 		<div
 			ref={ focusCaptureBeforeRef }
 			tabIndex="0"
-			onFocus={ onFocusCapture }
-		/>
+			role="button"
+			aria-label={ __( 'Editor canvas' ) }
+			aria-describedby={ hintId }
+			className="block-editor-writing-flow__canvas-stop"
+			style={ PREVENT_SCROLL_ON_FOCUS }
+			onFocus={ onStopFocus }
+			onKeyDown={ onStopKeyDown }
+			// Assistive technology activates a button with a click event,
+			// not a key press. Pointer clicks pass through the element, so
+			// a click can only come from such an activation.
+			onClick={ enterCanvas }
+		>
+			{ /* The hint is also the button's description for assistive
+			     technology. Content hidden with `display: none` still
+			     works for `aria-describedby`. */ }
+			<div
+				className="block-editor-writing-flow__canvas-stop-hint"
+				id={ hintId }
+			>
+				{ __( 'Press Enter to edit the document' ) }
+			</div>
+		</div>
 	);
 
+	// Focus landing on the element after the canvas enters it, the same
+	// as focus landing on the stop before it.
+	function onFocusCapture() {
+		// Do not act on focus set by the tab handler below, which moves
+		// focus here so that the default behaviour (moving focus to the
+		// next tabbable element) continues from this element.
+		if ( noCaptureRef.current ) {
+			noCaptureRef.current = null;
+			return;
+		}
+		enterCanvas();
+	}
+
 	const after = (
 		<div
 			ref={ focusCaptureAfterRef }
 			tabIndex="0"
 			onFocus={ onFocusCapture }
+			style={ PREVENT_SCROLL_ON_FOCUS }
 		/>
 	);
 
@@ -107,12 +201,39 @@ export default function useTabNav() {
 				return;
 			}
 
+			// Escape steps out of the canvas onto its stop. Everything with
+			// a stronger claim on the key runs first: handlers deeper in
+			// the tree, capture handlers, and listeners registered earlier
+			// on this node, like the automatic change undo. If the key is
+			// still unclaimed here, nothing else wants it.
+			if (
+				event.key === 'Escape' &&
+				! event.shiftKey &&
+				! event.ctrlKey &&
+				! event.metaKey &&
+				! event.altKey
+			) {
+				// While a content-only section is being edited, Escape first
+				// stops editing it. That handler lives in the parent
+				// document and runs after this one, so leave the key to it.
+				if ( getEditedContentOnlySection() ) {
+					return;
+				}
+				if ( focusCaptureBeforeRef.current ) {
+					event.preventDefault();
+					// Park on the stop instead of engaging the canvas,
+					// which is what focus arriving on it normally does.
+					noCaptureRef.current = true;
+					focusCaptureBeforeRef.current.focus();
+				}
+				return;
+			}
+
 			// In Edit mode, Tab should focus the first tabbable element after
 			// the content, which is normally the sidebar (with block controls)
 			// and Shift+Tab should focus the first tabbable element before the
 			// content, which is normally the block toolbar.
-			// Arrow keys can be used, and Tab and arrow keys can be used in
-			// Navigation mode (press Esc), to navigate through blocks.
+			// Arrow keys can be used to navigate through blocks.
 			if ( event.keyCode !== TAB ) {
 				return;
 			}
@@ -155,17 +276,15 @@ export default function useTabNav() {
 			) {
 				return;
 			}
+
 			const next = isShift ? focusCaptureBeforeRef : focusCaptureAfterRef;
 
-			// Disable focus capturing on the focus capture element, so it
-			// doesn't refocus this block and so it allows default behaviour
-			// (moving focus to the next tabbable element).
+			// Disable the focus forwarding on the focus capture element, so
+			// it allows default behaviour (moving focus to the next tabbable
+			// element).
 			noCaptureRef.current = true;
 
-			// Focusing the focus capture element, which is located above and
-			// below the editor, should not scroll the page all the way up or
-			// down.
-			next.current.focus( { preventScroll: true } );
+			next.current.focus();
 		}
 
 		function onFocusOut( event ) {
@@ -191,48 +310,14 @@ export default function useTabNav() {
 			}
 		}
 
-		// When tabbing back to an element in block list, this event handler prevents scrolling if the
-		// focus capture divs (before/after) are outside of the viewport. (For example shift+tab back to a paragraph
-		// when focus is on a sidebar element. This prevents the scrollable writing area from jumping either to the
-		// top or bottom of the document.
-		//
-		// Note that it isn't possible to disable scrolling in the onFocus event. We need to intercept this
-		// earlier in the keypress handler, and call focus( { preventScroll: true } ) instead.
-		// https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/focus#parameters
-		function preventScrollOnTab( event ) {
-			if ( event.keyCode !== TAB ) {
-				return;
-			}
-
-			if ( event.target?.getAttribute( 'role' ) === 'region' ) {
-				return;
-			}
-
-			if ( containerRef.current === event.target ) {
-				return;
-			}
-
-			const isShift = event.shiftKey;
-			const direction = isShift ? 'findPrevious' : 'findNext';
-			const target = focus.tabbable[ direction ]( event.target );
-			// Only do something when the next tabbable is a focus capture div (before/after)
-			if (
-				target === focusCaptureBeforeRef.current ||
-				target === focusCaptureAfterRef.current
-			) {
-				event.preventDefault();
-				target.focus( { preventScroll: true } );
-			}
-		}
+		// During an IME composition, Escape and Tab control the input
+		// method, not the editor.
+		const onKeyDownOutsideIME = withIgnoreIMEEvents( onKeyDown );
 
-		const { ownerDocument } = node;
-		const { defaultView } = ownerDocument;
-		defaultView.addEventListener( 'keydown', preventScrollOnTab );
-		node.addEventListener( 'keydown', onKeyDown );
+		node.addEventListener( 'keydown', onKeyDownOutsideIME );
 		node.addEventListener( 'focusout', onFocusOut );
 		return () => {
-			defaultView.removeEventListener( 'keydown', preventScrollOnTab );
-			node.removeEventListener( 'keydown', onKeyDown );
+			node.removeEventListener( 'keydown', onKeyDownOutsideIME );
 			node.removeEventListener( 'focusout', onFocusOut );
 		};
 	}, [] );

package/src/components/writing-flow/use-undo-automatic-change.js

@@ -0,0 +1,40 @@
+import { BACKSPACE, ESCAPE } from '@wordpress/keycodes';
+import { useSelect } from '@wordpress/data';
+import { useRefEffect } from '@wordpress/compose';
+import { store as blockEditorStore } from '../../store';
+
+export default function useUndoAutomaticChange() {
+	const { didAutomaticChange, getSettings } = useSelect( blockEditorStore );
+
+	function onKeyDown( event ) {
+		const { keyCode } = event;
+
+		if ( event.defaultPrevented ) {
+			return;
+		}
+
+		if ( keyCode !== BACKSPACE && keyCode !== ESCAPE ) {
+			return;
+		}
+
+		const { __experimentalUndo } = getSettings();
+
+		if ( ! __experimentalUndo ) {
+			return;
+		}
+
+		if ( ! didAutomaticChange() ) {
+			return;
+		}
+
+		event.preventDefault();
+		__experimentalUndo();
+	}
+
+	return useRefEffect( ( element ) => {
+		element.addEventListener( 'keydown', onKeyDown );
+		return () => {
+			element.removeEventListener( 'keydown', onKeyDown );
+		};
+	}, [] );
+}

package/src/elements/test/{index.js → index.jsdom.test.js}

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { __experimentalGetElementClassName } from '@wordpress/block-editor';
 
 describe( 'element class names', () => {

package/src/hooks/block-hooks.scss

@@ -17,15 +17,6 @@
 	}
 }
 
-.block-editor-hooks__position-control-item {
-
-	/**
-	 * Try to make items match the width of the anchor, subtract any margin on
-	 * items to calculate the correct inner width.
-	 */
-	max-inline-size: max(calc(var(--anchor-width) - (2 * var(--wp-ui-popup-padding))), 223px);
-}
-
 .block-editor-hooks__position-control-item-hint {
 	color: var(--wpds-color-foreground-content-neutral-weak);
 	margin-block-start: $grid-unit-05;

package/src/hooks/{border.js → border.jsx}

@@ -4,14 +4,12 @@ import { __experimentalHasSplitBorders as hasSplitBorders } from '@wordpress/com
 import { useCallback, useMemo } from '@wordpress/element';
 import { addFilter } from '@wordpress/hooks';
 import { useSelect } from '@wordpress/data';
-import { __ } from '@wordpress/i18n';
 import { getColorClassName } from '../components/colors';
 import InspectorControls from '../components/inspector-controls';
 import useMultipleOriginColorsAndGradients from '../components/colors-gradients/use-multiple-origin-colors-and-gradients';
 import { cleanEmptyObject, shouldSkipSerialization } from './utils';
 import {
 	useHasBorderPanel,
-	useHasBorderPanelControls,
 	BorderPanel as StylesBorderPanel,
 } from '../components/global-styles';
 import { useResolvedStyle } from '../components/global-styles/inherited-value-context';
@@ -22,13 +20,10 @@ import {
 	setStyleForState,
 	useBlockStyleState,
 } from './block-style-state';
-import { unlock } from '../lock-unlock';
 
 export const BORDER_SUPPORT_KEY = '__experimentalBorder';
 export const SHADOW_SUPPORT_KEY = 'shadow';
 
-const EMPTY_ARRAY = [];
-
 const getColorByProperty = ( colors, property, value ) => {
 	let matchedColor;
 
@@ -249,54 +244,6 @@ export function hasShadowSupport( blockName ) {
 	return hasBlockSupport( blockName, SHADOW_SUPPORT_KEY );
 }
 
-export function useBorderPanelLabel( {
-	clientId,
-	hasBorderControl,
-	hasShadowControl,
-} = {} ) {
-	const [ color, radius, style, width, shadow ] = useSelect(
-		( select ) => {
-			if ( ! clientId ) {
-				return EMPTY_ARRAY;
-			}
-			const { getBlockSettings } = unlock( select( blockEditorStore ) );
-			return getBlockSettings(
-				clientId,
-				'border.color',
-				'border.radius',
-				'border.style',
-				'border.width',
-				'shadow'
-			);
-		},
-		[ clientId ]
-	);
-	const settings = useMemo(
-		() => ( { border: { color, radius, style, width }, shadow } ),
-		[ color, radius, style, width, shadow ]
-	);
-	const controls = useHasBorderPanelControls( settings );
-
-	if ( ! hasBorderControl && ! hasShadowControl && clientId ) {
-		hasBorderControl =
-			controls?.hasBorderColor ||
-			controls?.hasBorderStyle ||
-			controls?.hasBorderWidth ||
-			controls?.hasBorderRadius;
-		hasShadowControl = controls?.hasShadow;
-	}
-
-	if ( hasBorderControl && hasShadowControl ) {
-		return __( 'Border & Shadow' );
-	}
-
-	if ( hasShadowControl ) {
-		return __( 'Shadow' );
-	}
-
-	return __( 'Border' );
-}
-
 /**
  * Returns a new style object where the specified border attribute has been
  * removed.

package/src/hooks/generate-fields-from-attributes.js

@@ -10,7 +10,7 @@
  * See https://github.com/WordPress/wordpress-develop/blob/8f6d31266deecd7eea258bd3d45597355cce13d0/src/wp-includes/block-supports/auto-register.php#L30
  *
  * @param {Object} attributes - Block type attributes from block registration
- * @return {{ fields: Array, form: Object }} fieldsKey and formKey values
+ * @return {{ fields: Array, form: Object }} DataForm fields and form definitions
  */
 export function generateFieldsFromAttributes( attributes ) {
 	const fields = [];

package/src/hooks/{grid-visualizer.js → grid-visualizer.jsx}

@@ -29,7 +29,7 @@ function GridTools( { clientId, layout } ) {
 
 				// These calls are purposely ordered from least expensive to most expensive.
 				// Hides the visualizer in cases where the user is not or cannot interact with it.
-				// Also hide if a child block is selected, because layout-child.js will render
+				// Also hide if a child block is selected, because layout-child.jsx will render
 				// the visualizer in that case (with proper childGridClientId handling).
 				if (
 					( ! isDraggingBlocks() && ! isBlockSelected( clientId ) ) ||

package/src/hooks/index.js

@@ -11,7 +11,6 @@ import './lock';
 import allowedBlocks from './allowed-blocks';
 import anchor from './anchor';
 import ariaLabel from './aria-label';
-import blockFields from './block-fields';
 import customClassName from './custom-class-name';
 import './generated-class-name';
 import style from './style';
@@ -53,7 +52,6 @@ createBlockEditFilter(
 		blockBindingsPanel,
 		childLayout,
 		allowedBlocks,
-		blockFields,
 		listView,
 		AutoRegisterControls,
 	].filter( Boolean )

package/src/hooks/{position.js → position.jsx}

@@ -261,6 +261,7 @@ export function PositionPanelPure( {
 				label={ __( 'Position' ) }
 				hideLabelFromVision
 				description={ stickyHelpText }
+				popupWidth="anchor"
 				items={ options }
 				value={ selectedOption }
 				onValueChange={ ( selectedItem ) => {
@@ -277,7 +278,6 @@ export function PositionPanelPure( {
 							key={ option.key }
 							value={ option }
 							label={ option.label }
-							className="block-editor-hooks__position-control-item"
 							aria-describedby={ hintId }
 						>
 							<div>{ option.label }</div>

package/src/hooks/{style.js → style.jsx}

@@ -36,6 +36,7 @@ import {
 	cleanEmptyObject,
 	shouldSkipSerialization,
 	useStyleOverride,
+	usePrivateStyleOverride,
 	useBlockSettings,
 } from './utils';
 import {
@@ -993,7 +994,7 @@ function getElementCSSRules( blockElementStyles, blockName, baseSelector ) {
 	return rules.length > 0 ? rules.join( '' ) : undefined;
 }
 
-function useBlockProps( { name, style } ) {
+function useBlockProps( { clientId, name, style } ) {
 	const blockElementsContainerIdentifier = useInstanceId(
 		STYLE_BLOCK_PROPS_REFERENCE,
 		'wp-elements'
@@ -1037,7 +1038,7 @@ function useBlockProps( { name, style } ) {
 		viewportSettings,
 	] );
 
-	useStyleOverride( { css: styles } );
+	usePrivateStyleOverride( { css: styles, clientId } );
 
 	return addSaveProps(
 		{ className: blockElementsContainerIdentifier },

package/src/hooks/test/{align.js → align.jsdom.test.jsx}

@@ -1,3 +1,4 @@
+import { afterEach, describe, expect, it } from 'vitest';
 import { applyFilters } from '@wordpress/hooks';
 import {
 	getBlockTypes,

package/src/hooks/test/allowed-blocks.js

@@ -1,3 +1,4 @@
+import { afterEach, describe, expect, it } from 'vitest';
 import {
 	getBlockTypes,
 	registerBlockType,

package/src/hooks/test/{anchor.js → anchor.jsdom.test.js}

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { applyFilters } from '@wordpress/hooks';
 import anchor from '../anchor';
 

package/src/hooks/test/{auto-inspector-controls.js → auto-inspector-controls.jsdom.test.js}

@@ -1,3 +1,4 @@
+import { afterEach, describe, expect, it } from 'vitest';
 import {
 	registerBlockType,
 	unregisterBlockType,

package/src/hooks/test/{background.js → background.jsdom.test.jsx}

@@ -1,3 +1,4 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { registerBlockType, unregisterBlockType } from '@wordpress/blocks';
@@ -9,6 +10,8 @@ import {
 } from '../background';
 import { BackgroundToolsPanel } from '../../components/global-styles/background-panel';
 
+globalThis.wpVitest.mockMatchMedia();
+
 describe( 'background', () => {
 	describe( 'backgroundResetAllFilter', () => {
 		it( 'clears every background-owned value, including a custom legacy color.gradient', () => {
@@ -164,7 +167,7 @@ describe( 'background', () => {
 				background: { gradient: true },
 			};
 			const user = userEvent.setup();
-			const setAttributes = jest.fn();
+			const setAttributes = vi.fn();
 
 			render(
 				<BackgroundImagePanel
@@ -201,7 +204,7 @@ describe( 'background', () => {
 				background: { gradient: false },
 			};
 			const user = userEvent.setup();
-			const setAttributes = jest.fn();
+			const setAttributes = vi.fn();
 
 			render(
 				<BackgroundImagePanel

package/src/hooks/test/{block-style-state.js → block-style-state.jsdom.test.js}

@@ -1,3 +1,4 @@
+import { describe, expect, it, vi } from 'vitest';
 import {
 	getStyleForState,
 	scopeResetAllFilterToState,
@@ -153,7 +154,7 @@ describe( 'setStyleForState', () => {
 
 describe( 'scopeResetAllFilterToState', () => {
 	it( 'passes only the selected state style to the reset filter', () => {
-		const innerReset = jest.fn( ( attributes ) => ( {
+		const innerReset = vi.fn( ( attributes ) => ( {
 			...attributes,
 			style: {
 				...attributes.style,
@@ -213,7 +214,7 @@ describe( 'scopeResetAllFilterToState', () => {
 	} );
 
 	it( 'calls the reset filter with an empty style when no state styles exist', () => {
-		const innerReset = jest.fn( ( attributes ) => attributes );
+		const innerReset = vi.fn( ( attributes ) => attributes );
 		const attributes = {
 			style: { color: { text: '#000000' } },
 		};
@@ -227,7 +228,7 @@ describe( 'scopeResetAllFilterToState', () => {
 	} );
 
 	it( 'passes only the selected viewport pseudo state style to the reset filter', () => {
-		const innerReset = jest.fn( () => ( { style: undefined } ) );
+		const innerReset = vi.fn( () => ( { style: undefined } ) );
 		const attributes = {
 			style: {
 				color: { text: '#000000' },