@wordpress/components 32.5.0 → 32.6.0

package/src/calendar/utils/use-localization-props.ts

@@ -10,10 +10,9 @@ import type { Modifiers, BaseProps } from '../types';
 
 function isLocaleRTL( localeCode: string ) {
 	const localeObj = new Intl.Locale( localeCode );
-	if ( 'getTextInfo' in localeObj ) {
-		// @ts-expect-error - getTextInfo is not typed yet
-		// see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo
-		return localeObj.getTextInfo().direction === 'rtl';
+	const direction = localeObj.getTextInfo?.().direction;
+	if ( direction ) {
+		return direction === 'rtl';
 	}
 	return [
 		'ar', // Arabic

package/src/checkbox-control/style.scss

@@ -17,7 +17,10 @@
 .components-checkbox-control__label {
 	// Ensure label is aligned with checkbox along X axis
 	line-height: var(--checkbox-input-size);
-	cursor: pointer;
+
+	.components-checkbox-control:not(:has(:disabled)) & {
+		cursor: var(--wpds-cursor-control);
+	}
 }
 
 .components-checkbox-control__input[type="checkbox"] {
@@ -25,7 +28,6 @@
 	background: $white;
 	color: $gray-900;
 	clear: none;
-	cursor: pointer;
 	display: inline-block;
 	line-height: 0;
 	margin: 0 $grid-unit-05 0 0;
@@ -46,12 +48,15 @@
 		@include button-style-outset__focus(var(--wp-admin-theme-color));
 	}
 
-	&:checked,
-	&:indeterminate {
+	&:not(:disabled):is(:checked, :indeterminate) {
 		background: $components-color-accent;
 		border-color: $components-color-accent;
 	}
 
+	&:not(:disabled) {
+		cursor: var(--wpds-cursor-control);
+	}
+
 	&:checked::before {
 		content: none;
 	}
@@ -73,7 +78,7 @@ svg.components-checkbox-control__indeterminate {
 	--checkmark-size: var(--checkbox-input-size);
 
 	fill: $white;
-	cursor: pointer;
+	cursor: var(--wpds-cursor-control);
 	position: absolute;
 	left: 50%;
 	top: 50%;
@@ -88,6 +93,13 @@ svg.components-checkbox-control__indeterminate {
 	}
 }
 
+.components-checkbox-control:has(:disabled) {
+	svg.components-checkbox-control__checked,
+	svg.components-checkbox-control__indeterminate {
+		fill: $components-color-gray-400;
+	}
+}
+
 .components-checkbox-control__help {
 	display: inline-block;
 	margin-inline-start: calc(var(--checkbox-input-size) + var(--checkbox-input-margin));

package/src/checkbox-control/types.ts

@@ -12,6 +12,10 @@ export type CheckboxControlProps = Pick<
 	BaseControlProps,
 	'__nextHasNoMarginBottom' | 'help'
 > & {
+	/**
+	 * Whether the checkbox should be disabled.
+	 */
+	disabled?: boolean;
 	/**
 	 * A function that receives the checked state (boolean) as input.
 	 */

package/src/circular-option-picker/style.scss

@@ -84,7 +84,7 @@ $color-palette-circle-spacing: 12px;
 		transition: 100ms box-shadow ease;
 	}
 
-	cursor: pointer;
+	cursor: var(--wpds-cursor-control);
 
 	&:hover {
 		// Override default button hover style.

package/src/color-palette/style.scss

@@ -16,7 +16,7 @@ $border-as-box-shadow: inset 0 0 0 $border-width rgba(0, 0, 0, 0.2);
 	height: $grid-unit-80;
 	width: 100%;
 	box-sizing: border-box;
-	cursor: pointer;
+	cursor: var(--wpds-cursor-control);
 	// Show a thin outline in Windows high contrast mode.
 	outline: 1px solid transparent;
 	border-radius: $radius-medium $radius-medium 0 0;

package/src/css.d.ts

@@ -1,3 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type * as CSS from 'csstype';
 
 // See: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/f6d4d15522356eba4a0267142834e3abc6b603fc/types/react/index.d.ts#L2580-L2587

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

@@ -76,6 +76,7 @@ const GradientTypePicker = ( {
 	);
 
 	if ( type === 'linear-gradient' && gradientAST.orientation ) {
+		// eslint-disable-next-line react-compiler/react-compiler -- false positive, see https://github.com/facebook/react/issues/29196
 		lastLinearOrientationAngle.current = Number(
 			gradientAST.orientation.value
 		);

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

@@ -13,7 +13,7 @@ import { __, sprintf } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
-import _CustomSelect from '../custom-select-control-v2/custom-select';
+import CustomSelect from '../custom-select-control-v2/custom-select';
 import CustomSelectItem from '../custom-select-control-v2/item';
 import * as Styled from '../custom-select-control-v2/styles';
 import type { CustomSelectProps, CustomSelectOption } from './types';
@@ -189,7 +189,7 @@ function CustomSelectControl< T extends CustomSelectOption >(
 
 	return (
 		<>
-			<_CustomSelect
+			<CustomSelect
 				aria-describedby={ descriptionId }
 				renderSelectedValue={ renderSelectedValue }
 				size={ translatedSize }
@@ -203,7 +203,7 @@ function CustomSelectControl< T extends CustomSelectOption >(
 				{ ...restProps }
 			>
 				{ children }
-			</_CustomSelect>
+			</CustomSelect>
 			<VisuallyHidden>
 				<span id={ descriptionId }>
 					{ getDescribedBy( selectedOption?.name, describedBy ) }

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

@@ -19,7 +19,7 @@ import type {
 	CustomSelectStore,
 	CustomSelectButtonProps,
 	CustomSelectButtonSize,
-	_CustomSelectInternalProps,
+	CustomSelectInternalProps,
 	_CustomSelectProps,
 } from './types';
 import InputBase from '../input-control/input-base';
@@ -85,8 +85,8 @@ const CustomSelectButton = ( {
 	);
 };
 
-function _CustomSelect(
-	props: _CustomSelectInternalProps &
+function CustomSelect(
+	props: CustomSelectInternalProps &
 		_CustomSelectProps &
 		CustomSelectStore &
 		CustomSelectButtonSize
@@ -161,4 +161,4 @@ function _CustomSelect(
 	);
 }
 
-export default _CustomSelect;
+export default CustomSelect;

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

@@ -5,7 +5,7 @@ import * as Ariakit from '@ariakit/react';
 /**
  * Internal dependencies
  */
-import _CustomSelect from './custom-select';
+import CustomSelect from './custom-select';
 import type { CustomSelectProps } from './types';
 import type { WordPressComponentProps } from '../context';
 import Item from './item';
@@ -21,7 +21,7 @@ function CustomSelectControlV2(
 		value,
 	} );
 
-	return <_CustomSelect { ...restProps } store={ store } />;
+	return <CustomSelect { ...restProps } store={ store } />;
 }
 
 CustomSelectControlV2.Item = Item;

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

@@ -50,7 +50,7 @@ export type CustomSelectButtonProps = {
 };
 
 // Props only exposed on the internal implementation
-export type _CustomSelectInternalProps = {
+export type CustomSelectInternalProps = {
 	/**
 	 * True if the consumer is emulating the legacy component behavior and look
 	 */

package/src/date-time/README.md

@@ -70,7 +70,7 @@ A callback function which receives a Date object representing a day as an argume
 
 -   Required: No
 
-### `onMonthPreviewed`: `( date: Date ) => void`
+### `onMonthPreviewed`: `( date: string ) => void`
 
 A callback invoked when selecting the previous/next month in the date picker. The callback receives the new month date in the ISO format as an argument.
 
@@ -87,5 +87,5 @@ List of events to show in the date picker. Each event will appear as a dot on th
 
 The day that the week should start on. 0 for Sunday, 1 for Monday, etc.
 
-- Required: No
-- Default: 0
+-   Required: No
+-   Default: 0

package/src/date-time/date-picker/README.md

@@ -0,0 +1,65 @@
+# DatePicker
+
+DatePicker is a React component that renders a calendar for date selection. It can be used independently or as part of the `DateTimePicker` component.
+
+## Usage
+
+Render a DatePicker.
+
+```jsx
+import { useState } from 'react';
+import { DatePicker } from '@wordpress/components';
+
+const MyDatePicker = () => {
+	const [ date, setDate ] = useState( new Date() );
+
+	return (
+		<DatePicker
+			currentDate={ date }
+			onChange={ ( newDate ) => setDate( newDate ) }
+		/>
+	);
+};
+```
+
+## Props
+
+The component accepts the following props:
+
+### `currentDate`: `Date | string | number | null`
+
+The current date at initialization. Optionally pass in a `null` value to specify no date is currently selected.
+
+-   Required: No
+-   Default: today's date
+
+### `onChange`: `( date: string ) => void`
+
+The function called when a new date has been selected. It is passed the `currentDate` as an argument.
+
+-   Required: No
+
+### `events`: `{ date: Date }[]`
+
+List of events to show in the date picker. Each event will appear as a dot on the day of the event.
+
+-   Required: No
+
+### `isInvalidDate`: `( date: Date ) => boolean`
+
+A callback function which receives a Date object representing a day as an argument, and should return a Boolean to signify if the day is valid or not.
+
+-   Required: No
+
+### `onMonthPreviewed`: `( date: string ) => void`
+
+A callback invoked when selecting the previous/next month in the date picker. The callback receives the new month date in the ISO format as an argument.
+
+-   Required: No
+
+### `startOfWeek`: `0 | 1 | 2 | 3 | 4 | 5 | 6`
+
+The day that the week should start on. 0 for Sunday, 1 for Monday, etc.
+
+-   Required: No
+-   Default: 0

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

@@ -11,8 +11,8 @@ import { forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { default as DatePicker } from '../date';
-import { default as TimePicker } from '../time';
+import { default as DatePicker } from '../date-picker';
+import { default as TimePicker } from '../time-picker';
 import type { DateTimePickerProps } from '../types';
 import { Wrapper } from './styles';
 

package/src/date-time/index.ts

@@ -1,8 +1,8 @@
 /**
  * Internal dependencies
  */
-import { default as DatePicker } from './date';
-import { default as TimePicker } from './time';
+import { default as DatePicker } from './date-picker';
+import { default as TimePicker } from './time-picker';
 import { default as DateTimePicker } from './date-time';
 
 export { DatePicker, TimePicker };

package/src/date-time/stories/date.story.tsx

@@ -11,7 +11,7 @@ import { useState, useEffect } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import DatePicker from '../date';
+import DatePicker from '../date-picker';
 import { daysFromNow, isWeekend } from './utils';
 
 const meta: Meta< typeof DatePicker > = {

package/src/date-time/stories/time.story.tsx

@@ -11,7 +11,7 @@ import { useState, useEffect } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import TimePicker from '../time';
+import TimePicker from '../time-picker';
 
 const meta: Meta< typeof TimePicker > = {
 	title: 'Components/Selection & Input/Time & Date/TimePicker',

package/src/date-time/time-picker/README.md

@@ -0,0 +1,119 @@
+# TimePicker
+
+TimePicker is a React component that renders form inputs for time and date selection. It can be used independently or as part of the `DateTimePicker` component.
+
+**Note:** `TimePicker` also exposes a compound sub-component, `TimePicker.TimeInput`, which can be used independently to render a time input field without the full picker UI.
+
+## Usage
+
+Render a TimePicker.
+
+```jsx
+import { useState } from 'react';
+import { TimePicker } from '@wordpress/components';
+
+const MyTimePicker = () => {
+	const [ time, setTime ] = useState( new Date() );
+
+	return (
+		<TimePicker
+			currentTime={ time }
+			onChange={ ( newTime ) => setTime( newTime ) }
+			is12Hour
+		/>
+	);
+};
+```
+
+## Props
+
+The component accepts the following props:
+
+### `currentTime`: `Date | string | number | null`
+
+The current time at initialization. Optionally pass in a `null` value to specify no time is currently selected.
+
+-   Required: No
+-   Default: current time
+
+### `onChange`: `( time: string ) => void`
+
+The function called when a new time has been selected. It is passed the time as an ISO-formatted string.
+
+-   Required: No
+
+### `is12Hour`: `boolean`
+
+Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is displayed.
+
+-   Required: No
+-   Default: false
+
+### `dateOrder`: `'dmy' | 'mdy' | 'ymd'`
+
+The order of day, month, and year. This prop overrides the time format determined by `is12Hour` prop.
+
+-   Required: No
+-   Default: `'dmy'` (or `'mdy'` when `is12Hour` is `true`)
+
+### `hideLabelFromVision`: `boolean`
+
+Whether to visually hide field labels while keeping them accessible to screen readers.
+
+-   Required: No
+-   Default: false
+
+## TimePicker.TimeInput
+
+A standalone time input component. Values are passed as an object in 24-hour format (`{ hours: number, minutes: number }`).
+
+### Usage
+
+```jsx
+import { useState } from 'react';
+import { TimePicker } from '@wordpress/components';
+
+const MyTimeInput = () => {
+	const [ time, setTime ] = useState( { hours: 13, minutes: 30 } );
+
+	return (
+		<TimePicker.TimeInput
+			value={ time }
+			onChange={ setTime }
+			label="Time"
+		/>
+	);
+};
+```
+
+### Props
+
+#### `value`: `{ hours: number, minutes: number }`
+
+The time input value in 24-hour format.
+
+-   Required: No
+
+#### `defaultValue`: `{ hours: number, minutes: number }`
+
+An optional default value for the control when used in uncontrolled mode. If left `undefined`, the current time will be used.
+
+-   Required: No
+
+#### `onChange`: `( time: { hours: number, minutes: number } ) => void`
+
+Called when the time changes. Receives the new value as an object with `hours` and `minutes`.
+
+-   Required: No
+
+#### `is12Hour`: `boolean`
+
+Whether to use a 12-hour clock. With a 12-hour clock, an AM/PM widget is displayed.
+
+-   Required: No
+
+#### `label`: `string`
+
+The label for the time input.
+
+-   Required: No

package/src/date-time/{time → time-picker}/index.tsx

@@ -30,7 +30,7 @@ import { TimeInput } from './time-input';
 const VALID_DATE_ORDERS = [ 'dmy', 'mdy', 'ymd' ];
 
 /**
- * TimePicker is a React component that renders a clock for time selection.
+ * TimePicker is a React component that renders form inputs for time and date selection. It can be used independently or as part of the `DateTimePicker` component.
  *
  * ```jsx
  * import { TimePicker } from '@wordpress/components';

package/src/date-time/types.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import type { MinutesInput } from './time/styles';
+import type { MinutesInput } from './time-picker/styles';
 
 export type TimePickerProps = {
 	/**

package/src/divider/README.md

@@ -11,17 +11,16 @@ This feature is still experimental. “Experimental” means this is an early im
 ```jsx
 import {
 	__experimentalDivider as Divider,
-	__experimentalText as Text,
-	__experimentalVStack as VStack,
 } from `@wordpress/components`;
+import { Stack } from '@wordpress/ui';
 
 function Example() {
 	return (
-		<VStack spacing={4}>
-			<Text>Some text here</Text>
+		<Stack direction="column" gap="lg">
+			<span>Some text here</span>
 			<Divider />
-			<Text>Some more text here</Text>
-		</VStack>
+			<span>Some more text here</span>
+		</Stack>
 	);
 }
 ```

package/src/dropdown-menu/style.scss

@@ -16,7 +16,7 @@
 		width: 100%;
 		padding: 6px;
 		outline: none;
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 		white-space: nowrap;
 		font-weight: $font-weight-regular;
 

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

@@ -34,7 +34,7 @@ const meta: Meta< typeof Flex > = {
 		componentStatus: {
 			status: 'not-recommended',
 			whereUsed: 'global',
-			notes: 'Planned for deprecation. For use cases not covered by `HStack` and `VStack`, write your own CSS.',
+			notes: 'Planned for deprecation. For use cases not covered by `Stack` from `@wordpress/ui`, write your own CSS.',
 		},
 	},
 };

package/src/form-file-upload/README.md

@@ -48,7 +48,7 @@ Children are passed as children of `Button`.
 
 ### `icon`
 
- - Type: `IconType`
+ - Type: `IconType | null`
  - Required: No
 
 The icon to render in the default button.
@@ -65,7 +65,7 @@ Whether to allow multiple selection of files or not.
 
 ### `onChange`
 
- - Type: `ChangeEventHandler<HTMLInputElement>`
+ - Type: `ChangeEventHandler<HTMLInputElement> | undefined`
  - Required: Yes
 
 Callback function passed directly to the `input` file element.
@@ -95,7 +95,7 @@ an empty string in the `onClick` function.
 
 ### `render`
 
- - Type: `(arg: { openFileDialog: () => void; }) => ReactNode`
+ - Type: `((arg: { openFileDialog: () => void; }) => ReactNode)`
  - Required: No
 
 Optional callback function used to render the UI.

package/src/form-toggle/style.scss

@@ -104,7 +104,40 @@ $transition-duration: 0.2s;
 	// Disabled state:
 	&.is-disabled,
 	.components-disabled & {
-		opacity: 0.3;
+		.components-form-toggle__track {
+			background-color: $components-color-gray-100;
+			border-color: $components-color-gray-300;
+
+			@media ( forced-colors: active ) {
+				border-color: GrayText;
+			}
+		}
+
+		.components-form-toggle__thumb {
+			background-color: $components-color-gray-400;
+			box-shadow: none;
+
+			@media ( forced-colors: active ) {
+				border-color: GrayText;
+			}
+		}
+
+		&.is-checked .components-form-toggle__track {
+			background-color: $components-color-gray-400;
+			border-color: $components-color-gray-400;
+
+			@media ( forced-colors: active ) {
+				border-color: GrayText;
+
+				&::after {
+					border-top-color: GrayText;
+				}
+			}
+		}
+
+		&.is-checked .components-form-toggle__thumb {
+			background-color: $white;
+		}
 	}
 }
 
@@ -132,6 +165,6 @@ $transition-duration: 0.2s;
 	}
 
 	&:not(:disabled, [aria-disabled="true"]) {
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 	}
 }

package/src/form-token-field/style.scss

@@ -11,8 +11,9 @@
 	cursor: text;
 
 	&.is-disabled {
-		background: $gray-300;
-		border-color: $gray-300;
+		background: $components-color-gray-100;
+		border-color: $components-color-gray-400;
+		cursor: default;
 	}
 
 	&.is-active {
@@ -82,6 +83,14 @@
 		}
 	}
 
+	&.is-disabled {
+		.components-form-token-field__token-text,
+		.components-form-token-field__remove-token.components-button {
+			background: $components-color-gray-100;
+			color: $components-color-gray-600;
+		}
+	}
+
 	&.is-borderless {
 		position: relative;
 		padding: 0 24px 0 0;
@@ -198,6 +207,6 @@
 	}
 
 	&:not(.is-empty) {
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 	}
 }

package/src/gradient-picker/README.md

@@ -141,7 +141,7 @@ Only used when `asButtons` is not true.
 
 ### `onChange`
 
- - Type: `(currentGradient: string) => void`
+ - Type: `(currentGradient: string | undefined) => void`
  - Required: Yes
 
 The function called when a new gradient has been defined. It is passed to
@@ -149,7 +149,7 @@ the `currentGradient` as an argument.
 
 ### `value`
 
- - Type: `string`
+ - Type: `string | null`
  - Required: No
  - Default: `'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'`