@wordpress/components 22.1.0 → 23.1.0

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

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { find } from 'lodash';
 import removeAccents from 'remove-accents';
 
 /**
@@ -290,8 +289,7 @@ function useAutocomplete( {
 		const textAfterSelection = getTextContent(
 			slice( record, undefined, getTextContent( record ).length )
 		);
-		const completer = find(
-			completers,
+		const completer = completers?.find(
 			( { triggerPrefix, allowContext } ) => {
 				const index = text.lastIndexOf( triggerPrefix );
 
@@ -415,26 +413,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/autocomplete/test/index.js

@@ -14,6 +14,8 @@ import { useRef } from '@wordpress/element';
  */
 import { getAutoCompleterUI } from '../autocompleter-ui';
 
+jest.useFakeTimers();
+
 describe( 'AutocompleterUI', () => {
 	describe( 'click outside behavior', () => {
 		it( 'should call reset function when a click on another element occurs', async () => {

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,53 @@
+/**
+ * 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(
+			// eslint-disable-next-line testing-library/no-node-access
+			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`

package/src/base-field/{hook.js → hook.ts}

@@ -6,26 +6,16 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { useControlGroupContext } from '../ui/control-group';
 import { useFlex } from '../flex';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
+import type { BaseFieldProps } from './types';
 
-/**
- * @typedef OwnProps
- * @property {boolean} [hasError=false] Renders an error.
- * @property {boolean} [disabled]       Whether the field is disabled.
- * @property {boolean} [isInline=false] Renders as an inline element (layout).
- * @property {boolean} [isSubtle=false] Renders a subtle variant.
- */
-
-/** @typedef {import('../flex/types').FlexProps & OwnProps} Props */
-
-/**
- * @param {import('../ui/context').WordPressComponentProps<Props, 'div'>} props
- */
-export function useBaseField( props ) {
+export function useBaseField(
+	props: WordPressComponentProps< BaseFieldProps, 'div' >
+) {
 	const {
 		className,
 		hasError = false,

package/src/base-field/{styles.js → styles.ts}

@@ -13,7 +13,7 @@ export const BaseField = css`
 	background: ${ CONFIG.controlBackgroundColor };
 	border-radius: ${ CONFIG.controlBorderRadius };
 	border: 1px solid;
-	border-color: ${ CONFIG.controlBorderColor };
+	border-color: ${ COLORS.ui.border };
 	box-shadow: ${ CONFIG.controlBoxShadow };
 	display: flex;
 	flex: 1;
@@ -30,7 +30,7 @@ export const BaseField = css`
 	}
 
 	&:hover {
-		border-color: ${ CONFIG.controlBorderColorHover };
+		border-color: ${ COLORS.ui.borderHover };
 	}
 
 	&:focus,

package/src/base-field/test/__snapshots__/{index.js.snap → index.tsx.snap}

@@ -12,7 +12,7 @@ Snapshot Diff:
       "background": "#fff",
       "border": "1px solid",
 -     "border-color": "#d94f4f",
-+     "border-color": "#757575",
++     "border-color": "#949494",
       "border-radius": "2px",
       "box-shadow": "transparent",
       "display": "flex",
@@ -28,7 +28,7 @@ Snapshot Diff:
 @@ -14,19 +14,18 @@
       "background": "#fff",
       "border": "1px solid",
-      "border-color": "#757575",
+      "border-color": "#949494",
       "border-radius": "2px",
       "box-shadow": "transparent",
 -     "display": "inline-flex",
@@ -62,7 +62,7 @@ Snapshot Diff:
       "background": "#fff",
 -     "background-color": "transparent",
       "border": "1px solid",
-      "border-color": "#757575",
+      "border-color": "#949494",
       "border-radius": "2px",
       "box-shadow": "transparent",
       "display": "flex",
@@ -89,7 +89,7 @@ exports[`base field should render correctly 1`] = `
   background: #fff;
   border-radius: 2px;
   border: 1px solid;
-  border-color: #757575;
+  border-color: #949494;
   box-shadow: transparent;
   display: -webkit-box;
   display: -webkit-flex;

package/src/base-field/test/{index.js → index.tsx}

@@ -8,9 +8,10 @@ import { render, screen } from '@testing-library/react';
  */
 import { useBaseField } from '../index';
 import { View } from '../../view';
+import type { BaseFieldProps } from '../types';
 
-const TestField = ( props ) => {
-	return <View { ...useBaseField( props ) } />;
+const TestField = ( props: Omit< BaseFieldProps, 'children' > ) => {
+	return <View { ...useBaseField( { ...props, children: '' } ) } />;
 };
 
 describe( 'base field', () => {
@@ -62,10 +63,14 @@ describe( 'base field', () => {
 			// wrap this in a component so that `useContext` calls don't fail inside the hook
 			// assertions will still run as normal when we `render` the component :)
 			const Component = () => {
-				const disabled = Symbol.for( 'disabled' );
-				const defaultValue = Symbol.for( 'defaultValue' );
+				const disabled = true;
+				const defaultValue = 'Lorem ipsum';
 
-				const result = useBaseField( { disabled, defaultValue } );
+				const result = useBaseField( {
+					disabled,
+					defaultValue,
+					children: '',
+				} );
 
 				expect( result.disabled ).toBe( disabled );
 				expect( result.defaultValue ).toBe( defaultValue );