@wordpress/components 28.2.0 → 28.3.0

package/src/button/README.md

@@ -115,6 +115,17 @@ The presence of a `href` prop determines whether an `anchor` element is rendered
 
 Props not included in this set will be applied to the `a` or `button` element.
 
+#### `accessibleWhenDisabled`: `boolean`
+
+Whether to keep the button focusable when disabled.
+
+In most cases, it is recommended to set this to `true`. Disabling a control without maintaining focusability can cause accessibility issues, by hiding their presence from screen reader users, or by preventing focus from returning to a trigger element.
+
+Learn more about the [focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols) in the WAI-ARIA Authoring Practices Guide.
+
+-   Required: No
+-   Default: `false`
+
 #### `children`: `ReactNode`
 
 The button's children.
@@ -137,6 +148,8 @@ An accessible description for the button.
 
 Whether the button is disabled. If `true`, this will force a `button` element to be rendered, even when an `href` is given.
 
+In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
+
 -   Required: No
 
 #### `href`: `string`

package/src/button/index.tsx

@@ -29,6 +29,7 @@ import { positionToPlacement } from '../popover/utils';
 const disabledEventsOnDisabledButton = [ 'onMouseDown', 'onClick' ] as const;
 
 function useDeprecatedProps( {
+	__experimentalIsFocusable,
 	isDefault,
 	isPrimary,
 	isSecondary,
@@ -43,7 +44,8 @@ function useDeprecatedProps( {
 	let computedSize = size;
 	let computedVariant = variant;
 
-	const newProps: { 'aria-pressed'?: boolean } = {
+	const newProps = {
+		accessibleWhenDisabled: __experimentalIsFocusable,
 		// @todo Mark `isPressed` as deprecated
 		'aria-pressed': isPressed,
 	};
@@ -91,6 +93,7 @@ export function UnforwardedButton(
 ) {
 	const {
 		__next40pxDefaultSize,
+		accessibleWhenDisabled,
 		isBusy,
 		isDestructive,
 		className,
@@ -106,7 +109,6 @@ export function UnforwardedButton(
 		size = 'default',
 		text,
 		variant,
-		__experimentalIsFocusable: isFocusable,
 		describedBy,
 		...buttonOrAnchorProps
 	} = useDeprecatedProps( props );
@@ -159,7 +161,7 @@ export function UnforwardedButton(
 		'has-icon': !! icon,
 	} );
 
-	const trulyDisabled = disabled && ! isFocusable;
+	const trulyDisabled = disabled && ! accessibleWhenDisabled;
 	const Tag = href !== undefined && ! trulyDisabled ? 'a' : 'button';
 	const buttonProps: ComponentPropsWithoutRef< 'button' > =
 		Tag === 'button'
@@ -177,7 +179,7 @@ export function UnforwardedButton(
 	const disableEventProps: {
 		[ key: string ]: ( event: MouseEvent ) => void;
 	} = {};
-	if ( disabled && isFocusable ) {
+	if ( disabled && accessibleWhenDisabled ) {
 		// In this case, the button will be disabled, but still focusable and
 		// perceivable by screen reader users.
 		buttonProps[ 'aria-disabled' ] = true;

package/src/button/stories/e2e/index.story.tsx

@@ -39,12 +39,13 @@ export const VariantStates: StoryFn< typeof Button > = (
 					key={ variant ?? 'undefined' }
 				>
 					<Button { ...props } variant={ variant } />
+					{ /* eslint-disable-next-line no-restricted-syntax */ }
 					<Button { ...props } variant={ variant } disabled />
 					<Button
 						{ ...props }
 						variant={ variant }
 						disabled
-						__experimentalIsFocusable
+						accessibleWhenDisabled
 					/>
 					<Button { ...props } variant={ variant } isBusy />
 					<Button { ...props } variant={ variant } isDestructive />

package/src/button/test/index.tsx

@@ -235,13 +235,14 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should add a disabled prop to the button', () => {
+			// eslint-disable-next-line no-restricted-syntax
 			render( <Button disabled /> );
 
 			expect( screen.getByRole( 'button' ) ).toBeDisabled();
 		} );
 
 		it( 'should add only aria-disabled attribute when disabled and isFocusable are true', () => {
-			render( <Button disabled __experimentalIsFocusable /> );
+			render( <Button disabled accessibleWhenDisabled /> );
 			const button = screen.getByRole( 'button' );
 
 			expect( button ).toBeEnabled();
@@ -536,6 +537,7 @@ describe( 'Button', () => {
 
 		it( 'should become a button again when disabled is supplied', () => {
 			// @ts-expect-error - a button should not have `href`
+			// eslint-disable-next-line no-restricted-syntax
 			render( <Button href="https://wordpress.org/" disabled /> );
 
 			expect( screen.getByRole( 'button' ) ).toBeVisible();
@@ -617,6 +619,15 @@ describe( 'Button', () => {
 				'mixed'
 			);
 		} );
+
+		it( 'should not break when the legacy __experimentalIsFocusable prop is passed', () => {
+			// eslint-disable-next-line no-restricted-syntax
+			render( <Button disabled __experimentalIsFocusable /> );
+			const button = screen.getByRole( 'button' );
+
+			expect( button ).toBeEnabled();
+			expect( button ).toHaveAttribute( 'aria-disabled' );
+		} );
 	} );
 
 	describe( 'static typing', () => {
@@ -624,15 +635,19 @@ describe( 'Button', () => {
 			<Button href="foo" />
 			{ /* @ts-expect-error - `target` requires `href` */ }
 			<Button target="foo" />
+
+			{ /* eslint-disable no-restricted-syntax */ }
 			{ /* @ts-expect-error - `disabled` is only for buttons */ }
 			<Button href="foo" disabled />
+			{ /* eslint-enable no-restricted-syntax */ }
+
 			<Button href="foo" type="image/png" />
 			{ /* @ts-expect-error - if button, type must be submit/reset/button */ }
 			<Button type="image/png" />
 			{ /* @ts-expect-error */ }
 			<Button type="invalidtype" />
 			{ /* @ts-expect-error - although the runtime behavior will allow this to be an anchor, this is probably a mistake. */ }
-			<Button disabled __experimentalIsFocusable href="foo" />
+			<Button disabled accessibleWhenDisabled href="foo" />
 		</>;
 	} );
 } );

package/src/button/types.ts

@@ -25,6 +25,19 @@ type BaseButtonProps = {
 	 * @default false
 	 */
 	__next40pxDefaultSize?: boolean;
+	/**
+	 * Whether to keep the button focusable when disabled.
+	 *
+	 * In most cases, it is recommended to set this to `true`. Disabling a control without maintaining focusability
+	 * can cause accessibility issues, by hiding their presence from screen reader users,
+	 * or by preventing focus from returning to a trigger element.
+	 *
+	 * Learn more about the [focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols)
+	 * in the WAI-ARIA Authoring Practices Guide.
+	 *
+	 * @default false
+	 */
+	accessibleWhenDisabled?: boolean;
 	/**
 	 * The button's children.
 	 */
@@ -105,28 +118,24 @@ type BaseButtonProps = {
 	 * 'link' (the link button styles)
 	 */
 	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
-	/**
-	 * Whether to keep the button focusable when disabled.
-	 *
-	 * @default false
-	 */
-	__experimentalIsFocusable?: boolean;
 };
 
 type _ButtonProps = {
 	/**
-	 * Whether the button is disabled.
+	 * Whether the button is disabled. If `true`, this will force a `button` element
+	 * to be rendered, even when an `href` is given.
 	 *
-	 * If `true`, this will force a `button` element to be rendered, even when an `href` is given.
+	 * In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
 	 */
 	disabled?: boolean;
 };
 
 type AnchorProps = {
 	/**
-	 * Whether the button is disabled.
+	 * Whether the button is disabled. If `true`, this will force a `button` element
+	 * to be rendered, even when an `href` is given.
 	 *
-	 * If `true`, this will force a `button` element to be rendered, even when an `href` is given.
+	 * In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
 	 */
 	disabled?: false;
 	/**
@@ -140,6 +149,14 @@ type AnchorProps = {
 };
 
 export type DeprecatedButtonProps = {
+	/**
+	 * Whether to keep the button focusable when disabled.
+	 *
+	 * @default false
+	 * @deprecated Use the `accessibleWhenDisabled` prop instead.
+	 * @ignore
+	 */
+	__experimentalIsFocusable?: boolean;
 	/**
 	 * Gives the button a default style.
 	 *

package/src/combobox-control/index.tsx

@@ -346,6 +346,8 @@ function ComboboxControl( props: ComboboxControlProps ) {
 								<Button
 									className="components-combobox-control__reset"
 									icon={ closeSmall }
+									// Disable reason: Focus returns to input field when reset is clicked.
+									// eslint-disable-next-line no-restricted-syntax
 									disabled={ ! value }
 									onClick={ handleOnReset }
 									label={ __( 'Reset' ) }

package/src/composite/current/index.ts

@@ -8,7 +8,6 @@
  * @see https://ariakit.org/components/composite
  */
 
-/* eslint-disable-next-line no-restricted-imports */
 export {
 	Composite,
 	CompositeGroup,
@@ -18,5 +17,4 @@ export {
 	useCompositeStore,
 } from '@ariakit/react';
 
-/* eslint-disable-next-line no-restricted-imports */
 export type { CompositeStore, CompositeStoreProps } from '@ariakit/react';

package/src/custom-select-control/test/index.js

@@ -190,14 +190,14 @@ describe.each( [
 		await user.keyboard( '{enter}' );
 		expect(
 			screen.getByRole( 'listbox', {
-				name: 'label!',
+				name: props.label,
 			} )
 		).toBeVisible();
 
 		await user.keyboard( '{escape}' );
 		expect(
 			screen.queryByRole( 'listbox', {
-				name: 'label!',
+				name: props.label,
 			} )
 		).not.toBeInTheDocument();
 
@@ -440,6 +440,16 @@ describe.each( [
 		);
 	} );
 
+	it( 'Should label the component correctly even when the label is not visible', () => {
+		render( <Component { ...props } hideLabelFromVision /> );
+
+		expect(
+			screen.getByRole( 'button', {
+				name: props.label,
+			} )
+		).toBeVisible();
+	} );
+
 	describe( 'Keyboard behavior and accessibility', () => {
 		it( 'Captures the keypress event and does not let it propagate', async () => {
 			const user = userEvent.setup();
@@ -460,7 +470,7 @@ describe.each( [
 			await user.click( currentSelectedItem );
 
 			const customSelect = screen.getByRole( 'listbox', {
-				name: 'label!',
+				name: props.label,
 			} );
 			await user.type( customSelect, '{enter}' );
 
@@ -482,7 +492,7 @@ describe.each( [
 			await user.keyboard( '{enter}' );
 			expect(
 				screen.getByRole( 'listbox', {
-					name: 'label!',
+					name: props.label,
 				} )
 			).toHaveFocus();
 
@@ -507,7 +517,7 @@ describe.each( [
 			await user.keyboard( '{enter}' );
 			expect(
 				screen.getByRole( 'listbox', {
-					name: 'label!',
+					name: props.label,
 				} )
 			).toHaveFocus();
 
@@ -533,7 +543,7 @@ describe.each( [
 
 			expect(
 				screen.queryByRole( 'listbox', {
-					name: 'label!',
+					name: props.label,
 					hidden: true,
 				} )
 			).not.toBeInTheDocument();
@@ -542,6 +552,32 @@ describe.each( [
 			expect( currentSelectedItem ).toHaveTextContent( 'aquamarine' );
 		} );
 
+		it( 'Can change selection with a focused input and closed dropdown while pressing arrow keys', async () => {
+			const user = userEvent.setup();
+
+			render( <Component { ...props } /> );
+
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+
+			await user.tab();
+			expect( currentSelectedItem ).toHaveFocus();
+			expect( currentSelectedItem ).toHaveTextContent(
+				props.options[ 0 ].name
+			);
+
+			await user.keyboard( '{arrowdown}' );
+			await user.keyboard( '{arrowdown}' );
+			expect(
+				screen.queryByRole( 'listbox', { name: props.label } )
+			).not.toBeInTheDocument();
+
+			expect( currentSelectedItem ).toHaveTextContent(
+				props.options[ 2 ].name
+			);
+		} );
+
 		it( 'Should have correct aria-selected value for selections', async () => {
 			const user = userEvent.setup();
 

package/src/custom-select-control-v2/custom-select.tsx

@@ -1,7 +1,12 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
 /**
  * WordPress dependencies
  */
-import { createContext, useMemo } from '@wordpress/element';
+import { createContext, useCallback, useMemo } from '@wordpress/element';
 import { __, sprintf } from '@wordpress/i18n';
 
 /**
@@ -14,11 +19,12 @@ import type {
 	CustomSelectStore,
 	CustomSelectButtonProps,
 	CustomSelectButtonSize,
+	_CustomSelectInternalProps,
 	_CustomSelectProps,
 } from './types';
-import type { WordPressComponentProps } from '../context';
 import InputBase from '../input-control/input-base';
 import SelectControlChevronDown from '../select-control/chevron-down';
+import BaseControl from '../base-control';
 
 export const CustomSelectContext =
 	createContext< CustomSelectContextType >( undefined );
@@ -50,11 +56,10 @@ const CustomSelectButton = ( {
 	store,
 	...restProps
 }: Omit<
-	WordPressComponentProps<
-		CustomSelectButtonProps & CustomSelectButtonSize & CustomSelectStore,
-		'button',
-		false
-	>,
+	React.ComponentProps< typeof Ariakit.Select > &
+		CustomSelectButtonProps &
+		CustomSelectButtonSize &
+		CustomSelectStore,
 	'onChange'
 > ) => {
 	const { value: currentValue } = store.useState();
@@ -70,9 +75,6 @@ const CustomSelectButton = ( {
 			size={ size }
 			hasCustomRenderProp={ !! renderSelectedValue }
 			store={ store }
-			// to match legacy behavior where using arrow keys
-			// move selection rather than open the popover
-			showOnKeyDown={ false }
 		>
 			{ computedRenderSelectedValue( currentValue ) }
 		</Styled.Select>
@@ -80,7 +82,10 @@ const CustomSelectButton = ( {
 };
 
 function _CustomSelect(
-	props: _CustomSelectProps & CustomSelectStore & CustomSelectButtonSize
+	props: _CustomSelectInternalProps &
+		_CustomSelectProps &
+		CustomSelectStore &
+		CustomSelectButtonSize
 ) {
 	const {
 		children,
@@ -88,18 +93,40 @@ function _CustomSelect(
 		label,
 		size,
 		store,
+		className,
+		isLegacy = false,
 		...restProps
 	} = props;
 
+	const onSelectPopoverKeyDown: React.KeyboardEventHandler< HTMLDivElement > =
+		useCallback(
+			( e ) => {
+				if ( isLegacy ) {
+					e.stopPropagation();
+				}
+			},
+			[ isLegacy ]
+		);
+
+	const contextValue = useMemo( () => ( { store, size } ), [ store, size ] );
+
 	return (
-		<>
-			{ hideLabelFromVision ? ( // TODO: Replace with BaseControl
-				<VisuallyHidden as="label">{ label }</VisuallyHidden>
-			) : (
-				<Styled.SelectLabel store={ store }>
-					{ label }
-				</Styled.SelectLabel>
-			) }
+		// Where should `restProps` be forwarded to?
+		<div className={ className }>
+			<Ariakit.SelectLabel
+				store={ store }
+				render={
+					hideLabelFromVision ? (
+						// @ts-expect-error `children` are passed via the render prop
+						<VisuallyHidden />
+					) : (
+						// @ts-expect-error `children` are passed via the render prop
+						<BaseControl.VisualLabel as="div" />
+					)
+				}
+			>
+				{ label }
+			</Ariakit.SelectLabel>
 			<InputBase
 				__next40pxDefaultSize
 				size={ size }
@@ -109,14 +136,22 @@ function _CustomSelect(
 					{ ...restProps }
 					size={ size }
 					store={ store }
+					// Match legacy behavior (move selection rather than open the popover)
+					showOnKeyDown={ ! isLegacy }
 				/>
-				<Styled.SelectPopover gutter={ 12 } store={ store } sameWidth>
-					<CustomSelectContext.Provider value={ { store } }>
+				<Styled.SelectPopover
+					gutter={ 12 }
+					store={ store }
+					sameWidth
+					slide={ false }
+					onKeyDown={ onSelectPopoverKeyDown }
+				>
+					<CustomSelectContext.Provider value={ contextValue }>
 						{ children }
 					</CustomSelectContext.Provider>
 				</Styled.SelectPopover>
 			</InputBase>
-		</>
+		</div>
 	);
 }
 

package/src/custom-select-control-v2/default-component/index.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
 /**
  * Internal dependencies

package/src/custom-select-control-v2/item.tsx

@@ -17,7 +17,11 @@ export function CustomSelectItem( {
 }: WordPressComponentProps< CustomSelectItemProps, 'div', false > ) {
 	const customSelectContext = useContext( CustomSelectContext );
 	return (
-		<Styled.SelectItem store={ customSelectContext?.store } { ...props }>
+		<Styled.SelectItem
+			store={ customSelectContext?.store }
+			size={ customSelectContext?.size ?? 'default' }
+			{ ...props }
+		>
 			{ children ?? props.value }
 			<Styled.SelectedItemCheck>
 				<Icon icon={ check } />

package/src/custom-select-control-v2/legacy-component/index.tsx

@@ -1,8 +1,8 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
+import clsx from 'clsx';
 
 /**
  * Internal dependencies
@@ -21,6 +21,7 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 		onChange,
 		size = 'default',
 		value,
+		className: classNameProp,
 		...restProps
 	} = props;
 
@@ -62,12 +63,15 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 	const children = options.map(
 		( { name, key, __experimentalHint, style, className } ) => {
 			const withHint = (
-				<Styled.WithHintWrapper>
+				<Styled.WithHintItemWrapper>
 					<span>{ name }</span>
-					<Styled.ExperimentalHintItem className="components-custom-select-control__item-hint">
+					<Styled.WithHintItemHint
+					// TODO: Legacy classname. Add V1 styles are removed from the codebase
+					// className="components-custom-select-control__item-hint"
+					>
 						{ __experimentalHint }
-					</Styled.ExperimentalHintItem>
-				</Styled.WithHintWrapper>
+					</Styled.WithHintItemHint>
+				</Styled.WithHintItemWrapper>
 			);
 
 			return (
@@ -76,7 +80,15 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 					value={ name }
 					children={ __experimentalHint ? withHint : name }
 					style={ style }
-					className={ className }
+					className={ clsx(
+						// TODO: Legacy classname. Add V1 styles are removed from the codebase
+						// 'components-custom-select-control__item',
+						className
+						// TODO: Legacy classname. Add V1 styles are removed from the codebase
+						// {
+						// 	'has-hint': __experimentalHint,
+						// }
+					) }
 				/>
 			);
 		}
@@ -92,7 +104,10 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 		return (
 			<Styled.SelectedExperimentalHintWrapper>
 				{ currentValue }
-				<Styled.SelectedExperimentalHintItem className="components-custom-select-control__hint">
+				<Styled.SelectedExperimentalHintItem
+				// TODO: Legacy classname. Add V1 styles are removed from the codebase
+				// className="components-custom-select-control__hint"
+				>
 					{ currentHint?.__experimentalHint }
 				</Styled.SelectedExperimentalHintItem>
 			</Styled.SelectedExperimentalHintWrapper>
@@ -122,6 +137,12 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) {
 			}
 			size={ translatedSize }
 			store={ store }
+			className={ clsx(
+				// TODO: Legacy classname. Add V1 styles are removed from the codebase
+				// 'components-custom-select-control',
+				classNameProp
+			) }
+			isLegacy
 			{ ...restProps }
 		>
 			{ children }