@wordpress/components 25.7.0 → 25.8.0

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

@@ -0,0 +1,133 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * Internal dependencies
+ */
+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,
+};
+
+function getOption( name: string ) {
+	return screen.getByRole( 'option', { name } );
+}
+
+describe( 'CircularOptionPicker', () => {
+	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();
+		} );
+	} );
+
+	describe( 'when `asButtons` is true', () => {
+		it( 'should render as buttons', async () => {
+			render(
+				<CircularOptionPicker { ...DEFAULT_PROPS } asButtons={ true } />
+			);
+
+			expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
+			expect( screen.queryByRole( 'option' ) ).not.toBeInTheDocument();
+			expect( screen.getByRole( 'button' ) ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'when `loop` is not set', () => {
+		it( 'should loop', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					options={ MULTIPLE_OPTIONS }
+				/>
+			);
+
+			await user.tab();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+			await user.keyboard( '[ArrowRight]' );
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+			await user.keyboard( '[ArrowRight]' );
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+		} );
+	} );
+
+	describe( 'when `loop` is true', () => {
+		it( 'should loop', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					options={ MULTIPLE_OPTIONS }
+					loop={ true }
+				/>
+			);
+
+			await user.tab();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+			await user.keyboard( '[ArrowRight]' );
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+			await user.keyboard( '[ArrowRight]' );
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+		} );
+	} );
+
+	describe( 'when `loop` is false', () => {
+		it( 'should not loop', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					loop={ false }
+					options={ MULTIPLE_OPTIONS }
+				/>
+			);
+
+			await user.tab();
+			expect( getOption( 'Option One' ) ).toHaveFocus();
+			await user.keyboard( '[ArrowRight]' );
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+			await user.keyboard( '[ArrowRight]' );
+			expect( getOption( 'Option Two' ) ).toHaveFocus();
+		} );
+	} );
+} );

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

@@ -14,8 +14,13 @@ import type { Icon } from '@wordpress/icons';
 import type { ButtonAsButtonProps } from '../button/types';
 import type { DropdownProps } from '../dropdown/types';
 import type { WordPressComponentProps } from '../ui/context';
+import type { CompositeState } from '../composite';
 
-export type CircularOptionPickerProps = {
+type CommonCircularOptionPickerProps = {
+	/**
+	 * An ID to apply to the component.
+	 */
+	id?: string;
 	/**
 	 * A CSS class to apply to the wrapper element.
 	 */
@@ -38,6 +43,54 @@ export type CircularOptionPickerProps = {
 	children?: ReactNode;
 };
 
+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;
+} & (
+		| {
+				'aria-label': string;
+				'aria-labelledby'?: never;
+		  }
+		| {
+				'aria-label'?: never;
+				'aria-labelledby': string;
+		  }
+	);
+
+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;
+};
+
+export type ButtonsCircularOptionPickerProps = WithBaseId &
+	Omit< FullButtonsCircularOptionPickerProps, 'asButtons' >;
+
+export type CircularOptionPickerProps =
+	| FullListboxCircularOptionPickerProps
+	| FullButtonsCircularOptionPickerProps;
+
 export type DropdownLinkActionProps = {
 	buttonProps?: Omit<
 		WordPressComponentProps< ButtonAsButtonProps, 'button', false >,
@@ -48,6 +101,11 @@ export type DropdownLinkActionProps = {
 	className?: string;
 };
 
+export type OptionGroupProps = {
+	className?: string;
+	options: ReactNode;
+};
+
 export type OptionProps = Omit<
 	WordPressComponentProps< ButtonAsButtonProps, 'button', false >,
 	'isPressed' | 'className'
@@ -64,3 +122,8 @@ export type OptionProps = Omit<
 		'icon' | 'size'
 	>;
 };
+
+export type CircularOptionPickerCompositeState = CompositeState;
+export type CircularOptionPickerContextProps =
+	| { isComposite?: false; baseId?: string }
+	| ( { isComposite: true } & CircularOptionPickerCompositeState );

package/src/color-palette/README.md

@@ -84,3 +84,17 @@ Currently active value.
 Callback called when a color is selected.
 
 -   Required: Yes
+
+### `asButtons`: `boolean`
+
+Whether the control should present as a set of buttons, each with its own tab stop.
+
+- Required: No
+- Default: `false`
+
+### `loop`: `boolean`
+
+Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+
+- Required: No
+- Default: `true`

package/src/color-palette/index.tsx

