@wordpress/components 25.15.1-next.79a6196f.0 → 26.0.0

package/src/checkbox-control/README.md

@@ -69,12 +69,11 @@ const MyCheckboxControl = () => {
 The set of props accepted by the component will be specified below.
 Props not included in this set will be applied to the input element.
 
-#### `label`: `string|false`
+#### `label`: `string`
 
 A label for the input field, that appears at the side of the checkbox.
 The prop will be rendered as content a label element.
 If no prop is passed an empty label is rendered.
-If the prop is set to false no label is rendered.
 
 -   Required: No
 

package/src/checkbox-control/stories/index.story.tsx

@@ -13,6 +13,7 @@ import { useState } from '@wordpress/element';
  */
 import CheckboxControl from '..';
 import { VStack } from '../../v-stack';
+import { HStack } from '../../h-stack';
 
 const meta: Meta< typeof CheckboxControl > = {
 	component: CheckboxControl,
@@ -115,3 +116,46 @@ Indeterminate.args = {
 	label: 'Select all',
 	__nextHasNoMarginBottom: true,
 };
+
+/**
+ * For more complex designs, a custom `<label>` element can be associated with the checkbox
+ * by leaving the `label` prop undefined and using the `id` and `htmlFor` props instead.
+ * Because the label element also functions as a click target for the checkbox, [do not
+ * place interactive elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#interactive_content)
+ * such as links or buttons inside the `<label>` node.
+ *
+ * Similarly, a custom description can be added by omitting the `help` prop
+ * and using the `aria-describedby` prop instead.
+ */
+export const WithCustomLabel: StoryFn< typeof CheckboxControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ isChecked, setChecked ] = useState( true );
+
+	return (
+		<HStack justify="flex-start" alignment="top" spacing={ 0 }>
+			<CheckboxControl
+				{ ...args }
+				checked={ isChecked }
+				onChange={ ( v ) => {
+					setChecked( v );
+					onChange( v );
+				} }
+				id="my-checkbox-with-custom-label"
+				aria-describedby="my-custom-description"
+			/>
+			<VStack>
+				<label htmlFor="my-checkbox-with-custom-label">
+					My custom label
+				</label>
+				<div id="my-custom-description" style={ { fontSize: 13 } }>
+					A custom description.
+				</div>
+			</VStack>
+		</HStack>
+	);
+};
+WithCustomLabel.args = {
+	__nextHasNoMarginBottom: true,
+};

package/src/checkbox-control/test/index.tsx

@@ -60,8 +60,8 @@ describe( 'CheckboxControl', () => {
 			expect( label ).toBeInTheDocument();
 		} );
 
