@wordpress/components 32.5.2-next.v.202604091042.0 → 33.0.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/disabled/stories/index.story.tsx

@@ -18,6 +18,7 @@ import TextareaControl from '../../textarea-control/';
 import { VStack } from '../../v-stack/';
 
 const meta: Meta< typeof Disabled > = {
+	tags: [ 'manifest' ],
 	title: 'Components/Utilities/Disabled',
 	id: 'components-disabled',
 	component: Disabled,

package/src/drop-zone/stories/index.story.tsx

@@ -17,6 +17,7 @@ import DropZone from '..';
 const ICONS = { upload, media };
 
 const meta: Meta< typeof DropZone > = {
+	tags: [ 'manifest' ],
 	component: DropZone,
 	id: 'components-dropzone',
 	title: 'Components/Selection & Input/File Upload/DropZone',

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

@@ -14,6 +14,7 @@ import MenuItem from '../../menu-item';
 import { DropdownContentWrapper } from '../dropdown-content-wrapper';
 
 const meta: Meta< typeof Dropdown > = {
+	tags: [ 'manifest' ],
 	title: 'Components/Overlays/Dropdown',
 	id: 'components-dropdown',
 	component: Dropdown,

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/external-link/index.tsx

@@ -26,12 +26,7 @@ function UnforwardedExternalLink(
 	const { href, children, className, rel = '', ...additionalProps } = props;
 	const optimizedRel = [
 		...new Set(
-			[
-				...rel.split( ' ' ),
-				'external',
-				'noreferrer',
-				'noopener',
-			].filter( Boolean )
+			[ ...rel.split( ' ' ), 'external', 'noopener' ].filter( Boolean )
 		),
 	].join( ' ' );
 	const classes = clsx( 'components-external-link', className );

package/src/external-link/stories/index.story.tsx

@@ -21,8 +21,9 @@ const meta: Meta< typeof ExternalLink > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'not-recommended',
 			whereUsed: 'global',
+			notes: 'Use `Link` from `@wordpress/ui` instead, with the `openInNewTab` prop set.',
 		},
 	},
 };

package/src/external-link/style.scss

@@ -1,12 +1,40 @@
 .components-external-link {
+	color: var(--wpds-color-fg-interactive-brand);
 	text-decoration: none;
+
+	// Match the `outset-ring--focus` utility used by `Link` in `@wordpress/ui`.
+	@media not ( prefers-reduced-motion ) {
+		transition: outline 0.1s ease-out;
+	}
+	// Outline width must be kept at 0 even with a transparent color,
+	// or else the outline will be visible in forced-colors mode.
+	outline: 0 solid transparent;
+	outline-offset: 1px;
+
+	&:visited {
+		color: var(--wpds-color-fg-interactive-brand);
+	}
+
+	&:hover,
+	&:active {
+		color: var(--wpds-color-fg-interactive-brand-active);
+	}
+
+	&:focus {
+		outline:
+			var(--wpds-border-width-focus) solid
+			var(--wpds-color-stroke-focus-brand);
+	}
 }
 
 .components-external-link__contents {
 	text-decoration: underline;
+	text-underline-offset: 0.2em;
+	text-decoration-thickness: from-font;
 }
 
 .components-external-link__icon {
-	margin-left: 0.5ch;
-	font-weight: 400;
+	display: inline-block;
+	margin-inline-start: var(--wpds-dimension-padding-xs);
+	font-weight: var(--wpds-typography-font-weight-regular);
 }

package/src/form-file-upload/stories/index.story.tsx

@@ -14,6 +14,7 @@ import { upload as uploadIcon } from '@wordpress/icons';
 import FormFileUpload from '..';
 
 const meta: Meta< typeof FormFileUpload > = {
+	tags: [ 'manifest' ],
 	title: 'Components/Selection & Input/File Upload/FormFileUpload',
 	id: 'components-formfileupload',
 	component: FormFileUpload,

package/src/form-toggle/stories/index.story.tsx

@@ -14,6 +14,7 @@ import { useState } from '@wordpress/element';
 import FormToggle from '..';
 
 const meta: Meta< typeof FormToggle > = {
+	tags: [ 'manifest' ],
 	component: FormToggle,
 	title: 'Components/FormToggle',
 	argTypes: {

package/src/form-toggle/style.scss

@@ -2,7 +2,6 @@
 @use "@wordpress/base-styles/colors" as *;
 @use "@wordpress/base-styles/mixins" as *;
 @use "@wordpress/base-styles/variables" as *;
-@use "@wordpress/base-styles/z-index" as *;
 @use "../utils/theme-variables" as *;
 
 $toggle-width: $grid-unit-40;
@@ -14,6 +13,7 @@ $transition-duration: 0.2s;
 
 .components-form-toggle {
 	position: relative;
+	isolation: isolate;
 	display: inline-block;
 	height: $toggle-height;
 
@@ -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;
+		}
 	}
 }
 
@@ -118,7 +151,8 @@ $transition-duration: 0.2s;
 	opacity: 0;
 	margin: 0;
 	padding: 0;
-	z-index: z-index(".components-form-toggle__input");
+	// Sit above the visual track and thumb so the invisible input receives pointer events.
+	z-index: 1;
 
 	// This overrides a border style that is inherited from parent checkbox styles.
 	border: none;
@@ -132,6 +166,6 @@ $transition-duration: 0.2s;
 	}
 
 	&:not(:disabled, [aria-disabled="true"]) {
-		cursor: pointer;
+		cursor: var(--wpds-cursor-control);
 	}
 }

package/src/form-token-field/README.md

