@wordpress/components 28.2.0 → 28.4.0

package/src/button/types.ts

@@ -25,14 +25,27 @@ type BaseButtonProps = {
 	 * @default false
 	 */
 	__next40pxDefaultSize?: boolean;
+	/**
+	 * Whether to keep the button focusable when disabled.
+	 *
+	 * In most cases, it is recommended to set this to `true`. Disabling a control without maintaining focusability
+	 * can cause accessibility issues, by hiding their presence from screen reader users,
+	 * or by preventing focus from returning to a trigger element.
+	 *
+	 * Learn more about the [focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols)
+	 * in the WAI-ARIA Authoring Practices Guide.
+	 *
+	 * @default false
+	 */
+	accessibleWhenDisabled?: boolean;
 	/**
 	 * The button's children.
 	 */
 	children?: ReactNode;
 	/**
-	 * An accessible description for the button.
+	 * A visually hidden accessible description for the button.
 	 */
-	describedBy?: string;
+	description?: string;
 	/**
 	 * If provided, renders an Icon component inside the button.
 	 */
@@ -105,28 +118,24 @@ type BaseButtonProps = {
 	 * 'link' (the link button styles)
 	 */
 	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
-	/**
-	 * Whether to keep the button focusable when disabled.
-	 *
-	 * @default false
-	 */
-	__experimentalIsFocusable?: boolean;
 };
 
 type _ButtonProps = {
 	/**
-	 * Whether the button is disabled.
+	 * Whether the button is disabled. If `true`, this will force a `button` element
+	 * to be rendered, even when an `href` is given.
 	 *
-	 * If `true`, this will force a `button` element to be rendered, even when an `href` is given.
+	 * In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
 	 */
 	disabled?: boolean;
 };
 
 type AnchorProps = {
 	/**
-	 * Whether the button is disabled.
+	 * Whether the button is disabled. If `true`, this will force a `button` element
+	 * to be rendered, even when an `href` is given.
 	 *
-	 * If `true`, this will force a `button` element to be rendered, even when an `href` is given.
+	 * In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
 	 */
 	disabled?: false;
 	/**
@@ -140,6 +149,14 @@ type AnchorProps = {
 };
 
 export type DeprecatedButtonProps = {
+	/**
+	 * Whether to keep the button focusable when disabled.
+	 *
+	 * @default false
+	 * @deprecated Use the `accessibleWhenDisabled` prop instead.
+	 * @ignore
+	 */
+	__experimentalIsFocusable?: boolean;
 	/**
 	 * Gives the button a default style.
 	 *
@@ -182,6 +199,13 @@ export type DeprecatedButtonProps = {
 	 * @ignore
 	 */
 	isSmall?: boolean;
+	/**
+	 * A visually hidden accessible description for the button.
+	 *
+	 * @deprecated Use the `description` prop instead.
+	 * @ignore
+	 */
+	describedBy?: string;
 };
 
 export type DeprecatedIconButtonProps = {

package/src/card/card/README.md

@@ -106,7 +106,7 @@ const Example = () => (
 
 ### Context
 
-`<Card />`'s sub-components are connected to `<Card />` using [Context](https://reactjs.org/docs/context.html). Certain props like `size` and `isBorderless` are passed through to some of the sub-components.
+`<Card />`'s sub-components are connected to `<Card />` using [Context](https://react.dev/learn/passing-data-deeply-with-context). Certain props like `size` and `isBorderless` are passed through to some of the sub-components.
 
 In the following example, the `<CardBody />` will render with a size of `small`:
 

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
 /**
  * Internal dependencies
@@ -41,51 +41,52 @@ const meta: Meta< typeof Card > = {
 
 export default meta;
 
-const Template: StoryFn< typeof Card > = ( args ) => <Card { ...args } />;
-
-export const Default = Template.bind( {} );
-Default.args = {
-	children: (
-		<>
-			<CardHeader>
-				<Heading>CardHeader</Heading>
-			</CardHeader>
-			<CardBody>
-				<Text>CardBody</Text>
-			</CardBody>
-			<CardBody>
-				<Text>CardBody (before CardDivider)</Text>
-			</CardBody>
-			<CardDivider />
-			<CardBody>
-				<Text>CardBody (after CardDivider)</Text>
-			</CardBody>
-			<CardMedia>
-				<img
-					alt="Card Media"
-					src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
-				/>
-			</CardMedia>
-			<CardFooter>
-				<Text>CardFooter</Text>
-				<Button variant="secondary">Action Button</Button>
-			</CardFooter>
-		</>
-	),
+export const Default: StoryObj< typeof Card > = {
+	args: {
+		children: (
+			<>
+				<CardHeader>
+					<Heading>CardHeader</Heading>
+				</CardHeader>
+				<CardBody>
+					<Text>CardBody</Text>
+				</CardBody>
+				<CardBody>
+					<Text>CardBody (before CardDivider)</Text>
+				</CardBody>
+				<CardDivider />
+				<CardBody>
+					<Text>CardBody (after CardDivider)</Text>
+				</CardBody>
+				<CardMedia>
+					<img
+						alt="Card Media"
+						src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
+					/>
+				</CardMedia>
+				<CardFooter>
+					<Text>CardFooter</Text>
+					<Button variant="secondary">Action Button</Button>
+				</CardFooter>
+			</>
+		),
+	},
 };
 
 /**
  * `CardMedia` provides a container for full-bleed content within a `Card`,
  * such as images, video, or even just a background color. The corners will be rounded if necessary.
  */
-export const FullBleedContent = Template.bind( {} );
-FullBleedContent.args = {
-	...Default.args,
-	children: (
-		<CardMedia>
-			<div style={ { padding: 16, background: 'beige' } }>
-				Some full bleed content
-			</div>
-		</CardMedia>
-	),
+export const FullBleedContent: StoryObj< typeof Card > = {
+	...Default,
+	args: {
+		...Default.args,
+		children: (
+			<CardMedia>
+				<div style={ { padding: 16, background: 'beige' } }>
+					Some full bleed content
+				</div>
+			</CardMedia>
+		),
+	},
 };

package/src/checkbox-control/README.md

@@ -55,6 +55,7 @@ const MyCheckboxControl = () => {
 	const [ isChecked, setChecked ] = useState( true );
 	return (
 		<CheckboxControl
+			__nextHasNoMarginBottom
 			label="Is author"
 			help="Is the user a author or not?"
 			checked={ isChecked }
@@ -102,6 +103,13 @@ If indeterminate is true the state of the checkbox will be indeterminate.
 
 -   Required: No
 
+#### `__nextHasNoMarginBottom`: `boolean`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Required: No
+-   Default: `false`
+
 ## Related components
 
 -   To select one option from a set, and you want to show all the available options at once, use the `RadioControl` component.

package/src/checkbox-control/index.tsx

@@ -31,6 +31,7 @@ import type { WordPressComponentProps } from '../context';
  *   const [ isChecked, setChecked ] = useState( true );
  *   return (
  *     <CheckboxControl
+ *       __nextHasNoMarginBottom
  *       label="Is author"
  *       help="Is the user a author or not?"
  *       checked={ isChecked }

package/src/checkbox-control/style.scss

@@ -3,7 +3,7 @@
 	--checkbox-input-size: 24px; // Width & height for small viewports.
 
 	@include break-small() {
-		--checkbox-input-size: 20px;
+		--checkbox-input-size: 16px;
 	}
 
 	--checkbox-input-margin: #{$grid-unit-10};
@@ -12,6 +12,7 @@
 .components-checkbox-control__label {
 	// Ensure label is aligned with checkbox along X axis
 	line-height: var(--checkbox-input-size);
+	cursor: pointer;
 }
 
 .components-checkbox-control__input[type="checkbox"] {
@@ -61,6 +62,7 @@
 	vertical-align: middle;
 	width: var(--checkbox-input-size);
 	aspect-ratio: 1;
+	line-height: 1; // maintains proper height even with WP common.css
 	flex-shrink: 0;
 }
 

package/src/color-picker/component.tsx

@@ -16,11 +16,7 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
-import {
-	useContextSystem,
-	contextConnect,
-	ContextSystemProvider,
-} from '../context';
+import { useContextSystem, contextConnect } from '../context';
 import {
 	ColorfulWrapper,
 	SelectControl,
@@ -43,9 +39,6 @@ const options = [
 	{ label: 'Hex', value: 'hex' as const },
 ];
 
-// `isBorderless` is still experimental and not a public prop for InputControl yet.
-const BORDERLESS_SELECT_CONTROL_CONTEXT = { InputBase: { isBorderless: true } };
-
 const UnconnectedColorPicker = (
 	props: ColorPickerProps,
 	forwardedRef: ForwardedRef< any >
@@ -92,20 +85,17 @@ const UnconnectedColorPicker = (
 			/>
 			<AuxiliaryColorArtefactWrapper>
 				<AuxiliaryColorArtefactHStackHeader justify="space-between">
-					<ContextSystemProvider
-						value={ BORDERLESS_SELECT_CONTROL_CONTEXT }
-					>
-						<SelectControl
-							__nextHasNoMarginBottom
-							options={ options }
-							value={ colorType }
-							onChange={ ( nextColorType ) =>
-								setColorType( nextColorType as ColorType )
-							}
-							label={ __( 'Color format' ) }
-							hideLabelFromVision
-						/>
-					</ContextSystemProvider>
+					<SelectControl
+						__nextHasNoMarginBottom
+						options={ options }
+						value={ colorType }
+						onChange={ ( nextColorType ) =>
+							setColorType( nextColorType as ColorType )
+						}
+						label={ __( 'Color format' ) }
+						hideLabelFromVision
+						variant="minimal"
+					/>
 					<ColorCopyButton
 						color={ safeColordColor }
 						colorType={ copyFormat || colorType }

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

@@ -1,12 +1,7 @@
 /**
  * External dependencies
  */
-import type { Meta, StoryFn } from '@storybook/react';
-
-/**
- * WordPress dependencies
- */
-import { useState } from '@wordpress/element';
+import type { Meta, StoryObj } from '@storybook/react';
 
 /**
  * Internal dependencies
@@ -30,19 +25,4 @@ const meta: Meta< typeof ColorPicker > = {
 };
 export default meta;
 
-const Template: StoryFn< typeof ColorPicker > = ( { onChange, ...props } ) => {
-	const [ color, setColor ] = useState< string | undefined >();
-
-	return (
-		<ColorPicker
-			{ ...props }
-			color={ color }
-			onChange={ ( ...changeArgs ) => {
-				onChange?.( ...changeArgs );
-				setColor( ...changeArgs );
-			} }
-		/>
-	);
-};
-
-export const Default = Template.bind( {} );
+export const Default: StoryObj< typeof ColorPicker > = {};

package/src/combobox-control/README.md

@@ -34,6 +34,7 @@ function MyComboboxControl() {
 	const [ filteredOptions, setFilteredOptions ] = useState( options );
 	return (
 		<ComboboxControl
+			__nextHasNoMarginBottom
 			label="Font Size"
 			value={ fontSize }
 			onChange={ setFontSize }
@@ -117,6 +118,14 @@ Custom renderer invoked for each option in the suggestion list. The render prop
 -   Type: `( args: { item: object } ) => ReactNode`
 -   Required: No
 
+#### __nextHasNoMarginBottom
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
+
 ## Related components
 
 -   Like this component, but without a search input, the [`CustomSelectControl`](https://developer.wordpress.org/block-editor/reference-guides/components/custom-select-control/) component.

package/src/combobox-control/index.tsx

@@ -92,6 +92,7 @@ const getIndexOfMatchingSuggestion = (
  * 	const [ filteredOptions, setFilteredOptions ] = useState( options );
  * 	return (
  * 		<ComboboxControl
+ * 			__nextHasNoMarginBottom
  * 			label="Font Size"
  * 			value={ fontSize }
  * 			onChange={ setFontSize }
@@ -267,6 +268,15 @@ function ComboboxControl( props: ComboboxControlProps ) {
 		inputContainer.current?.focus();
 	};
 
+	// Stop propagation of the keydown event when pressing Enter on the Reset
+	// button to prevent calling the onKeydown callback on the container div
+	// element which actually sets the selected suggestion.
+	const handleResetStopPropagation: React.KeyboardEventHandler<
+		HTMLButtonElement
+	> = ( event ) => {
+		event.stopPropagation();
+	};
+
 	// Update current selections when the filter input changes.
 	useEffect( () => {
 		const hasMatchingSuggestions = matchingSuggestions.length > 0;
@@ -346,8 +356,11 @@ function ComboboxControl( props: ComboboxControlProps ) {
 								<Button
 									className="components-combobox-control__reset"
 									icon={ closeSmall }
+									// Disable reason: Focus returns to input field when reset is clicked.
+									// eslint-disable-next-line no-restricted-syntax
 									disabled={ ! value }
 									onClick={ handleOnReset }
+									onKeyDown={ handleResetStopPropagation }
 									label={ __( 'Reset' ) }
 								/>
 							</FlexItem>

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

@@ -89,7 +89,6 @@ describe.each( [
 			<Component options={ timezones } label={ defaultLabelText } />
 		);
 		const label = getLabel( defaultLabelText );
-		expect( label ).toBeInTheDocument();
 		expect( label ).toBeVisible();
 	} );
 
@@ -306,4 +305,131 @@ describe.each( [
 		expect( onChangeSpy ).toHaveBeenCalledWith( targetOption.value );
 		expect( input ).toHaveValue( targetOption.label );
 	} );
+
+	it( 'should render with Reset button disabled', () => {
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				allowReset
+			/>
+		);
+
+		const resetButton = screen.getByRole( 'button', { name: 'Reset' } );
+
+		expect( resetButton ).toBeVisible();
+		expect( resetButton ).toBeDisabled();
+	} );
+
+	it( 'should reset input when clicking the Reset button', async () => {
+		const user = await userEvent.setup();
+		const targetOption = timezones[ 13 ];
+
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				allowReset
+			/>
+		);
+
+		// Pressing tab selects the input and shows the options.
+		await user.tab();
+		// Type enough characters to ensure a predictable search result.
+		await user.keyboard( getOptionSearchString( targetOption ) );
+		// Pressing Enter/Return selects the currently focused option.
+		await user.keyboard( '{Enter}' );
+
+		const input = getInput( defaultLabelText );
+
+		expect( input ).toHaveValue( targetOption.label );
+
+		const resetButton = screen.getByRole( 'button', { name: 'Reset' } );
+
+		expect( resetButton ).toBeEnabled();
+
+		await user.click( resetButton );
+
+		expect( input ).toHaveValue( '' );
+		expect( resetButton ).toBeDisabled();
+		expect( input ).toHaveFocus();
+	} );
+
+	it( 'should reset input when pressing the Reset button with the Enter key', async () => {
+		const user = await userEvent.setup();
+		const targetOption = timezones[ 13 ];
+
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				allowReset
+			/>
+		);
+
+		// Pressing tab selects the input and shows the options.
+		await user.tab();
+		// Type enough characters to ensure a predictable search result.
+		await user.keyboard( getOptionSearchString( targetOption ) );
+		// Pressing Enter/Return selects the currently focused option.
+		await user.keyboard( '{Enter}' );
+
+		const input = getInput( defaultLabelText );
+
+		expect( input ).toHaveValue( targetOption.label );
+
+		// Pressing tab moves focus to the Reset buttons
+		await user.tab();
+
+		const resetButton = screen.getByRole( 'button', { name: 'Reset' } );
+
+		// If the button has focus that implies it is enabled.
+		expect( resetButton ).toHaveFocus();
+
+		// Pressing Enter/Return resets the input.
+		await user.keyboard( '{Enter}' );
+
+		expect( input ).toHaveValue( '' );
+		expect( resetButton ).toBeDisabled();
+		expect( input ).toHaveFocus();
+	} );
+
+	it( 'should reset input when pressing the Reset button with the Spacebar key', async () => {
+		const user = await userEvent.setup();
+		const targetOption = timezones[ 13 ];
+
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				allowReset
+			/>
+		);
+
+		// Pressing tab selects the input and shows the options.
+		await user.tab();
+		// Type enough characters to ensure a predictable search result.
+		await user.keyboard( getOptionSearchString( targetOption ) );
+		// Pressing Enter/Return selects the currently focused option.
+		await user.keyboard( '{Enter}' );
+
+		const input = getInput( defaultLabelText );
+
+		expect( input ).toHaveValue( targetOption.label );
+
+		// Pressing tab moves focus to the Reset buttons.
+		await user.tab();
+
+		const resetButton = screen.getByRole( 'button', { name: 'Reset' } );
+
+		// If the button has focus that implies it is enabled.
+		expect( resetButton ).toHaveFocus();
+
+		// Pressing Spacebar resets the input.
+		await user.keyboard( '[Space]' );
+
+		expect( input ).toHaveValue( '' );
+		expect( resetButton ).toBeDisabled();
+		expect( input ).toHaveFocus();
+	} );
 } );

package/src/composite/current/index.ts

@@ -8,7 +8,6 @@
  * @see https://ariakit.org/components/composite
  */
 
-/* eslint-disable-next-line no-restricted-imports */
 export {
 	Composite,
 	CompositeGroup,
@@ -18,5 +17,4 @@ export {
 	useCompositeStore,
 } from '@ariakit/react';
 
-/* eslint-disable-next-line no-restricted-imports */
 export type { CompositeStore, CompositeStoreProps } from '@ariakit/react';

package/src/custom-select-control/README.md

@@ -63,81 +63,83 @@ function MyControlledCustomSelectControl() {
 
 ### Props
 
-#### className
+#### `className`: `string`
 
-A custom class name to append to the outer `<div>`.
+Optional classname for the component.
 
--   Type: `String`
 -   Required: No
 
-#### hideLabelFromVision
+#### `hideLabelFromVision`: `boolean`
 
-Used to visually hide the label. It will always be visible to screen readers.
+Hide the label visually, while keeping available to assistive technology.
 
--   Type: `Boolean`
 -   Required: No
 
-#### label
+#### `describedBy`: `string`
 
-The label for the control.
+Description for the select trigger button used by assistive technology. If no value is passed, the text "Currently selected: selectedItem.name" will be used fully translated.
+
+-   Required: No
+
+#### `label`: `string`
+
+Label for the control.
 
--   Type: `String`
 -   Required: Yes
 
-#### describedBy
+#### `onChange`: `( newValue: ChangeObject ) => void`
 
-Pass in a description that will be shown to screen readers associated with the select trigger button. If no value is passed, the text "Currently selected: selectedItem.name" will be used fully translated.
+Function called with the control's internal state changes. The `selectedItem` property contains the next selected item.
 
--   Type: `String`
 -   Required: No
 
-#### options
+#### `options`: `Array< Option >`
 
-The options that can be chosen from.
+The list of options that can be chosen from.
 
--   Type: `Array<{ key: String, name: String, style: ?{}, className: ?String, ...rest }>`
 -   Required: Yes
 
-#### onChange
+#### `size`: `'default' | 'small' | '\_\_unstable-large'`
 
-Function called with the control's internal state changes. The `selectedItem` property contains the next selected item.
+The size of the control.
+
+-   Default: `'default'`
+-   Required: No
+
+#### `showSelectedHint`: `boolean`
+
+Show the hint of the selected item in the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### value
+#### `value`: `Option`
 
 Can be used to externally control the value of the control, like in the `MyControlledCustomSelectControl` example above.
 
--   Type: `Object`
 -   Required: No
 
-#### onMouseOver
+#### `onMouseOver`: `MouseEventHandler< HTMLButtonElement >`
 
-A handler for onMouseOver events.
+A handler for `mouseover` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### onMouseOut
+#### `onMouseOut`: `MouseEventHandler< HTMLButtonElement >`
 
-A handler for onMouseOut events.
+A handler for `mouseout` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### onFocus
+#### `onFocus`: `FocusEventHandler< HTMLButtonElement >`
 
-A handler for onFocus events.
+A handler for `focus` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
-#### onBlur
+#### `onBlur`: `FocusEventHandler< HTMLButtonElement >`
 
-A handler for onBlur events.
+A handler for `blur` events on the trigger button.
 
--   Type: `Function`
 -   Required: No
 
 ## Related components