@wordpress/components 28.5.0 → 28.6.0

package/src/composite/types.ts

@@ -0,0 +1,298 @@
+/**
+ * External dependencies
+ */
+import type * as Ariakit from '@ariakit/react';
+
+export type CompositeContextProps =
+	| {
+			/**
+			 * Object returned by the `useCompositeStore` hook.
+			 */
+			store: Ariakit.CompositeStore;
+	  }
+	| undefined;
+
+export type CompositeStoreProps = {
+	/**
+	 * The current active item `id`. The active item is the element within the
+	 * composite widget that has either DOM or virtual focus (in case
+	 * the `virtualFocus` prop is enabled).
+	 * - `null` represents the base composite element (the one with a [composite
+	 *   role](https://w3c.github.io/aria/#composite)). Users will be able to
+	 *   navigate out of it using arrow keys.
+	 * - If `activeId` is initially set to `null`, the base composite element
+	 *   itself will have focus and users will be able to navigate to it using
+	 *   arrow keys.
+	 */
+	activeId?: Ariakit.CompositeStoreProps[ 'activeId' ];
+	/**
+	 * The composite item id that should be active by default when the composite
+	 * widget is rendered. If `null`, the composite element itself will have focus
+	 * and users will be able to navigate to it using arrow keys. If `undefined`,
+	 * the first enabled item will be focused.
+	 */
+	defaultActiveId?: Ariakit.CompositeStoreProps[ 'defaultActiveId' ];
+	/**
+	 * A callback that gets called when the `activeId` state changes.
+	 */
+	setActiveId?: Ariakit.CompositeStoreProps[ 'setActiveId' ];
+	/**
+	 * Determines how the focus behaves when the user reaches the end of the
+	 * composite widget.
+	 *
+	 * On one-dimensional composite widgets:
+	 * - `true` loops from the last item to the first item and vice-versa.
+	 * - `horizontal` loops only if `orientation` is `horizontal` or not set.
+	 * - `vertical` loops only if `orientation` is `vertical` or not set.
+	 * - If `activeId` is initially set to `null`, the composite element will
+	 *   be focused in between the last and first items.
+	 *
+	 * On two-dimensional composite widgets (ie. when using `CompositeRow`):
+	 * - `true` loops from the last row/column item to the first item in the same
+	 *   row/column and vice-versa. If it's the last item in the last row, it
+	 *   moves to the first item in the first row and vice-versa.
+	 * - `horizontal` loops only from the last row item to the first item in the
+	 *   same row.
+	 * - `vertical` loops only from the last column item to the first item in the
+	 *   column row.
+	 * - If `activeId` is initially set to `null`, vertical loop will have no
+	 *   effect as moving down from the last row or up from the first row will
+	 *   focus on the composite element.
+	 * - If `focusWrap` matches the value of `focusLoop`, it'll wrap between the
+	 *   last item in the last row or column and the first item in the first row or
+	 *   column and vice-versa.
+	 *
+	 * @default false
+	 */
+	focusLoop?: Ariakit.CompositeStoreProps[ 'focusLoop' ];
+	/**
+	 * **Works only on two-dimensional composite widgets**.
+	 *
+	 * If enabled, moving to the next item from the last one in a row or column
+	 * will focus on the first item in the next row or column and vice-versa.
+	 * - `true` wraps between rows and columns.
+	 * - `horizontal` wraps only between rows.
+	 * - `vertical` wraps only between columns.
+	 * - If `focusLoop` matches the value of `focusWrap`, it'll wrap between the
+	 *   last item in the last row or column and the first item in the first row or
+	 *   column and vice-versa.
+	 *
+	 * @default false
+	 */
+	focusWrap?: Ariakit.CompositeStoreProps[ 'focusWrap' ];
+	/**
+	 * **Works only on two-dimensional composite widgets**.
+	 *
+	 * If enabled, moving up or down when there's no next item or when the next
+	 * item is disabled will shift to the item right before it.
+	 *
+	 * @default false
+	 */
+	focusShift?: Ariakit.CompositeStoreProps[ 'focusShift' ];
+	/**
+	 * If enabled, the composite element will act as an
+	 * [`aria-activedescendant`](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant)
+	 * container instead of [roving
+	 * tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex).
+	 * DOM focus will remain on the composite element while its items receive
+	 * virtual focus.
+	 *
+	 * In both scenarios, the item in focus will carry the `data-active-item`
+	 * attribute.
+	 *
+	 * @default false
+	 */
+	virtualFocus?: Ariakit.CompositeStoreProps[ 'virtualFocus' ];
+	/**
+	 * Defines the orientation of the composite widget. If the composite has a
+	 * single row or column (one-dimensional), the `orientation` value determines
+	 * which arrow keys can be used to move focus:
+	 * - `both`: all arrow keys work.
+	 * - `horizontal`: only left and right arrow keys work.
+	 * - `vertical`: only up and down arrow keys work.
+	 *
+	 * It doesn't have any effect on two-dimensional composites.
+	 *
+	 * @default "both"
+	 */
+	orientation?: Ariakit.CompositeStoreProps[ 'orientation' ];
+	/**
+	 * Determines how the `store`'s `next` and `previous` functions will behave.
+	 * If `rtl` is set to `true`, they will be inverted.
+	 *
+	 * This only affects the composite widget behavior. You still need to set
+	 * `dir="rtl"` on HTML/CSS.
+	 *
+	 * @default false
+	 */
+	rtl?: Ariakit.CompositeStoreProps[ 'rtl' ];
+};
+
+export type CompositeProps = {
+	/**
+	 * Object returned by the `useCompositeStore` hook.
+	 */
+	store: Ariakit.CompositeStore;
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeProps[ 'render' ];
+	/**
+	 * Makes the component a focusable element. When this element gains keyboard
+	 * focus, it gets a `data-focus-visible` attribute and triggers the
+	 * `onFocusVisible` prop.
+	 * The component supports the `disabled` prop even for those elements not
+	 * supporting the native `disabled` attribute. Disabled elements may be
+	 * still accessible via keyboard by using the the `accessibleWhenDisabled`
+	 * prop.
+	 * Non-native focusable elements will lose their focusability entirely.
+	 * However, native focusable elements will retain their inherent focusability.
+	 */
+	focusable?: Ariakit.CompositeProps[ 'focusable' ];
+	/**
+	 * Determines if the element is disabled. This sets the `aria-disabled`
+	 * attribute accordingly, enabling support for all elements, including those
+	 * that don't support the native `disabled` attribute.
+	 *
+	 * This feature can be combined with the `accessibleWhenDisabled` prop to
+	 * make disabled elements still accessible via keyboard.
+	 *
+	 * **Note**: For this prop to work, the `focusable` prop must be set to
+	 * `true`, if it's not set by default.
+	 *
+	 * @default false
+	 */
+	disabled?: Ariakit.CompositeProps[ 'disabled' ];
+	/**
+	 * Indicates whether the element should be focusable even when it is
+	 * `disabled`.
+	 *
+	 * This is important when discoverability is a concern. For example:
+	 *
+	 * > A toolbar in an editor contains a set of special smart paste functions
+	 * that are disabled when the clipboard is empty or when the function is not
+	 * applicable to the current content of the clipboard. It could be helpful to
+	 * keep the disabled buttons focusable if the ability to discover their
+	 * functionality is primarily via their presence on the toolbar.
+	 *
+	 * Learn more on [Focusability of disabled
+	 * controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols).
+	 */
+	accessibleWhenDisabled?: Ariakit.CompositeProps[ 'accessibleWhenDisabled' ];
+	/**
+	 * Custom event handler invoked when the element gains focus through keyboard
+	 * interaction or a key press occurs while the element is in focus. This is
+	 * the programmatic equivalent of the `data-focus-visible` attribute.
+	 *
+	 * **Note**: For this prop to work, the `focusable` prop must be set to `true`
+	 * if it's not set by default.
+	 */
+	onFocusVisible?: Ariakit.CompositeProps[ 'onFocusVisible' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeProps[ 'children' ];
+};
+
+export type CompositeGroupProps = {
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeGroupProps[ 'render' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeGroupProps[ 'children' ];
+};
+
+export type CompositeGroupLabelProps = {
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeGroupLabelProps[ 'render' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeGroupLabelProps[ 'children' ];
+};
+
+export type CompositeItemProps = {
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeItemProps[ 'render' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeItemProps[ 'children' ];
+	/**
+	 * Indicates whether the element should be focusable even when it is
+	 * `disabled`.
+	 *
+	 * This is important when discoverability is a concern. For example:
+	 *
+	 * > A toolbar in an editor contains a set of special smart paste functions
+	 * that are disabled when the clipboard is empty or when the function is not
+	 * applicable to the current content of the clipboard. It could be helpful to
+	 * keep the disabled buttons focusable if the ability to discover their
+	 * functionality is primarily via their presence on the toolbar.
+	 *
+	 * Learn more on [Focusability of disabled
+	 * controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols).
+	 */
+	accessibleWhenDisabled?: Ariakit.CompositeItemProps[ 'accessibleWhenDisabled' ];
+};
+
+export type CompositeRowProps = {
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeRowProps[ 'render' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeRowProps[ 'children' ];
+};
+
+export type CompositeHoverProps = {
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeHoverProps[ 'render' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeHoverProps[ 'children' ];
+};
+
+export type CompositeTypeaheadProps = {
+	/**
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 */
+	render?: Ariakit.CompositeTypeaheadProps[ 'render' ];
+	/**
+	 * The contents of the component.
+	 */
+	children?: Ariakit.CompositeTypeaheadProps[ 'children' ];
+};

package/src/custom-gradient-picker/style.scss

@@ -1,7 +1,7 @@
 $components-custom-gradient-picker__padding: $grid-unit-20; // 48px container, 16px handles inside, that leaves 32px padding, half of which is 1å6.
 
 .components-custom-gradient-picker__gradient-bar {
-	border-radius: $radius-block-ui;
+	border-radius: $radius-small;
 	width: 100%;
 	height: $grid-unit-60;
 	position: relative;
@@ -112,7 +112,7 @@ $components-custom-gradient-picker__padding: $grid-unit-20; // 48px container, 1
 		&.is-pressed {
 			> svg {
 				background: $white;
-				border: 1px solid $gray-600;
+				border: $border-width solid $gray-600;
 				border-radius: 2px;
 			}
 		}

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

@@ -142,6 +142,13 @@ A handler for `blur` events on the trigger button.
 
 -   Required: No
 
+#### `__next40pxDefaultSize`: `boolean`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+- Required: No
+- Default: `false`
+
 ## Related components
 
 -   Like this component, but implemented using a native `<select>` for when custom styling is not necessary, the `SelectControl` component.

package/src/custom-select-control/test/index.tsx

@@ -689,3 +689,128 @@ describe.each( [
 		} );
 	} );
 } );
+
+describe( 'Type checking', () => {
+	// eslint-disable-next-line jest/expect-expect
+	it( 'should infer the value type from available `options`, but not the `value` or `onChange` prop', () => {
+		const options = [
+			{
+				key: 'narrow',
+				name: 'Narrow',
+			},
+			{
+				key: 'value',
+				name: 'Value',
+			},
+		];
+		const optionsReadOnly = [
+			{
+				key: 'narrow',
+				name: 'Narrow',
+			},
+			{
+				key: 'value',
+				name: 'Value',
+			},
+		] as const;
+
+		const onChange = (): void => {};
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'random string is also accepted for non-readonly options',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+				// @ts-expect-error: the option type should not be inferred from `value`
+				foo: 'foo',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			// To ensure the type inferring is working correctly, but this is not a common use case.
+			// @ts-expect-error: the option type should not be inferred from `onChange`
+			onChange={
+				onChange as ( obj: {
+					selectedItem: { key: string; name: string; foo: string };
+				} ) => void
+			}
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				// @ts-expect-error: random string is not accepted for immutable options
+				key: 'random string is not accepted for readonly options',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+				// @ts-expect-error: the option type should not be inferred from `value`
+				foo: 'foo',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			// To ensure the type inferring is working correctly, but this is not a common use case.
+			// @ts-expect-error: the option type should not be inferred from `onChange`
+			onChange={
+				onChange as ( obj: {
+					selectedItem: { key: string; name: string; foo: string };
+				} ) => void
+			}
+		/>;
+	} );
+} );

package/src/custom-select-control/types.ts

@@ -55,7 +55,7 @@ export type CustomSelectProps< T extends CustomSelectOption > = {
 	 * Function called with the control's internal state changes. The `selectedItem`
 	 * property contains the next selected item.
 	 */
-	onChange?: ( newValue: CustomSelectChangeObject< T > ) => void;
+	onChange?: ( newValue: CustomSelectChangeObject< NoInfer< T > > ) => void;
 	/**
 	 * A handler for `blur` events on the trigger button.
 	 *
@@ -83,7 +83,7 @@ export type CustomSelectProps< T extends CustomSelectOption > = {
 	/**
 	 * The list of options that can be chosen from.
 	 */
-	options: Array< T >;
+	options: ReadonlyArray< T >;
 	/**
 	 * The size of the control.
 	 *
@@ -93,7 +93,7 @@ export type CustomSelectProps< T extends CustomSelectOption > = {
 	/**
 	 * Can be used to externally control the value of the control.
 	 */
-	value?: T;
+	value?: NoInfer< T >;
 	/**
 	 * Use the `showSelectedHint` property instead.
 	 * @deprecated

package/src/custom-select-control-v2/custom-select.tsx

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
+import { useStoreState } from '@ariakit/react';
 
 /**
  * WordPress dependencies
@@ -62,7 +63,7 @@ const CustomSelectButton = ( {
 		CustomSelectStore,
 	'onChange'
 > ) => {
-	const { value: currentValue } = store.useState();
+	const { value: currentValue } = useStoreState( store );
 
 	const computedRenderSelectedValue = useMemo(
 		() => renderSelectedValue ?? defaultRenderSelectedValue,

package/src/date-time/time/index.tsx

@@ -13,6 +13,7 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import BaseControl from '../../base-control';
+import { VisuallyHidden } from '../../visually-hidden';
 import SelectControl from '../../select-control';
 import TimeZone from './timezone';
 import type { TimeInputValue, TimePickerProps } from '../types';
@@ -61,6 +62,7 @@ export function TimePicker( {
 	currentTime,
 	onChange,
 	dateOrder: dateOrderProp,
+	hideLabelFromVision = false,
 }: TimePickerProps ) {
 	const [ date, setDate ] = useState( () =>
 		// Truncate the date at the minutes, see: #15495.
@@ -219,12 +221,18 @@ export function TimePicker( {
 			className="components-datetime__time" // Unused, for backwards compatibility.
 		>
 			<Fieldset>
-				<BaseControl.VisualLabel
-					as="legend"
-					className="components-datetime__time-legend" // Unused, for backwards compatibility.
-				>
-					{ __( 'Time' ) }
-				</BaseControl.VisualLabel>
+				{ hideLabelFromVision ? (
+					<VisuallyHidden as="legend">
+						{ __( 'Time' ) }
+					</VisuallyHidden>
+				) : (
+					<BaseControl.VisualLabel
+						as="legend"
+						className="components-datetime__time-legend" // Unused, for backwards compatibility.
+					>
+						{ __( 'Time' ) }
+					</BaseControl.VisualLabel>
+				) }
 				<HStack
 					className="components-datetime__time-wrapper" // Unused, for backwards compatibility.
 				>
@@ -241,12 +249,18 @@ export function TimePicker( {
 				</HStack>
 			</Fieldset>
 			<Fieldset>
-				<BaseControl.VisualLabel
-					as="legend"
-					className="components-datetime__time-legend" // Unused, for backwards compatibility.
-				>
-					{ __( 'Date' ) }
-				</BaseControl.VisualLabel>
+				{ hideLabelFromVision ? (
+					<VisuallyHidden as="legend">
+						{ __( 'Date' ) }
+					</VisuallyHidden>
+				) : (
+					<BaseControl.VisualLabel
+						as="legend"
+						className="components-datetime__time-legend" // Unused, for backwards compatibility.
+					>
+						{ __( 'Date' ) }
+					</BaseControl.VisualLabel>
+				) }
 				<HStack
 					className="components-datetime__time-wrapper" // Unused, for backwards compatibility.
 				>

package/src/date-time/types.ts

@@ -29,6 +29,13 @@ export type TimePickerProps = {
 	 * time as an argument.
 	 */
 	onChange?: ( time: string ) => void;
+
+	/**
+	 * If true, the label will only be visible to screen readers.
+	 *
+	 * @default false
+	 */
+	hideLabelFromVision?: boolean;
 };
 
 export type TimeInputValue = {
@@ -130,7 +137,10 @@ export type DatePickerProps = {
 };
 
 export type DateTimePickerProps = Omit< DatePickerProps, 'onChange' > &
-	Omit< TimePickerProps, 'currentTime' | 'onChange' > & {
+	Omit<
+		TimePickerProps,
+		'currentTime' | 'onChange' | 'hideLabelFromVision'
+	> & {
 		/**
 		 * The function called when a new date or time has been selected. It is
 		 * passed the date and time as an argument.

package/src/dimension-control/README.md

@@ -17,6 +17,7 @@ export default function MyCustomDimensionControl() {
 
 	return (
 		<DimensionControl
+			__nextHasNoMarginBottom
 			label={ 'Padding' }
 			icon={ 'desktop' }
 			onChange={ ( value ) => setPaddingSize( value ) }
@@ -91,3 +92,19 @@ A callback which is triggered when a spacing size value changes (is selected/cli
 -   **Required:** No
 
 A string of classes to be added to the control component.
+
+### `__next40pxDefaultSize`
+
+-   **Type:** `Boolean`
+-   **Required:** No
+-   **Default:** `false`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+### `__nextHasNoMarginBottom`
+
+-   **Type:** `Boolean`
+-   **Required:** No
+-   **Default:** `false`
+
+Start opting into the new margin-free styles that will become the default in a future version.

package/src/dimension-control/index.tsx

@@ -16,6 +16,15 @@ import SelectControl from '../select-control';
 import sizesTable, { findSizeBySlug } from './sizes';
 import type { DimensionControlProps, Size } from './types';
 import type { SelectControlSingleSelectionProps } from '../select-control/types';
+import { ContextSystemProvider } from '../context';
+
+const CONTEXT_VALUE = {
+	BaseControl: {
+		// Temporary during deprecation grace period: Overrides the underlying `__associatedWPComponentName`
+		// via the context system to override the value set by SelectControl.
+		_overrides: { __associatedWPComponentName: 'DimensionControl' },
+	},
+};
 
 /**
  * `DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
@@ -31,6 +40,7 @@ import type { SelectControlSingleSelectionProps } from '../select-control/types'
  *
  * 	return (
  * 		<DimensionControl
+ * 			__nextHasNoMarginBottom
  * 			label={ 'Padding' }
  * 			icon={ 'desktop' }
  * 			onChange={ ( value ) => setPaddingSize( value ) }
@@ -43,6 +53,7 @@ import type { SelectControlSingleSelectionProps } from '../select-control/types'
 export function DimensionControl( props: DimensionControlProps ) {
 	const {
 		__next40pxDefaultSize = false,
+		__nextHasNoMarginBottom = false,
 		label,
 		value,
 		sizes = sizesTable,
@@ -85,15 +96,21 @@ export function DimensionControl( props: DimensionControlProps ) {
 	);
 
 	return (
-		<SelectControl
-			__next40pxDefaultSize={ __next40pxDefaultSize }
-			className={ clsx( className, 'block-editor-dimension-control' ) }
-			label={ selectLabel }
-			hideLabelFromVision={ false }
-			value={ value }
-			onChange={ onChangeSpacingSize }
-			options={ formatSizesAsOptions( sizes ) }
-		/>
+		<ContextSystemProvider value={ CONTEXT_VALUE }>
+			<SelectControl
+				__next40pxDefaultSize={ __next40pxDefaultSize }
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				className={ clsx(
+					className,
+					'block-editor-dimension-control'
+				) }
+				label={ selectLabel }
+				hideLabelFromVision={ false }
+				value={ value }
+				onChange={ onChangeSpacingSize }
+				options={ formatSizesAsOptions( sizes ) }
+			/>
+		</ContextSystemProvider>
 	);
 }