@@ -51,6 +51,7 @@ The `value` property is handled in a manner similar to controlled form component
 -   `maxLength` - If passed, `TokenField` will disable ability to add new tokens once number of tokens is greater than or equal to `maxLength`.
 -   `disabled` - When true, tokens are not able to be added or removed.
 -   `placeholder` - If passed, the `TokenField` input will show a placeholder string if no value tokens are present.
+-   `help` - Additional description for the control. Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the `FormTokenField` via `aria-describedby`. Defaults to a how-to message (e.g. _Separate with commas or the Enter key._); pass an empty string to hide it.
 -   `messages` - Allows customizing the messages presented by screen readers in different occasions:
     -   `added` - The user added a new token.
     -   `removed` - The user removed an existing token.
@@ -58,7 +59,7 @@ The `value` property is handled in a manner similar to controlled form component
     -   `__experimentalInvalid` - The user tried to add a token that didn't pass the validation.
 -   `__experimentalRenderItem` - Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the `item` key, the single option's data (directly from the array of data passed to the `options` prop).
 -   `__experimentalExpandOnFocus` - If true, the suggestions list will be always expanded when the input field has the focus.
--   `__experimentalShowHowTo` - If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
+-   `__experimentalShowHowTo` - **Deprecated.** Use the `help` prop instead. The `help` prop now defaults to the previous how-to text; if you were passing `__experimentalShowHowTo={ false }` to hide it, pass an empty string to `help` instead.
 -   `__experimentalValidateInput` - If passed, all introduced values will be validated before being added as tokens.
 -   `__experimentalAutoSelectFirstMatch` - If true, the select the first matching suggestion when the user presses the Enter key (or space when tokenizeOnSpace is true).
 -   `__next40pxDefaultSize` - Start opting into the larger default height that will become the default size in a future version.

package/src/form-token-field/index.tsx

@@ -2,7 +2,13 @@
  * External dependencies
  */
 import clsx from 'clsx';
-import type { KeyboardEvent, MouseEvent, TouchEvent, FocusEvent } from 'react';
+import type {
+	KeyboardEvent,
+	MouseEvent,
+	TouchEvent,
+	FocusEvent,
+	ReactNode,
+} from 'react';
 
 /**
  * WordPress dependencies
@@ -12,6 +18,7 @@ import { __, _n, sprintf } from '@wordpress/i18n';
 import { useDebounce, useInstanceId, usePrevious } from '@wordpress/compose';
 import { speak } from '@wordpress/a11y';
 import { isShallowEqual } from '@wordpress/is-shallow-equal';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -70,10 +77,11 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__experimentalRenderItem,
 		__experimentalExpandOnFocus = false,
 		__experimentalValidateInput = () => true,
-		__experimentalShowHowTo = true,
+		__experimentalShowHowTo,
 		__next40pxDefaultSize = false,
 		__experimentalAutoSelectFirstMatch = false,
 		tokenizeOnBlur = false,
+		help,
 	} = useDeprecated36pxDefaultSizeProp< FormTokenFieldProps >( props );
 
 	maybeWarnDeprecated36pxSize( {
@@ -82,6 +90,27 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__next40pxDefaultSize,
 	} );
 
+	const defaultHelp = tokenizeOnSpace
+		? __( 'Separate with commas, spaces, or the Enter key.' )
+		: __( 'Separate with commas or the Enter key.' );
+
+	let computedHelp: ReactNode = help !== undefined ? help : defaultHelp;
+
+	if ( typeof __experimentalShowHowTo === 'boolean' ) {
+		deprecated(
+			'`__experimentalShowHowTo` prop in wp.components.FormTokenField',
+			{
+				since: '7.1',
+				alternative: '`help` prop',
+				hint: 'The `help` prop now defaults to the previous how-to text. Pass an empty string to hide it.',
+			}
+		);
+
+		if ( __experimentalShowHowTo === false && help === undefined ) {
+			computedHelp = '';
+		}
+	}
+
 	const instanceId = useInstanceId( FormTokenField );
 
 	// We reset to these initial values again in the onBlur
@@ -655,6 +684,10 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function renderInput() {
+		const describedById = computedHelp
+			? `components-form-token-input-${ instanceId }__help`
+			: undefined;
+
 		const inputProps = {
 			instanceId,
 			autoCapitalize,
@@ -665,6 +698,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 			onBlur,
 			isExpanded,
 			selectedSuggestionIndex,
+			'aria-describedby': describedById,
 		};
 
 		return (
@@ -749,16 +783,12 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 					/>
 				) }
 			</div>
-			{ __experimentalShowHowTo && (
+			{ computedHelp && (
 				<StyledHelp
-					id={ `components-form-token-suggestions-howto-${ instanceId }` }
+					id={ `components-form-token-input-${ instanceId }__help` }
 					className="components-form-token-field__help"
 				>
-					{ tokenizeOnSpace
-						? __(
-								'Separate with commas, spaces, or the Enter key.'
-						  )
-						: __( 'Separate with commas or the Enter key.' ) }
+					{ computedHelp }
 				</StyledHelp>
 			) }
 		</div>

package/src/form-token-field/stories/index.story.tsx

@@ -14,6 +14,7 @@ import { useState } from '@wordpress/element';
 import FormTokenField from '../';
 
 const meta: Meta< typeof FormTokenField > = {
+	tags: [ 'manifest' ],
 	component: FormTokenField,
 	title: 'Components/Selection & Input/Common/FormTokenField',
 	id: 'components-formtokenfield',
@@ -24,6 +25,7 @@ const meta: Meta< typeof FormTokenField > = {
 		__experimentalValidateInput: {
 			control: false,
 		},
+		help: { control: 'text' },
 	},
 	parameters: {
 		controls: {

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);
 	}
 }