@wordpress/components 39.0.0 → 40.0.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

@@ -72,17 +72,6 @@ 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 ) => {
@@ -273,6 +262,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

@@ -28,6 +28,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" /> );
 

package/src/keyboard-shortcuts/stories/index.story.tsx

@@ -34,7 +34,7 @@ Default.args = {
 			{ /* eslint-disable react/no-unescaped-entities */ }
 			<p>Hit the "a" or "b" key in this textarea:</p>
 			{ /* eslint-enable react/no-unescaped-entities */ }
-			<textarea />
+			<textarea aria-label="Keyboard shortcuts demo" />
 		</div>
 	),
 };
@@ -52,7 +52,7 @@ Default.parameters = {
     <p>
       Hit the "a" or "b" key in this textarea:
     </p>
-    <textarea />
+    <textarea aria-label="Keyboard shortcuts demo" />
   </div>
 </KeyboardShortcuts>
 			`,

package/src/menu-group/stories/index.story.tsx

@@ -3,6 +3,7 @@ import { useState } from '@wordpress/element';
 import MenuGroup from '..';
 import MenuItem from '../../menu-item';
 import MenuItemsChoice from '../../menu-items-choice';
+import { NavigableMenu } from '../../navigable-container';
 
 const meta: Meta< typeof MenuGroup > = {
 	tags: [ 'manifest' ],
@@ -26,10 +27,12 @@ export default meta;
 
 const Template: StoryFn< typeof MenuGroup > = ( args ) => {
 	return (
-		<MenuGroup { ...args }>
-			<MenuItem>Menu Item 1</MenuItem>
-			<MenuItem>Menu Item 2</MenuItem>
-		</MenuGroup>
+		<NavigableMenu>
+			<MenuGroup { ...args }>
+				<MenuItem>Menu Item 1</MenuItem>
+				<MenuItem>Menu Item 2</MenuItem>
+			</MenuGroup>
+		</NavigableMenu>
 	);
 };
 
@@ -49,7 +52,7 @@ const MultiGroupsTemplate: StoryFn< typeof MenuGroup > = ( args ) => {
 	];
 
 	return (
-		<>
+		<NavigableMenu>
 			<MenuGroup label="View">
 				<MenuItem>Top Toolbar</MenuItem>
 				<MenuItem>Spotlight Mode</MenuItem>
@@ -63,7 +66,7 @@ const MultiGroupsTemplate: StoryFn< typeof MenuGroup > = ( args ) => {
 					onHover={ () => {} }
 				/>
 			</MenuGroup>
-		</>
+		</NavigableMenu>
 	);
 };
 

package/src/menu-item/stories/index.story.tsx

@@ -3,6 +3,7 @@ import { link, more, check } from '@wordpress/icons';
 import MenuGroup from '../../menu-group';
 import MenuItem from '..';
 import Shortcut from '../../shortcut';
+import { NavigableMenu } from '../../navigable-container';
 
 const meta: Meta< typeof MenuItem > = {
 	tags: [ 'manifest' ],
@@ -37,9 +38,11 @@ export default meta;
 
 const Template: StoryFn< typeof MenuItem > = ( props ) => {
 	return (
-		<MenuGroup>
-			<MenuItem { ...props }>Menu Item 1</MenuItem>
-		</MenuGroup>
+		<NavigableMenu>
+			<MenuGroup>
+				<MenuItem { ...props }>Menu Item 1</MenuItem>
+			</MenuGroup>
+		</NavigableMenu>
 	);
 };
 

package/src/menu-items-choice/stories/index.story.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryFn } from '@storybook/react-vite';
 import { useState } from '@wordpress/element';
 import MenuItemsChoice from '..';
 import MenuGroup from '../../menu-group';
+import { NavigableMenu } from '../../navigable-container';
 
 const meta: Meta< typeof MenuItemsChoice > = {
 	tags: [ 'manifest' ],
@@ -35,17 +36,19 @@ const Template: StoryFn< typeof MenuItemsChoice > = ( {
 	const [ choice, setChoice ] = useState( choices[ 0 ]?.value ?? '' );
 
 	return (
-		<MenuGroup label="Editor">
-			<MenuItemsChoice
-				choices={ choices }
-				value={ choice }
-				onSelect={ ( ...selectArgs ) => {
-					onSelect( ...selectArgs );
-					setChoice( ...selectArgs );
-				} }
-				onHover={ onHover }
-			/>
-		</MenuGroup>
+		<NavigableMenu>
+			<MenuGroup label="Editor">
+				<MenuItemsChoice
+					choices={ choices }
+					value={ choice }
+					onSelect={ ( ...selectArgs ) => {
+						onSelect( ...selectArgs );
+						setChoice( ...selectArgs );
+					} }
+					onHover={ onHover }
+				/>
+			</MenuGroup>
+		</NavigableMenu>
 	);
 };
 

package/src/modal/index.tsx

@@ -195,6 +195,7 @@ function UnforwardedModal(
 			! event.defaultPrevented
 		) {
 			event.preventDefault();
+			event.stopPropagation();
 			closeModal().then( () => onRequestClose( event ) );
 		}
 	}

package/src/modal/test/index.tsx

@@ -82,6 +82,25 @@ describe( 'Modal', () => {
 		expect( onRequestClose ).toHaveBeenCalled();
 	} );
 
+	it( 'should stop an Escape key press from propagating when it dismisses the modal', async () => {
+		const user = userEvent.setup();
+		const documentKeyDownHandler = jest.fn();
+		document.addEventListener( 'keydown', documentKeyDownHandler );
+
+		try {
+			render(
+				<Modal onRequestClose={ noop }>
+					<p>Modal content</p>
+				</Modal>
+			);
+
+			await user.keyboard( '[Escape]' );
+			expect( documentKeyDownHandler ).not.toHaveBeenCalled();
+		} finally {
+			document.removeEventListener( 'keydown', documentKeyDownHandler );
+		}
+	} );
+
 	it( 'should return focus when dismissed by clicking outside', async () => {
 		const user = userEvent.setup();
 		const ReturnDemo = () => {

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

@@ -12,11 +12,6 @@ const meta: Meta< typeof Navigator > = {
 		Button: Navigator.Button,
 		BackButton: Navigator.BackButton,
 	},
-	// Temporary: Due to an upstream bug, render the root explicitly so the
-	// components manifest extractor can resolve props from the JSX.
-	//
-	// See: https://github.com/storybookjs/storybook/issues/34877
-	render: ( args ) => <Navigator { ...args } />,
 	title: 'Components/Navigation/Navigator',
 	id: 'components-navigator',
 	argTypes: {

package/src/number-control/stories/index.story.tsx

@@ -14,14 +14,14 @@ const meta: Meta< typeof NumberControl > = {
 		type: { control: { type: 'text' } },
 		value: { control: false },
 	},
-	tags: [ 'status-experimental', 'manifest' ],
+	tags: [ 'status-experimental' ],
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'recommended',
+			status: 'not-recommended',
 			whereUsed: 'global',
-			notes: 'Will be superseded by [`InputControl`](?path=/docs/design-system-components-form-inputcontrol--docs) with `type="number"` in `@wordpress/ui`, but continue using for now.',
+			notes: 'For new use cases, use [`InputControl`](?path=/docs/design-system-components-form-inputcontrol--docs) with `type="number"` from `@wordpress/ui` instead. Existing usages should migrate with caution, due to significant differences in behavior. See the [migration guide](?path=/docs/components-inputcontrol--migration-guide).',
 		},
 	},
 };