@wordpress/components 25.6.1 → 25.8.0

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 /**
  * WordPress dependencies
  */
@@ -9,16 +9,27 @@ import { useState, createContext, useContext } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { default as CircularOptionPicker } from '..';
+import CircularOptionPicker from '..';
 
 const CircularOptionPickerStoryContext = createContext< {
 	currentColor?: string;
 	setCurrentColor?: ( v: string | undefined ) => void;
 } >( {} );
 
-const meta: ComponentMeta< typeof CircularOptionPicker > = {
+const meta: Meta< typeof CircularOptionPicker > = {
 	title: 'Components/CircularOptionPicker',
 	component: CircularOptionPicker,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'CircularOptionPicker.Option': CircularOptionPicker.Option,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'CircularOptionPicker.OptionGroup': CircularOptionPicker.OptionGroup,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'CircularOptionPicker.ButtonAction': CircularOptionPicker.ButtonAction,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'CircularOptionPicker.DropdownLinkAction':
+			CircularOptionPicker.DropdownLinkAction,
+	},
 	argTypes: {
 		actions: { control: { type: null } },
 		options: { control: { type: null } },
@@ -95,12 +106,38 @@ const DefaultActions = () => {
 	);
 };
 
-const Template: ComponentStory< typeof CircularOptionPicker > = ( props ) => (
+const Template: StoryFn< typeof CircularOptionPicker > = ( props ) => (
 	<CircularOptionPicker { ...props } />
 );
 
 export const Default = Template.bind( {} );
-Default.args = { options: <DefaultOptions /> };
+Default.args = {
+	'aria-label': 'Circular Option Picker',
+	options: <DefaultOptions />,
+};
+
+export const AsButtons = Template.bind( {} );
+AsButtons.args = {
+	...Default.args,
+	asButtons: true,
+};
+
+export const WithLoopingDisabled = Template.bind( {} );
+WithLoopingDisabled.args = {
+	...Default.args,
+	loop: false,
+};
+WithLoopingDisabled.parameters = {
+	docs: {
+		source: {
+			code: `<CircularOptionPicker
+  aria-label="${ WithLoopingDisabled.args[ 'aria-label' ] }"
+  loop={false}
+  options={<DefaultOptions />}
+/>`,
+		},
+	},
+};
 
 export const WithButtonAction = Template.bind( {} );
 WithButtonAction.args = {

package/src/circular-option-picker/style.scss

@@ -116,14 +116,19 @@ $color-palette-circle-spacing: 12px;
 	&:focus {
 		&::after {
 			content: "";
-			border: #{ $border-width * 2 } solid $gray-700;
-			width: 32px;
-			height: 32px;
-			position: absolute;
-			top: -2px;
-			left: -2px;
 			border-radius: $radius-round;
 			box-shadow: inset 0 0 0 2px $white;
+
+			// Make sure it's always centered
+			position: absolute;
+			top: 50%;
+			left: 50%;
+			transform: translate(-50%, -50%);
+
+			// Make sure dimensions account for border width
+			border: #{ $border-width * 2 } solid $gray-700;
+			width: calc(100% + #{ ( $border-width * 2 ) * 2 });
+			height: calc(100% + #{ ( $border-width * 2 ) * 2 });
 		}
 	}
 
@@ -139,7 +144,6 @@ $color-palette-circle-spacing: 12px;
 	background: $white;
 }
 
-
 .components-circular-option-picker__dropdown-link-action {
 	margin-right: $grid-unit-20;
 

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-indicator/stories/index.story.tsx

@@ -1,14 +1,14 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * Internal dependencies
  */
 import ColorIndicator from '..';
 
-const meta: ComponentMeta< typeof ColorIndicator > = {
+const meta: Meta< typeof ColorIndicator > = {
 	component: ColorIndicator,
 	title: 'Components/ColorIndicator',
 	argTypes: {
@@ -25,13 +25,11 @@ const meta: ComponentMeta< typeof ColorIndicator > = {
 };
 export default meta;
 
-const Template: ComponentStory< typeof ColorIndicator > = ( { ...args } ) => (
+const Template: StoryFn< typeof ColorIndicator > = ( { ...args } ) => (
 	<ColorIndicator { ...args } />
 );
 
-export const Default: ComponentStory< typeof ColorIndicator > = Template.bind(
-	{}
-);
+export const Default: StoryFn< typeof ColorIndicator > = Template.bind( {} );
 Default.args = {
 	colorValue: '#0073aa',
 };

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

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import type { CSSProperties } from 'react';
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -13,10 +13,8 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import ColorPalette from '..';
-import Popover from '../../popover';
-import { Provider as SlotFillProvider } from '../../slot-fill';
 
-const meta: ComponentMeta< typeof ColorPalette > = {
+const meta: Meta< typeof ColorPalette > = {
 	title: 'Components/ColorPalette',
 	component: ColorPalette,
 	argTypes: {
@@ -31,25 +29,22 @@ const meta: ComponentMeta< typeof ColorPalette > = {
 };
 export default meta;
 
-const Template: ComponentStory< typeof ColorPalette > = ( {
+const Template: StoryFn< typeof ColorPalette > = ( {
 	onChange,
+	value,
 	...args
 } ) => {
-	const [ color, setColor ] = useState< string | undefined >();
+	const [ color, setColor ] = useState< string | undefined >( value );
 
 	return (
-		<SlotFillProvider>
-			<ColorPalette
-				{ ...args }
-				value={ color }
-				onChange={ ( newColor ) => {
-					setColor( newColor );
-					onChange?.( newColor );
-				} }
-			/>
-			{ /* @ts-expect-error The 'Slot' component hasn't been typed yet. */ }
-			<Popover.Slot />
-		</SlotFillProvider>
+		<ColorPalette
+			{ ...args }
+			value={ color }
+			onChange={ ( newColor ) => {
+				setColor( newColor );
+				onChange?.( newColor );
+			} }
+		/>
 	);
 };
 
@@ -62,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: [
@@ -84,7 +89,7 @@ MultipleOrigins.args = {
 	],
 };
 
-export const CSSVariables: ComponentStory< typeof ColorPalette > = ( args ) => {
+export const CSSVariables: StoryFn< typeof ColorPalette > = ( args ) => {
 	return (
 		<div
 			style={