@wordpress/components 39.0.0 → 40.1.0

package/src/input-control/stories/migration-guide.mdx

@@ -0,0 +1,201 @@
+import { Markdown, Meta } from '@storybook/addon-docs/blocks';
+import * as InputControlStories from './index.story';
+
+<Meta of={ InputControlStories } name="Migration Guide" />
+
+# InputControl migration guide
+
+Migrate from [`InputControl`](?path=/docs/components-inputcontrol--docs) in `@wordpress/components` to [`InputControl`](?path=/docs/design-system-components-form-inputcontrol--docs) in `@wordpress/ui`.
+
+The same guidance applies when replacing legacy [`TextControl`](?path=/docs/components-textcontrol--docs) and [`NumberControl`](?path=/docs/components-numbercontrol--docs) usages.
+
+## Basic migration
+
+Update the import and swap the callback prop:
+
+```jsx
+// Before
+import { __experimentalInputControl as InputControl } from '@wordpress/components';
+
+<InputControl
+	label="Width"
+	value={ value }
+	onChange={ ( nextValue ) => setValue( nextValue ?? '' ) }
+	help="Enter a value in pixels."
+/>;
+
+// After
+import { InputControl } from '@wordpress/ui';
+
+<InputControl
+	label="Width"
+	value={ value }
+	onValueChange={ ( nextValue ) => setValue( nextValue ) }
+	description="Enter a value in pixels."
+/>;
+```
+
+## Prop mapping
+
+<Markdown>{ `
+| \`@wordpress/components\` | \`@wordpress/ui\` | Notes |
+| --- | --- | --- |
+| \`onChange\` | \`onValueChange\` | Receives the next string value on every change. Legacy \`NumberControl\` also rewrites values to match \`min\`, \`max\`, and \`step\` on Enter and blur; see [Number inputs](#number-inputs). |
+| \`help\` | \`description\` | Use plain text only. |
+| \`help\` with links or other markup | \`details\` | Use when the help text needs semantic content. |
+| \`hideLabelFromVision\` | \`hideLabelFromVision\` | Same behavior. |
+| \`prefix\` / \`suffix\` | \`prefix\` / \`suffix\` | Wrap slot content in [\`InputLayout.Slot\`](?path=/docs/design-system-components-form-primitives-input--docs#with-prefix) instead of \`InputControlPrefixWrapper\` / \`InputControlSuffixWrapper\`. |
+| \`size\` | \`size\` | Supports \`default\` and \`compact\`. |
+| \`type\` | \`type\` | Same HTML input types, including \`number\`. |
+` }</Markdown>
+
+## Labels
+
+`InputControl` requires a `label` prop with a plain `string` value. Legacy `InputControl`, `TextControl`, and `NumberControl` accept an optional `label`, and the legacy `InputControl` `label` can be a `ReactNode`.
+
+When the visible label text already exists elsewhere, pass a descriptive string and hide it visually:
+
+```jsx
+<InputControl
+	label="Search"
+	hideLabelFromVision
+	value={ value }
+	onValueChange={ setValue }
+/>;
+```
+
+When the label is not a plain string, or you need a custom layout, compose the [`Input`](?path=/docs/design-system-components-form-primitives-input--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives instead of `InputControl`:
+
+```jsx
+import { Field, Input } from '@wordpress/ui';
+
+<Field.Root>
+	<Field.Label>
+		Custom <strong>label</strong> content
+	</Field.Label>
+	<Input
+		value={ value }
+		onValueChange={ setValue }
+	/>
+</Field.Root>
+```
+
+See the [`Field` stories](?path=/docs/design-system-components-form-primitives-field--docs) for other association patterns, such as external labels with `aria-labelledby`.
+
+## Prefix and suffix slots
+
+Replace the wrapper components with `InputLayout.Slot`:
+
+```jsx
+// Before
+import { Icon } from '@wordpress/components';
+import {
+	__experimentalInputControl as InputControl,
+	__experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
+} from '@wordpress/components';
+import { link } from '@wordpress/icons';
+
+<InputControl
+	prefix={
+		<InputControlPrefixWrapper variant="icon">
+			<Icon icon={ link } />
+		</InputControlPrefixWrapper>
+	}
+/>;
+
+// After
+import { Icon, InputControl, InputLayout } from '@wordpress/ui';
+import { link } from '@wordpress/icons';
+
+<InputControl
+	prefix={
+		<InputLayout.Slot padding="minimal">
+			<Icon icon={ link } />
+		</InputLayout.Slot>
+	}
+/>;
+```
+
+Use `padding="minimal"` for icons and controls. Omit it for text prefixes and suffixes such as `@` or `%`.
+
+## Number inputs
+
+Replace `NumberControl` usages with `InputControl` and `type="number"`:
+
+```jsx
+import { InputControl } from '@wordpress/ui';
+
+<InputControl
+	label="Quantity"
+	type="number"
+	min={ 1 }
+	max={ 10 }
+	step={ 1 }
+	value={ value }
+	onValueChange={ setValue }
+/>;
+```
+
+### Value clamping and step alignment
+
+Legacy `NumberControl` rewrites the value on Enter and blur: it clamps to `min`/`max` and aligns to `step`. `@wordpress/ui` `InputControl` passes these constraints to the native `<input type="number">` for validation, but does not rewrite invalid values when the field loses focus.
+
+If you relied on the legacy rewrite behavior, normalize the value yourself. A common pattern is to keep accepting edits in `onValueChange`, then clamp on blur:
+
+```jsx
+import { InputControl } from '@wordpress/ui';
+
+function constrainValue( value, min, max, step ) {
+	const num = parseFloat( value );
+	if ( Number.isNaN( num ) ) {
+		return value;
+	}
+
+	const clamped = Math.min( max, Math.max( min, num ) );
+	if ( step === 'any' ) {
+		return String( clamped );
+	}
+
+	const stepNum = parseFloat( step );
+	const aligned =
+		min + Math.round( ( clamped - min ) / stepNum ) * stepNum;
+	return String( aligned );
+}
+
+<InputControl
+	label="Quantity"
+	type="number"
+	min={ min }
+	max={ max }
+	step={ step }
+	value={ value }
+	onValueChange={ setValue }
+	onBlur={ ( event ) => {
+		setValue( constrainValue( event.target.value, min, max, step ) );
+	} }
+/>;
+```
+
+Adapt the helper to match your product requirements. The legacy component also fires `onChange` while typing with unclamped values, then again with the clamped value on blur.
+
+### Removed NumberControl features
+
+The `@wordpress/ui` `InputControl` does not support these `@wordpress/components` `NumberControl` features:
+
+-   **`spinControls`** — When desired, use explicit controls in a `suffix` slot. See the [`NumberWithSteppers` story](?path=/story/design-system-components-form-inputcontrol--number-with-steppers).
+-   **`isShiftStepEnabled` / `shiftStep`** — Apply larger increments in your stepper handlers or `onValueChange` logic.
+-   **Mouse-drag value changes** — Not recommended, as they can be confusing and are not supported on touch devices.
+
+## Removed features
+
+The `@wordpress/ui` `InputControl` does not support these `@wordpress/components` features:
+
+-   **`labelPosition`** — Only top labels are recommended. If other layouts are necessary, compose using the [`Input`](?path=/docs/design-system-components-form-primitives-input--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives.
+-   **`isPressEnterToChange`** — Keep a local draft value and commit to your state on `Enter` or `blur` if you need deferred updates.
+-   **`onValidate`** — Run validation in your `onValueChange` handler instead.
+-   **`isDragEnabled`, `dragDirection`, and related drag callbacks** — Not recommended, as they can be confusing and are not supported on touch devices.
+-   **`__unstableInputWidth`** — If the label needs to be a different width from the input field, compose using the [`Input`](?path=/docs/design-system-components-form-primitives-input--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives.
+-   **`__unstableStateReducer`** — This hook intercepted the internal state machine. Some workarounds for known patterns:
+    -   **Display formatting** (for example, zero-padded time segments): always pass a formatted `value`, or format in an `onBlur` handler if updates should be deferred until the field loses focus.
+    -   **Paste normalization**: normalize in `onValueChange`, or handle `onPaste` on `InputControl`.
+    -   **Custom step or spin behavior**: apply adjustments in `onValueChange`, in an `onBlur` handler, or with explicit controls in a `suffix` slot.

package/src/input-control/style.scss

@@ -0,0 +1,11 @@
+@use "@wordpress/base-styles/mixins";
+
+.components-input-control__container {
+	// Don't show the input's focus ring when an auxiliary control in a prefix
+	// or suffix has focus.
+	&:focus-within:not(:has(:is(.components-input-control__prefix, .components-input-control__suffix):focus-within)) {
+		.components-input-control__backdrop {
+			@include mixins.outset-ring__focus();
+		}
+	}
+}

package/src/input-control/styles/input-control-styles.tsx

@@ -47,6 +47,21 @@ const backdropBorderColor = ( {
 	return COLORS.ui.border;
 };
 
+const backdropDisabledStyles = ( {
+	disabled,
+	isBorderless,
+}: BackdropProps ) => {
+	if ( ! disabled || isBorderless ) {
+		return undefined;
+	}
+
+	return css`
+		@media ( forced-colors: active ) {
+			border-color: GrayText;
+		}
+	`;
+};
+
 export const BackdropUI = styled.div< BackdropProps >`
 	&&& {
 		box-sizing: border-box;
@@ -64,6 +79,7 @@ export const BackdropUI = styled.div< BackdropProps >`
 		top: 0;
 
 		${ rtl( { paddingLeft: 2 } ) }
+		${ backdropDisabledStyles }
 	}
 `;
 
@@ -72,25 +88,20 @@ export const Root = styled( Flex )`
 	position: relative;
 	border-radius: ${ CONFIG.radiusSmall };
 	padding-top: 0;
-
-	// Focus within, excluding cases where auxiliary controls in prefix or suffix have focus.
-	&:focus-within:not( :has( :is( ${ Prefix }, ${ Suffix } ):focus-within ) ) {
-		${ BackdropUI } {
-			border-color: ${ COLORS.ui.borderFocus };
-			box-shadow: ${ CONFIG.controlBoxShadowFocus };
-			// Windows High Contrast mode will show this outline, but not the box-shadow.
-			outline: 2px solid transparent;
-			outline-offset: -2px;
-		}
-	}
 `;
 
 const containerDisabledStyles = ( { disabled }: ContainerProps ) => {
-	const backgroundColor = disabled
-		? COLORS.ui.backgroundDisabled
-		: COLORS.ui.background;
+	if ( ! disabled ) {
+		return undefined;
+	}
+
+	return css`
+		color: ${ COLORS.ui.textDisabled };
 
-	return css( { backgroundColor } );
+		@media ( forced-colors: active ) {
+			color: GrayText;
+		}
+	`;
 };
 
 const containerWidthStyles = ( {
@@ -121,6 +132,7 @@ export const Container = styled.div< ContainerProps >`
 	display: flex;
 	flex: 1;
 	position: relative;
+	background-color: ${ COLORS.ui.background };
 
 	${ containerDisabledStyles }
 	${ containerWidthStyles }
@@ -140,9 +152,17 @@ const disabledStyles = ( { disabled }: InputProps ) => {
 		return '';
 	}
 
-	return css( {
-		color: COLORS.ui.textDisabled,
-	} );
+	return css`
+		color: ${ COLORS.ui.textDisabled };
+
+		@media ( forced-colors: active ) {
+			color: GrayText;
+		}
+
+		&:disabled::placeholder {
+			color: ${ COLORS.ui.textDisabled };
+		}
+	`;
 };
 
 export const fontSizeStyles = ( { inputSize: size }: InputProps ) => {
@@ -273,6 +293,36 @@ export const Input = styled.input< InputProps >`
 			color: ${ COLORS.ui.darkGrayPlaceholder };
 		}
 
+		&[type='date'],
+		&[type='datetime-local'],
+		&[type='month'],
+		&[type='time'],
+		&[type='week'] {
+			&::-webkit-datetime-edit {
+				display: flex;
+				align-items: center;
+				height: 100%;
+			}
+		}
+
+		/* Hide Safari's value-like placeholder (e.g. \`12:30\`) in empty
+		   date/time inputs. While the input is focused, the browser's
+		   segment editor must stay visible for typing. */
+		@supports ( -webkit-hyphens: none ) and
+			( not ( -moz-appearance: none ) ) {
+			/* Safari only */
+			&[type='date'][data-empty-value]:not( :focus ),
+			&[type='time'][data-empty-value]:not( :focus ),
+			&[type='datetime-local'][data-empty-value]:not( :focus ) {
+				color: transparent;
+
+				/* Hide slashes in date when input is disabled. */
+				&:disabled::-webkit-datetime-edit-text {
+					color: transparent;
+				}
+			}
+		}
+
 		&[type='email'],
 		&[type='url'] {
 			/* rtl:ignore */

package/src/input-control/test/{index.js → index.jsdom.test.tsx}

@@ -1,16 +1,17 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import type { KeyboardEvent } from 'react';
 import { useState } from '@wordpress/element';
 import BaseInputControl from '../';
 import InputControlPrefixWrapper from '../input-prefix-wrapper';
+import type { InputControlProps } from '../types';
 
-const getInput = () => screen.getByTestId( 'input' );
+const getInput = () => screen.getByTestId< HTMLInputElement >( 'input' );
 
 describe( 'InputControl', () => {
-	const InputControl = ( props ) => {
+	const InputControl = ( props: InputControlProps ) => {
 		return <BaseInputControl { ...props } data-testid="input" />;
 	};
-
 	describe( 'Basic rendering', () => {
 		it( 'should render', () => {
 			render( <InputControl /> );
@@ -28,6 +29,16 @@ describe( 'InputControl', () => {
 			expect( input ).toHaveAttribute( 'type', 'number' );
 		} );
 
+		it( 'should flag empty inputs with data-empty-value', () => {
+			const { rerender } = render( <InputControl type="time" /> );
+
+			expect( getInput() ).toHaveAttribute( 'data-empty-value' );
+
+			rerender( <InputControl type="time" value="12:30" /> );
+
+			expect( getInput() ).not.toHaveAttribute( 'data-empty-value' );
+		} );
+
 		it( 'should render label', () => {
 			render( <InputControl label="Hello" value="There" /> );
 
@@ -75,14 +86,16 @@ describe( 'InputControl', () => {
 		it( 'should work as a controlled component given normal, falsy or nullish values', async () => {
 			const user = await userEvent.setup();
 			const spy = jest.fn();
-			const heldKeySet = new Set();
+			const heldKeySet = new Set< string >();
 			const Example = () => {
-				const [ state, setState ] = useState( 'one' );
-				const onChange = ( value ) => {
+				const [ state, setState ] = useState< string | undefined >(
+					'one'
+				);
+				const onChange = ( value: string | undefined ) => {
 					setState( value );
 					spy( value );
 				};
-				const onKeyDown = ( { key } ) => {
+				const onKeyDown = ( { key }: KeyboardEvent ) => {
 					heldKeySet.add( key );
 					if ( key === 'Escape' ) {
 						if ( heldKeySet.has( 'Meta' ) ) {
@@ -94,7 +107,8 @@ describe( 'InputControl', () => {
 						}
 					}
 				};
-				const onKeyUp = ( { key } ) => heldKeySet.delete( key );
+				const onKeyUp = ( { key }: KeyboardEvent ) =>
+					heldKeySet.delete( key );
 				return (
 					<InputControl
 						value={ state }
@@ -179,7 +193,8 @@ describe( 'InputControl', () => {
 						let { value } = state;
 						if (
 							action.type === 'COMMIT' &&
-							action.payload.event.type === 'blur'
+							action.payload.event?.type === 'blur' &&
+							value !== undefined
 						) {
 							value = value.replace( /\bnow\b/, 'meow' );
 						}
@@ -209,7 +224,8 @@ describe( 'InputControl', () => {
 				<InputControl
 					label="Test"
 					prefix={ prefix }
-					{ ...{ size: '__unstable-large' } }
+					// @ts-expect-error Verify the legacy value that is omitted from the public type.
+					size="__unstable-large"
 				/>
 			);
 

package/src/isolated-event-container/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import IsolatedEventContainer from '..';
@@ -5,7 +6,7 @@ import IsolatedEventContainer from '..';
 describe( 'IsolatedEventContainer', () => {
 	it( 'should pass props to container', async () => {
 		const user = userEvent.setup();
-		const clickHandler = jest.fn();
+		const clickHandler = vi.fn();
 		render(
 			<IsolatedEventContainer
 				title="Container"
@@ -38,8 +39,8 @@ describe( 'IsolatedEventContainer', () => {
 	it( 'should stop event propagation only for mousedown, but not for keydown', async () => {
 		const user = userEvent.setup();
 
-		const mousedownHandler = jest.fn();
-		const keydownHandler = jest.fn();
+		const mousedownHandler = vi.fn();
+		const keydownHandler = vi.fn();
 		render(
 			<button
 				onMouseDown={ mousedownHandler }

package/src/item-group/context.ts

@@ -2,6 +2,7 @@ import { createContext, useContext } from '@wordpress/element';
 import type { ItemGroupContext as Context } from './types';
 
 export const ItemGroupContext = createContext( {
+	isList: false,
 	size: 'medium',
 } as Context );
 ItemGroupContext.displayName = 'ItemGroupContext';

package/src/item-group/item/component.tsx

@@ -1,18 +1,36 @@
 import type { ForwardedRef } from 'react';
+import { useEffect, useRef } from '@wordpress/element';
 import type { ItemProps } from '../types';
 import { useItem } from './hook';
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect } from '../../context';
 import { View } from '../../view';
+import { useItemGroupContext } from '../context';
 
 function UnconnectedItem(
 	props: WordPressComponentProps< ItemProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
 	const { role, wrapperClassName, ...otherProps } = useItem( props );
+	const itemRef = useRef< HTMLDivElement >( null );
+	const { isList } = useItemGroupContext();
+
+	useEffect( () => {
+		if (
+			isList &&
+			role === 'listitem' &&
+			! itemRef.current?.closest(
+				'ol, ul, menu, [role="list"], [role="directory"]'
+			)
+		) {
+			throw new Error(
+				'Item with list semantics must be rendered inside an element with role="list".'
+			);
+		}
+	}, [ isList, role ] );
 
 	return (
-		<div role={ role } className={ wrapperClassName }>
+		<div ref={ itemRef } role={ role } className={ wrapperClassName }>
 			<View { ...otherProps } ref={ forwardedRef } />
 		</div>
 	);

package/src/item-group/item/hook.ts

@@ -12,17 +12,16 @@ const sizeClassName = {
 };
 
 export function useItem( props: WordPressComponentProps< ItemProps, 'div' > ) {
+	const { isList, spacedAround, size: contextSize } = useItemGroupContext();
 	const {
 		as: asProp,
 		className,
 		onClick,
-		role = 'listitem',
+		role = isList ? 'listitem' : undefined,
 		size: sizeProp,
 		...otherProps
 	} = useContextSystem( props, 'Item' );
 
-	const { spacedAround, size: contextSize } = useItemGroupContext();
-
 	const size = sizeProp || contextSize;
 
 	const as = asProp || ( typeof onClick !== 'undefined' ? 'button' : 'div' );

package/src/item-group/item-group/component.tsx

@@ -23,6 +23,7 @@ function UnconnectedItemGroup(
 	const size = sizeProp || contextSize;
 
 	const contextValue = {
+		isList: otherProps.role === 'list' || otherProps.role === 'directory',
 		spacedAround,
 		size,
 	};

package/src/item-group/style.module.scss

@@ -70,8 +70,7 @@ $padding-y-large: calc((calc(#{$control-height} * 1.2) - #{$base-font-height} -
 		background: none;
 		text-align: start;
 
-		svg,
-		path {
+		svg {
 			fill: currentColor;
 		}
 

package/src/item-group/test/__snapshots__/{index.js.snap → index.jsdom.test.tsx.snap}

@@ -1,6 +1,6 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`ItemGroup Item should read the value of the size prop from context when the prop is not defined 1`] = `
+exports[`ItemGroup > Item > should read the value of the size prop from context when the prop is not defined 1`] = `
 Snapshot Diff:
 - First value
 + Second value
@@ -33,15 +33,15 @@ Snapshot Diff:
         </div>
 `;
 
-exports[`ItemGroup Item should use different amounts of padding depending on the value of the size prop 1`] = `
+exports[`ItemGroup > Item > should use different amounts of padding depending on the value of the size prop 1`] = `
 Snapshot Diff:
 - First value
 + Second value
 
-@@ -2,11 +2,11 @@
+@@ -1,11 +1,11 @@
+  <div>
     <div
       class="style-item-wrapper"
-      role="listitem"
     >
       <div
 -       class="style-item style-is-size-medium components-item"
@@ -53,7 +53,7 @@ Snapshot Diff:
       </div>
 `;
 
-exports[`ItemGroup ItemGroup component should render correctly 1`] = `
+exports[`ItemGroup > ItemGroup component > should render correctly 1`] = `
 <div>
   <div
     class="style-item-group style-is-rounded components-item-group"
@@ -77,7 +77,7 @@ exports[`ItemGroup ItemGroup component should render correctly 1`] = `
 </div>
 `;
 
-exports[`ItemGroup ItemGroup component should render items individually when the isSeparated prop is true 1`] = `
+exports[`ItemGroup > ItemGroup component > should render items individually when the isSeparated prop is true 1`] = `
 Snapshot Diff:
 - First value
 + Second value
@@ -105,7 +105,7 @@ Snapshot Diff:
         </div>
 `;
 
-exports[`ItemGroup ItemGroup component should show borders when the isBordered prop is true 1`] = `
+exports[`ItemGroup > ItemGroup component > should show borders when the isBordered prop is true 1`] = `
 Snapshot Diff:
 - First value
 + Second value
@@ -133,7 +133,7 @@ Snapshot Diff:
         </div>
 `;
 
-exports[`ItemGroup ItemGroup component should show rounded corners when the isRounded prop is true 1`] = `
+exports[`ItemGroup > ItemGroup component > should show rounded corners when the isRounded prop is true 1`] = `
 Snapshot Diff:
 - First value
 + Second value