@wordpress/components 39.0.0 → 40.0.0

package/src/duotone-picker/stories/duotone-picker.story.tsx

@@ -1,13 +1,16 @@
-import type { Meta, StoryFn } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { fn } from 'storybook/test';
 import { useState } from '@wordpress/element';
 import { DuotonePicker } from '..';
-import type { DuotonePickerProps } from '../types';
 
 const meta: Meta< typeof DuotonePicker > = {
 	title: 'Components/DuotonePicker',
 	component: DuotonePicker,
+	args: {
+		onChange: fn(),
+	},
 	argTypes: {
-		onChange: { action: 'onChange' },
+		selectedSlug: { control: false },
 		value: { control: false },
 	},
 	parameters: {
@@ -21,6 +24,8 @@ const meta: Meta< typeof DuotonePicker > = {
 };
 export default meta;
 
+type DuotonePickerStory = StoryObj< typeof DuotonePicker >;
+
 const DUOTONE_PALETTE = [
 	{
 		colors: [ '#8c00b7', '#fcff41' ],
@@ -34,6 +39,22 @@ const DUOTONE_PALETTE = [
 	},
 ];
 
+// Two presets holding the same colors. Adding duotones with the `+` button in
+// the Global Styles palette editor seeds each one from the palette's darkest
+// and lightest colors, so this is the normal case rather than a contrived one.
+const DUPLICATE_DUOTONE_PALETTE = [
+	{
+		colors: [ '#000000', '#ffffff' ],
+		name: 'Dark background',
+		slug: 'dark-background',
+	},
+	{
+		colors: [ '#000000', '#ffffff' ],
+		name: 'Dark text',
+		slug: 'dark-text',
+	},
+];
+
 const COLOR_PALETTE = [
 	{ color: '#ff4747', name: 'Red', slug: 'red' },
 	{ color: '#fcff41', name: 'Yellow', slug: 'yellow' },
@@ -41,23 +62,50 @@ const COLOR_PALETTE = [
 	{ color: '#8c00b7', name: 'Purple', slug: 'purple' },
 ];
 
-const Template: StoryFn< typeof DuotonePicker > = ( { onChange, ...args } ) => {
-	const [ value, setValue ] = useState< DuotonePickerProps[ 'value' ] >();
-
+const Template = ( {
+	onChange,
+	value,
+	selectedSlug,
+	...props
+}: React.ComponentProps< typeof DuotonePicker > ) => {
+	const [ duotone, setDuotone ] =
+		useState< React.ComponentProps< typeof DuotonePicker >[ 'value' ] >(
+			value
+		);
+	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
 	return (
 		<DuotonePicker
-			{ ...args }
-			onChange={ ( ...changeArgs ) => {
-				setValue( ...changeArgs );
-				onChange( ...changeArgs );
+			{ ...props }
+			value={ duotone }
+			selectedSlug={ slug }
+			onChange={ ( newValue, index, newSlug ) => {
+				setDuotone( newValue );
+				setSlug( newSlug );
+				onChange?.( newValue, index, newSlug );
 			} }
-			value={ value }
 		/>
 	);
 };
 
-export const Default = Template.bind( {} );
-Default.args = {
-	colorPalette: COLOR_PALETTE,
-	duotonePalette: DUOTONE_PALETTE,
+export const Default: DuotonePickerStory = {
+	render: Template,
+	args: {
+		colorPalette: COLOR_PALETTE,
+		duotonePalette: DUOTONE_PALETTE,
+	},
+};
+
+export const DuplicateDuotones: DuotonePickerStory = {
+	render: Template,
+	args: {
+		colorPalette: COLOR_PALETTE,
+		duotonePalette: DUPLICATE_DUOTONE_PALETTE,
+	},
+	parameters: {
+		docs: {
+			description: {
+				story: 'Two presets can hold the same pair of colors. Selection is tracked by slug, so picking one marks only that preset rather than both.',
+			},
+		},
+	},
 };

package/src/duotone-picker/test/custom-duotone-bar.tsx

@@ -0,0 +1,114 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import CustomDuotoneBar from '../custom-duotone-bar';
+
+const VALUE = [ '#000000', '#ffffff' ];
+
+describe( 'CustomDuotoneBar', () => {
+	it( 'does not offer to reposition control points, since a duotone has no positions to save', () => {
+		render( <CustomDuotoneBar value={ VALUE } onChange={ jest.fn() } /> );
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+
+		expect( firstPoint ).toHaveAccessibleDescription(
+			'Press the button to change the color.'
+		);
+		expect(
+			screen.queryByText( /change the gradient position/ )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'ignores arrow keys on a control point', async () => {
+		const user = userEvent.setup();
+		const onChange = jest.fn();
+
+		render( <CustomDuotoneBar value={ VALUE } onChange={ onChange } /> );
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+		firstPoint.focus();
+		await user.keyboard( '[ArrowRight][ArrowRight][ArrowLeft]' );
+
+		expect( onChange ).not.toHaveBeenCalled();
+	} );
+
+	it( 'ignores dragging a control point', () => {
+		const onChange = jest.fn();
+
+		render( <CustomDuotoneBar value={ VALUE } onChange={ onChange } /> );
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+
+		fireEvent.mouseDown( firstPoint );
+		fireEvent.mouseMove( window, { clientX: 50 } );
+		fireEvent.mouseUp( window );
+
+		expect( onChange ).not.toHaveBeenCalled();
+	} );
+
+	// The point cannot move, but the keys still have to be consumed. Letting
+	// them bubble would move focus out of the control, which is what the
+	// gradient bar's own `stopPropagation` guards against.
+	it( 'does not let arrow keys bubble out of the control', async () => {
+		const user = userEvent.setup();
+		const onAncestorKeyDown = jest.fn();
+
+		render(
+			// eslint-disable-next-line jsx-a11y/no-static-element-interactions
+			<div onKeyDown={ onAncestorKeyDown }>
+				<CustomDuotoneBar value={ VALUE } onChange={ jest.fn() } />
+			</div>
+		);
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+		firstPoint.focus();
+		await user.keyboard( '[ArrowLeft][ArrowRight]' );
+
+		expect( onAncestorKeyDown ).not.toHaveBeenCalled();
+	} );
+
+	// Disabling positioning must not disable the one thing a duotone control
+	// point can still do.
+	it( 'still opens the color picker when a control point is clicked', async () => {
+		const user = userEvent.setup();
+
+		render( <CustomDuotoneBar value={ VALUE } onChange={ jest.fn() } /> );
+
+		await user.click(
+			screen.getAllByRole( 'button', {
+				name: /Gradient control point/,
+			} )[ 0 ]
+		);
+
+		expect(
+			await screen.findByRole( 'slider', { name: 'Color' } )
+		).toBeVisible();
+	} );
+
+	it( 'still lets other keys bubble', async () => {
+		const user = userEvent.setup();
+		const onAncestorKeyDown = jest.fn();
+
+		render(
+			// eslint-disable-next-line jsx-a11y/no-static-element-interactions
+			<div onKeyDown={ onAncestorKeyDown }>
+				<CustomDuotoneBar value={ VALUE } onChange={ jest.fn() } />
+			</div>
+		);
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+		firstPoint.focus();
+		await user.keyboard( '[Escape]' );
+
+		expect( onAncestorKeyDown ).toHaveBeenCalled();
+	} );
+} );

package/src/duotone-picker/test/index.tsx

@@ -0,0 +1,346 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useState } from '@wordpress/element';
+import { DuotonePicker } from '..';
+import type { DuotonePickerProps } from '../types';
+
+const COLORS_A = [ '#000000', '#ffffff' ];
+const COLORS_B = [ '#8c00b7', '#fcff41' ];
+
+// Adding two duotones with the `+` button in the Global Styles palette editor
+// seeds both from the palette's darkest and lightest colors, so two presets
+// holding the same pair is the normal case rather than a contrived one.
+const DUPLICATE_DUOTONES = [
+	{ name: 'Dark Background', slug: 'dark-background', colors: COLORS_A },
+	{ name: 'Dark Text', slug: 'dark-text', colors: COLORS_A },
+];
+
+const COLOR_PALETTE = [
+	{ color: '#000000', name: 'Black', slug: 'black' },
+	{ color: '#ffffff', name: 'White', slug: 'white' },
+];
+
+describe( 'DuotonePicker', () => {
+	it( 'should use matching values only for display in command button presentation', async () => {
+		const user = userEvent.setup();
+		const onChange = jest.fn();
+		render(
+			<DuotonePicker
+				aria-label="Duotones"
+				duotonePalette={ DUPLICATE_DUOTONES }
+				colorPalette={ COLOR_PALETTE }
+				value={ COLORS_A }
+				selectedSlug="dark-background"
+				onChange={ onChange }
+				presentation="command-buttons"
+				unsetable={ false }
+				clearable={ false }
+				disableCustomDuotone
+				disableCustomColors
+			/>
+		);
+
+		const duotone = screen.getByRole( 'button', {
+			name: 'Duotone: Dark Background',
+		} );
+		expect(
+			screen.getByRole( 'group', { name: 'Duotones' } )
+		).toBeVisible();
+		expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
+		expect( duotone ).not.toHaveAttribute( 'aria-pressed' );
+
+		await user.click( duotone );
+		expect( onChange ).toHaveBeenCalledWith(
+			COLORS_A,
+			0,
+			'dark-background'
+		);
+	} );
+
+	it( 'should warn for asButtons and prefer an explicit presentation', () => {
+		render(
+			<DuotonePicker
+				aria-label="Duotones"
+				duotonePalette={ DUPLICATE_DUOTONES }
+				colorPalette={ COLOR_PALETTE }
+				onChange={ jest.fn() }
+				asButtons={ false }
+				presentation="command-buttons"
+				disableCustomDuotone
+				disableCustomColors
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Duotone: Dark Background',
+			} )
+		).not.toHaveAttribute( 'aria-pressed' );
+		expect( console ).toHaveWarnedWith(
+			'`asButtons` prop in wp.components.DuotonePicker is deprecated since version 7.2. Please use `presentation` instead. Note: `asButtons={ true }` maps to `presentation="toggle-buttons"`. Explicit `presentation` takes precedence.'
+		);
+	} );
+
+	it( 'should preserve asButtons as a toggle-button alias', () => {
+		render(
+			<DuotonePicker
+				aria-label="Duotones"
+				duotonePalette={ DUPLICATE_DUOTONES }
+				colorPalette={ COLOR_PALETTE }
+				value={ COLORS_A }
+				selectedSlug="dark-background"
+				onChange={ jest.fn() }
+				asButtons
+				unsetable={ false }
+				clearable={ false }
+				disableCustomDuotone
+				disableCustomColors
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Duotone: Dark Background',
+				pressed: true,
+			} )
+		).toBeVisible();
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Duotone: Dark Text',
+				pressed: false,
+			} )
+		).toBeVisible();
+	} );
+
+	describe( 'duplicate duotones in palette', () => {
+		it( 'should render all swatches even when two entries share the same colors', () => {
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ DUPLICATE_DUOTONES }
+					colorPalette={ COLOR_PALETTE }
+					value={ undefined }
+					onChange={ jest.fn() }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			expect( screen.getAllByRole( 'option' ) ).toHaveLength( 3 );
+		} );
+
+		it( 'should select by slug when selectedSlug is provided, marking only the matching entry', () => {
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ DUPLICATE_DUOTONES }
+					colorPalette={ COLOR_PALETTE }
+					value={ COLORS_A }
+					selectedSlug="dark-text"
+					onChange={ jest.fn() }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			// "dark-background" is index 0, "dark-text" is index 1.
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'false' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should fall back to value selection and mark all matching duplicates when no selectedSlug is provided', () => {
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ DUPLICATE_DUOTONES }
+					colorPalette={ COLOR_PALETTE }
+					value={ COLORS_A }
+					onChange={ jest.fn() }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should treat an empty-string selectedSlug as no slug and fall back to value selection', () => {
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ DUPLICATE_DUOTONES }
+					colorPalette={ COLOR_PALETTE }
+					value={ COLORS_A }
+					selectedSlug=""
+					onChange={ jest.fn() }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'true' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+
+		it( 'should pass index and slug to onChange when a swatch is clicked', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ DUPLICATE_DUOTONES }
+					colorPalette={ COLOR_PALETTE }
+					value={ undefined }
+					onChange={ onChange }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			await user.click(
+				screen.getByRole( 'option', { name: 'Duotone: Dark Text' } )
+			);
+
+			expect( onChange ).toHaveBeenCalledWith( COLORS_A, 1, 'dark-text' );
+		} );
+
+		it( 'should clear only the selected preset, identified by slug', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ DUPLICATE_DUOTONES }
+					colorPalette={ COLOR_PALETTE }
+					value={ COLORS_A }
+					selectedSlug="dark-text"
+					onChange={ onChange }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			// The unselected twin must still report its own identity rather
+			// than clearing, which is what happens when selection is decided
+			// by color alone.
+			await user.click(
+				screen.getByRole( 'option', {
+					name: 'Duotone: Dark Background',
+				} )
+			);
+
+			expect( onChange ).toHaveBeenCalledWith(
+				COLORS_A,
+				0,
+				'dark-background'
+			);
+		} );
+	} );
+
+	describe( 'controlled usage', () => {
+		// Mirrors how a consumer wires the picker up: value and slug both held
+		// in state and fed back in.
+		function Controlled( {
+			duotonePalette,
+		}: Pick< DuotonePickerProps, 'duotonePalette' > ) {
+			const [ value, setValue ] =
+				useState< DuotonePickerProps[ 'value' ] >();
+			const [ slug, setSlug ] = useState< string | undefined >();
+			return (
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ duotonePalette }
+					colorPalette={ COLOR_PALETTE }
+					value={ value }
+					selectedSlug={ slug }
+					onChange={ ( newValue, index, newSlug ) => {
+						setValue( newValue );
+						setSlug( newSlug );
+					} }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+		}
+
+		it( 'should clear both the value and the selected state when the selected preset is clicked again', async () => {
+			const user = userEvent.setup();
+			render( <Controlled duotonePalette={ DUPLICATE_DUOTONES } /> );
+
+			const option = () =>
+				screen.getByRole( 'option', { name: 'Duotone: Dark Text' } );
+
+			await user.click( option() );
+			expect( option() ).toHaveAttribute( 'aria-selected', 'true' );
+
+			// Clicking it again deselects. If the slug were reported back on
+			// deselection, the swatch would stay selected with no value.
+			await user.click( option() );
+			expect( option() ).toHaveAttribute( 'aria-selected', 'false' );
+			expect(
+				screen.getByRole( 'option', {
+					name: 'Duotone: Dark Background',
+				} )
+			).toHaveAttribute( 'aria-selected', 'false' );
+		} );
+
+		it( 'should move the selection when a different preset is clicked', async () => {
+			const user = userEvent.setup();
+			render( <Controlled duotonePalette={ DUPLICATE_DUOTONES } /> );
+
+			await user.click(
+				screen.getByRole( 'option', { name: 'Duotone: Dark Text' } )
+			);
+			await user.click(
+				screen.getByRole( 'option', {
+					name: 'Duotone: Dark Background',
+				} )
+			);
+
+			expect(
+				screen.getByRole( 'option', {
+					name: 'Duotone: Dark Background',
+				} )
+			).toHaveAttribute( 'aria-selected', 'true' );
+			expect(
+				screen.getByRole( 'option', { name: 'Duotone: Dark Text' } )
+			).toHaveAttribute( 'aria-selected', 'false' );
+		} );
+	} );
+
+	describe( 'distinct duotones', () => {
+		it( 'should mark the preset matching value as selected', () => {
+			render(
+				<DuotonePicker
+					aria-label="Duotone"
+					duotonePalette={ [
+						{ name: 'A', slug: 'a', colors: COLORS_A },
+						{ name: 'B', slug: 'b', colors: COLORS_B },
+					] }
+					colorPalette={ COLOR_PALETTE }
+					value={ COLORS_B }
+					onChange={ jest.fn() }
+					unsetable={ false }
+					disableCustomDuotone
+					disableCustomColors
+				/>
+			);
+
+			const options = screen.getAllByRole( 'option' );
+			expect( options[ 0 ] ).toHaveAttribute( 'aria-selected', 'false' );
+			expect( options[ 1 ] ).toHaveAttribute( 'aria-selected', 'true' );
+		} );
+	} );
+} );

