@wordpress/components 39.0.0 → 40.0.0

package/src/confirm-dialog/types.ts

@@ -53,4 +53,15 @@ export type ConfirmDialogProps = {
 	 * Both buttons will be disabled.
 	 */
 	isBusy?: boolean;
+	/**
+	 * The title of the underlying `Modal`: its accessible name, and the
+	 * visible heading unless `__experimentalHideHeader` is `true`.
+	 */
+	title?: ModalProps[ 'title' ];
+	/**
+	 * Whether the underlying `Modal` should hide its header, `title` included.
+	 *
+	 * @default true
+	 */
+	__experimentalHideHeader?: ModalProps[ '__experimentalHideHeader' ];
 };

package/src/content-editable-control/style.module.scss

@@ -7,7 +7,6 @@
 	background: $components-color-background;
 	color: $components-color-foreground;
 	@include input-control;
-	border-color: $components-color-border;
 
 	// `::placeholder` only applies to native form fields, so draw the text
 	// from the `aria-placeholder` attribute while the element has no content.

package/src/context/context-system-provider.js

@@ -1,6 +1,5 @@
 import deepmerge from 'deepmerge';
 import fastDeepEqual from 'fast-deep-equal/es6/index.js';
-// @ts-expect-error https://github.com/jonschlinkert/is-plain-object/pull/47
 import { isPlainObject } from 'is-plain-object';
 import {
 	createContext,

package/src/custom-gradient-picker/gradient-bar/control-points.tsx

@@ -36,6 +36,7 @@ function ControlPointButton( {
 	isOpen,
 	position,
 	color,
+	disablePositioning,
 	...additionalProps
 }: WordPressComponentProps< ControlPointButtonProps, 'button', true > ) {
 	const instanceId = useInstanceId( ControlPointButton );
@@ -64,9 +65,11 @@ function ControlPointButton( {
 				{ ...additionalProps }
 			/>
 			<VisuallyHidden id={ descriptionId }>
-				{ __(
-					'Use your left or right arrow keys or drag and drop with the mouse to change the gradient position. Press the button to change the color or remove the control point.'
-				) }
+				{ disablePositioning
+					? __( 'Press the button to change the color.' )
+					: __(
+							'Use your left or right arrow keys or drag and drop with the mouse to change the gradient position. Press the button to change the color or remove the control point.'
+					  ) }
 			</VisuallyHidden>
 		</>
 	);
@@ -109,6 +112,7 @@ function GradientColorPickerDropdown( {
 function ControlPoints( {
 	disableRemove,
 	disableAlpha,
+	disablePositioning,
 	gradientPickerDomRef,
 	ignoreMarkerPosition,
 	value: controlPoints,
@@ -206,6 +210,9 @@ function ControlPoints( {
 										onToggle();
 									} }
 									onMouseDown={ () => {
+										if ( disablePositioning ) {
+											return;
+										}
 										if (
 											window &&
 											window.addEventListener
@@ -228,6 +235,19 @@ function ControlPoints( {
 										}
 									} }
 									onKeyDown={ ( event ) => {
+										if ( disablePositioning ) {
+											// The point cannot move, but the
+											// arrow keys are still consumed so
+											// they do not bubble away and move
+											// focus to another editor area.
+											if (
+												event.code === 'ArrowLeft' ||
+												event.code === 'ArrowRight'
+											) {
+												event.stopPropagation();
+											}
+											return;
+										}
 										if ( event.code === 'ArrowLeft' ) {
 											// Stop propagation of the key press event to avoid focus moving
 											// to another editor area.
@@ -263,6 +283,7 @@ function ControlPoints( {
 									isOpen={ isOpen }
 									position={ point.position }
 									color={ point.color }
+									disablePositioning={ disablePositioning }
 								/>
 							) }
 							renderContent={ ( { onClose } ) => (

package/src/custom-gradient-picker/gradient-bar/index.tsx

@@ -74,6 +74,7 @@ export default function CustomGradientBar( {
 	onChange,
 	disableInserter = false,
 	disableAlpha = false,
+	disablePositioning = false,
 	__experimentalIsRenderedInSidebar = false,
 }: CustomGradientBarProps ) {
 	const gradientMarkersContainerDomRef = useRef< HTMLDivElement >( null );
@@ -169,6 +170,7 @@ export default function CustomGradientBar( {
 					}
 					disableAlpha={ disableAlpha }
 					disableRemove={ disableInserter }
+					disablePositioning={ disablePositioning }
 					gradientPickerDomRef={ gradientMarkersContainerDomRef }
 					ignoreMarkerPosition={
 						isInsertingControlPoint

package/src/custom-gradient-picker/test/index.tsx

@@ -2,6 +2,8 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useState } from '@wordpress/element';
 import CustomGradientPicker from '../';
+import CustomGradientBar from '../gradient-bar';
+import { KEYBOARD_CONTROL_POINT_VARIATION } from '../gradient-bar/constants';
 
 function ControlledCustomGradientPicker( {
 	initialValue = 'linear-gradient(90deg,rgb(0,0,0) 0%,rgb(255,255,255) 100%)',
@@ -178,3 +180,135 @@ describe( 'CustomGradientPicker', () => {
 		} );
 	} );
 } );
+
+describe( 'CustomGradientBar', () => {
+	const POINTS = [
+		{ position: 0, color: 'rgb(0,0,0)' },
+		{ position: 100, color: 'rgb(255,255,255)' },
+	];
+
+	// The counterpart to the duotone bar's tests: positioning is on unless a
+	// consumer opts out, so arrow keys must still move a control point.
+	it( 'moves a control point with the arrow keys', async () => {
+		const user = userEvent.setup();
+		const onChange = jest.fn();
+
+		render(
+			<CustomGradientBar
+				background="linear-gradient(90deg,rgb(0,0,0) 0%,rgb(255,255,255) 100%)"
+				hasGradient
+				value={ POINTS }
+				onChange={ onChange }
+			/>
+		);
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+
+		// The description still offers positioning and removal, which the
+		// duotone bar's shorter one drops.
+		expect( firstPoint ).toHaveAccessibleDescription(
+			/change the gradient position.+remove the control point/
+		);
+
+		firstPoint.focus();
+		await user.keyboard( '[ArrowRight]' );
+
+		expect( onChange ).toHaveBeenCalledWith( [
+			{ position: KEYBOARD_CONTROL_POINT_VARIATION, color: 'rgb(0,0,0)' },
+			POINTS[ 1 ],
+		] );
+	} );
+
+	// Dragging is driven by window-level listeners attached on mousedown, and
+	// the position comes from the markers container's box, so that has to be
+	// given one in jsdom.
+	it( 'moves a control point when dragged', () => {
+		const onChange = jest.fn();
+
+		const { container } = render(
+			<CustomGradientBar
+				background="linear-gradient(90deg,rgb(0,0,0) 0%,rgb(255,255,255) 100%)"
+				hasGradient
+				value={ POINTS }
+				onChange={ onChange }
+			/>
+		);
+
+		// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+		const markers = container.querySelector(
+			'.components-custom-gradient-picker__markers-container'
+		) as HTMLElement;
+		markers.getBoundingClientRect = () =>
+			( { x: 0, width: 200 } ) as DOMRect;
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+
+		fireEvent.mouseDown( firstPoint );
+		fireEvent.mouseMove( window, { clientX: 100 } );
+		fireEvent.mouseUp( window );
+
+		// 100px into a 200px container is 50%.
+		expect( onChange ).toHaveBeenCalledWith( [
+			{ position: 50, color: 'rgb(0,0,0)' },
+			POINTS[ 1 ],
+		] );
+	} );
+
+	it( 'does not move a control point when dragged and positioning is disabled', () => {
+		const onChange = jest.fn();
+
+		const { container } = render(
+			<CustomGradientBar
+				background="linear-gradient(90deg,rgb(0,0,0) 0%,rgb(255,255,255) 100%)"
+				hasGradient
+				disablePositioning
+				value={ POINTS }
+				onChange={ onChange }
+			/>
+		);
+
+		// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+		const markers = container.querySelector(
+			'.components-custom-gradient-picker__markers-container'
+		) as HTMLElement;
+		markers.getBoundingClientRect = () =>
+			( { x: 0, width: 200 } ) as DOMRect;
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+
+		fireEvent.mouseDown( firstPoint );
+		fireEvent.mouseMove( window, { clientX: 100 } );
+		fireEvent.mouseUp( window );
+
+		expect( onChange ).not.toHaveBeenCalled();
+	} );
+
+	it( 'does not move a control point when positioning is disabled', async () => {
+		const user = userEvent.setup();
+		const onChange = jest.fn();
+
+		render(
+			<CustomGradientBar
+				background="linear-gradient(90deg,rgb(0,0,0) 0%,rgb(255,255,255) 100%)"
+				hasGradient
+				disablePositioning
+				value={ POINTS }
+				onChange={ onChange }
+			/>
+		);
+
+		const [ firstPoint ] = screen.getAllByRole( 'button', {
+			name: /Gradient control point/,
+		} );
+		firstPoint.focus();
+		await user.keyboard( '[ArrowRight]' );
+
+		expect( onChange ).not.toHaveBeenCalled();
+	} );
+} );

package/src/custom-gradient-picker/types.ts

@@ -60,6 +60,14 @@ export type CustomGradientBarProps = {
 	onChange: ( newControlPoints: ControlPoint[] ) => void;
 	disableInserter?: boolean;
 	disableAlpha?: boolean;
+	/**
+	 * Whether control points are fixed in place. Set by consumers whose value
+	 * has no positions to store, such as a duotone, so the control does not
+	 * offer a move it cannot save.
+	 *
+	 * @default false
+	 */
+	disablePositioning?: boolean;
 	__experimentalIsRenderedInSidebar?: boolean;
 };
 
@@ -92,11 +100,13 @@ export type ControlPointButtonProps = {
 	isOpen: boolean;
 	position: ControlPoint[ 'position' ];
 	color: string;
+	disablePositioning?: boolean;
 };
 
 export type ControlPointsProps = {
 	disableRemove: boolean;
 	disableAlpha: boolean;
+	disablePositioning?: boolean;
 	gradientPickerDomRef: React.RefObject< HTMLDivElement | null >;
 	ignoreMarkerPosition?: number;
 	value: ControlPoint[];

package/src/dropdown/dropdown-content-wrapper.tsx

@@ -1,22 +1,32 @@
+import clsx from 'clsx';
 import type { ForwardedRef } from 'react';
 import type { WordPressComponentProps } from '../context';
 import { contextConnect, useContextSystem } from '../context';
-import { DropdownContentWrapperDiv } from './styles';
 import type { DropdownContentWrapperProps } from './types';
+import styles from './style.module.scss';
 
 function UnconnectedDropdownContentWrapper(
 	props: WordPressComponentProps< DropdownContentWrapperProps, 'div', false >,
 	forwardedRef: ForwardedRef< any >
 ) {
-	const { paddingSize = 'small', ...derivedProps } = useContextSystem(
-		props,
-		'DropdownContentWrapper'
-	);
+	const {
+		paddingSize = 'small',
+		className,
+		...derivedProps
+	} = useContextSystem( props, 'DropdownContentWrapper' );
 
 	return (
-		<DropdownContentWrapperDiv
+		<div
 			{ ...derivedProps }
-			paddingSize={ paddingSize }
+			className={ clsx(
+				styles[ 'content-wrapper' ],
+				{
+					[ styles[ 'padding-small' ] ]:
+						paddingSize !== 'none' && paddingSize !== 'medium',
+					[ styles[ 'padding-medium' ] ]: paddingSize === 'medium',
+				},
+				className
+			) }
 			ref={ forwardedRef }
 		/>
 	);

package/src/dropdown/stories/index.story.tsx

@@ -12,11 +12,6 @@ const meta: Meta< typeof Dropdown > = {
 	id: 'components-dropdown',
 	component: Dropdown,
 	subcomponents: { DropdownContentWrapper },
-	// 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 ) => <Dropdown { ...args } />,
 	args: {
 		onClose: fn(),
 		onToggle: fn(),

package/src/dropdown/style.module.scss

@@ -0,0 +1,25 @@
+@use "@wordpress/base-styles/variables" as *;
+
+.content-wrapper {
+	// Negative margin to reset (offset) the default padding on .components-popover__content.
+	/* stylelint-disable plugin/use-logical-properties-and-values -- Preserve the previous physical offsets against Popover padding. */
+	margin-left: -$grid-unit-10;
+	margin-right: -$grid-unit-10;
+
+	&:first-of-type {
+		margin-top: -$grid-unit-10;
+	}
+
+	&:last-of-type {
+		margin-bottom: -$grid-unit-10;
+	}
+	/* stylelint-enable plugin/use-logical-properties-and-values */
+}
+
+.padding-small {
+	padding: $grid-unit-10;
+}
+
+.padding-medium {
+	padding: $grid-unit-20;
+}

package/src/dropdown/test/index.tsx

@@ -1,6 +1,57 @@
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import Dropdown from '..';
+import { DropdownContentWrapper } from '../dropdown-content-wrapper';
+import styles from '../style.module.scss';
+
+describe( 'DropdownContentWrapper', () => {
+	it( 'should apply the small padding class by default', () => {
+		render(
+			<DropdownContentWrapper>
+				<span>content</span>
+			</DropdownContentWrapper>
+		);
+
+		// Disable reason: Semantic queries can't reach the wrapper.
+		// eslint-disable-next-line testing-library/no-node-access
+		expect( screen.getByText( 'content' ).parentElement ).toHaveClass(
+			styles[ 'content-wrapper' ],
+			styles[ 'padding-small' ]
+		);
+	} );
+
+	it( 'should apply the medium padding class', () => {
+		render(
+			<DropdownContentWrapper paddingSize="medium">
+				<span>content</span>
+			</DropdownContentWrapper>
+		);
+
+		// Disable reason: Semantic queries can't reach the wrapper.
+		// eslint-disable-next-line testing-library/no-node-access
+		const wrapper = screen.getByText( 'content' ).parentElement;
+		expect( wrapper ).toHaveClass(
+			styles[ 'content-wrapper' ],
+			styles[ 'padding-medium' ]
+		);
+		expect( wrapper ).not.toHaveClass( styles[ 'padding-small' ] );
+	} );
+
+	it( 'should omit padding classes when paddingSize is none', () => {
+		render(
+			<DropdownContentWrapper paddingSize="none">
+				<span>content</span>
+			</DropdownContentWrapper>
+		);
+
+		// Disable reason: Semantic queries can't reach the wrapper.
+		// eslint-disable-next-line testing-library/no-node-access
+		const wrapper = screen.getByText( 'content' ).parentElement;
+		expect( wrapper ).toHaveClass( styles[ 'content-wrapper' ] );
+		expect( wrapper ).not.toHaveClass( styles[ 'padding-small' ] );
+		expect( wrapper ).not.toHaveClass( styles[ 'padding-medium' ] );
+	} );
+} );
 
 describe( 'Dropdown', () => {
 	it( 'should toggle the dropdown properly', async () => {

package/src/duotone-picker/README.md

@@ -57,23 +57,38 @@ Array of duotone presets of the form `{ colors: [ '#000000', '#ffffff' ], name:
 
 An array of colors for the duotone effect.
 
+### `selectedSlug`
+
+-   Type: `string`
+-   Required: No
+
+The slug of the selected duotone preset. When a non-empty `selectedSlug` is given, 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.
+
 ### `onChange`
 
--   Type: `Function`
+-   Type: `(value: string[] | 'unset' | undefined, index?: number | undefined, slug?: string | undefined) => void`
 -   Required: Yes
 
-Callback which is called when the duotone colors change.
+The function called when the duotone colors change. It is passed the new `value` as an argument. When a preset from `duotonePalette` is picked, the second argument is its index and the third is its slug.
+
+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.
+
+### `presentation`: `'listbox' | 'toggle-buttons' | 'command-buttons'`
 
-### `asButtons`: `boolean`
+Controls the predefined swatches' interaction and accessibility semantics.
 
-Whether the control should present as a set of buttons, each with its own tab stop.
+-   `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. The `value` and `selectedSlug` props do not mark predefined swatches as selected, and activating a swatch always calls `onChange` with that swatch.
 
 - 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/duotone-picker/custom-duotone-bar.tsx

@@ -21,6 +21,7 @@ export default function CustomDuotoneBar( {
 	return (
 		<CustomGradientBar
 			disableInserter
+			disablePositioning
 			background={ background }
 			hasGradient={ hasGradient }
 			value={ controlPoints }

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

@@ -4,6 +4,7 @@ import { __, sprintf } from '@wordpress/i18n';
 import ColorListPicker from './color-list-picker';
 import CircularOptionPicker, {
 	getComputeCircularOptionPickerCommonProps,
+	warnIfCircularOptionPickerAsButtonsIsSet,
 } from '../circular-option-picker';
 import { VStack } from '../v-stack';
 import CustomDuotoneBar from './custom-duotone-bar';
@@ -46,6 +47,7 @@ import type { DuotonePickerProps } from './types';
  */
 function DuotonePicker( {
 	asButtons,
+	presentation,
 	loop,
 	clearable = true,
 	unsetable = true,
@@ -54,74 +56,95 @@ function DuotonePicker( {
 	disableCustomColors,
 	disableCustomDuotone,
 	value,
+	selectedSlug,
 	onChange,
 	'aria-label': ariaLabel,
 	'aria-labelledby': ariaLabelledby,
 	...otherProps
 }: DuotonePickerProps ) {
+	warnIfCircularOptionPickerAsButtonsIsSet( 'DuotonePicker', asButtons );
+	const { metaProps, labelProps, resolvedPresentation } =
+		getComputeCircularOptionPickerCommonProps(
+			asButtons,
+			loop,
+			ariaLabel,
+			ariaLabelledby,
+			presentation
+		);
 	const [ defaultDark, defaultLight ] = useMemo(
 		() => getDefaultColors( colorPalette ),
 		[ colorPalette ]
 	);
 
 	const isUnset = value === 'unset';
+	const isUnsetSelected =
+		resolvedPresentation !== 'command-buttons' && isUnset;
 	const unsetOptionLabel = __( 'Unset' );
 
 	const unsetOption = (
 		<CircularOptionPicker.Option
 			key="unset"
 			value="unset"
-			isSelected={ isUnset }
+			isSelected={ isUnsetSelected }
 			tooltipText={ unsetOptionLabel }
 			aria-label={ unsetOptionLabel }
 			className="components-duotone-picker__color-indicator"
 			onClick={ () => {
-				onChange( isUnset ? undefined : 'unset' );
+				onChange( isUnsetSelected ? undefined : 'unset' );
 			} }
 		/>
 	);
 
-	const duotoneOptions = duotonePalette.map( ( { colors, slug, name } ) => {
-		const style = {
-			background: getGradientFromCSSColors( colors, '135deg' ),
-			color: 'transparent',
-		};
-		const tooltipText =
-			name ??
-			sprintf(
-				// translators: %s: duotone code e.g: "dark-grayscale" or "7f7f7f-ffffff".
-				__( 'Duotone code: %s' ),
-				slug
-			);
-		const label = name
-			? sprintf(
-					// translators: %s: The name of the option e.g: "Dark grayscale".
-					__( 'Duotone: %s' ),
-					name
-			  )
-			: tooltipText;
-		const isSelected = fastDeepEqual( colors, value );
-
-		return (
-			<CircularOptionPicker.Option
-				key={ slug }
-				value={ colors }
-				isSelected={ isSelected }
-				aria-label={ label }
-				tooltipText={ tooltipText }
-				style={ style }
-				onClick={ () => {
-					onChange( isSelected ? undefined : colors );
-				} }
-			/>
-		);
-	} );
+	const duotoneOptions = duotonePalette.map(
+		( { colors, slug, name }, index ) => {
+			const style = {
+				background: getGradientFromCSSColors( colors, '135deg' ),
+				color: 'transparent',
+			};
+			const tooltipText =
+				name ??
+				sprintf(
+					// translators: %s: duotone code e.g: "dark-grayscale" or "7f7f7f-ffffff".
+					__( 'Duotone code: %s' ),
+					slug
+				);
+			const label = name
+				? sprintf(
+						// translators: %s: The name of the option e.g: "Dark grayscale".
+						__( 'Duotone: %s' ),
+						name
+				  )
+				: tooltipText;
+			// When a non-empty selectedSlug is provided, selection is decided
+			// strictly by slug, which keeps two presets holding the same
+			// colors apart. Otherwise selection falls back to matching the
+			// colors themselves.
+			const isSelected =
+				resolvedPresentation !== 'command-buttons' &&
+				( selectedSlug
+					? slug === selectedSlug
+					: fastDeepEqual( colors, value ) );
 
-	const { metaProps, labelProps } = getComputeCircularOptionPickerCommonProps(
-		asButtons,
-		loop,
-		ariaLabel,
-		ariaLabelledby
+			return (
+				<CircularOptionPicker.Option
+					key={ slug }
+					value={ colors }
+					isSelected={ isSelected }
+					aria-label={ label }
+					tooltipText={ tooltipText }
+					style={ style }
+					onClick={
+						// Deselecting reports no preset, matching
+						// `ColorPalette` and `GradientPicker`. Passing the slug
+						// back would leave a controlled consumer marking the
+						// swatch as selected after its value had been cleared.
+						isSelected
+							? () => onChange( undefined )
+							: () => onChange( colors, index, slug )
+					}
+				/>
+			);
+		}
 	);
 
 	const options = unsetable
@@ -146,15 +169,17 @@ function DuotonePicker( {
 				)
 			}
 		>
-			<Spacer paddingTop={ options.length === 0 ? 0 : 4 }>
-				<VStack spacing={ 3 }>
-					{ ! disableCustomColors && ! disableCustomDuotone && (
-						<CustomDuotoneBar
-							value={ isUnset ? undefined : value }
-							onChange={ onChange }
-						/>
-					) }
-					{ ! disableCustomDuotone && (
+			{ /* Both controls are hidden when custom duotones are disabled,
+			   so the wrapper would contribute only its padding. */ }
+			{ ! disableCustomDuotone && (
+				<Spacer paddingTop={ options.length === 0 ? 0 : 4 }>
+					<VStack spacing={ 3 }>
+						{ ! disableCustomColors && (
+							<CustomDuotoneBar
+								value={ isUnset ? undefined : value }
+								onChange={ onChange }
+							/>
+						) }
 						<ColorListPicker
 							labels={ [ __( 'Shadows' ), __( 'Highlights' ) ] }
 							colors={ colorPalette }
@@ -178,9 +203,9 @@ function DuotonePicker( {
 								onChange( newValue );
 							} }
 						/>
-					) }
-				</VStack>
-			</Spacer>
+					</VStack>
+				</Spacer>
+			) }
 		</CircularOptionPicker>
 	);
 }