@wordpress/components 39.0.0 → 40.1.0

package/src/circular-option-picker/README.md

@@ -77,16 +77,20 @@ The child elements.
 
 - Required: No
 
-### `asButtons`: `boolean`
+### `presentation`: `'listbox' | 'toggle-buttons' | 'command-buttons'`
 
-Whether the control should present as a set of buttons, each with its own tab stop.
+Controls the swatches' interaction and accessibility semantics.
+
+-   `listbox` uses one tab stop for the picker. Arrow keys move between options. Options expose selection with `aria-selected`.
+-   `toggle-buttons` uses a tab stop for each swatch. Swatches expose selection with `aria-pressed`.
+-   `command-buttons` uses a tab stop for each swatch. Swatches do not expose selection. Use this presentation when each swatch runs a command, such as opening an editor.
 
 - Required: No
-- Default: `false`
+- Default: `listbox`
 
 ### `loop`: `boolean`
 
-Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+Prevents arrow-key navigation from wrapping around. Only used with the `listbox` presentation.
 
 - Required: No
 - Default: `true`

package/src/circular-option-picker/circular-option-picker-option.tsx

@@ -79,7 +79,11 @@ export function Option( {
 	tooltipText,
 	...additionalProps
 }: OptionProps ) {
-	const { baseId, setActiveId } = useContext( CircularOptionPickerContext );
+	// Preserve the historical toggle-button fallback when this public
+	// subcomponent is rendered without a parent picker.
+	const { baseId, presentation = 'toggle-buttons' } = useContext(
+		CircularOptionPickerContext
+	);
 	const id = useInstanceId(
 		Option,
 		baseId || 'components-circular-option-picker__option'
@@ -91,20 +95,24 @@ export function Option( {
 		...additionalProps,
 	};
 
-	const isListbox = setActiveId !== undefined;
-	const optionControl = isListbox ? (
-		<OptionAsOption
-			{ ...commonProps }
-			label={ tooltipText }
-			isSelected={ isSelected }
-		/>
-	) : (
-		<OptionAsButton
-			{ ...commonProps }
-			label={ tooltipText }
-			isPressed={ isSelected }
-		/>
-	);
+	const optionControl =
+		presentation === 'listbox' ? (
+			<OptionAsOption
+				{ ...commonProps }
+				label={ tooltipText }
+				isSelected={ isSelected }
+			/>
+		) : (
+			<OptionAsButton
+				{ ...commonProps }
+				label={ tooltipText }
+				isPressed={
+					presentation === 'toggle-buttons'
+						? !! isSelected
+						: undefined
+				}
+			/>
+		);
 
 	return (
 		<div
@@ -114,7 +122,9 @@ export function Option( {
 			) }
 		>
 			{ optionControl }
-			{ isSelected && <Icon icon={ check } { ...selectedIconProps } /> }
+			{ presentation !== 'command-buttons' && isSelected && (
+				<Icon icon={ check } { ...selectedIconProps } />
+			) }
 		</div>
 	);
 }

package/src/circular-option-picker/circular-option-picker.tsx

@@ -15,6 +15,10 @@ import {
 	ButtonAction,
 	DropdownLinkAction,
 } from './circular-option-picker-actions';
+import {
+	resolveCircularOptionPickerPresentation,
+	warnIfCircularOptionPickerAsButtonsIsSet,
+} from './utils';
 
 /**
  *`CircularOptionPicker` is a component that displays a set of options as circular buttons.
@@ -83,6 +87,7 @@ function ListboxCircularOptionPicker(
 			baseId,
 			activeId,
 			setActiveId,
+			presentation: 'listbox' as const,
 		} ),
 		[ baseId, activeId, setActiveId ]
 	);
@@ -111,13 +116,21 @@ function ListboxCircularOptionPicker(
 function ButtonsCircularOptionPicker(
 	props: ButtonsCircularOptionPickerProps
 ) {
-	const { actions, options, children, baseId, ...additionalProps } = props;
+	const {
+		actions,
+		options,
+		children,
+		baseId,
+		presentation,
+		...additionalProps
+	} = props;
 
 	const contextValue = useMemo(
 		() => ( {
 			baseId,
+			presentation,
 		} ),
-		[ baseId ]
+		[ baseId, presentation ]
 	);
 
 	return (
@@ -134,12 +147,22 @@ function ButtonsCircularOptionPicker(
 function CircularOptionPicker( props: CircularOptionPickerProps ) {
 	const {
 		asButtons,
+		presentation,
+		loop,
 		actions: actionsProp,
 		options: optionsProp,
 		children,
 		className,
 		...additionalProps
 	} = props;
+	warnIfCircularOptionPickerAsButtonsIsSet(
+		'CircularOptionPicker',
+		asButtons
+	);
+	const resolvedPresentation = resolveCircularOptionPickerPresentation(
+		presentation,
+		asButtons
+	);
 
 	const baseId = useInstanceId(
 		CircularOptionPicker,
@@ -147,10 +170,6 @@ function CircularOptionPicker( props: CircularOptionPickerProps ) {
 		additionalProps.id
 	);
 
-	const OptionPickerImplementation = asButtons
-		? ButtonsCircularOptionPicker
-		: ListboxCircularOptionPicker;
-
 	const actions = actionsProp ? (
 		<div className="components-circular-option-picker__custom-clear-wrapper">
 			{ actionsProp }
@@ -163,16 +182,30 @@ function CircularOptionPicker( props: CircularOptionPickerProps ) {
 		</div>
 	);
 
+	const sharedProps = {
+		baseId,
+		className: clsx( 'components-circular-option-picker', className ),
+		actions,
+		options,
+		children,
+	};
+
+	if ( resolvedPresentation === 'listbox' ) {
+		return (
+			<ListboxCircularOptionPicker
+				{ ...additionalProps }
+				{ ...sharedProps }
+				loop={ loop }
+			/>
+		);
+	}
+
 	return (
-		<OptionPickerImplementation
+		<ButtonsCircularOptionPicker
 			{ ...additionalProps }
-			baseId={ baseId }
-			className={ clsx( 'components-circular-option-picker', className ) }
-			actions={ actions }
-			options={ options }
-		>
-			{ children }
-		</OptionPickerImplementation>
+			{ ...sharedProps }
+			presentation={ resolvedPresentation }
+		/>
 	);
 }
 

package/src/circular-option-picker/index.tsx

@@ -6,6 +6,10 @@ export {
 	ButtonAction,
 	DropdownLinkAction,
 } from './circular-option-picker-actions';
-export { getComputeCircularOptionPickerCommonProps } from './utils';
+export {
+	getComputeCircularOptionPickerCommonProps,
+	resolveCircularOptionPickerPresentation,
+	warnIfCircularOptionPickerAsButtonsIsSet,
+} from './utils';
 
 export default CircularOptionPicker;

package/src/circular-option-picker/stories/index.story.tsx

@@ -107,10 +107,10 @@ Default.args = {
 	options: <DefaultOptions />,
 };
 
-export const AsButtons = Template.bind( {} );
-AsButtons.args = {
+export const AsToggleButtons = Template.bind( {} );
+AsToggleButtons.args = {
 	...Default.args,
-	asButtons: true,
+	presentation: 'toggle-buttons',
 };
 
 export const WithLoopingDisabled = Template.bind( {} );

package/src/circular-option-picker/test/index.jsdom.test.tsx

@@ -0,0 +1,263 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { press } from '@ariakit/test';
+import { logged } from '@wordpress/deprecated';
+import CircularOptionPicker from '..';
+
+const SINGLE_OPTION = [ <CircularOptionPicker.Option key="option" /> ];
+
+const MULTIPLE_OPTIONS = [
+	<CircularOptionPicker.Option key="option-1" aria-label="Option One" />,
+	<CircularOptionPicker.Option key="option-2" aria-label="Option Two" />,
+];
+
+const DEFAULT_PROPS = {
+	'aria-label': 'Circular Option Picker',
+	options: SINGLE_OPTION,
+};
+const AS_BUTTONS_DEPRECATION =
+	'`asButtons` prop in wp.components.CircularOptionPicker is deprecated since version 7.2. Please use `presentation` instead. Note: `asButtons={ true }` maps to `presentation="toggle-buttons"`. Explicit `presentation` takes precedence.';
+
+function getOption( name: string ) {
+	return screen.getByRole( 'option', { name } );
+}
+
+describe( 'CircularOptionPicker', () => {
+	beforeEach( () => {
+		Object.keys( logged ).forEach( ( key ) => delete logged[ key ] );
+	} );
+
+	it( 'should preserve toggle-button semantics when an option is rendered without a picker', () => {
+		render(
+			<CircularOptionPicker.Option
+				isSelected
+				aria-label="Standalone option"
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Standalone option',
+				pressed: true,
+			} )
+		).toBeInTheDocument();
+		expect( screen.queryByRole( 'option' ) ).not.toBeInTheDocument();
+	} );
+
+	describe( 'when `asButtons` is not set', () => {
+		it( 'should render as a listbox', async () => {
+			render( <CircularOptionPicker { ...DEFAULT_PROPS } /> );
+
+			expect( screen.getByRole( 'listbox' ) ).toBeInTheDocument();
+			expect( screen.getByRole( 'option' ) ).toBeInTheDocument();
+			expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'when `asButtons` is false', () => {
+		it( 'should render as a listbox', async () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					asButtons={ false }
+				/>
+			);
+
+			expect( screen.getByRole( 'listbox' ) ).toBeInTheDocument();
+			expect( screen.getByRole( 'option' ) ).toBeInTheDocument();
+			expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+			expect( console ).toHaveWarnedWith( AS_BUTTONS_DEPRECATION );
+		} );
+	} );
+
+	describe( 'when `asButtons` is true', () => {
+		it( 'should render as toggle buttons with selected and unselected states', async () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					asButtons
+					options={ [
+						<CircularOptionPicker.Option
+							key="selected"
+							isSelected
+							aria-label="Selected"
+						/>,
+						<CircularOptionPicker.Option
+							key="unselected"
+							aria-label="Unselected"
+						/>,
+					] }
+				/>
+			);
+
+			expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
+			expect( screen.queryByRole( 'option' ) ).not.toBeInTheDocument();
+			expect( screen.getByRole( 'group' ) ).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Selected',
+					pressed: true,
+				} )
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Unselected',
+					pressed: false,
+				} )
+			).toBeInTheDocument();
+			expect( console ).toHaveWarnedWith( AS_BUTTONS_DEPRECATION );
+		} );
+	} );
+
+	describe( 'when `presentation` is set', () => {
+		it( 'should render a selected listbox option', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					presentation="listbox"
+					options={ [
+						<CircularOptionPicker.Option
+							key="option"
+							isSelected
+							aria-label="Selected"
+						/>,
+					] }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'option', {
+					name: 'Selected',
+					selected: true,
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should render toggle buttons with selected and unselected states', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					presentation="toggle-buttons"
+					options={ [
+						<CircularOptionPicker.Option
+							key="selected"
+							isSelected
+							aria-label="Selected"
+						/>,
+						<CircularOptionPicker.Option
+							key="unselected"
+							aria-label="Unselected"
+						/>,
+					] }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Selected',
+					pressed: true,
+				} )
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Unselected',
+					pressed: false,
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should render command buttons without selection state or a selected check', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					presentation="command-buttons"
+					options={ [
+						<CircularOptionPicker.Option
+							key="option"
+							isSelected
+							aria-label="Edit"
+						/>,
+					] }
+				/>
+			);
+
+			const button = screen.getByRole( 'button', { name: 'Edit' } );
+			expect( button ).not.toHaveAttribute( 'aria-pressed' );
+			expect( button ).not.toHaveAttribute( 'aria-selected' );
+			// The selected check is decorative and therefore has no semantic query.
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( button.nextElementSibling ).toBeNull();
+		} );
+
+		it( 'should prefer an explicit presentation over asButtons', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					asButtons
+					presentation="command-buttons"
+				/>
+			);
+
+			expect( screen.getByRole( 'button' ) ).not.toHaveAttribute(
+				'aria-pressed'
+			);
+			expect( console ).toHaveWarnedWith( AS_BUTTONS_DEPRECATION );
+		} );
+	} );
+
+	describe( 'when `loop` is not set', () => {
+		it( 'should loop', async () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					options={ MULTIPLE_OPTIONS }
+				/>
+			);
+
+			await press.Tab();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+			await press.ArrowRight();
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+			await press.ArrowRight();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+		} );
+	} );
+
+	describe( 'when `loop` is true', () => {
+		it( 'should loop', async () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					options={ MULTIPLE_OPTIONS }
+					loop
+				/>
+			);
+
+			await press.Tab();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+			await press.ArrowRight();
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+			await press.ArrowRight();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+		} );
+	} );
+
+	describe( 'when `loop` is false', () => {
+		it( 'should not loop', async () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					loop={ false }
+					options={ MULTIPLE_OPTIONS }
+				/>
+			);
+
+			await press.Tab();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+			await press.ArrowRight();
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+			await press.ArrowRight();
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+		} );
+	} );
+} );

package/src/circular-option-picker/types.ts

@@ -4,7 +4,7 @@ import type { ButtonAsButtonProps } from '../button/types';
 import type { DropdownProps } from '../dropdown/types';
 import type { WordPressComponentProps } from '../context';
 
-type CommonCircularOptionPickerProps = {
+export type CircularOptionPickerProps = {
 	/**
 	 * An ID to apply to the component.
 	 */
@@ -29,6 +29,35 @@ type CommonCircularOptionPickerProps = {
 	 * The child elements.
 	 */
 	children?: ReactNode;
+	/**
+	 * How the swatches behave and are exposed to assistive technology.
+	 *
+	 * - `listbox` uses one tab stop and arrow-key navigation, and exposes
+	 *   selection with `aria-selected`.
+	 * - `toggle-buttons` gives each swatch a tab stop and exposes selection with
+	 *   `aria-pressed`.
+	 * - `command-buttons` gives each swatch a tab stop and exposes no selection
+	 *   state. Use it when swatches run commands such as opening an editor.
+	 *
+	 * @default 'listbox'
+	 */
+	presentation?: 'listbox' | 'toggle-buttons' | 'command-buttons';
+	/**
+	 * Whether the control should present as toggle buttons.
+	 *
+	 * @deprecated Use `presentation="toggle-buttons"` instead. An explicit
+	 * `presentation` takes precedence.
+	 * @default false
+	 * @ignore
+	 */
+	asButtons?: boolean;
+	/**
+	 * Prevents keyboard interaction from wrapping around.
+	 * Only used with the `listbox` presentation.
+	 *
+	 * @default true
+	 */
+	loop?: boolean;
 	/**
 	 * The ID reference list of one or more elements that label the wrapper
 	 * element.
@@ -45,40 +74,16 @@ type WithBaseId = {
 	baseId: string;
 };
 
-type FullListboxCircularOptionPickerProps = CommonCircularOptionPickerProps & {
-	/**
-	 * Whether the control should present as a set of buttons,
-	 * each with its own tab stop.
-	 */
-	asButtons?: false;
-	/**
-	 * Prevents keyboard interaction from wrapping around.
-	 * Only used when `asButtons` is not true.
-	 *
-	 * @default true
-	 */
-	loop?: boolean;
-};
-
 export type ListboxCircularOptionPickerProps = WithBaseId &
-	Omit< FullListboxCircularOptionPickerProps, 'asButtons' >;
-
-type FullButtonsCircularOptionPickerProps = CommonCircularOptionPickerProps & {
-	/**
-	 * Whether the control should present as a set of buttons,
-	 * each with its own tab stop.
-	 *
-	 * @default false
-	 */
-	asButtons: true;
-};
+	Omit< CircularOptionPickerProps, 'asButtons' | 'presentation' >;
 
 export type ButtonsCircularOptionPickerProps = WithBaseId &
-	Omit< FullButtonsCircularOptionPickerProps, 'asButtons' >;
-
-export type CircularOptionPickerProps =
-	| FullListboxCircularOptionPickerProps
-	| FullButtonsCircularOptionPickerProps;
+	Omit< CircularOptionPickerProps, 'asButtons' | 'presentation' | 'loop' > & {
+		presentation: Exclude<
+			NonNullable< CircularOptionPickerProps[ 'presentation' ] >,
+			'listbox'
+		>;
+	};
 
 export type DropdownLinkActionProps = {
 	buttonProps?: Omit<
@@ -116,4 +121,5 @@ export type CircularOptionPickerContextProps = {
 	baseId?: string;
 	activeId?: string | null | undefined;
 	setActiveId?: ( newId: string | null | undefined ) => void;
+	presentation?: CircularOptionPickerProps[ 'presentation' ];
 };

package/src/circular-option-picker/utils.tsx

@@ -1,4 +1,28 @@
 import { __ } from '@wordpress/i18n';
+import deprecated from '@wordpress/deprecated';
+import type { CircularOptionPickerProps } from './types';
+
+export function warnIfCircularOptionPickerAsButtonsIsSet(
+	componentName: string,
+	asButtons?: boolean
+) {
+	if ( asButtons === undefined ) {
+		return;
+	}
+
+	deprecated( `\`asButtons\` prop in wp.components.${ componentName }`, {
+		since: '7.2',
+		alternative: '`presentation`',
+		hint: '`asButtons={ true }` maps to `presentation="toggle-buttons"`. Explicit `presentation` takes precedence.',
+	} );
+}
+
+export function resolveCircularOptionPickerPresentation(
+	presentation?: CircularOptionPickerProps[ 'presentation' ],
+	asButtons?: boolean
+): NonNullable< CircularOptionPickerProps[ 'presentation' ] > {
+	return presentation ?? ( asButtons ? 'toggle-buttons' : 'listbox' );
+}
 
 /**
  * Computes the common props for the CircularOptionPicker.
@@ -7,11 +31,17 @@ export function getComputeCircularOptionPickerCommonProps(
 	asButtons?: boolean,
 	loop?: boolean,
 	ariaLabel?: string,
-	ariaLabelledby?: string
+	ariaLabelledby?: string,
+	presentation?: CircularOptionPickerProps[ 'presentation' ]
 ) {
-	const metaProps = asButtons
-		? { asButtons: true }
-		: { asButtons: false, loop };
+	const resolvedPresentation = resolveCircularOptionPickerPresentation(
+		presentation,
+		asButtons
+	);
+	const metaProps =
+		resolvedPresentation === 'listbox'
+			? { presentation: 'listbox' as const, loop }
+			: { presentation: resolvedPresentation };
 
 	const labelProps = {
 		'aria-labelledby': ariaLabelledby,
@@ -20,5 +50,5 @@ export function getComputeCircularOptionPickerCommonProps(
 			: ariaLabel || __( 'Custom color picker' ),
 	};
 
-	return { metaProps, labelProps };
+	return { metaProps, labelProps, resolvedPresentation };
 }

package/src/clipboard-button/index.tsx

@@ -21,7 +21,7 @@ export default function ClipboardButton( {
 		alternative: 'wp.compose.useCopyToClipboard',
 	} );
 
-	const timeoutIdRef = useRef< NodeJS.Timeout >( undefined );
+	const timeoutIdRef = useRef< ReturnType< typeof setTimeout > >( undefined );
 	const ref = useCopyToClipboard( text, () => {
 		onCopy();
 		if ( timeoutIdRef.current ) {

package/src/color-indicator/test/__snapshots__/{index.tsx.snap → index.jsdom.test.tsx.snap}

@@ -1,6 +1,6 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`ColorIndicator matches the snapshot 1`] = `
+exports[`ColorIndicator > matches the snapshot 1`] = `
 <div>
   <span
     aria-label="sample label"

package/src/color-indicator/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { render } from '@testing-library/react';
 import ColorIndicator from '..';