@wordpress/components 25.10.0 → 25.11.0

package/src/autocomplete/index.tsx

@@ -22,6 +22,8 @@ import {
 	isCollapsed,
 	getTextContent,
 } from '@wordpress/rich-text';
+import { speak } from '@wordpress/a11y';
+import { isAppleOS } from '@wordpress/keycodes';
 
 /**
  * Internal dependencies
@@ -39,6 +41,35 @@ import type {
 	WPCompleter,
 } from './types';
 
+const getNodeText = ( node: React.ReactNode ): string => {
+	if ( node === null ) {
+		return '';
+	}
+
+	switch ( typeof node ) {
+		case 'string':
+		case 'number':
+			return node.toString();
+			break;
+		case 'boolean':
+			return '';
+			break;
+		case 'object': {
+			if ( node instanceof Array ) {
+				return node.map( getNodeText ).join( '' );
+			}
+			if ( 'props' in node ) {
+				return getNodeText( node.props.children );
+			}
+			break;
+		}
+		default:
+			return '';
+	}
+
+	return '';
+};
+
 const EMPTY_FILTERED_OPTIONS: KeyedOption[] = [];
 
 export function useAutocomplete( {
@@ -163,20 +194,35 @@ export function useAutocomplete( {
 		) {
 			return;
 		}
+
 		switch ( event.key ) {
-			case 'ArrowUp':
-				setSelectedIndex(
+			case 'ArrowUp': {
+				const newIndex =
 					( selectedIndex === 0
 						? filteredOptions.length
-						: selectedIndex ) - 1
-				);
+						: selectedIndex ) - 1;
+				setSelectedIndex( newIndex );
+				// See the related PR as to why this is necessary: https://github.com/WordPress/gutenberg/pull/54902.
+				if ( isAppleOS() ) {
+					speak(
+						getNodeText( filteredOptions[ newIndex ].label ),
+						'assertive'
+					);
+				}
 				break;
+			}
 
-			case 'ArrowDown':
-				setSelectedIndex(
-					( selectedIndex + 1 ) % filteredOptions.length
-				);
+			case 'ArrowDown': {
+				const newIndex = ( selectedIndex + 1 ) % filteredOptions.length;
+				setSelectedIndex( newIndex );
+				if ( isAppleOS() ) {
+					speak(
+						getNodeText( filteredOptions[ newIndex ].label ),
+						'assertive'
+					);
+				}
 				break;
+			}
 
 			case 'Escape':
 				setAutocompleter( null );
@@ -218,82 +264,95 @@ export function useAutocomplete( {
 			return;
 		}
 
-		const completer = completers?.find(
-			( { triggerPrefix, allowContext } ) => {
-				const index = textContent.lastIndexOf( triggerPrefix );
-
-				if ( index === -1 ) {
-					return false;
-				}
-
-				const textWithoutTrigger = textContent.slice(
-					index + triggerPrefix.length
+		// Find the completer with the highest triggerPrefix index in the
+		// textContent.
+		const completer = completers.reduce< WPCompleter | null >(
+			( lastTrigger, currentCompleter ) => {
+				const triggerIndex = textContent.lastIndexOf(
+					currentCompleter.triggerPrefix
 				);
+				const lastTriggerIndex =
+					lastTrigger !== null
+						? textContent.lastIndexOf( lastTrigger.triggerPrefix )
+						: -1;
+
+				return triggerIndex > lastTriggerIndex
+					? currentCompleter
+					: lastTrigger;
+			},
+			null
+		);
 
-				const tooDistantFromTrigger = textWithoutTrigger.length > 50; // 50 chars seems to be a good limit.
-				// This is a final barrier to prevent the effect from completing with
-				// an extremely long string, which causes the editor to slow-down
-				// significantly. This could happen, for example, if `matchingWhileBackspacing`
-				// is true and one of the "words" end up being too long. If that's the case,
-				// it will be caught by this guard.
-				if ( tooDistantFromTrigger ) return false;
-
-				const mismatch = filteredOptions.length === 0;
-				const wordsFromTrigger = textWithoutTrigger.split( /\s/ );
-				// We need to allow the effect to run when not backspacing and if there
-				// was a mismatch. i.e when typing a trigger + the match string or when
-				// clicking in an existing trigger word on the page. We do that if we
-				// detect that we have one word from trigger in the current textual context.
-				//
-				// Ex.: "Some text @a" <-- "@a" will be detected as the trigger word and
-				// allow the effect to run. It will run until there's a mismatch.
-				const hasOneTriggerWord = wordsFromTrigger.length === 1;
-				// This is used to allow the effect to run when backspacing and if
-				// "touching" a word that "belongs" to a trigger. We consider a "trigger
-				// word" any word up to the limit of 3 from the trigger character.
-				// Anything beyond that is ignored if there's a mismatch. This allows
-				// us to "escape" a mismatch when backspacing, but still imposing some
-				// sane limits.
-				//
-				// Ex: "Some text @marcelo sekkkk" <--- "kkkk" caused a mismatch, but
-				// if the user presses backspace here, it will show the completion popup again.
-				const matchingWhileBackspacing =
-					backspacing.current &&
-					textWithoutTrigger.split( /\s/ ).length <= 3;
-
-				if (
-					mismatch &&
-					! ( matchingWhileBackspacing || hasOneTriggerWord )
-				) {
-					return false;
-				}
-
-				const textAfterSelection = getTextContent(
-					slice( record, undefined, getTextContent( record ).length )
-				);
+		if ( ! completer ) {
+			if ( autocompleter ) reset();
+			return;
+		}
 
-				if (
-					allowContext &&
-					! allowContext(
-						textContent.slice( 0, index ),
-						textAfterSelection
-					)
-				) {
-					return false;
-				}
+		const { allowContext, triggerPrefix } = completer;
+		const triggerIndex = textContent.lastIndexOf( triggerPrefix );
+		const textWithoutTrigger = textContent.slice(
+			triggerIndex + triggerPrefix.length
+		);
 
-				if (
-					/^\s/.test( textWithoutTrigger ) ||
-					/\s\s+$/.test( textWithoutTrigger )
-				) {
-					return false;
-				}
+		const tooDistantFromTrigger = textWithoutTrigger.length > 50; // 50 chars seems to be a good limit.
+		// This is a final barrier to prevent the effect from completing with
+		// an extremely long string, which causes the editor to slow-down
+		// significantly. This could happen, for example, if `matchingWhileBackspacing`
+		// is true and one of the "words" end up being too long. If that's the case,
+		// it will be caught by this guard.
+		if ( tooDistantFromTrigger ) return;
+
+		const mismatch = filteredOptions.length === 0;
+		const wordsFromTrigger = textWithoutTrigger.split( /\s/ );
+		// We need to allow the effect to run when not backspacing and if there
+		// was a mismatch. i.e when typing a trigger + the match string or when
+		// clicking in an existing trigger word on the page. We do that if we
+		// detect that we have one word from trigger in the current textual context.
+		//
+		// Ex.: "Some text @a" <-- "@a" will be detected as the trigger word and
+		// allow the effect to run. It will run until there's a mismatch.
+		const hasOneTriggerWord = wordsFromTrigger.length === 1;
+		// This is used to allow the effect to run when backspacing and if
+		// "touching" a word that "belongs" to a trigger. We consider a "trigger
+		// word" any word up to the limit of 3 from the trigger character.
+		// Anything beyond that is ignored if there's a mismatch. This allows
+		// us to "escape" a mismatch when backspacing, but still imposing some
+		// sane limits.
+		//
+		// Ex: "Some text @marcelo sekkkk" <--- "kkkk" caused a mismatch, but
+		// if the user presses backspace here, it will show the completion popup again.
+		const matchingWhileBackspacing =
+			backspacing.current && wordsFromTrigger.length <= 3;
+
+		if ( mismatch && ! ( matchingWhileBackspacing || hasOneTriggerWord ) ) {
+			if ( autocompleter ) reset();
+			return;
+		}
 
-				return /[\u0000-\uFFFF]*$/.test( textWithoutTrigger );
-			}
+		const textAfterSelection = getTextContent(
+			slice( record, undefined, getTextContent( record ).length )
 		);
 
-		if ( ! completer ) {
+		if (
+			allowContext &&
+			! allowContext(
+				textContent.slice( 0, triggerIndex ),
+				textAfterSelection
+			)
+		) {
+			if ( autocompleter ) reset();
+			return;
+		}
+
+		if (
+			/^\s/.test( textWithoutTrigger ) ||
+			/\s\s+$/.test( textWithoutTrigger )
+		) {
+			if ( autocompleter ) reset();
+			return;
+		}
+
+		if ( ! /[\u0000-\uFFFF]*$/.test( textWithoutTrigger ) ) {
 			if ( autocompleter ) reset();
 			return;
 		}

package/src/dimension-control/test/__snapshots__/index.test.js.snap

@@ -119,8 +119,8 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
-  height: 30px;
-  min-height: 30px;
+  height: 32px;
+  min-height: 32px;
   padding-top: 0;
   padding-bottom: 0;
   padding-left: 8px;
@@ -390,8 +390,8 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
-  height: 30px;
-  min-height: 30px;
+  height: 32px;
+  min-height: 32px;
   padding-top: 0;
   padding-bottom: 0;
   padding-left: 8px;
@@ -671,8 +671,8 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
-  height: 30px;
-  min-height: 30px;
+  height: 32px;
+  min-height: 32px;
   padding-top: 0;
   padding-bottom: 0;
   padding-left: 8px;
@@ -964,8 +964,8 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
-  height: 30px;
-  min-height: 30px;
+  height: 32px;
+  min-height: 32px;
   padding-top: 0;
   padding-bottom: 0;
   padding-left: 8px;

package/src/dropdown-menu-v2-ariakit/README.md

@@ -0,0 +1,324 @@
+# `DropdownMenu` (v2)
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`DropdownMenu` displays a menu to the user (such as a set of actions or functions) triggered by a button.
+
+
+## Design guidelines
+
+### Usage
+
+#### When to use a DropdownMenu
+
+Use a DropdownMenu when you want users to:
+
+-   Choose an action or change a setting from a list, AND
+-   Only see the available choices contextually.
+
+`DropdownMenu` is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button.
+
+If you need to display all the available options at all times, consider using a Toolbar instead. Use a `DropdownMenu` to display a list of actions after the user interacts with a button.
+
+**Do**
+Use a `DropdownMenu` to display a list of actions after the user interacts with an icon.
+
+**Don’t** use a `DropdownMenu` for important actions that should always be visible. Use a `Toolbar` instead.
+
+**Don’t**
+Don’t use a `DropdownMenu` for frequently used actions. Use a `Toolbar` instead.
+
+#### Behavior
+
+Generally, the parent button should indicate that interacting with it will show a `DropdownMenu`.
+
+The parent button should retain the same visual styling regardless of whether the `DropdownMenu` is displayed or not.
+
+#### Placement
+
+The `DropdownMenu` should typically appear directly below, or below and to the left of, the parent button. If there isn’t enough space below to display the full `DropdownMenu`, it can be displayed instead above the parent button.
+
+## Development guidelines
+
+This component is still highly experimental, and it's not normally accessible to consumers of the `@wordpress/components` package.
+
+The component exposes a set of components that are meant to be used in combination with each other in order to implement a `DropdownMenu` correctly.
+
+### `DropdownMenu`
+
+The root component, used to specify the menu's trigger and its contents.
+
+#### Props
+
+The component accepts the following props:
+
+##### `trigger`: `React.ReactNode`
+
+The trigger button
+
+- Required: yes
+
+##### `children`: `React.ReactNode`
+
+The contents of the dropdown
+
+- Required: yes
+
+##### `defaultOpen`: `boolean`
+
+The open state of the dropdown menu when it is initially rendered. Use when not wanting to control its open state.
+
+- Required: no
+- Default: `false`
+
+##### `open`: `boolean`
+
+The controlled open state of the dropdown menu. Must be used in conjunction with `onOpenChange`.
+
+- Required: no
+
+##### `onOpenChange`: `(open: boolean) => void`
+
+Event handler called when the open state of the dropdown menu changes.
+
+- Required: no
+
+##### `modal`: `boolean`
+
+The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
+
+- Required: no
+- Default: `true`
+
+##### `placement`: ``'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
+
+The placement of the dropdown menu popover.
+
+- Required: no
+- Default: `'bottom-start'` for root-level menus, `'right-start'` for nested menus
+
+##### `gutter`: `number`
+
+The distance in pixels from the trigger.
+
+- Required: no
+- Default: `8` for root-level menus, `16` for nested menus
+
+##### `shift`: `number`
+
+The skidding of the popover along the anchor element. Can be set to negative values to make the popover shift to the opposite side.
+
+- Required: no
+- Default: `0` for root-level menus, `-8` for nested menus
+
+##### `hideOnEscape`: `boolean | ( ( event: KeyboardEvent | React.KeyboardEvent< Element > ) => boolean )`
+
+Determines whether the menu popover will be hidden when the user presses the Escape key.
+
+- Required: no
+- Default: `true`
+
+### `DropdownMenuItem`
+
+Used to render a menu item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item
+
+- Required: yes
+
+##### `prefix`: `React.ReactNode`
+
+The contents of the item's prefix.
+
+- Required: no
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Required: no
+
+##### `hideOnClick`: `boolean`
+
+Whether to hide the dropdown menu when the menu item is clicked.
+
+- Required: no
+- Default: `true`
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled.
+
+- Required: no
+- Default: `false`
+
+### `DropdownMenuCheckboxItem`
+
+Used to render a checkbox item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item
+
+- Required: yes
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Required: no
+
+##### `hideOnClick`: `boolean`
+
+Whether to hide the dropdown menu when the menu item is clicked.
+
+- Required: no
+- Default: `false`
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled.
+
+- Required: no
+- Default: `false`
+
+##### `name`: `string`
+
+The checkbox item's name.
+
+- Required: yes
+
+##### `value`: `string`
+
+The checkbox item's value, useful when using multiple checkbox items
+ associated to the same `name`.
+
+- Required: no
+
+##### `checked`: `boolean`
+
+The checkbox item's value, useful when using multiple checkbox items
+ associated to the same `name`.
+
+- Required: no
+
+##### `defaultChecked`: `boolean`
+
+The checked state of the checkbox menu item when it is initially rendered. Use when not wanting to control its checked state.
+
+- Required: no
+
+##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;`
+
+Event handler called when the checked state of the checkbox menu item changes.
+
+- Required: no
+
+### `DropdownMenuRadioItem`
+
+Used to render a radio item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item
+
+- Required: yes
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Required: no
+
+##### `hideOnClick`: `boolean`
+
+Whether to hide the dropdown menu when the menu item is clicked.
+
+- Required: no
+- Default: `false`
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled.
+
+- Required: no
+- Default: `false`
+
+##### `name`: `string`
+
+The radio item's name.
+
+- Required: yes
+
+##### `value`: `string | number`
+
+The radio item's value.
+
+- Required: yes
+
+##### `checked`: `boolean`
+
+The checkbox item's value, useful when using multiple checkbox items
+ associated to the same `name`.
+
+- Required: no
+
+##### `defaultChecked`: `boolean`
+
+The checked state of the radio menu item when it is initially rendered. Use when not wanting to control its checked state.
+
+- Required: no
+
+##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;`
+
+Event handler called when the checked radio menu item changes.
+
+- Required: no
+
+### `DropdownMenuGroup`
+
+Used to group menu items.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the group.
+
+- Required: yes
+
+### `DropdownMenuGroupLabel`
+
+Used to render a group label.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the group.
+
+- Required: yes
+
+### `DropdownMenuSeparatorProps`
+
+Used to render a visual separator.