@wordpress/components 39.0.0 → 40.1.0

package/src/color-palette/README.md

@@ -85,16 +85,20 @@ Callback called when a color is selected.
 
 -   Required: Yes
 
-### `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 predefined swatches' interaction and accessibility semantics.
 
-- Required: No
-- Default: `false`
+-   `listbox` uses one tab stop for the palette. 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. The `value` and `selectedSlug` props do not mark predefined swatches as selected, and activating a swatch always calls `onChange` with that swatch. The `value` prop still controls the custom color picker.
+
+-   Required: No
+-   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`
+-   Required: No
+-   Default: `true`

package/src/color-palette/index.tsx

@@ -10,11 +10,13 @@ import Dropdown from '../dropdown';
 import { ColorPicker } from '../color-picker';
 import CircularOptionPicker, {
 	getComputeCircularOptionPickerCommonProps,
+	warnIfCircularOptionPickerAsButtonsIsSet,
 } from '../circular-option-picker';
 import { VStack } from '../v-stack';
 import { Truncate } from '../truncate';
-import { ColorHeading } from './styles';
+import { Heading } from '../heading';
 import DropdownContentWrapper from '../dropdown/dropdown-content-wrapper';
+import styles from './style.module.scss';
 import type {
 	ColorObject,
 	ColorPaletteProps,
@@ -40,6 +42,7 @@ function SinglePalette( {
 	onChange,
 	value,
 	selectedSlug,
+	presentation,
 	...additionalProps
 }: SinglePaletteProps ) {
 	const colorOptions = useMemo( () => {
@@ -51,9 +54,9 @@ function SinglePalette( {
 			// This correctly handles mixed palettes where some entries have slugs
 			// and others don't. Fall back to color value matching otherwise
 			// (including when selectedSlug is an empty string).
-			const isSelected = selectedSlug
-				? slug === selectedSlug
-				: value === color;
+			const isSelected =
+				presentation !== 'command-buttons' &&
+				( selectedSlug ? slug === selectedSlug : value === color );
 
 			return (
 				<CircularOptionPicker.Option
@@ -62,7 +65,7 @@ function SinglePalette( {
 					selectedIconProps={
 						isSelected
 							? {
-									fill:
+									color:
 										colordColor.contrast() >
 										colordColor.contrast( '#000' )
 											? '#fff'
@@ -84,7 +87,7 @@ function SinglePalette( {
 				/>
 			);
 		} );
-	}, [ colors, value, selectedSlug, onChange, clearColor ] );
+	}, [ colors, value, selectedSlug, onChange, clearColor, presentation ] );
 
 	return (
 		<CircularOptionPicker.OptionGroup
@@ -103,6 +106,7 @@ function MultiplePalettes( {
 	value,
 	selectedSlug,
 	headingLevel,
+	presentation,
 }: MultiplePalettesProps ) {
 	const instanceId = useInstanceId( MultiplePalettes, 'color-palette' );
 
@@ -116,9 +120,13 @@ function MultiplePalettes( {
 				const id = `${ instanceId }-${ index }`;
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading id={ id } level={ headingLevel }>
+						<Heading
+							className={ styles[ 'color-heading' ] }
+							id={ id }
+							level={ headingLevel }
+						>
 							{ name }
-						</ColorHeading>
+						</Heading>
 						<SinglePalette
 							clearColor={ clearColor }
 							colors={ colorPalette }
@@ -127,6 +135,7 @@ function MultiplePalettes( {
 							}
 							value={ value }
 							selectedSlug={ selectedSlug }
+							presentation={ presentation }
 							aria-labelledby={ id }
 						/>
 					</VStack>
@@ -180,6 +189,7 @@ function UnforwardedColorPalette(
 ) {
 	const {
 		asButtons,
+		presentation,
 		loop,
 		clearable = true,
 		colors = [],
@@ -194,6 +204,7 @@ function UnforwardedColorPalette(
 		'aria-labelledby': ariaLabelledby,
 		...additionalProps
 	} = props;
+	warnIfCircularOptionPickerAsButtonsIsSet( 'ColorPalette', asButtons );
 	const [ normalizedColorValue, setNormalizedColorValue ] = useState( value );
 
 	const clearColor = useCallback( () => onChange( undefined ), [ onChange ] );
@@ -241,11 +252,21 @@ function UnforwardedColorPalette(
 		  )
 		: __( 'Custom color picker' );
 
+	const { metaProps, labelProps, resolvedPresentation } =
+		getComputeCircularOptionPickerCommonProps(
+			asButtons,
+			loop,
+			ariaLabel,
+			ariaLabelledby,
+			presentation
+		);
+
 	const paletteCommonProps = {
 		clearColor,
 		onChange,
 		value,
 		selectedSlug,
+		presentation: resolvedPresentation,
 	};
 
 	const actions = !! clearable && (
@@ -258,13 +279,6 @@ function UnforwardedColorPalette(
 		</CircularOptionPicker.ButtonAction>
 	);
 
-	const { metaProps, labelProps } = getComputeCircularOptionPickerCommonProps(
-		asButtons,
-		loop,
-		ariaLabel,
-		ariaLabelledby
-	);
-
 	// If disableCustomColors is true and colors.length is 0, return null to avoid rendering an empty palette wrapper.
 	if ( disableCustomColors && colors.length === 0 && ! actions ) {
 		return null;

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

@@ -73,6 +73,11 @@ export const InitialValue: ColorPaletteStory = {
 };
 
 export const MultipleOrigins: ColorPaletteStory = {
+	parameters: {
+		// FIXME: Multiple Origins: origin groups are missing required ARIA children (aria-required-children).
+		// See: https://github.com/WordPress/gutenberg/issues/81596
+		a11y: { test: 'todo' },
+	},
 	render: Template,
 	args: {
 		colors: [

package/src/color-palette/style.module.scss

@@ -0,0 +1,12 @@
+.color-heading {
+	text-transform: uppercase;
+
+	// Triple specificity to override the base Heading styles, matching the
+	// pre-migration Emotion `&&&` behavior. Dart Sass disallows `&&&`, so the
+	// selector is repeated via interpolation to produce the same specificity.
+	&#{&}#{&} {
+		font-size: 11px;
+		line-height: 24px;
+		margin-bottom: 0;
+	}
+}

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

@@ -1,13 +1,20 @@
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useState } from '@wordpress/element';
 import ColorPalette from '..';
 
+globalThis.wpVitest.mockMatchMedia();
+
 const EXAMPLE_COLORS = [
 	{ name: 'red', color: '#f00' },
 	{ name: 'green', color: '#0f0' },
 	{ name: 'blue', color: '#00f' },
 ];
+const DUPLICATE_COLOR_PALETTE = [
+	{ name: 'Dark Background', slug: 'dark-background', color: '#000' },
+	{ name: 'Dark Text', slug: 'dark-text', color: '#000' },
+];
 const INITIAL_COLOR = EXAMPLE_COLORS[ 0 ].color;
 
 const ControlledColorPalette = ( {
@@ -30,8 +37,84 @@ const ControlledColorPalette = ( {
 };
 
 describe( 'ColorPalette', () => {
+	it( 'should use matching values only for display in command button presentation', async () => {
+		const user = userEvent.setup();
+		const onChange = vi.fn();
+		render(
+			<ColorPalette
+				aria-label="Colors"
+				colors={ DUPLICATE_COLOR_PALETTE }
+				value="#000"
+				selectedSlug="dark-background"
+				onChange={ onChange }
+				presentation="command-buttons"
+				disableCustomColors
+				clearable={ false }
+			/>
+		);
+
+		const darkBackground = screen.getByRole( 'button', {
+			name: 'Dark Background',
+		} );
+		expect( screen.getByRole( 'group', { name: 'Colors' } ) ).toBeVisible();
+		expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
+		expect( darkBackground ).not.toHaveAttribute( 'aria-pressed' );
+
+		await user.click( darkBackground );
+		expect( onChange ).toHaveBeenCalledWith( '#000', 0, 'dark-background' );
+	} );
+
+	it( 'should warn for asButtons and prefer an explicit presentation', () => {
+		render(
+			<ColorPalette
+				aria-label="Colors"
+				colors={ EXAMPLE_COLORS }
+				onChange={ vi.fn() }
+				asButtons={ false }
+				presentation="command-buttons"
+				disableCustomColors
+				clearable={ false }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', { name: 'red' } )
+		).not.toHaveAttribute( 'aria-pressed' );
+		expect( console ).toHaveWarnedWith(
+			'`asButtons` prop in wp.components.ColorPalette 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(
+			<ColorPalette
+				aria-label="Colors"
+				colors={ DUPLICATE_COLOR_PALETTE }
+				value="#000"
+				selectedSlug="dark-background"
+				onChange={ vi.fn() }
+				asButtons
+				disableCustomColors
+				clearable={ false }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Dark Background',
+				pressed: true,
+			} )
+		).toBeVisible();
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Dark Text',
+				pressed: false,
+			} )
+		).toBeVisible();
+	} );
+
 	it( 'should render three color button options', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -46,7 +129,7 @@ describe( 'ColorPalette', () => {
 
 	it( 'should call onClick on an active button with undefined', async () => {
 		const user = userEvent.setup();
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -64,7 +147,7 @@ describe( 'ColorPalette', () => {
 
 	it( 'should call onClick on an inactive button', async () => {
 		const user = userEvent.setup();
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -93,7 +176,7 @@ describe( 'ColorPalette', () => {
 
 	it( 'should call onClick with undefined, when the clearButton onClick is triggered', async () => {
 		const user = userEvent.setup();
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -110,7 +193,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should render custom color picker', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -126,7 +209,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should allow disabling custom color picker', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -143,7 +226,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should render nothing when custom colors are disabled, there are no colors, and it is not clearable', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 		const { container } = render(
 			<ColorPalette
 				colors={ [] }
@@ -158,7 +241,7 @@ describe( 'ColorPalette', () => {
 
 	it( 'should render dropdown and its content', async () => {
 		const user = userEvent.setup();
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -197,7 +280,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should show the clear button by default', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -213,7 +296,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should show the clear button even when `colors` is an empty array', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render( <ColorPalette colors={ [] } onChange={ onChange } /> );
 
@@ -223,7 +306,7 @@ describe( 'ColorPalette', () => {
 	} );
 
 	it( 'should still show the clear button when colors is empty and custom colors are disabled', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render(
 			<ColorPalette
@@ -289,17 +372,12 @@ describe( 'ColorPalette', () => {
 	} );
 
 	describe( 'duplicate colors in palette', () => {
-		const DUPLICATE_COLOR_PALETTE = [
-			{ name: 'Dark Background', slug: 'dark-background', color: '#000' },
-			{ name: 'Dark Text', slug: 'dark-text', color: '#000' },
-		];
-
 		it( 'should render all swatches even when two entries share the same color value', () => {
 			render(
 				<ColorPalette
 					colors={ DUPLICATE_COLOR_PALETTE }
 					value={ undefined }
-					onChange={ jest.fn() }
+					onChange={ vi.fn() }
 				/>
 			);
 
@@ -312,7 +390,7 @@ describe( 'ColorPalette', () => {
 					colors={ DUPLICATE_COLOR_PALETTE }
 					value="#000"
 					selectedSlug="dark-text"
-					onChange={ jest.fn() }
+					onChange={ vi.fn() }
 				/>
 			);
 
@@ -328,7 +406,7 @@ describe( 'ColorPalette', () => {
 				<ColorPalette
 					colors={ DUPLICATE_COLOR_PALETTE }
 					value="#000"
-					onChange={ jest.fn() }
+					onChange={ vi.fn() }
 				/>
 			);
 
@@ -345,7 +423,7 @@ describe( 'ColorPalette', () => {
 					colors={ DUPLICATE_COLOR_PALETTE }
 					value="#000"
 					selectedSlug=""
-					onChange={ jest.fn() }
+					onChange={ vi.fn() }
 				/>
 			);
 
@@ -360,7 +438,7 @@ describe( 'ColorPalette', () => {
 					colors={ DUPLICATE_COLOR_PALETTE }
 					value="#000"
 					selectedSlug="dark-text"
-					onChange={ jest.fn() }
+					onChange={ vi.fn() }
 				/>
 			);
 
@@ -373,7 +451,7 @@ describe( 'ColorPalette', () => {
 
 		it( 'should pass slug as third argument to onChange when a swatch is clicked', async () => {
 			const user = userEvent.setup();
-			const onChange = jest.fn();
+			const onChange = vi.fn();
 
 			render(
 				<ColorPalette
@@ -391,7 +469,7 @@ describe( 'ColorPalette', () => {
 
 		it( 'should clear the selection when the selected swatch is clicked', async () => {
 			const user = userEvent.setup();
-			const onChange = jest.fn();
+			const onChange = vi.fn();
 
 			render(
 				<ColorPalette
@@ -421,7 +499,7 @@ describe( 'ColorPalette', () => {
 					colors={ MIXED_PALETTE }
 					value="#fff"
 					selectedSlug="brand-white"
-					onChange={ jest.fn() }
+					onChange={ vi.fn() }
 				/>
 			);
 

package/src/color-palette/test/{utils.ts → utils.jsdom.test.ts}

@@ -1,3 +1,4 @@
+import { describe, expect, test } from 'vitest';
 import {
 	extractColorNameFromCurrentValue,
 	normalizeColorValue,

package/src/color-palette/types.ts

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactNode } from 'react';
 import type { DropdownProps } from '../dropdown/types';
 import type { HeadingSize } from '../heading/types';
+import type { CircularOptionPickerProps } from '../circular-option-picker/types';
 
 export type ColorObject = {
 	name: string;
@@ -36,6 +37,7 @@ type PaletteProps = {
 	selectedSlug?: string;
 	actions?: ReactNode;
 	headingLevel?: HeadingSize;
+	presentation: NonNullable< CircularOptionPickerProps[ 'presentation' ] >;
 };
 
 export type SinglePaletteProps = PaletteProps & {
@@ -93,15 +95,33 @@ export type ColorPaletteProps = Pick<
 	 */
 	value?: string;
 	/**
-	 * Whether the control should present as a set of buttons,
-	 * each with its own tab stop.
+	 * How predefined color 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. `value` still controls the custom color picker.
+	 *
+	 * @default 'listbox'
+	 */
+	presentation?: CircularOptionPickerProps[ 'presentation' ];
+	/**
+	 * 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/color-picker/stories/index.story.tsx

@@ -5,11 +5,6 @@ import { ColorPicker } from '../component';
 const meta: Meta< typeof ColorPicker > = {
 	tags: [ 'manifest' ],
 	component: ColorPicker,
-	// Temporary: Due to an upstream bug, render the root explicitly so the
-	// components manifest extractor can resolve props from the JSX.
-	//
-	// See: https://github.com/storybookjs/storybook/issues/34877
-	render: ( args ) => <ColorPicker { ...args } />,
 	title: 'Components/Selection & Input/Color/ColorPicker',
 	id: 'components-colorpicker',
 	argTypes: {

package/src/combobox-control/README.md

@@ -92,7 +92,7 @@ Function called when the control's search input value changes. The argument cont
 
 Function called when the selected value changes.
 
--   Type: `( value: string | null | undefined ) => void`
+-   Type: `( value: string | null ) => void`
 -   Required: No
 
 #### value

package/src/combobox-control/index.tsx

@@ -11,18 +11,18 @@ import { useInstanceId } from '@wordpress/compose';
 import { speak } from '@wordpress/a11y';
 import { closeSmall } from '@wordpress/icons';
 import { withIgnoreIMEEvents } from '@wordpress/keycodes';
-import { InputWrapperFlex } from './styles';
 import TokenInput from '../form-token-field/token-input';
 import SuggestionsList from '../form-token-field/suggestions-list';
 import BaseControl from '../base-control';
 import Button from '../button';
-import { FlexBlock } from '../flex';
+import { Flex, FlexBlock } from '../flex';
 import withFocusOutside from '../higher-order/with-focus-outside';
 import { useControlledValue } from '../utils/hooks';
 import { normalizeTextString } from '../utils/strings';
 import type { ComboboxControlOption, ComboboxControlProps } from './types';
 import type { TokenInputProps } from '../form-token-field/types';
 import Spinner from '../spinner';
+import styles from './style.module.scss';
 
 const noop = () => {};
 
@@ -318,7 +318,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 					tabIndex={ -1 }
 					onKeyDown={ onKeyDown }
 				>
-					<InputWrapperFlex>
+					<Flex className={ styles[ 'input-wrapper' ] }>
 						<FlexBlock>
 							<TokenInput
 								className="components-combobox-control__input"
@@ -353,7 +353,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 								label={ __( 'Reset' ) }
 							/>
 						) }
-					</InputWrapperFlex>
+					</Flex>
 					{ isExpanded && ! isLoading && (
 						<SuggestionsList
 							instanceId={ instanceId }

package/src/combobox-control/style.module.scss

@@ -0,0 +1,6 @@
+@use "@wordpress/base-styles/variables" as *;
+
+.input-wrapper {
+	height: 38px; // 40px - 2px vertical borders on parent container
+	padding-inline: $grid-unit-10;
+}

package/src/combobox-control/style.scss

@@ -41,7 +41,7 @@ input.components-combobox-control__input[type="text"] {
 	padding: 0;
 
 	&:focus-within {
-		@include input-style__focus;
+		@include outset-ring__focus;
 	}
 
 	.components-spinner {

package/src/combobox-control/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,9 +1,14 @@
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useState } from '@wordpress/element';
 import _ComboboxControl from '..';
 import type { ComboboxControlOption, ComboboxControlProps } from '../types';
 
+globalThis.wpVitest.mockMatchMedia();
+
+globalThis.wpVitest.mockScrollIntoView();
+
 const timezones = [
 	{ label: 'Greenwich Mean Time', value: 'GMT' },
 	{ label: 'Universal Coordinated Time', value: 'UTC' },
@@ -120,7 +125,7 @@ describe.each( [
 	it( 'should select the correct option via click events', async () => {
 		const user = await userEvent.setup();
 		const targetOption = timezones[ 2 ];
-		const onChangeSpy = jest.fn();
+		const onChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }
@@ -145,7 +150,7 @@ describe.each( [
 		const user = await userEvent.setup();
 		const targetIndex = 4;
 		const targetOption = timezones[ targetIndex ];
-		const onChangeSpy = jest.fn();
+		const onChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }
@@ -173,7 +178,7 @@ describe.each( [
 
 	it( 'calls onFilterValueChange whenever the textbox changes', async () => {
 		const user = userEvent.setup();
-		const onFilterValueChangeSpy = jest.fn();
+		const onFilterValueChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }
@@ -190,7 +195,7 @@ describe.each( [
 
 	it( 'clears the textbox value if there is no selected value on blur', async () => {
 		const user = userEvent.setup();
-		const onFilterValueChangeSpy = jest.fn();
+		const onFilterValueChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }
@@ -214,7 +219,7 @@ describe.each( [
 	it( 'should select the correct option from a search', async () => {
 		const user = await userEvent.setup();
 		const targetOption = timezones[ 13 ];
-		const onChangeSpy = jest.fn();
+		const onChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }
@@ -241,7 +246,7 @@ describe.each( [
 	it( 'should render aria-live announcement upon selection', async () => {
 		const user = await userEvent.setup();
 		const targetOption = timezones[ 9 ];
-		const onChangeSpy = jest.fn();
+		const onChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }
@@ -270,7 +275,7 @@ describe.each( [
 		const user = await userEvent.setup();
 		const unmatchedString = 'Mordor';
 		const targetOption = timezones[ 6 ];
-		const onChangeSpy = jest.fn();
+		const onChangeSpy = vi.fn();
 		render(
 			<Component
 				options={ timezones }