@wordpress/components 22.1.0 → 23.0.0

package/src/alignment-matrix-control/styles/{alignment-matrix-control-icon-styles.js → alignment-matrix-control-icon-styles.ts}

@@ -12,6 +12,10 @@ import {
 	pointBase,
 	Cell as CellBase,
 } from './alignment-matrix-control-styles';
+import type {
+	AlignmentMatrixControlIconProps,
+	AlignmentMatrixControlCellProps,
+} from '../types';
 
 const rootSize = () => {
 	const padding = 1.5;
@@ -25,9 +29,11 @@ const rootSize = () => {
 	} );
 };
 
-const rootPointerEvents = ( { disablePointerEvents } ) => {
+const rootPointerEvents = ( {
+	disablePointerEvents,
+}: Pick< AlignmentMatrixControlIconProps, 'disablePointerEvents' > ) => {
 	return css( {
-		pointerEvents: disablePointerEvents ? 'none' : null,
+		pointerEvents: disablePointerEvents ? 'none' : undefined,
 	} );
 };
 
@@ -46,7 +52,9 @@ export const Root = styled.div`
 	${ rootPointerEvents };
 `;
 
-const pointActive = ( { isActive } ) => {
+const pointActive = ( {
+	isActive,
+}: Pick< AlignmentMatrixControlCellProps, 'isActive' > ) => {
 	const boxShadow = isActive ? `0 0 0 1px currentColor` : null;
 
 	return css`

package/src/alignment-matrix-control/styles/{alignment-matrix-control-styles.js → alignment-matrix-control-styles.ts}

@@ -8,6 +8,10 @@ import { css } from '@emotion/react';
  * Internal dependencies
  */
 import { COLORS, reduceMotion } from '../../utils';
+import type {
+	AlignmentMatrixControlProps,
+	AlignmentMatrixControlCellProps,
+} from '../types';
 
 export const rootBase = () => {
 	return css`
@@ -27,7 +31,9 @@ const rootSize = ( { size = 92 } ) => {
 	`;
 };
 
-export const Root = styled.div`
+export const Root = styled.div< {
+	size: AlignmentMatrixControlProps[ 'width' ];
+} >`
 	${ rootBase };
 
 	border: 1px solid transparent;
@@ -43,7 +49,9 @@ export const Row = styled.div`
 	grid-template-columns: repeat( 3, 1fr );
 `;
 
-const pointActive = ( { isActive } ) => {
+const pointActive = ( {
+	isActive,
+}: Pick< AlignmentMatrixControlCellProps, 'isActive' > ) => {
 	const boxShadow = isActive ? `0 0 0 2px ${ COLORS.gray[ 900 ] }` : null;
 	const pointColor = isActive ? COLORS.gray[ 900 ] : COLORS.gray[ 400 ];
 	const pointColorHover = isActive ? COLORS.gray[ 900 ] : COLORS.ui.theme;
@@ -58,7 +66,9 @@ const pointActive = ( { isActive } ) => {
 	`;
 };
 
-export const pointBase = ( props ) => {
+export const pointBase = (
+	props: Pick< AlignmentMatrixControlCellProps, 'isActive' >
+) => {
 	return css`
 		background: currentColor;
 		box-sizing: border-box;

package/src/alignment-matrix-control/test/{index.js → index.tsx}

@@ -1,18 +1,18 @@
 /**
  * External dependencies
  */
-import { render, screen, within } from '@testing-library/react';
+import { act, render, screen, within } from '@testing-library/react';
 
 /**
  * Internal dependencies
  */
-import AlignmentMatrixControl from '../';
+import AlignmentMatrixControl from '..';
 
 const getControl = () => {
 	return screen.getByRole( 'grid' );
 };
 
-const getCell = ( name ) => {
+const getCell = ( name: string ) => {
 	return within( getControl() ).getByRole( 'gridcell', { name } );
 };
 
@@ -30,14 +30,14 @@ describe( 'AlignmentMatrixControl', () => {
 
 		it.each( alignments )(
 			'should change value on %s cell click',
-			( alignment ) => {
+			async ( alignment ) => {
 				const spy = jest.fn();
 
 				render(
 					<AlignmentMatrixControl value="center" onChange={ spy } />
 				);
 
-				getCell( alignment ).focus();
+				await act( () => getCell( alignment ).focus() );
 
 				expect( spy ).toHaveBeenCalledWith( alignment );
 			}

package/src/alignment-matrix-control/types.ts

@@ -0,0 +1,54 @@
+export type AlignmentMatrixControlValue =
+	| 'top left'
+	| 'top center'
+	| 'top right'
+	| 'center left'
+	| 'center'
+	| 'center center'
+	| 'center right'
+	| 'bottom left'
+	| 'bottom center'
+	| 'bottom right';
+
+export type AlignmentMatrixControlProps = {
+	/**
+	 * Accessible label. If provided, sets the `aria-label` attribute of the
+	 * underlying `grid` widget.
+	 *
+	 * @default 'Alignment Matrix Control'
+	 */
+	label?: string;
+	/**
+	 * If provided, sets the default alignment value.
+	 *
+	 * @default 'center center'
+	 */
+	defaultValue?: AlignmentMatrixControlValue;
+	/**
+	 * The current alignment value.
+	 */
+	value?: AlignmentMatrixControlValue;
+	/**
+	 * A function that receives the updated alignment value.
+	 */
+	onChange?: ( newValue: AlignmentMatrixControlValue ) => void;
+	/**
+	 * If provided, sets the width of the control.
+	 *
+	 * @default 92
+	 */
+	width?: number;
+};
+
+export type AlignmentMatrixControlIconProps = Pick<
+	AlignmentMatrixControlProps,
+	'value'
+> & {
+	disablePointerEvents?: boolean;
+	size?: number;
+};
+
+export type AlignmentMatrixControlCellProps = {
+	isActive?: boolean;
+	value: NonNullable< AlignmentMatrixControlProps[ 'value' ] >;
+};

package/src/alignment-matrix-control/{utils.js → utils.tsx}

@@ -2,20 +2,25 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
+/**
+ * Internal dependencies
+ */
+import type { AlignmentMatrixControlValue } from './types';
 
-export const GRID = [
+export const GRID: AlignmentMatrixControlValue[][] = [
 	[ 'top left', 'top center', 'top right' ],
 	[ 'center left', 'center center', 'center right' ],
 	[ 'bottom left', 'bottom center', 'bottom right' ],
 ];
 
 // Stored as map as i18n __() only accepts strings (not variables)
-export const ALIGNMENT_LABEL = {
+export const ALIGNMENT_LABEL: Record< AlignmentMatrixControlValue, string > = {
 	'top left': __( 'Top Left' ),
 	'top center': __( 'Top Center' ),
 	'top right': __( 'Top Right' ),
 	'center left': __( 'Center Left' ),
 	'center center': __( 'Center Center' ),
+	center: __( 'Center Center' ),
 	'center right': __( 'Center Right' ),
 	'bottom left': __( 'Bottom Left' ),
 	'bottom center': __( 'Bottom Center' ),
@@ -28,25 +33,28 @@ export const ALIGNMENTS = GRID.flat();
 /**
  * Parses and transforms an incoming value to better match the alignment values
  *
- * @param {string} value An alignment value to parse.
+ * @param  value An alignment value to parse.
  *
- * @return {string} The parsed value.
+ * @return The parsed value.
  */
-export function transformValue( value ) {
+export function transformValue( value: AlignmentMatrixControlValue ) {
 	const nextValue = value === 'center' ? 'center center' : value;
 
-	return nextValue.replace( '-', ' ' );
+	return nextValue.replace( '-', ' ' ) as AlignmentMatrixControlValue;
 }
 
 /**
  * Creates an item ID based on a prefix ID and an alignment value.
  *
- * @param {string} prefixId An ID to prefix.
- * @param {string} value    An alignment value.
+ * @param  prefixId An ID to prefix.
+ * @param  value    An alignment value.
  *
- * @return {string} The item id.
+ * @return The item id.
  */
-export function getItemId( prefixId, value ) {
+export function getItemId(
+	prefixId: string,
+	value: AlignmentMatrixControlValue
+) {
 	const valueId = transformValue( value ).replace( ' ', '-' );
 
 	return `${ prefixId }-${ valueId }`;
@@ -55,12 +63,14 @@ export function getItemId( prefixId, value ) {
 /**
  * Retrieves the alignment index from a value.
  *
- * @param {string} alignment Value to check.
+ * @param  alignment Value to check.
  *
- * @return {number} The index of a matching alignment.
+ * @return The index of a matching alignment.
  */
-export function getAlignmentIndex( alignment = 'center' ) {
-	const item = transformValue( alignment ).replace( '-', ' ' );
+export function getAlignmentIndex(
+	alignment: AlignmentMatrixControlValue = 'center'
+) {
+	const item = transformValue( alignment );
 	const index = ALIGNMENTS.indexOf( item );
 
 	return index > -1 ? index : undefined;

package/src/angle-picker-control/styles/angle-picker-control-styles.js

@@ -42,6 +42,10 @@ export const CircleIndicatorWrapper = styled.div`
 	position: relative;
 	width: 100%;
 	height: 100%;
+
+	:focus-visible {
+		outline: none;
+	}
 `;
 
 export const CircleIndicator = styled.div`

package/src/autocomplete/index.js

@@ -415,26 +415,57 @@ function useAutocomplete( {
 }
 
 export function useAutocompleteProps( options ) {
+	const [ isVisible, setIsVisible ] = useState( false );
 	const ref = useRef();
+	const recordAfterInput = useRef();
 	const onKeyDownRef = useRef();
 	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 ) {
+		return { ref: mergedRefs };
+	}
+
 	return {
-		ref: useMergeRefs( [
-			ref,
-			useRefEffect( ( element ) => {
-				function _onKeyDown( event ) {
-					onKeyDownRef.current( event );
-				}
-				element.addEventListener( 'keydown', _onKeyDown );
-				return () => {
-					element.removeEventListener( 'keydown', _onKeyDown );
-				};
-			}, [] ),
-		] ),
+		ref: mergedRefs,
 		children: popover,
 		'aria-autocomplete': listBoxId ? 'list' : undefined,
 		'aria-owns': listBoxId,

package/src/base-control/README.md

@@ -4,16 +4,23 @@
 
 ## Usage
 
-Render a `BaseControl` for a textarea input:
-
 ```jsx
-import { BaseControl } from '@wordpress/components';
-
-// The `id` prop is necessary to accessibly associate the label with the textarea
-const MyBaseControl = () => (
-	<BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
-		<textarea id="textarea-1" />
-	</BaseControl>
+import { BaseControl, useBaseControlProps } from '@wordpress/components';
+
+// Render a `BaseControl` for a textarea input
+const MyCustomTextareaControl = ({ children, ...baseProps }) => (
+	// `useBaseControlProps` is a convenience hook to get the props for the `BaseControl`
+	// and the inner control itself. Namely, it takes care of generating a unique `id`,
+	// properly associating it with the `label` and `help` elements.
+	const { baseControlProps, controlProps } = useBaseControlProps( baseProps );
+
+	return (
+		<BaseControl { ...baseControlProps } __nextHasNoMarginBottom={ true }>
+			<textarea { ...controlProps }>
+			  { children }
+			</textarea>
+		</BaseControl>
+	);
 );
 ```
 
@@ -23,7 +30,9 @@ The component accepts the following props:
 
 ### id
 
-The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated. This is necessary to accessibly associate the label with that element.
+The HTML `id` of the control element (passed in as a child to `BaseControl`) to which labels and help text are being generated. This is necessary to accessibly associate the label with that element.
+
+The recommended way is to use the `useBaseControlProps` hook, which takes care of generating a unique `id` for you. Otherwise, if you choose to pass an explicit `id` to this prop, you are responsible for ensuring the uniqueness of the `id`.
 
 -   Type: `String`
 -   Required: No
@@ -44,9 +53,9 @@ If true, the label will only be visible to screen readers.
 
 ### help
 
-If this property is added, a help text will be generated using help property as the content.
+Additional description for the control. It is preferable to use plain text for `help`, as it can be accessibly associated with the control using `aria-describedby`. When the `help` contains links, or otherwise non-plain text content, it will be associated with the control using `aria-details`.
 
--   Type: `String|WPElement`
+-   Type: `ReactNode`
 -   Required: No
 
 ### className

package/src/base-control/hooks.ts

@@ -0,0 +1,45 @@
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '.';
+import type { BaseControlProps } from './types';
+
+/**
+ * Generate props for the `BaseControl` and the inner control itself.
+ *
+ * Namely, it takes care of generating a unique `id`, properly associating it with the `label` and `help` elements.
+ *
+ * @param  props
+ */
+export function useBaseControlProps(
+	props: Omit< BaseControlProps, 'children' >
+) {
+	const { help, id: preferredId, ...restProps } = props;
+
+	const uniqueId = useInstanceId(
+		BaseControl,
+		'wp-components-base-control',
+		preferredId
+	);
+
+	// ARIA descriptions can only contain plain text, so fall back to aria-details if not.
+	const helpPropName =
+		typeof help === 'string' ? 'aria-describedby' : 'aria-details';
+
+	return {
+		baseControlProps: {
+			id: uniqueId,
+			help,
+			...restProps,
+		},
+		controlProps: {
+			id: uniqueId,
+			...( !! help ? { [ helpPropName ]: `${ uniqueId }__help` } : {} ),
+		},
+	};
+}

package/src/base-control/index.tsx

@@ -17,19 +17,30 @@ import {
 } from './styles/base-control-styles';
 import type { WordPressComponentProps } from '../ui/context';
 
+export { useBaseControlProps } from './hooks';
+
 /**
  * `BaseControl` is a component used to generate labels and help text for components handling user inputs.
  *
- * @example
+ * ```jsx
+ * import { BaseControl, useBaseControlProps } from '@wordpress/components';
+ *
  * // Render a `BaseControl` for a textarea input
- * import { BaseControl } from '@wordpress/components';
+ * const MyCustomTextareaControl = ({ children, ...baseProps }) => (
+ * 	// `useBaseControlProps` is a convenience hook to get the props for the `BaseControl`
+ * 	// and the inner control itself. Namely, it takes care of generating a unique `id`,
+ * 	// properly associating it with the `label` and `help` elements.
+ * 	const { baseControlProps, controlProps } = useBaseControlProps( baseProps );
  *
- * // The `id` prop is necessary to accessibly associate the label with the textarea
- * const MyBaseControl = () => (
- *   <BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
- *     <textarea id="textarea-1" />
- *   </BaseControl>
+ * 	return (
+ * 		<BaseControl { ...baseControlProps } __nextHasNoMarginBottom={ true }>
+ * 			<textarea { ...controlProps }>
+ * 			  { children }
+ * 			</textarea>
+ * 		</BaseControl>
+ * 	);
  * );
+ * ```
  */
 export const BaseControl = ( {
 	__nextHasNoMarginBottom = false,

package/src/base-control/stories/index.tsx

@@ -6,7 +6,7 @@ import type { ComponentMeta, ComponentStory } from '@storybook/react';
 /**
  * Internal dependencies
  */
-import BaseControl from '..';
+import BaseControl, { useBaseControlProps } from '..';
 import Button from '../../button';
 
 const meta: ComponentMeta< typeof BaseControl > = {
@@ -24,13 +24,14 @@ const meta: ComponentMeta< typeof BaseControl > = {
 };
 export default meta;
 
-const BaseControlWithTextarea: ComponentStory< typeof BaseControl > = ( {
-	id,
-	...props
-} ) => {
+const BaseControlWithTextarea: ComponentStory< typeof BaseControl > = (
+	props
+) => {
+	const { baseControlProps, controlProps } = useBaseControlProps( props );
+
 	return (
-		<BaseControl id={ id } { ...props }>
-			<textarea style={ { display: 'block' } } id={ id } />
+		<BaseControl { ...baseControlProps }>
+			<textarea style={ { display: 'block' } } { ...controlProps } />
 		</BaseControl>
 	);
 };
@@ -39,14 +40,12 @@ export const Default: ComponentStory< typeof BaseControl > =
 	BaseControlWithTextarea.bind( {} );
 Default.args = {
 	__nextHasNoMarginBottom: true,
-	id: 'textarea-default-1',
 	label: 'Label text',
 };
 
 export const WithHelpText = BaseControlWithTextarea.bind( {} );
 WithHelpText.args = {
 	...Default.args,
-	id: 'textarea-with-help-text-1',
 	help: 'Help text adds more explanation.',
 };
 
@@ -75,6 +74,5 @@ export const WithVisualLabel: ComponentStory< typeof BaseControl > = (
 WithVisualLabel.args = {
 	...Default.args,
 	help: 'This button is already accessibly labeled.',
-	id: undefined,
 	label: undefined,
 };

package/src/base-control/test/index.tsx

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '..';
+import { useBaseControlProps } from '../hooks';
+import type { BaseControlProps } from '../types';
+
+const MyBaseControl = ( props: Omit< BaseControlProps, 'children' > ) => {
+	const { baseControlProps, controlProps } = useBaseControlProps( props );
+
+	return (
+		<BaseControl { ...baseControlProps } __nextHasNoMarginBottom={ true }>
+			<textarea { ...controlProps } />
+		</BaseControl>
+	);
+};
+
+describe( 'BaseControl', () => {
+	it( 'should render help text as description', () => {
+		render( <MyBaseControl label="Text" help="My help text" /> );
+
+		expect(
+			screen.getByRole( 'textbox', {
+				description: 'My help text',
+			} )
+		).toBeInTheDocument();
+	} );
+
+	it( 'should render help as aria-details when not plain text', () => {
+		render(
+			<MyBaseControl
+				label="Text"
+				help={ <a href="/foo">My help text</a> }
+			/>
+		);
+
+		const textarea = screen.getByRole( 'textbox' );
+		const help = screen.getByRole( 'link', {
+			name: 'My help text',
+		} );
+
+		expect( textarea ).toHaveAttribute( 'aria-details' );
+		expect(
+			help.closest( `#${ textarea.getAttribute( 'aria-details' ) }` )
+		).toBeVisible();
+	} );
+} );

package/src/base-control/types.ts

@@ -11,12 +11,18 @@ export type BaseControlProps = {
 	 */
 	__nextHasNoMarginBottom?: boolean;
 	/**
-	 * The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
+	 * The HTML `id` of the control element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
 	 * This is necessary to accessibly associate the label with that element.
+	 *
+	 * The recommended way is to use the `useBaseControlProps` hook, which takes care of generating a unique `id` for you.
+	 * Otherwise, if you choose to pass an explicit `id` to this prop, you are responsible for ensuring the uniqueness of the `id`.
 	 */
 	id?: string;
 	/**
-	 * If this property is added, a help text will be generated using help property as the content.
+	 * Additional description for the control.
+	 *
+	 * It is preferable to use plain text for `help`, as it can be accessibly associated with the control using `aria-describedby`.
+	 * When the `help` contains links, or otherwise non-plain text content, it will be associated with the control using `aria-details`.
 	 */
 	help?: ReactNode;
 	/**

package/src/base-field/README.md

@@ -12,37 +12,25 @@ This feature is still experimental. “Experimental” means this is an early im
 
 ```js
 function useExampleField( props ) {
-	const { 
-		as = 'input',
-		...baseProps,
-	} = useBaseField( props );
+	const { as = 'input', ...baseProps } = useBaseField( props );
 
 	const inputProps = {
 		as,
 		// more cool stuff here
-	}
+	};
 
 	return { inputProps, ...baseProps };
 }
 
 function ExampleField( props, forwardRef ) {
-	const {
-		preFix,
-		affix,
-		disabled,
-		inputProps,
-		...baseProps
-	} = useExampleField( props );
+	const { preFix, affix, disabled, inputProps, ...baseProps } =
+		useExampleField( props );
 
 	return (
 		<View { ...baseProps } disabled={ disabled }>
-			{preFix}
-			<View
-				autocomplete="off"
-				{ ...inputProps }
-				disabled={ disabled }
-			/>
-			{affix}
+			{ preFix }
+			<View autocomplete="off" { ...inputProps } disabled={ disabled } />
+			{ affix }
 		</View>
 	);
 }
@@ -50,18 +38,29 @@ function ExampleField( props, forwardRef ) {
 
 ## Props
 
+### `disabled`: `boolean`
+
+Whether the field is disabled.
+
+-   Required: No
+
 ### `hasError`: `boolean`
 
 Renders an error style around the component.
 
-### `disabled`: `boolean`
-
-Whether the field is disabled.
+-   Required: No
+-   Default: `false`
 
 ### `isInline`: `boolean`
 
 Renders a component that can be inlined in some text.
 
+-   Required: No
+-   Default: `false`
+
 ### `isSubtle`: `boolean`
 
 Renders a subtle variant of the component.
+
+-   Required: No
+-   Default: `false`