@@ -10,6 +10,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
+import { useInstanceId } from '@wordpress/compose';
 import { __, sprintf } from '@wordpress/i18n';
 import { useCallback, useMemo, useState, forwardRef } from '@wordpress/element';
 
@@ -47,7 +48,7 @@ function SinglePalette( {
 	colors,
 	onChange,
 	value,
-	actions,
+	...additionalProps
 }: SinglePaletteProps ) {
 	const colorOptions = useMemo( () => {
 		return colors.map( ( { color, name }, index ) => {
@@ -91,10 +92,10 @@ function SinglePalette( {
 	}, [ colors, value, onChange, clearColor ] );
 
 	return (
-		<CircularOptionPicker
+		<CircularOptionPicker.OptionGroup
 			className={ className }
 			options={ colorOptions }
-			actions={ actions }
+			{ ...additionalProps }
 		/>
 	);
 }
@@ -105,9 +106,10 @@ function MultiplePalettes( {
 	colors,
 	onChange,
 	value,
-	actions,
 	headingLevel,
 }: MultiplePalettesProps ) {
+	const instanceId = useInstanceId( MultiplePalettes, 'color-palette' );
+
 	if ( colors.length === 0 ) {
 		return null;
 	}
@@ -115,9 +117,10 @@ function MultiplePalettes( {
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ colors.map( ( { name, colors: colorPalette }, index ) => {
+				const id = `${ instanceId }-${ index }`;
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading level={ headingLevel }>
+						<ColorHeading id={ id } level={ headingLevel }>
 							{ name }
 						</ColorHeading>
 						<SinglePalette
@@ -127,9 +130,7 @@ function MultiplePalettes( {
 								onChange( newColor, index )
 							}
 							value={ value }
-							actions={
-								colors.length === index + 1 ? actions : null
-							}
+							aria-labelledby={ id }
 						/>
 					</VStack>
 				);
@@ -177,6 +178,8 @@ function UnforwardedColorPalette(
 	forwardedRef: ForwardedRef< any >
 ) {
 	const {
+		asButtons,
+		loop,
 		clearable = true,
 		colors = [],
 		disableCustomColors = false,
@@ -185,7 +188,9 @@ function UnforwardedColorPalette(
 		value,
 		__experimentalIsRenderedInSidebar = false,
 		headingLevel = 2,
-		...otherProps
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledby,
+		...additionalProps
 	} = props;
 	const [ normalizedColorValue, setNormalizedColorValue ] = useState( value );
 
@@ -234,20 +239,47 @@ function UnforwardedColorPalette(
 		: __( 'Custom color picker.' );
 
 	const paletteCommonProps = {
-		clearable,
 		clearColor,
 		onChange,
 		value,
-		actions: !! clearable && (
-			<CircularOptionPicker.ButtonAction onClick={ clearColor }>
-				{ __( 'Clear' ) }
-			</CircularOptionPicker.ButtonAction>
-		),
-		headingLevel,
 	};
 
+	const actions = !! clearable && (
+		<CircularOptionPicker.ButtonAction onClick={ clearColor }>
+			{ __( 'Clear' ) }
+		</CircularOptionPicker.ButtonAction>
+	);
+
+	let metaProps:
+		| { asButtons: false; loop?: boolean; 'aria-label': string }
+		| { asButtons: false; loop?: boolean; 'aria-labelledby': string }
+		| { asButtons: true };
+
+	if ( asButtons ) {
+		metaProps = { asButtons: true };
+	} else {
+		const _metaProps: { asButtons: false; loop?: boolean } = {
+			asButtons: false,
+			loop,
+		};
+
+		if ( ariaLabel ) {
+			metaProps = { ..._metaProps, 'aria-label': ariaLabel };
+		} else if ( ariaLabelledby ) {
+			metaProps = {
+				..._metaProps,
+				'aria-labelledby': ariaLabelledby,
+			};
+		} else {
+			metaProps = {
+				..._metaProps,
+				'aria-label': __( 'Custom color picker.' ),
+			};
+		}
+	}
+
 	return (
-		<VStack spacing={ 3 } ref={ forwardedRef } { ...otherProps }>
+		<VStack spacing={ 3 } ref={ forwardedRef } { ...additionalProps }>
 			{ ! disableCustomColors && (
 				<CustomColorPickerDropdown
 					isRenderedInSidebar={ __experimentalIsRenderedInSidebar }
@@ -298,17 +330,26 @@ function UnforwardedColorPalette(
 					) }
 				/>
 			) }
-			{ hasMultipleColorOrigins ? (
-				<MultiplePalettes
-					{ ...paletteCommonProps }
-					colors={ colors as PaletteObject[] }
-				/>
-			) : (
-				<SinglePalette
-					{ ...paletteCommonProps }
-					colors={ colors as ColorObject[] }
-				/>
-			) }
+			<CircularOptionPicker
+				{ ...metaProps }
+				actions={ actions }
+				options={
+					hasMultipleColorOrigins ? (
+						<MultiplePalettes
+							{ ...paletteCommonProps }
+							headingLevel={ headingLevel }
+							colors={ colors as PaletteObject[] }
+							value={ value }
+						/>
+					) : (
+						<SinglePalette
+							{ ...paletteCommonProps }
+							colors={ colors as ColorObject[] }
+							value={ value }
+						/>
+					)
+				}
+			/>
 		</VStack>
 	);
 }

package/src/color-palette/stories/index.story.tsx

@@ -29,8 +29,12 @@ const meta: Meta< typeof ColorPalette > = {
 };
 export default meta;
 
-const Template: StoryFn< typeof ColorPalette > = ( { onChange, ...args } ) => {
-	const [ color, setColor ] = useState< string | undefined >();
+const Template: StoryFn< typeof ColorPalette > = ( {
+	onChange,
+	value,
+	...args
+} ) => {
+	const [ color, setColor ] = useState< string | undefined >( value );
 
 	return (
 		<ColorPalette
@@ -53,6 +57,16 @@ Default.args = {
 	],
 };
 
+export const InitialValue = Template.bind( {} );
+InitialValue.args = {
+	colors: [
+		{ name: 'Red', color: '#f00' },
+		{ name: 'White', color: '#fff' },
+		{ name: 'Blue', color: '#00f' },
+	],
+	value: '#00f',
+};
+
 export const MultipleOrigins = Template.bind( {} );
 MultipleOrigins.args = {
 	colors: [

package/src/color-palette/test/index.tsx

@@ -19,10 +19,6 @@ const EXAMPLE_COLORS = [
 ];
 const INITIAL_COLOR = EXAMPLE_COLORS[ 0 ].color;
 
-function getWrappingPopoverElement( element: HTMLElement ) {
-	return element.closest( '.components-popover' );
-}
-
 const ControlledColorPalette = ( {
 	onChange,
 }: {
@@ -43,20 +39,6 @@ const ControlledColorPalette = ( {
 };
 
 describe( 'ColorPalette', () => {
-	it( 'should render a dynamic toolbar of colors', () => {
-		const onChange = jest.fn();
-
-		const { container } = render(
-			<ColorPalette
-				colors={ EXAMPLE_COLORS }
-				value={ INITIAL_COLOR }
-				onChange={ onChange }
-			/>
-		);
-
-		expect( container ).toMatchSnapshot();
-	} );
-
 	it( 'should render three color button options', () => {
 		const onChange = jest.fn();
 
@@ -69,7 +51,7 @@ describe( 'ColorPalette', () => {
 		);
 
 		expect(
-			screen.getAllByRole( 'button', { name: /^Color:/ } )
+			screen.getAllByRole( 'option', { name: /^Color:/ } )
 		).toHaveLength( 3 );
 	} );
 
@@ -86,7 +68,7 @@ describe( 'ColorPalette', () => {
 		);
 
 		await user.click(
-			screen.getByRole( 'button', { name: /^Color:/, pressed: true } )
+			screen.getByRole( 'option', { name: /^Color:/, selected: true } )
 		);
 
 		expect( onChange ).toHaveBeenCalledTimes( 1 );
@@ -108,9 +90,9 @@ describe( 'ColorPalette', () => {
 		// Click the first unpressed button
 		// (i.e. a button representing a color that is not the current color)
 		await user.click(
-			screen.getAllByRole( 'button', {
+			screen.getAllByRole( 'option', {
 				name: /^Color:/,
-				pressed: false,
+				selected: false,
 			} )[ 0 ]
 		);
 
@@ -137,10 +119,26 @@ describe( 'ColorPalette', () => {
 		expect( onChange ).toHaveBeenCalledWith( undefined );
 	} );
 
+	it( 'should render custom color picker', () => {
+		const onChange = jest.fn();
+
+		render(
+			<ColorPalette
+				colors={ EXAMPLE_COLORS }
+				value={ INITIAL_COLOR }
+				onChange={ onChange }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', { name: /^Custom color picker\./ } )
+		).toBeInTheDocument();
+	} );
+
 	it( 'should allow disabling custom color picker', () => {
 		const onChange = jest.fn();
 
-		const { container } = render(
+		render(
 			<ColorPalette
 				colors={ EXAMPLE_COLORS }
 				disableCustomColors
@@ -149,7 +147,9 @@ describe( 'ColorPalette', () => {
 			/>
 		);
 
-		expect( container ).toMatchSnapshot();
+		expect(
+			screen.queryByRole( 'button', { name: /^Custom color picker\./ } )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'should render dropdown and its content', async () => {
@@ -188,9 +188,7 @@ describe( 'ColorPalette', () => {
 		const dropdownColorInput = screen.getByLabelText( 'Hex color' );
 
 		await waitFor( () =>
-			expect(
-				getWrappingPopoverElement( dropdownColorInput )
-			).toBePositionedPopover()
+			expect( dropdownColorInput ).toBePositionedPopover()
 		);
 	} );
 
@@ -231,9 +229,9 @@ describe( 'ColorPalette', () => {
 
 		// Click the first unpressed button
 		await user.click(
-			screen.getAllByRole( 'button', {
+			screen.getAllByRole( 'option', {
 				name: /^Color:/,
-				pressed: false,
+				selected: false,
 			} )[ 0 ]
 		);
 
@@ -258,7 +256,11 @@ describe( 'ColorPalette', () => {
 		// Clear the color, confirm that the relative values are cleared/updated.
 		await user.click( screen.getByRole( 'button', { name: 'Clear' } ) );
 		expect( screen.getByText( 'No color selected' ) ).toBeVisible();
-		expect( screen.queryByText( colorName ) ).not.toBeInTheDocument();
+		expect(
+			screen.queryByText( colorName, {
+				selector: '.components-color-palette__custom-color-name',
+			} )
+		).not.toBeInTheDocument();
 		expect( screen.queryByText( colorCode ) ).not.toBeInTheDocument();
 		expect(
 			screen.getByRole( 'button', {

package/src/color-palette/types.ts

@@ -82,10 +82,43 @@ export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
 	 * Currently active value.
 	 */
 	value?: string;
+	/**
+	 * Whether the control should present as a set of buttons,
+	 * each with its own tab stop.
+	 *
+	 * @default false
+	 */
+	asButtons?: boolean;
+	/**
+	 * Prevents keyboard interaction from wrapping around.
+	 * Only used when `asButtons` is not true.
+	 *
+	 * @default true
+	 */
+	loop?: boolean;
 	/**
 	 * Whether this is rendered in the sidebar.
 	 *
 	 * @default false
 	 */
 	__experimentalIsRenderedInSidebar?: boolean;
-};
+} & (
+		| {
+				/**
+				 * A label to identify the purpose of the control.
+				 *
+				 * @todo [#54055] Either this or `aria-labelledby` should be required
+				 */
+				'aria-label'?: string;
+				'aria-labelledby'?: never;
+		  }
+		| {
+				/**
+				 * An ID of an element to provide a label for the control.
+				 *
+				 * @todo [#54055] Either this or `aria-label` should be required
+				 */
+				'aria-labelledby'?: string;
+				'aria-label'?: never;
+		  }
+	);

package/src/combobox-control/index.tsx

@@ -36,16 +36,18 @@ import { useDeprecated36pxDefaultSizeProp } from '../utils/use-deprecated-props'
 
 const noop = () => {};
 
+interface DetectOutsideComponentProps {
+	onFocusOutside: ( event: React.FocusEvent ) => void;
+	children?: React.ReactNode;
+}
+
 const DetectOutside = withFocusOutside(
-	class extends Component {
-		// @ts-expect-error - TODO: Should be resolved when `withFocusOutside` is refactored to TypeScript
-		handleFocusOutside( event ) {
-			// @ts-expect-error - TODO: Should be resolved when `withFocusOutside` is refactored to TypeScript
+	class extends Component< DetectOutsideComponentProps > {
+		handleFocusOutside( event: React.FocusEvent ) {
 			this.props.onFocusOutside( event );
 		}
 
 		render() {
-			// @ts-expect-error - TODO: Should be resolved when `withFocusOutside` is refactored to TypeScript
 			return this.props.children;
 		}
 	}

package/src/composite/{index.js → index.ts}

@@ -17,3 +17,6 @@ export {
 	CompositeItem,
 	useCompositeState,
 } from 'reakit';
+
+/* eslint-disable-next-line no-restricted-imports */
+export type { CompositeStateReturn as CompositeState } from 'reakit';