package/src/duotone-picker/types.ts

@@ -1,3 +1,5 @@
+import type { CircularOptionPickerProps } from '../circular-option-picker/types';
+
 export type DuotonePickerProps = {
 	/**
 	 * Whether there should be a button to clear the duotone value.
@@ -35,20 +37,62 @@ export type DuotonePickerProps = {
 	 * An array of colors for the duotone effect.
 	 */
 	value?: string[] | 'unset';
+	/**
+	 * The slug of the selected duotone preset. When a non-empty `selectedSlug`
+	 * is provided, selection is decided strictly by slug, which keeps two
+	 * presets holding the same pair of colors apart. Presets whose slug does
+	 * not match will not appear selected in this mode, even if their colors
+	 * match `value`.
+	 *
+	 * An empty string is treated the same as `undefined`: selection falls back
+	 * to matching by color value.
+	 */
+	selectedSlug?: string;
 	/**
 	 * Callback which is called when the duotone colors change.
+	 *
+	 * When the change comes from picking a preset out of `duotonePalette`, the
+	 * preset's index and slug are passed too. Two presets can hold the same
+	 * pair of colors, so the value alone does not identify which one was
+	 * picked.
+	 *
+	 * Both are omitted whenever no preset is being picked: the custom, unset
+	 * and clear controls, and deselecting the currently selected preset, which
+	 * reports `undefined` alone.
+	 */
+	onChange: (
+		value: DuotonePickerProps[ 'value' ] | undefined,
+		index?: number,
+		slug?: string
+	) => void;
+	/**
+	 * How predefined duotone 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. `value` and `selectedSlug` do not mark predefined swatches as
+	 *   selected, and activating a swatch always calls `onChange` with that
+	 *   swatch.
+	 *
+	 * @default 'listbox'
 	 */
-	onChange: ( value: DuotonePickerProps[ 'value' ] | undefined ) => void;
+	presentation?: CircularOptionPickerProps[ 'presentation' ];
 	/**
-	 * Whether the control should present as a set of buttons,
-	 * each with its own tab stop.
+	 * 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 when `asButtons` is not true.
+	 * Only used with the `listbox` presentation.
 	 *
 	 * @default true
 	 */

package/src/focal-point-picker/index.tsx

@@ -233,7 +233,6 @@ export function FocalPointPicker( {
 	};
 
 	const classes = clsx( 'components-focal-point-picker-control', className );
-	const Label = hideLabelFromVision ? VisuallyHidden : StyledLabel;
 
 	useUpdateEffect( () => {
 		setShowGridOverlay( true );
@@ -246,7 +245,12 @@ export function FocalPointPicker( {
 
 	return (
 		<Container { ...restProps } as="fieldset" className={ classes }>
-			{ !! label && <Label as="legend">{ label }</Label> }
+			{ !! label &&
+				( hideLabelFromVision ? (
+					<VisuallyHidden as="legend">{ label }</VisuallyHidden>
+				) : (
+					<StyledLabel as="legend">{ label }</StyledLabel>
+				) ) }
 			<MediaWrapper className="components-focal-point-picker-wrapper">
 				<MediaContainer
 					className="components-focal-point-picker"