@wordpress/components 23.4.0 → 23.6.0

package/build-types/visually-hidden/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,oBAAY,mBAAmB,GAAG;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,mBAAmB,GAAG;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}

package/build-types/z-stack/types.d.ts

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import type { ReactNode } from 'react';
-export declare type ZStackProps = {
+export type ZStackProps = {
     /**
      * Layers children elements on top of each other (first: highest z-index,
      * last: lowest z-index).

package/build-types/z-stack/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/z-stack/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,oBAAY,WAAW,GAAG;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/z-stack/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,WAAW,GAAG;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "23.4.0",
+	"version": "23.6.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -36,35 +36,37 @@
 		"@emotion/serialize": "^1.0.2",
 		"@emotion/styled": "^11.6.0",
 		"@emotion/utils": "^1.0.0",
-		"@floating-ui/react-dom": "^1.0.0",
-		"@use-gesture/react": "^10.2.6",
-		"@wordpress/a11y": "^3.27.0",
-		"@wordpress/compose": "^6.4.0",
-		"@wordpress/date": "^4.27.0",
-		"@wordpress/deprecated": "^3.27.0",
-		"@wordpress/dom": "^3.27.0",
-		"@wordpress/element": "^5.4.0",
-		"@wordpress/escape-html": "^2.27.0",
-		"@wordpress/hooks": "^3.27.0",
-		"@wordpress/html-entities": "^3.27.0",
-		"@wordpress/i18n": "^4.27.0",
-		"@wordpress/icons": "^9.18.0",
-		"@wordpress/is-shallow-equal": "^4.27.0",
-		"@wordpress/keycodes": "^3.27.0",
-		"@wordpress/primitives": "^3.25.0",
-		"@wordpress/private-apis": "^0.9.0",
-		"@wordpress/rich-text": "^6.4.0",
-		"@wordpress/warning": "^2.27.0",
+		"@floating-ui/react-dom": "1.0.0",
+		"@use-gesture/react": "^10.2.24",
+		"@wordpress/a11y": "^3.29.0",
+		"@wordpress/compose": "^6.6.0",
+		"@wordpress/date": "^4.29.0",
+		"@wordpress/deprecated": "^3.29.0",
+		"@wordpress/dom": "^3.29.0",
+		"@wordpress/element": "^5.6.0",
+		"@wordpress/escape-html": "^2.29.0",
+		"@wordpress/hooks": "^3.29.0",
+		"@wordpress/html-entities": "^3.29.0",
+		"@wordpress/i18n": "^4.29.0",
+		"@wordpress/icons": "^9.20.0",
+		"@wordpress/is-shallow-equal": "^4.29.0",
+		"@wordpress/keycodes": "^3.29.0",
+		"@wordpress/primitives": "^3.27.0",
+		"@wordpress/private-apis": "^0.11.0",
+		"@wordpress/rich-text": "^6.6.0",
+		"@wordpress/warning": "^2.29.0",
 		"change-case": "^4.1.2",
 		"classnames": "^2.3.1",
 		"colord": "^2.7.0",
 		"date-fns": "^2.28.0",
+		"deepmerge": "^4.3.0",
 		"dom-scroll-into-view": "^1.2.1",
 		"downshift": "^6.0.15",
 		"fast-deep-equal": "^3.1.3",
 		"framer-motion": "^7.6.1",
 		"gradient-parser": "^0.1.5",
 		"highlight-words-core": "^1.2.2",
+		"is-plain-object": "^5.0.0",
 		"lodash": "^4.17.21",
 		"memize": "^1.1.0",
 		"path-to-regexp": "^6.2.1",
@@ -74,7 +76,7 @@
 		"remove-accents": "^0.4.2",
 		"use-lilius": "^2.0.1",
 		"uuid": "^8.3.0",
-		"valtio": "^1.7.0"
+		"valtio": "1.7.0"
 	},
 	"peerDependencies": {
 		"react": "^18.0.0",
@@ -83,5 +85,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "c25ff895413bad4354c55c0c2d732552618b0d56"
+	"gitHead": "9534a7b3bbf07c1d40b94fdb7a3d091f297bfb06"
 }

package/src/animate/index.js

@@ -25,7 +25,7 @@ function getDefaultOrigin( type ) {
 /**
  * @param {GetAnimateOptions} options
  *
- * @return {string | void} ClassName that applies the animations
+ * @return {string | undefined} ClassName that applies the animations
  */
 export function getAnimateClassName( options ) {
 	if ( options.type === 'loading' ) {
@@ -48,6 +48,8 @@ export function getAnimateClassName( options ) {
 			'is-from-' + origin
 		);
 	}
+
+	return undefined;
 }
 
 // @ts-ignore Reason: Planned for deprecation

package/src/autocomplete/README.md

@@ -2,6 +2,57 @@
 
 This component is used to provide autocompletion support for a child input component.
 
+## Props
+
+The following props are used to control the behavior of the component.
+
+### record
+
+The rich text value object the autocomleter is being applied to.
+
+-   Required: Yes
+-   Type: `RichTextValue`
+
+### onChange
+
+A function to be called when an option is selected to insert into the existing text.
+
+-   Required: Yes
+-   Type: `( value: string ) => void`
+
+A function to be called when an option is selected to replace the existing text.
+
+-   Required: Yes
+-   Type: `( arg: [ OptionCompletion[ 'value' ] ] ) => void;`
+
+### completers
+
+An array of all of the completers to apply to the current element.
+
+-   Required: Yes
+-   Type: `Array< WPCompleter >`
+ 
+### contentRef
+
+A ref containing the editable element that will serve as the anchor for `Autocomplete`'s `Popover`.
+
+-   Required: Yes
+-   `MutableRefObject< HTMLElement | undefined >`
+
+### children
+
+A function that returns nodes to be rendered within the Autocomplete.
+
+-   Required: Yes
+-   Type: `Function`
+
+### isSelected
+
+Whether or not the Autocomplte componenet is selected, and if its `Popover` should be displayed.
+
+- Required: Yes
+- Type: `Boolean`
+
 ## Autocompleters
 
 Autocompleters enable us to offer users options for completing text input. For example, Gutenberg includes a user autocompleter that provides a list of user names and completes a selection with a user mention like `@mary`.

package/src/autocomplete/autocompleter-ui.tsx

@@ -0,0 +1,167 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	useLayoutEffect,
+	useRef,
+	useEffect,
+	useState,
+} from '@wordpress/element';
+// Error expected because `@wordpress/rich-text` is not yet fully typed.
+// @ts-expect-error
+import { useAnchor } from '@wordpress/rich-text';
+import { useMergeRefs, useRefEffect } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import getDefaultUseItems from './get-default-use-items';
+import Button from '../button';
+import Popover from '../popover';
+import { VisuallyHidden } from '../visually-hidden';
+import { createPortal } from 'react-dom';
+import type { AutocompleterUIProps, WPCompleter } from './types';
+
+export function getAutoCompleterUI( autocompleter: WPCompleter ) {
+	const useItems = autocompleter.useItems
+		? autocompleter.useItems
+		: getDefaultUseItems( autocompleter );
+
+	function AutocompleterUI( {
+		filterValue,
+		instanceId,
+		listBoxId,
+		className,
+		selectedIndex,
+		onChangeOptions,
+		onSelect,
+		onReset,
+		reset,
+		contentRef,
+	}: AutocompleterUIProps ) {
+		const [ items ] = useItems( filterValue );
+		const popoverAnchor = useAnchor( {
+			editableContentElement: contentRef.current,
+		} );
+
+		const [ needsA11yCompat, setNeedsA11yCompat ] = useState( false );
+		const popoverRef = useRef< HTMLElement >( null );
+		const popoverRefs = useMergeRefs( [
+			popoverRef,
+			useRefEffect(
+				( node ) => {
+					if ( ! contentRef.current ) return;
+
+					// If the popover is rendered in a different document than
+					// the content, we need to duplicate the options list in the
+					// content document so that it's available to the screen
+					// readers, which check the DOM ID based aira-* attributes.
+					setNeedsA11yCompat(
+						node.ownerDocument !== contentRef.current.ownerDocument
+					);
+				},
+				[ contentRef ]
+			),
+		] );
+
+		useOnClickOutside( popoverRef, reset );
+
+		useLayoutEffect( () => {
+			onChangeOptions( items );
+			// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
+			// See https://github.com/WordPress/gutenberg/pull/41820
+			// eslint-disable-next-line react-hooks/exhaustive-deps
+		}, [ items ] );
+
+		if ( items.length === 0 ) {
+			return null;
+		}
+
+		const ListBox = ( {
+			Component = 'div',
+		}: {
+			Component?: React.ElementType;
+		} ) => (
+			<Component
+				id={ listBoxId }
+				role="listbox"
+				className="components-autocomplete__results"
+			>
+				{ items.map( ( option, index ) => (
+					<Button
+						key={ option.key }
+						id={ `components-autocomplete-item-${ instanceId }-${ option.key }` }
+						role="option"
+						aria-selected={ index === selectedIndex }
+						disabled={ option.isDisabled }
+						className={ classnames(
+							'components-autocomplete__result',
+							className,
+							{
+								'is-selected': index === selectedIndex,
+							}
+						) }
+						onClick={ () => onSelect( option ) }
+					>
+						{ option.label }
+					</Button>
+				) ) }
+			</Component>
+		);
+
+		return (
+			<>
+				<Popover
+					focusOnMount={ false }
+					onClose={ onReset }
+					placement="top-start"
+					className="components-autocomplete__popover"
+					anchor={ popoverAnchor }
+					ref={ popoverRefs }
+				>
+					<ListBox />
+				</Popover>
+				{ contentRef.current &&
+					needsA11yCompat &&
+					createPortal(
+						<ListBox Component={ VisuallyHidden } />,
+						contentRef.current.ownerDocument.body
+					) }
+			</>
+		);
+	}
+
+	return AutocompleterUI;
+}
+
+function useOnClickOutside(
+	ref: React.RefObject< HTMLElement >,
+	handler: AutocompleterUIProps[ 'reset' ]
+) {
+	useEffect( () => {
+		const listener = ( event: MouseEvent | TouchEvent ) => {
+			// Do nothing if clicking ref's element or descendent elements, or if the ref is not referencing an element
+			if (
+				! ref.current ||
+				ref.current.contains( event.target as Node )
+			) {
+				return;
+			}
+			handler( event );
+		};
+		document.addEventListener( 'mousedown', listener );
+		document.addEventListener( 'touchstart', listener );
+		return () => {
+			document.removeEventListener( 'mousedown', listener );
+			document.removeEventListener( 'touchstart', listener );
+		};
+		// Disable reason: `ref` is a ref object and should not be included in a
+		// hook's dependency list.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ handler ] );
+}

package/src/autocomplete/{get-default-use-items.js → get-default-use-items.tsx}

@@ -13,8 +13,13 @@ import { useLayoutEffect, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import { escapeRegExp } from '../utils/strings';
+import type { CancelablePromise, KeyedOption, WPCompleter } from './types';
 
-function filterOptions( search, options = [], maxResults = 10 ) {
+function filterOptions(
+	search: RegExp,
+	options: Array< KeyedOption > = [],
+	maxResults = 10
+) {
 	const filtered = [];
 	for ( let i = 0; i < options.length; i++ ) {
 		const option = options[ i ];
@@ -43,9 +48,9 @@ function filterOptions( search, options = [], maxResults = 10 ) {
 	return filtered;
 }
 
-export default function getDefaultUseItems( autocompleter ) {
-	return ( filterValue ) => {
-		const [ items, setItems ] = useState( [] );
+export default function getDefaultUseItems( autocompleter: WPCompleter ) {
+	return ( filterValue: string ) => {
+		const [ items, setItems ] = useState< Array< KeyedOption > >( [] );
 		/*
 		 * We support both synchronous and asynchronous retrieval of completer options
 		 * but internally treat all as async so we maintain a single, consistent code path.
@@ -61,7 +66,7 @@ export default function getDefaultUseItems( autocompleter ) {
 			const { options, isDebounced } = autocompleter;
 			const loadOptions = debounce(
 				() => {
-					const promise = Promise.resolve(
+					const promise: CancelablePromise = Promise.resolve(
 						typeof options === 'function'
 							? options( filterValue )
 							: options
@@ -112,6 +117,6 @@ export default function getDefaultUseItems( autocompleter ) {
 			};
 		}, [ filterValue ] );
 
-		return [ items ];
+		return [ items ] as const;
 	};
 }