@wordpress/components 23.3.5 → 23.5.0

package/src/angle-picker-control/README.md

@@ -1,6 +1,6 @@
 # AnglePickerControl
 
-AnglePickerControl is a React component to render a UI that allows users to pick an angle.
+`AnglePickerControl` is a React component to render a UI that allows users to pick an angle.
 Users can choose an angle in a visual UI with the mouse by dragging an angle indicator inside a circle or by directly inserting the desired angle in a text field.
 
 ## Usage
@@ -9,9 +9,15 @@ Users can choose an angle in a visual UI with the mouse by dragging an angle ind
 import { useState } from '@wordpress/element';
 import { AnglePickerControl } from '@wordpress/components';
 
-const MyAnglePicker = () => {
-	const [ angle, setAngle ] = useState();
-	return <AnglePickerControl value={ angle } onChange={ setAngle } __nextHasNoMarginBottom />;
+function Example() {
+	const [ angle, setAngle ] = useState( 0 );
+	return (
+		<AnglePickerControl
+			value={ angle }
+			onChange={ setAngle }
+			__nextHasNoMarginBottom
+		/>
+	);
 };
 ```
 
@@ -19,31 +25,28 @@ const MyAnglePicker = () => {
 
 The component accepts the following props.
 
-### label
+### `label`: `string`
 
-Label to use for the angle picker. If not set the a translated label "Angle" is used.
+Label to use for the angle picker.
 
--   Type: `String`
 -   Required: No
+-   Default: `__( 'Angle' )`
 
-### value
+### `value`: `number | string`
 
 The current value of the input. The value represents an angle in degrees and should be a value between 0 and 360.
 
--   Type: `Number`
 -   Required: Yes
 
-### onChange
+### `onChange`: `( value: number ) => void`
 
 A function that receives the new value of the input.
 
--   Type: `function`
 -   Required: Yes
 
-### __nextHasNoMarginBottom
+### `__nextHasNoMarginBottom`: `boolean`
 
 Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.4. (The prop can be safely removed once this happens.)
 
--   Type: `boolean`
 -   Required: No
--   Default: `false`
+-   Default: `false`

package/src/angle-picker-control/{angle-circle.js → angle-circle.tsx}

@@ -13,12 +13,29 @@ import {
 	CircleIndicator,
 } from './styles/angle-picker-control-styles';
 
-function AngleCircle( { value, onChange, ...props } ) {
-	const angleCircleRef = useRef();
-	const angleCircleCenter = useRef();
-	const previousCursorValue = useRef();
+import type { WordPressComponentProps } from '../ui/context';
+import type { AngleCircleProps } from './types';
+
+type UseDraggingArgumentType = Parameters< typeof useDragging >[ 0 ];
+type UseDraggingCallbackEvent =
+	| Parameters< UseDraggingArgumentType[ 'onDragStart' ] >[ 0 ]
+	| Parameters< UseDraggingArgumentType[ 'onDragMove' ] >[ 0 ]
+	| Parameters< UseDraggingArgumentType[ 'onDragEnd' ] >[ 0 ];
+
+function AngleCircle( {
+	value,
+	onChange,
+	...props
+}: WordPressComponentProps< AngleCircleProps, 'div' > ) {
+	const angleCircleRef = useRef< HTMLDivElement | null >( null );
+	const angleCircleCenter = useRef< { x: number; y: number } | undefined >();
+	const previousCursorValue = useRef< CSSStyleDeclaration[ 'cursor' ] >();
 
 	const setAngleCircleCenter = () => {
+		if ( angleCircleRef.current === null ) {
+			return;
+		}
+
 		const rect = angleCircleRef.current.getBoundingClientRect();
 		angleCircleCenter.current = {
 			x: rect.x + rect.width / 2,
@@ -26,14 +43,26 @@ function AngleCircle( { value, onChange, ...props } ) {
 		};
 	};
 
-	const changeAngleToPosition = ( event ) => {
-		const { x: centerX, y: centerY } = angleCircleCenter.current;
+	const changeAngleToPosition = ( event: UseDraggingCallbackEvent ) => {
+		if ( event === undefined ) {
+			return;
+		}
+
 		// Prevent (drag) mouse events from selecting and accidentally
 		// triggering actions from other elements.
 		event.preventDefault();
 		// Input control needs to lose focus and by preventDefault above, it doesn't.
-		event.target.focus();
-		onChange( getAngle( centerX, centerY, event.clientX, event.clientY ) );
+		( event.target as HTMLDivElement | null )?.focus();
+
+		if (
+			angleCircleCenter.current !== undefined &&
+			onChange !== undefined
+		) {
+			const { x: centerX, y: centerY } = angleCircleCenter.current;
+			onChange(
+				getAngle( centerX, centerY, event.clientX, event.clientY )
+			);
+		}
 	};
 
 	const { startDrag, isDragging } = useDragging( {
@@ -52,13 +81,12 @@ function AngleCircle( { value, onChange, ...props } ) {
 			}
 			document.body.style.cursor = 'grabbing';
 		} else {
-			document.body.style.cursor = previousCursorValue.current || null;
+			document.body.style.cursor = previousCursorValue.current || '';
 			previousCursorValue.current = undefined;
 		}
 	}, [ isDragging ] );
 
 	return (
-		/* eslint-disable jsx-a11y/no-static-element-interactions */
 		<CircleRoot
 			ref={ angleCircleRef }
 			onMouseDown={ startDrag }
@@ -76,11 +104,15 @@ function AngleCircle( { value, onChange, ...props } ) {
 				<CircleIndicator className="components-angle-picker-control__angle-circle-indicator" />
 			</CircleIndicatorWrapper>
 		</CircleRoot>
-		/* eslint-enable jsx-a11y/no-static-element-interactions */
 	);
 }
 
-function getAngle( centerX, centerY, pointX, pointY ) {
+function getAngle(
+	centerX: number,
+	centerY: number,
+	pointX: number,
+	pointY: number
+) {
 	const y = pointY - centerY;
 	const x = pointX - centerX;
 

package/src/angle-picker-control/{index.js → index.tsx}

@@ -1,12 +1,14 @@
 /**
  * External dependencies
  */
+import type { ForwardedRef } from 'react';
 import classnames from 'classnames';
 
 /**
  * WordPress dependencies
  */
 import deprecated from '@wordpress/deprecated';
+import { forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 
 /**
@@ -21,14 +23,22 @@ import { Text } from '../text';
 import { Spacer } from '../spacer';
 import { COLORS } from '../utils/colors-values';
 
-export default function AnglePickerControl( {
-	/** Start opting into the new margin-free styles that will become the default in a future version. */
-	__nextHasNoMarginBottom = false,
-	className,
-	label = __( 'Angle' ),
-	onChange,
-	value,
-} ) {
+import type { WordPressComponentProps } from '../ui/context';
+import type { AnglePickerControlProps } from './types';
+
+function UnforwardedAnglePickerControl(
+	props: WordPressComponentProps< AnglePickerControlProps, 'div' >,
+	ref: ForwardedRef< any >
+) {
+	const {
+		__nextHasNoMarginBottom = false,
+		className,
+		label = __( 'Angle' ),
+		onChange,
+		value,
+		...restProps
+	} = props;
+
 	if ( ! __nextHasNoMarginBottom ) {
 		deprecated(
 			'Bottom margin styles for wp.components.AnglePickerControl',
@@ -40,9 +50,15 @@ export default function AnglePickerControl( {
 		);
 	}
 
-	const handleOnNumberChange = ( unprocessedValue ) => {
+	const handleOnNumberChange = ( unprocessedValue: string | undefined ) => {
+		if ( onChange === undefined ) {
+			return;
+		}
+
 		const inputValue =
-			unprocessedValue !== '' ? parseInt( unprocessedValue, 10 ) : 0;
+			unprocessedValue !== undefined && unprocessedValue !== ''
+				? parseInt( unprocessedValue, 10 )
+				: 0;
 		onChange( inputValue );
 	};
 
@@ -50,6 +66,8 @@ export default function AnglePickerControl( {
 
 	return (
 		<Root
+			{ ...restProps }
+			ref={ ref }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			className={ classes }
 			gap={ 4 }
@@ -94,3 +112,29 @@ export default function AnglePickerControl( {
 		</Root>
 	);
 }
+
+/**
+ * `AnglePickerControl` is a React component to render a UI that allows users to
+ * pick an angle. Users can choose an angle in a visual UI with the mouse by
+ * dragging an angle indicator inside a circle or by directly inserting the
+ * desired angle in a text field.
+ *
+ * ```jsx
+ * import { useState } from '@wordpress/element';
+ * import { AnglePickerControl } from '@wordpress/components';
+ *
+ * function Example() {
+ *   const [ angle, setAngle ] = useState( 0 );
+ *   return (
+ *     <AnglePickerControl
+ *       value={ angle }
+ *       onChange={ setAngle }
+ *       __nextHasNoMarginBottom
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export const AnglePickerControl = forwardRef( UnforwardedAnglePickerControl );
+
+export default AnglePickerControl;

package/src/angle-picker-control/stories/index.tsx

@@ -0,0 +1,57 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { AnglePickerControl } from '..';
+
+const meta: ComponentMeta< typeof AnglePickerControl > = {
+	title: 'Components/AnglePickerControl',
+	component: AnglePickerControl,
+	argTypes: {
+		as: { control: { type: null } },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+
+export default meta;
+
+const AnglePickerWithState: ComponentStory< typeof AnglePickerControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ angle, setAngle ] = useState< number >( 0 );
+
+	const handleChange = ( newValue: number ) => {
+		setAngle( newValue );
+		onChange( newValue );
+	};
+
+	return (
+		<AnglePickerControl
+			{ ...args }
+			value={ angle }
+			onChange={ handleChange }
+		/>
+	);
+};
+
+export const Default = AnglePickerWithState.bind( {} );
+Default.args = {
+	__nextHasNoMarginBottom: true,
+};

package/src/angle-picker-control/styles/{angle-picker-control-styles.js → angle-picker-control-styles.tsx}

@@ -12,10 +12,14 @@ import { COLORS } from '../../utils';
 import { space } from '../../ui/utils/space';
 import CONFIG from '../../utils/config-values';
 
+import type { AnglePickerControlProps } from '../types';
+
 const CIRCLE_SIZE = 32;
 const INNER_CIRCLE_SIZE = 3;
 
-const deprecatedBottomMargin = ( { __nextHasNoMarginBottom } ) => {
+const deprecatedBottomMargin = ( {
+	__nextHasNoMarginBottom,
+}: Pick< AnglePickerControlProps, '__nextHasNoMarginBottom' > ) => {
 	return ! __nextHasNoMarginBottom
 		? css`
 				margin-bottom: ${ space( 2 ) };

package/src/angle-picker-control/types.ts

@@ -0,0 +1,29 @@
+export type AnglePickerControlProps = {
+	/**
+	 * Start opting into the new margin-free styles that will become the default
+	 * in a future version.
+	 *
+	 * @default false
+	 */
+	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * Label to use for the angle picker.
+	 *
+	 * @default __( 'Angle' )
+	 */
+	label?: string;
+	/**
+	 * A function that receives the new value of the input.
+	 */
+	onChange: ( value: number ) => void;
+	/**
+	 * The current value of the input. The value represents an angle in degrees
+	 * and should be a value between 0 and 360.
+	 */
+	value: number | string;
+};
+
+export type AngleCircleProps = Pick<
+	AnglePickerControlProps,
+	'value' | 'onChange'
+>;

package/src/autocomplete/autocompleter-ui.js

@@ -6,8 +6,14 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { useLayoutEffect, useRef, useEffect } from '@wordpress/element';
+import {
+	useLayoutEffect,
+	useRef,
+	useEffect,
+	useState,
+} from '@wordpress/element';
 import { useAnchor } from '@wordpress/rich-text';
+import { useMergeRefs, useRefEffect } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -15,6 +21,8 @@ import { useAnchor } from '@wordpress/rich-text';
 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';
 
 export function getAutoCompleterUI( autocompleter ) {
 	const useItems = autocompleter.useItems
@@ -40,7 +48,25 @@ export function getAutoCompleterUI( autocompleter ) {
 			value,
 		} );
 
+		const [ needsA11yCompat, setNeedsA11yCompat ] = useState( false );
 		const popoverRef = useRef();
+		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 );
 
@@ -55,41 +81,53 @@ export function getAutoCompleterUI( autocompleter ) {
 			return null;
 		}
 
-		return (
-			<Popover
-				focusOnMount={ false }
-				onClose={ onReset }
-				placement="top-start"
-				className="components-autocomplete__popover"
-				anchor={ popoverAnchor }
-				ref={ popoverRef }
+		const ListBox = ( { Component = 'div' } ) => (
+			<Component
+				id={ listBoxId }
+				role="listbox"
+				className="components-autocomplete__results"
 			>
-				<div
-					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 }
 				>
-					{ 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>
-					) ) }
-				</div>
-			</Popover>
+					<ListBox />
+				</Popover>
+				{ contentRef.current &&
+					needsA11yCompat &&
+					createPortal(
+						<ListBox Component={ VisuallyHidden } />,
+						contentRef.current.ownerDocument.body
+					) }
+			</>
 		);
 	}
 

package/src/autocomplete/autocompleter-ui.native.js

@@ -144,6 +144,7 @@ export function getAutoCompleterUI( autocompleter ) {
 					<Animated.View style={ contentStyles }>
 						<BackgroundView>
 							<ScrollView
+								testID="autocompleter"
 								ref={ scrollViewRef }
 								horizontal
 								contentContainerStyle={

package/src/autocomplete/index.js

@@ -35,6 +35,8 @@ import { speak } from '@wordpress/a11y';
 import { getAutoCompleterUI } from './autocompleter-ui';
 import { escapeRegExp } from '../utils/strings';
 
+const EMPTY_ARRAY = [];
+
 /**
  * A raw completer option.
  *
@@ -121,7 +123,7 @@ function useAutocomplete( {
 	const debouncedSpeak = useDebounce( speak, 500 );
 	const instanceId = useInstanceId( useAutocomplete );
 	const [ selectedIndex, setSelectedIndex ] = useState( 0 );
-	const [ filteredOptions, setFilteredOptions ] = useState( [] );
+	const [ filteredOptions, setFilteredOptions ] = useState( EMPTY_ARRAY );
 	const [ filterValue, setFilterValue ] = useState( '' );
 	const [ autocompleter, setAutocompleter ] = useState( null );
 	const [ AutocompleterUI, setAutocompleterUI ] = useState( null );
@@ -169,7 +171,7 @@ function useAutocomplete( {
 
 	function reset() {
 		setSelectedIndex( 0 );
-		setFilteredOptions( [] );
+		setFilteredOptions( EMPTY_ARRAY );
 		setFilterValue( '' );
 		setAutocompleter( null );
 		setAutocompleterUI( null );
@@ -281,23 +283,19 @@ function useAutocomplete( {
 
 	useEffect( () => {
 		if ( ! textContent ) {
-			reset();
+			if ( autocompleter ) reset();
 			return;
 		}
 
-		const text = removeAccents( textContent );
-		const textAfterSelection = getTextContent(
-			slice( record, undefined, getTextContent( record ).length )
-		);
 		const completer = completers?.find(
 			( { triggerPrefix, allowContext } ) => {
-				const index = text.lastIndexOf( triggerPrefix );
+				const index = textContent.lastIndexOf( triggerPrefix );
 
 				if ( index === -1 ) {
 					return false;
 				}
 
-				const textWithoutTrigger = text.slice(
+				const textWithoutTrigger = textContent.slice(
 					index + triggerPrefix.length
 				);
 
@@ -339,9 +337,16 @@ function useAutocomplete( {
 					return false;
 				}
 
+				const textAfterSelection = getTextContent(
+					slice( record, undefined, getTextContent( record ).length )
+				);
+
 				if (
 					allowContext &&
-					! allowContext( text.slice( 0, index ), textAfterSelection )
+					! allowContext(
+						textContent.slice( 0, index ),
+						textAfterSelection
+					)
 				) {
 					return false;
 				}
@@ -358,11 +363,12 @@ function useAutocomplete( {
 		);
 
 		if ( ! completer ) {
-			reset();
+			if ( autocompleter ) reset();
 			return;
 		}
 
 		const safeTrigger = escapeRegExp( completer.triggerPrefix );
+		const text = removeAccents( textContent );
 		const match = text
 			.slice( text.lastIndexOf( completer.triggerPrefix ) )
 			.match( new RegExp( `${ safeTrigger }([\u0000-\uFFFF]*)$` ) );
@@ -412,53 +418,47 @@ function useAutocomplete( {
 	};
 }
 
+function useLastDifferentValue( value ) {
+	const history = useRef( new Set() );
+
+	history.current.add( value );
+
+	// Keep the history size to 2.
+	if ( history.current.size > 2 ) {
+		history.current.delete( Array.from( history.current )[ 0 ] );
+	}
+
+	return Array.from( history.current )[ 0 ];
+}
+
 export function useAutocompleteProps( options ) {
-	const [ isVisible, setIsVisible ] = useState( false );
 	const ref = useRef();
-	const recordAfterInput = useRef();
 	const onKeyDownRef = useRef();
+	const { record } = options;
+	const previousRecord = useLastDifferentValue( record );
 	const { popover, listBoxId, activeId, onKeyDown } = useAutocomplete( {
 		...options,
 		contentRef: ref,
 	} );
 	onKeyDownRef.current = onKeyDown;
 
-	useEffect( () => {
-		if ( isVisible ) {
-			if ( ! recordAfterInput.current ) {
-				recordAfterInput.current = options.record;
-			} else if (
-				recordAfterInput.current.start !== options.record.start ||
-				recordAfterInput.current.end !== options.record.end
-			) {
-				setIsVisible( false );
-				recordAfterInput.current = null;
-			}
-		}
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ options.record ] );
-
 	const mergedRefs = useMergeRefs( [
 		ref,
 		useRefEffect( ( element ) => {
 			function _onKeyDown( event ) {
 				onKeyDownRef.current( event );
 			}
-			function _onInput() {
-				// Only show auto complete UI if the user is inputting text.
-				setIsVisible( true );
-				recordAfterInput.current = null;
-			}
 			element.addEventListener( 'keydown', _onKeyDown );
-			element.addEventListener( 'input', _onInput );
 			return () => {
 				element.removeEventListener( 'keydown', _onKeyDown );
-				element.removeEventListener( 'input', _onInput );
 			};
 		}, [] ),
 	] );
 
-	if ( ! isVisible ) {
+	// We only want to show the popover if the user has typed something.
+	const didUserInput = record.text !== previousRecord?.text;
+
+	if ( ! didUserInput ) {
 		return { ref: mergedRefs };
 	}
 

package/src/base-control/hooks.ts

@@ -14,7 +14,7 @@ import type { BaseControlProps } from './types';
  *
  * Namely, it takes care of generating a unique `id`, properly associating it with the `label` and `help` elements.
  *
- * @param  props
+ * @param props
  */
 export function useBaseControlProps(
 	props: Omit< BaseControlProps, 'children' >