@wordpress/components 22.0.0 → 23.0.0

package/src/autocomplete/index.js

@@ -212,7 +212,7 @@ function useAutocomplete( {
 	}
 
 	function handleKeyDown( event ) {
-		backspacing.current = event.code === 'Backspace';
+		backspacing.current = event.key === 'Backspace';
 
 		if ( ! autocompleter ) {
 			return;
@@ -220,10 +220,19 @@ function useAutocomplete( {
 		if ( filteredOptions.length === 0 ) {
 			return;
 		}
-		if ( event.defaultPrevented ) {
+
+		if (
+			event.defaultPrevented ||
+			// Ignore keydowns from IMEs
+			event.isComposing ||
+			// Workaround for Mac Safari where the final Enter/Backspace of an IME composition
+			// is `isComposing=false`, even though it's technically still part of the composition.
+			// These can only be detected by keyCode.
+			event.keyCode === 229
+		) {
 			return;
 		}
-		switch ( event.code ) {
+		switch ( event.key ) {
 			case 'ArrowUp':
 				setSelectedIndex(
 					( selectedIndex === 0
@@ -406,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/autocomplete/style.scss

@@ -11,6 +11,6 @@
 	width: 100%;
 
 	&.is-selected {
-		box-shadow: 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
+		box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
 	}
 }

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`

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;
@@ -127,13 +127,15 @@ exports[`base field should render correctly 1`] = `
 
 .emotion-0:focus,
 .emotion-0[data-focused='true'] {
-  border-color: var( --wp-admin-theme-color, #007cba);
-  box-shadow: 0 0 0 0.5px var( --wp-admin-theme-color, #007cba);
+  border-color: var(--wp-components-color-accent, var(--wp-admin-theme-color, #007cba));
+  box-shadow: 0 0 0 0.5px var(--wp-components-color-accent, var(--wp-admin-theme-color, #007cba));
 }
 
-<div
-  class="components-flex components-base-field emotion-0 emotion-1"
-  data-wp-c16t="true"
-  data-wp-component="BaseField"
-/>
+<div>
+  <div
+    class="components-flex components-base-field emotion-0 emotion-1"
+    data-wp-c16t="true"
+    data-wp-component="BaseField"
+  />
+</div>
 `;

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

@@ -0,0 +1,84 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { useBaseField } from '../index';
+import { View } from '../../view';
+import type { BaseFieldProps } from '../types';
+
+const TestField = ( props: Omit< BaseFieldProps, 'children' > ) => {
+	return <View { ...useBaseField( { ...props, children: '' } ) } />;
+};
+
+describe( 'base field', () => {
+	it( 'should render correctly', () => {
+		const { container } = render( <TestField /> );
+		expect( container ).toMatchSnapshot();
+	} );
+
+	describe( 'props', () => {
+		it( 'should render error styles', () => {
+			render(
+				<>
+					<TestField data-testid="base-field" />
+					<TestField hasError data-testid="base-field-error" />
+				</>
+			);
+			expect(
+				screen.getByTestId( 'base-field-error' )
+			).toMatchStyleDiffSnapshot( screen.getByTestId( 'base-field' ) );
+		} );
+
+		it( 'should render inline styles', () => {
+			render(
+				<>
+					<TestField data-testid="base-field" />
+					<TestField isInline data-testid="base-field-inline" />
+				</>
+			);
+			expect(
+				screen.getByTestId( 'base-field-inline' )
+			).toMatchStyleDiffSnapshot( screen.getByTestId( 'base-field' ) );
+		} );
+
+		it( 'should render subtle styles', () => {
+			render(
+				<>
+					<TestField data-testid="base-field" />
+					<TestField isSubtle data-testid="base-field-subtle" />
+				</>
+			);
+			expect(
+				screen.getByTestId( 'base-field-subtle' )
+			).toMatchStyleDiffSnapshot( screen.getByTestId( 'base-field' ) );
+		} );
+	} );
+
+	describe( 'useBaseField', () => {
+		it( 'should pass through disabled and defaultValue props', () => {
+			// 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 = true;
+				const defaultValue = 'Lorem ipsum';
+
+				const result = useBaseField( {
+					disabled,
+					defaultValue,
+					children: '',
+				} );
+
+				expect( result.disabled ).toBe( disabled );
+				expect( result.defaultValue ).toBe( defaultValue );
+
+				return null;
+			};
+
+			render( <Component /> );
+		} );
+	} );
+} );

package/src/base-field/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal dependencies
+ */
+import type { FlexProps } from '../flex/types';
+
+export type BaseFieldProps = FlexProps & {
+	/**
+	 * Whether the field is disabled.
+	 */
+	disabled?: boolean;
+	/**
+	 * Renders an error style around the component.
+	 *
+	 * @default false
+	 */
+	hasError?: boolean;
+	/**
+	 * Renders a component that can be inlined in some text.
+	 *
+	 * @default false
+	 */
+	isInline?: boolean;
+	/**
+	 * Renders a subtle variant of the component.
+	 *
+	 * @default false
+	 */
+	isSubtle?: boolean;
+};