@wordpress/components 38.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

@@ -1,14 +1,7 @@
-/**
- * External dependencies
- */
 import type { SerializedStyles } from '@emotion/react';
 import { css } from '@emotion/react';
 import styled from '@emotion/styled';
 import type { CSSProperties, ReactNode } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../../context';
 import { Flex, FlexItem } from '../../flex';
 import { Text } from '../../text';
@@ -79,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 ) => {
@@ -280,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

@@ -1,17 +1,6 @@
-/**
- * External dependencies
- */
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import BaseInputControl from '../';
 import InputControlPrefixWrapper from '../input-prefix-wrapper';
 
@@ -39,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/input-control/types.ts

@@ -1,6 +1,3 @@
-/**
- * External dependencies
- */
 import type {
 	CSSProperties,
 	ReactNode,
@@ -8,10 +5,6 @@ import type {
 	HTMLInputTypeAttribute,
 } from 'react';
 import type { useDrag } from '@use-gesture/react';
-
-/**
- * Internal dependencies
- */
 import type { StateReducer } from './reducer/state';
 import type { WordPressComponentProps } from '../context';
 import type { FlexProps } from '../flex/types';

package/src/input-control/utils.ts

@@ -1,21 +1,10 @@
-/**
- * External dependencies
- */
 import type { FocusEventHandler } from 'react';
-
-/**
- * WordPress dependencies
- */
 import {
 	useEffect,
 	useLayoutEffect,
 	useRef,
 	useState,
 } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import type { InputChangeCallback } from './types';
 
 /**
@@ -60,8 +49,7 @@ export function useDragCursor(
 		if ( isDragging ) {
 			document.documentElement.style.cursor = dragCursor;
 		} else {
-			// @ts-expect-error
-			document.documentElement.style.cursor = null;
+			document.documentElement.style.removeProperty( 'cursor' );
 		}
 	}, [ isDragging, dragCursor ] );
 

package/src/isolated-event-container/index.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ComponentPropsWithoutRef, MouseEvent } from 'react';
-
-/**
- * WordPress dependencies
- */
 import { forwardRef } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 

package/src/isolated-event-container/test/index.tsx

@@ -1,12 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-
-/**
- * Internal dependencies
- */
 import IsolatedEventContainer from '..';
 
 describe( 'IsolatedEventContainer', () => {

package/src/item-group/context.ts

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { createContext, useContext } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import type { ItemGroupContext as Context } from './types';
 
 export const ItemGroupContext = createContext( {

package/src/item-group/item/README.md

@@ -1,8 +1,6 @@
 # `Item`
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<p class="callout callout-alert">This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.</p>
 
 `Item` is used in combination with `ItemGroup` to display a list of items grouped and styled together.
 

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

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ForwardedRef } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { ItemProps } from '../types';
 import { useItem } from './hook';
 import type { WordPressComponentProps } from '../../context';

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

@@ -1,17 +1,15 @@
-/**
- * WordPress dependencies
- */
-import { useMemo } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
+import clsx from 'clsx';
 import type { WordPressComponentProps } from '../../context';
 import { useContextSystem } from '../../context';
-import * as styles from '../styles';
 import { useItemGroupContext } from '../context';
-import { useCx } from '../../utils/hooks/use-cx';
 import type { ItemProps } from '../types';
+import styles from '../style.module.scss';
+
+const sizeClassName = {
+	small: styles[ 'is-size-small' ],
+	medium: styles[ 'is-size-medium' ],
+	large: styles[ 'is-size-large' ],
+};
 
 export function useItem( props: WordPressComponentProps< ItemProps, 'div' > ) {
 	const {
@@ -29,22 +27,16 @@ export function useItem( props: WordPressComponentProps< ItemProps, 'div' > ) {
 
 	const as = asProp || ( typeof onClick !== 'undefined' ? 'button' : 'div' );
 
-	const cx = useCx();
-
-	const classes = useMemo(
-		() =>
-			cx(
-				( as === 'button' || as === 'a' ) &&
-					styles.unstyledButton( as ),
-				styles.itemSizes[ size ] || styles.itemSizes.medium,
-				styles.item,
-				spacedAround && styles.spacedAround,
-				className
-			),
-		[ as, className, cx, size, spacedAround ]
+	const classes = clsx(
+		styles.item,
+		as === 'button' && styles[ 'is-unstyled-button' ],
+		as === 'a' && styles[ 'is-unstyled-link' ],
+		sizeClassName[ size ] || sizeClassName.medium,
+		spacedAround && styles[ 'is-spaced-around' ],
+		className
 	);
 
-	const wrapperClassName = cx( styles.itemWrapper );
+	const wrapperClassName = styles[ 'item-wrapper' ];
 
 	return {
 		as,

package/src/item-group/item-group/README.md

@@ -1,8 +1,6 @@
 # `ItemGroup`
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<p class="callout callout-alert">This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.</p>
 
 `ItemGroup` displays a list of `Item`s grouped and styled together.
 

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

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ForwardedRef } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect } from '../../context';
 import { useItemGroup } from './hook';

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

@@ -1,15 +1,8 @@
-/**
- * Internal dependencies
- */
+import clsx from 'clsx';
 import type { WordPressComponentProps } from '../../context';
 import { useContextSystem } from '../../context';
-
-/**
- * Internal dependencies
- */
-import * as styles from '../styles';
-import { useCx } from '../../utils/hooks/use-cx';
 import type { ItemGroupProps } from '../types';
+import styles from '../style.module.scss';
 
 export function useItemGroup(
 	props: WordPressComponentProps< ItemGroupProps, 'div' >
@@ -23,12 +16,13 @@ export function useItemGroup(
 		...otherProps
 	} = useContextSystem( props, 'ItemGroup' );
 
-	const cx = useCx();
-
-	const classes = cx(
-		isBordered && styles.bordered,
-		isSeparated && styles.separated,
-		isRounded && styles.rounded,
+	const classes = clsx(
+		styles[ 'item-group' ],
+		{
+			[ styles[ 'is-bordered' ] ]: isBordered,
+			[ styles[ 'is-separated' ] ]: isSeparated,
+			[ styles[ 'is-rounded' ] ]: isRounded,
+		},
 		className
 	);
 

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

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { Meta, StoryFn } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { ItemGroup } from '../item-group/component';
 import { Item } from '../item/component';
 

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

@@ -0,0 +1,115 @@
+@use "../utils/theme-variables" as *;
+
+// Matches CONFIG.surfaceBorderColor — not the WPDS stroke token (#dbdbdb).
+$surface-border-color: rgba(0, 0, 0, 0.1);
+
+// Matches CONFIG.controlHeight.
+$control-height: 36px;
+$base-font-height: calc(13px * 1.4);
+
+/*
+ * Math:
+ * - Use the desired height as the base value
+ * - Subtract the computed height of (default) text
+ * - Subtract the effects of border
+ * - Divide the calculated number by 2, in order to get an individual top/bottom padding
+ */
+$padding-y: calc((#{$control-height} - #{$base-font-height} - 2px) / 2);
+$padding-y-small: calc((calc(#{$control-height} * 0.8) - #{$base-font-height} - 2px) / 2);
+$padding-y-large: calc((calc(#{$control-height} * 1.2) - #{$base-font-height} - 2px) / 2);
+
+.item-group {
+	&.is-bordered {
+		border: 1px solid $surface-border-color;
+	}
+
+	&.is-separated {
+		> *:not(marquee) > * {
+			border-block-end: 1px solid $surface-border-color;
+		}
+
+		> *:last-of-type > * {
+			border-block-end-color: transparent;
+		}
+	}
+
+	&.is-rounded {
+		border-radius: var(--wpds-border-radius-sm);
+
+		> *:first-of-type > * {
+			border-start-start-radius: var(--wpds-border-radius-sm);
+			border-start-end-radius: var(--wpds-border-radius-sm);
+		}
+
+		> *:last-of-type > * {
+			border-end-start-radius: var(--wpds-border-radius-sm);
+			border-end-end-radius: var(--wpds-border-radius-sm);
+		}
+	}
+}
+
+.item-wrapper {
+	width: 100%;
+	display: block;
+}
+
+.item {
+	box-sizing: border-box;
+	width: 100%;
+	display: block;
+	margin: 0;
+	color: inherit;
+
+	&.is-unstyled-button,
+	&.is-unstyled-link {
+		font-size: 13px;
+		font-family: inherit;
+		appearance: none;
+		border: 1px solid transparent;
+		cursor: var(--wpds-cursor-control);
+		background: none;
+		text-align: start;
+
+		svg,
+		path {
+			fill: currentColor;
+		}
+
+		&:hover {
+			color: $components-color-accent;
+		}
+
+		&:focus {
+			box-shadow: none;
+			outline: none;
+		}
+
+		&:focus-visible {
+			box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
+			// Windows high contrast mode.
+			outline: 2px solid transparent;
+			outline-offset: 0;
+		}
+	}
+
+	&.is-unstyled-link {
+		text-decoration: none;
+	}
+
+	&.is-spaced-around {
+		border-radius: var(--wpds-border-radius-sm);
+	}
+
+	&.is-size-small {
+		padding: $padding-y-small 8px;
+	}
+
+	&.is-size-medium {
+		padding: $padding-y 12px;
+	}
+
+	&.is-size-large {
+		// Matches CONFIG.controlPaddingXLarge (`12 * 1.3334`).
+		padding: $padding-y-large 16.0008px;
+	}
+}