-		it( 'should not render label element if label is set to false', () => {
-			render( <CheckboxControl label={ false } /> );
+		it( 'should not render label element if label is not set', () => {
+			render( <CheckboxControl /> );
 
 			const label = screen.queryByRole( 'label' );
 			expect( label ).not.toBeInTheDocument();

package/src/checkbox-control/types.ts

@@ -19,10 +19,9 @@ export type CheckboxControlProps = Pick<
 	/**
 	 * A label for the input field, that appears at the side of the checkbox.
 	 * The prop will be rendered as content a label element. If no prop is
-	 * passed an empty label is rendered. If the prop is set to false no label
-	 * is rendered.
+	 * passed an empty label is rendered.
 	 */
-	label?: string | false;
+	label?: string;
 	/**
 	 * If checked is true the checkbox will be checked. If checked is false the
 	 * checkbox will be unchecked. If no value is passed the checkbox will be

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

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
+import { press } from '@ariakit/test';
 
 /**
  * Internal dependencies
@@ -71,8 +71,6 @@ describe( 'CircularOptionPicker', () => {
 
 	describe( 'when `loop` is not set', () => {
 		it( 'should loop', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<CircularOptionPicker
 					{ ...DEFAULT_PROPS }
@@ -80,19 +78,17 @@ describe( 'CircularOptionPicker', () => {
 				/>
 			);
 
-			await user.tab();
+			await press.Tab();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
-			await user.keyboard( '[ArrowRight]' );
+			await press.ArrowRight();
 			expect( getOption( 'Option Two' ) ).toHaveFocus();
-			await user.keyboard( '[ArrowRight]' );
+			await press.ArrowRight();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
 		} );
 	} );
 
 	describe( 'when `loop` is true', () => {
 		it( 'should loop', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<CircularOptionPicker
 					{ ...DEFAULT_PROPS }
@@ -101,19 +97,17 @@ describe( 'CircularOptionPicker', () => {
 				/>
 			);
 
-			await user.tab();
+			await press.Tab();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
-			await user.keyboard( '[ArrowRight]' );
+			await press.ArrowRight();
 			expect( getOption( 'Option Two' ) ).toHaveFocus();
-			await user.keyboard( '[ArrowRight]' );
+			await press.ArrowRight();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
 		} );
 	} );
 
 	describe( 'when `loop` is false', () => {
 		it( 'should not loop', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<CircularOptionPicker
 					{ ...DEFAULT_PROPS }
@@ -122,11 +116,11 @@ describe( 'CircularOptionPicker', () => {
 				/>
 			);
 
-			await user.tab();
+			await press.Tab();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
-			await user.keyboard( '[ArrowRight]' );
+			await press.ArrowRight();
 			expect( getOption( 'Option Two' ) ).toHaveFocus();
-			await user.keyboard( '[ArrowRight]' );
+			await press.ArrowRight();
 			expect( getOption( 'Option Two' ) ).toHaveFocus();
 		} );
 	} );

package/src/color-picker/hsl-input.tsx

@@ -3,6 +3,11 @@
  */
 import { colord } from 'colord';
 
+/**
+ * WordPress dependencies
+ */
+import { useState, useEffect, useMemo } from '@wordpress/element';
+
 /**
  * Internal dependencies
  */
@@ -10,7 +15,49 @@ import { InputWithSlider } from './input-with-slider';
 import type { HslInputProps } from './types';
 
 export const HslInput = ( { color, onChange, enableAlpha }: HslInputProps ) => {
-	const { h, s, l, a } = color.toHsl();
+	const colorPropHSLA = useMemo( () => color.toHsl(), [ color ] );
+
+	const [ internalHSLA, setInternalHSLA ] = useState( { ...colorPropHSLA } );
+
+	const isInternalColorSameAsReceivedColor = color.isEqual(
+		colord( internalHSLA )
+	);
+
+	useEffect( () => {
+		if ( ! isInternalColorSameAsReceivedColor ) {
+			// Keep internal HSLA color up to date with the received color prop
+			setInternalHSLA( colorPropHSLA );
+		}
+	}, [ colorPropHSLA, isInternalColorSameAsReceivedColor ] );
+
+	// If the internal color is equal to the received color prop, we can use the
+	// HSLA values from the local state which, compared to the received color prop,
+	// retain more details about the actual H and S values that the user selected,
+	// and thus allow for better UX when interacting with the H and S sliders.
+	const colorValue = isInternalColorSameAsReceivedColor
+		? internalHSLA
+		: colorPropHSLA;
+
+	const updateHSLAValue = (
+		partialNewValue: Partial< typeof colorPropHSLA >
+	) => {
+		const nextOnChangeValue = colord( {
+			...colorValue,
+			...partialNewValue,
+		} );
+
+		// Fire `onChange` only if the resulting color is different from the
+		// current one.
+		// Otherwise, update the internal HSLA color to cause a re-render.
+		if ( ! color.isEqual( nextOnChangeValue ) ) {
+			onChange( nextOnChangeValue );
+		} else {
+			setInternalHSLA( ( prevHSLA ) => ( {
+				...prevHSLA,
+				...partialNewValue,
+			} ) );
+		}
+	};
 
 	return (
 		<>
@@ -19,9 +66,9 @@ export const HslInput = ( { color, onChange, enableAlpha }: HslInputProps ) => {
 				max={ 359 }
 				label="Hue"
 				abbreviation="H"
-				value={ h }
+				value={ colorValue.h }
 				onChange={ ( nextH: number ) => {
-					onChange( colord( { h: nextH, s, l, a } ) );
+					updateHSLAValue( { h: nextH } );
 				} }
 			/>
 			<InputWithSlider
@@ -29,16 +76,9 @@ export const HslInput = ( { color, onChange, enableAlpha }: HslInputProps ) => {
 				max={ 100 }
 				label="Saturation"
 				abbreviation="S"
-				value={ s }
+				value={ colorValue.s }
 				onChange={ ( nextS: number ) => {
-					onChange(
-						colord( {
-							h,
-							s: nextS,
-							l,
-							a,
-						} )
-					);
+					updateHSLAValue( { s: nextS } );
 				} }
 			/>
 			<InputWithSlider
@@ -46,16 +86,9 @@ export const HslInput = ( { color, onChange, enableAlpha }: HslInputProps ) => {
 				max={ 100 }
 				label="Lightness"
 				abbreviation="L"
-				value={ l }
+				value={ colorValue.l }
 				onChange={ ( nextL: number ) => {
-					onChange(
-						colord( {
-							h,
-							s,
-							l: nextL,
-							a,
-						} )
-					);
+					updateHSLAValue( { l: nextL } );
 				} }
 			/>
 			{ enableAlpha && (
@@ -64,16 +97,9 @@ export const HslInput = ( { color, onChange, enableAlpha }: HslInputProps ) => {
 					max={ 100 }
 					label="Alpha"
 					abbreviation="A"
-					value={ Math.trunc( 100 * a ) }
+					value={ Math.trunc( 100 * colorValue.a ) }
 					onChange={ ( nextA: number ) => {
-						onChange(
-							colord( {
-								h,
-								s,
-								l,
-								a: nextA / 100,
-							} )
-						);
+						updateHSLAValue( { a: nextA / 100 } );
 					} }
 				/>
 			) }

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

@@ -1,13 +1,19 @@
 /**
  * External dependencies
  */
-import { screen, render } from '@testing-library/react';
+import { fireEvent, screen, render, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
 /**
  * Internal dependencies
  */
 import { ColorPicker } from '..';
+import { click } from '@ariakit/test';
 
 const hslaMatcher = expect.objectContaining( {
 	h: expect.any( Number ),
@@ -133,20 +139,39 @@ describe( 'ColorPicker', () => {
 		} );
 	} );
 
-	describe.each( [
-		[ 'hue', 'Hue', '#aad52a' ],
-		[ 'saturation', 'Saturation', '#20dfdf' ],
-		[ 'lightness', 'Lightness', '#95eaea' ],
-	] )( 'HSL inputs', ( colorInput, inputLabel, expected ) => {
-		it( `should fire onChange with the correct value when the ${ colorInput } value is updated`, async () => {
+	describe( 'HSL inputs', () => {
+		it( 'sliders should use accurate H and S values based on user interaction when possible', async () => {
 			const user = userEvent.setup();
 			const onChange = jest.fn();
-			const color = '#2ad5d5';
+
+			const ControlledColorPicker = ( {
+				onChange: onChangeProp,
+				...restProps
+			}: React.ComponentProps< typeof ColorPicker > ) => {
+				const [ colorState, setColorState ] = useState( '#000000' );
+
+				const internalOnChange: typeof onChangeProp = ( newColor ) => {
+					onChangeProp?.( newColor );
+					setColorState( newColor );
+				};
+
+				return (
+					<>
+						<ColorPicker
+							{ ...restProps }
+							onChange={ internalOnChange }
+							color={ colorState }
+						/>
+						<button onClick={ () => setColorState( '#4d87ba' ) }>
+							Set color to #4d87ba
+						</button>
+					</>
+				);
+			};
 
 			render(
-				<ColorPicker
+				<ControlledColorPicker
 					onChange={ onChange }
-					color={ color }
 					enableAlpha={ false }
 				/>
 			);
@@ -156,16 +181,165 @@ describe( 'ColorPicker', () => {
 
 			await user.selectOptions( formatSelector, 'hsl' );
 
-			const inputElement = screen.getByRole( 'spinbutton', {
-				name: inputLabel,
+			const hueSliders = screen.getAllByRole( 'slider', {
+				name: 'Hue',
 			} );
-			expect( inputElement ).toBeVisible();
+			expect( hueSliders ).toHaveLength( 2 );
 
-			await user.clear( inputElement );
-			await user.type( inputElement, '75' );
+			// Reason for the `!` post-fix expression operator: if the check above
+			// doesn't fail, we're guaranteed that `hueSlider` is not undefined.
+			const hueSlider = hueSliders.at( -1 )!;
+			const saturationSlider = screen.getByRole( 'slider', {
+				name: 'Saturation',
+			} );
+			const lightnessSlider = screen.getByRole( 'slider', {
+				name: 'Lightness',
+			} );
+			const hueNumberInput = screen.getByRole( 'spinbutton', {
+				name: 'Hue',
+			} );
+			const saturationNumberInput = screen.getByRole( 'spinbutton', {
+				name: 'Saturation',
+			} );
+			const lightnessNumberInput = screen.getByRole( 'spinbutton', {
+				name: 'Lightness',
+			} );
+
+			// All initial inputs should have a value of `0` since the color is black.
+			expect( hueSlider ).toHaveValue( '0' );
+			expect( saturationSlider ).toHaveValue( '0' );
+			expect( lightnessSlider ).toHaveValue( '0' );
+			expect( hueNumberInput ).toHaveValue( 0 );
+			expect( saturationNumberInput ).toHaveValue( 0 );
+			expect( lightnessNumberInput ).toHaveValue( 0 );
+
+			// Interact with the Hue slider, it should change its value (and the
+			// value of the associated number input), but it shouldn't cause the
+			// `onChange` callback to fire, since the resulting color is still black.
+			fireEvent.change( hueSlider, { target: { value: 80 } } );
+
+			expect( hueSlider ).toHaveValue( '80' );
+			expect( hueNumberInput ).toHaveValue( 80 );
+			expect( onChange ).not.toHaveBeenCalled();
+
+			// Interact with the Saturation slider, it should change its value (and the
+			// value of the associated number input), but it shouldn't cause the
+			// `onChange` callback to fire, since the resulting color is still black.
+			fireEvent.change( saturationSlider, { target: { value: 50 } } );
+
+			expect( saturationSlider ).toHaveValue( '50' );
+			expect( saturationNumberInput ).toHaveValue( 50 );
+			expect( onChange ).not.toHaveBeenCalled();
+
+			// Interact with the Lightness slider, it should change its value (and the
+			// value of the associated number input). It should also cause the
+			// `onChange` callback to fire, since changing the lightness actually
+			// causes the color to change.
+			fireEvent.change( lightnessSlider, { target: { value: 30 } } );
 
+			await waitFor( () =>
+				expect( lightnessSlider ).toHaveValue( '30' )
+			);
+			expect( lightnessNumberInput ).toHaveValue( 30 );
+			expect( onChange ).toHaveBeenCalledTimes( 1 );
+			expect( onChange ).toHaveBeenLastCalledWith( '#597326' );
+
+			// Interact with the Lightness slider, setting to 100 (ie. white).
+			// It should also cause the `onChange` callback to fire, and reset the
+			// hue and saturation inputs to `0`.
+			fireEvent.change( lightnessSlider, { target: { value: 100 } } );
+
+			await waitFor( () =>
+				expect( lightnessSlider ).toHaveValue( '100' )
+			);
+			expect( lightnessNumberInput ).toHaveValue( 100 );
+			expect( hueSlider ).toHaveValue( '0' );
+			expect( saturationSlider ).toHaveValue( '0' );
+			expect( hueNumberInput ).toHaveValue( 0 );
+			expect( saturationNumberInput ).toHaveValue( 0 );
+			expect( onChange ).toHaveBeenCalledTimes( 2 );
+			expect( onChange ).toHaveBeenLastCalledWith( '#ffffff' );
+
+			// Interact with the Hue slider, it should change its value (and the
+			// value of the associated number input), but it shouldn't cause the
+			// `onChange` callback to fire, since the resulting color is still white.
+			fireEvent.change( hueSlider, { target: { value: 147 } } );
+
+			expect( hueSlider ).toHaveValue( '147' );
+			expect( hueNumberInput ).toHaveValue( 147 );
+			expect( onChange ).toHaveBeenCalledTimes( 2 );
+
+			// Interact with the Saturation slider, it should change its value (and the
+			// value of the associated number input), but it shouldn't cause the
+			// `onChange` callback to fire, since the resulting color is still white.
+			fireEvent.change( saturationSlider, { target: { value: 82 } } );
+
+			expect( saturationSlider ).toHaveValue( '82' );
+			expect( saturationNumberInput ).toHaveValue( 82 );
+			expect( onChange ).toHaveBeenCalledTimes( 2 );
+
+			// Interact with the Lightness slider, it should change its value (and the
+			// value of the associated number input). It should also cause the
+			// `onChange` callback to fire, since changing the lightness actually
+			// causes the color to change.
+			fireEvent.change( lightnessSlider, { target: { value: 14 } } );
+
+			await waitFor( () =>
+				expect( lightnessSlider ).toHaveValue( '14' )
+			);
+			expect( lightnessNumberInput ).toHaveValue( 14 );
 			expect( onChange ).toHaveBeenCalledTimes( 3 );
-			expect( onChange ).toHaveBeenLastCalledWith( expected );
+			expect( onChange ).toHaveBeenLastCalledWith( '#064121' );
+
+			// Set the color externally. All inputs should update to match the H/S/L
+			// value of the new color.
+			const setColorButton = screen.getByRole( 'button', {
+				name: /set color/i,
+			} );
+			await click( setColorButton );
+
+			expect( hueSlider ).toHaveValue( '208' );
+			expect( hueNumberInput ).toHaveValue( 208 );
+			expect( saturationSlider ).toHaveValue( '44' );
+			expect( saturationNumberInput ).toHaveValue( 44 );
+			expect( lightnessSlider ).toHaveValue( '52' );
+			expect( lightnessNumberInput ).toHaveValue( 52 );
+		} );
+
+		describe.each( [
+			[ 'hue', 'Hue', '#aad52a' ],
+			[ 'saturation', 'Saturation', '#20dfdf' ],
+			[ 'lightness', 'Lightness', '#95eaea' ],
+		] )( 'HSL inputs', ( colorInput, inputLabel, expected ) => {
+			it( `should fire onChange with the correct value when the ${ colorInput } value is updated`, async () => {
+				const user = userEvent.setup();
+				const onChange = jest.fn();
+				const color = '#2ad5d5';
+
+				render(
+					<ColorPicker
+						onChange={ onChange }
+						color={ color }
+						enableAlpha={ false }
+					/>
+				);
+
+				const formatSelector = screen.getByRole( 'combobox' );
+				expect( formatSelector ).toBeVisible();
+
+				await user.selectOptions( formatSelector, 'hsl' );
+
+				const inputElement = screen.getByRole( 'spinbutton', {
+					name: inputLabel,
+				} );
+				expect( inputElement ).toBeVisible();
+
+				await user.clear( inputElement );
+				await user.type( inputElement, '75' );
+
+				expect( onChange ).toHaveBeenCalledTimes( 3 );
+				expect( onChange ).toHaveBeenLastCalledWith( expected );
+			} );
 		} );
 	} );
 } );

package/src/combobox-control/index.tsx

@@ -124,10 +124,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 			selected: __( 'Item selected.' ),
 		},
 		__experimentalRenderItem,
-	} = useDeprecated36pxDefaultSizeProp< ComboboxControlProps >(
-		props,
-		'wp.components.ComboboxControl'
-	);
+	} = useDeprecated36pxDefaultSizeProp( props );
 
 	const [ value, setValue ] = useControlledValue( {
 		value: valueProp,

package/src/composite/current/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Composite is a component that may contain navigable items represented by
+ * CompositeItem. It's inspired by the WAI-ARIA Composite Role and implements
+ * all the keyboard navigation mechanisms to ensure that there's only one
+ * tab stop for the whole Composite element. This means that it can behave as
+ * a roving tabindex or aria-activedescendant container.
+ *
+ * @see https://ariakit.org/components/composite
+ */
+
+/* eslint-disable-next-line no-restricted-imports */
+export {
+	Composite,
+	CompositeGroup,
+	CompositeGroupLabel,
+	CompositeItem,
+	CompositeRow,
+	useCompositeStore,
+} from '@ariakit/react';
+
+/* eslint-disable-next-line no-restricted-imports */
+export type { CompositeStore, CompositeStoreProps } from '@ariakit/react';

package/src/composite/current/stories/index.story.tsx

@@ -0,0 +1,86 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { isRTL } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import {
+	Composite,
+	CompositeGroup,
+	CompositeRow,
+	CompositeItem,
+	useCompositeStore,
+} from '..';
+import { UseCompositeStorePlaceholder, transform } from './utils';
+
+const meta: Meta< typeof UseCompositeStorePlaceholder > = {
+	title: 'Components/Composite (V2)',
+	component: UseCompositeStorePlaceholder,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		Composite,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		CompositeGroup,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		CompositeRow,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		CompositeItem,
+	},
+	parameters: {
+		badges: [ 'private' ],
+		docs: {
+			canvas: { sourceState: 'shown' },
+			source: { transform },
+			extractArgTypes: ( component: React.FunctionComponent ) => {
+				const name = component.displayName;
+				const path = name
+					?.replace(
+						/([a-z])([A-Z])/g,
+						( _, a, b ) => `${ a }-${ b.toLowerCase() }`
+					)
+					.toLowerCase();
+				const url = `https://ariakit.org/reference/${ path }`;
+				return {
+					props: {
+						name: 'Props',
+						description: `See <a href="${ url }">Ariakit docs</a> for <code>${ name }</code>`,
+						table: { type: { summary: undefined } },
+					},
+				};
+			},
+		},
+	},
+};
+export default meta;
+
+export const Default: StoryFn< typeof Composite > = ( { ...initialState } ) => {
+	const rtl = isRTL();
+	const store = useCompositeStore( { rtl, ...initialState } );
+
+	return (
+		<Composite role="grid" store={ store } aria-label="Ariakit Composite">
+			<CompositeRow role="row">
+				<CompositeItem role="gridcell">Item A1</CompositeItem>
+				<CompositeItem role="gridcell">Item A2</CompositeItem>
+				<CompositeItem role="gridcell">Item A3</CompositeItem>
+			</CompositeRow>
+			<CompositeRow role="row">
+				<CompositeItem role="gridcell">Item B1</CompositeItem>
+				<CompositeItem role="gridcell">Item B2</CompositeItem>
+				<CompositeItem role="gridcell">Item B3</CompositeItem>
+			</CompositeRow>
+			<CompositeRow role="row">
+				<CompositeItem role="gridcell">Item C1</CompositeItem>
+				<CompositeItem role="gridcell">Item C2</CompositeItem>
+				<CompositeItem role="gridcell">Item C3</CompositeItem>
+			</CompositeRow>
+		</Composite>
+	);
+};