@wordpress/ui 0.9.1-next.v.202603161435.0 → 0.11.0

package/src/empty-state/title.tsx

@@ -0,0 +1,29 @@
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { Text } from '../text';
+import type { EmptyStateTitleProps } from './types';
+import styles from './style.module.css';
+
+const DEFAULT_TAG = <h2 />;
+
+/**
+ * The title is a short heading that communicates the empty state.
+ */
+export const Title = forwardRef< HTMLHeadingElement, EmptyStateTitleProps >(
+	function EmptyStateTitle(
+		{ render = DEFAULT_TAG, className, children, ...props },
+		ref
+	) {
+		return (
+			<Text
+				ref={ ref }
+				variant="heading-lg"
+				render={ render }
+				className={ clsx( styles.title, className ) }
+				{ ...props }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);

package/src/empty-state/types.ts

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+import type { ComponentProps } from '../utils/types';
+import type { IconProps } from '../icon/types';
+
+export interface EmptyStateRootProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateVisualProps extends ComponentProps< 'div' > {
+	/**
+	 * The visual content of the empty state (e.g., icon, illustration).
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateIconProps extends ComponentProps< 'div' > {
+	/**
+	 * The icon to render.
+	 */
+	icon: IconProps[ 'icon' ];
+}
+
+export interface EmptyStateTitleProps extends ComponentProps< 'h2' > {
+	/**
+	 * The title text of the empty state.
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateDescriptionProps extends ComponentProps< 'p' > {
+	/**
+	 * The description text of the empty state.
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateActionsProps extends ComponentProps< 'div' > {
+	/**
+	 * The action buttons for the empty state.
+	 */
+	children?: ReactNode;
+}

package/src/empty-state/visual.tsx

@@ -0,0 +1,24 @@
+import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import type { EmptyStateVisualProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * A container for visual content in an empty state (e.g., icons, illustrations).
+ * Provides appropriate spacing and alignment for visual elements.
+ */
+export const Visual = forwardRef< HTMLDivElement, EmptyStateVisualProps >(
+	function EmptyStateVisual( { render, ...props }, ref ) {
+		const className = clsx( styles.visual );
+
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( { className }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/form/index.ts

@@ -0,0 +1,3 @@
+export * from './primitives';
+
+export * from './input-control';

package/src/form/input-control/index.ts

@@ -0,0 +1 @@
+export { InputControl } from './input-control';

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

@@ -0,0 +1,33 @@
+import { forwardRef } from '@wordpress/element';
+import { Input, Field } from '../primitives';
+import type { InputControlProps } from './types';
+
+/**
+ * A complete input field with integrated label and description.
+ */
+export const InputControl = forwardRef< HTMLInputElement, InputControlProps >(
+	function InputControl(
+		{
+			className,
+			label,
+			description,
+			details,
+			hideLabelFromVision,
+			...restProps
+		},
+		ref
+	) {
+		return (
+			<Field.Root className={ className }>
+				<Field.Label hideFromVision={ hideLabelFromVision }>
+					{ label }
+				</Field.Label>
+				<Input ref={ ref } { ...restProps } />
+				{ description && (
+					<Field.Description>{ description }</Field.Description>
+				) }
+				{ details && <Field.Details>{ details }</Field.Details> }
+			</Field.Root>
+		);
+	}
+);

package/src/form/input-control/stories/index.story.tsx

@@ -0,0 +1,163 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from '@wordpress/element';
+import { plus, reset, seen, unseen } from '@wordpress/icons';
+import { IconButton, InputControl, InputLayout, Stack } from '../../..';
+import {
+	WithPrefix,
+	WithSuffixControl,
+} from '../../primitives/input/stories/index.story';
+import {
+	WITH_DETAILS_DESCRIPTION,
+	DETAILS_EXAMPLE,
+} from '../../stories/shared';
+
+const meta: Meta< typeof InputControl > = {
+	title: 'Design System/Components/Form/InputControl',
+	component: InputControl,
+	argTypes: {
+		defaultValue: { control: false },
+		onValueChange: { action: 'onValueChange' },
+		value: { control: false },
+		type: { control: 'text' },
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof InputControl >;
+
+export const Default: Story = {
+	args: {
+		label: 'Label',
+		description: 'This is the description.',
+		placeholder: 'Placeholder',
+	},
+};
+
+export const VisuallyHiddenLabel: Story = {
+	args: {
+		...Default.args,
+		hideLabelFromVision: true,
+	},
+};
+
+export const WithDetails: Story = {
+	parameters: {
+		docs: { description: { story: WITH_DETAILS_DESCRIPTION } },
+	},
+	args: {
+		...Default.args,
+		description: undefined,
+		details: DETAILS_EXAMPLE,
+	},
+};
+
+WithPrefix.args = {
+	...WithPrefix.args,
+	...Default.args,
+};
+WithSuffixControl.args = {
+	...WithSuffixControl.args,
+	...Default.args,
+};
+export { WithPrefix, WithSuffixControl };
+
+export const Password: Story = {
+	render: function Template( args ) {
+		const [ show, setShow ] = useState( false );
+
+		return (
+			<InputControl
+				{ ...args }
+				type={ show ? 'text' : 'password' }
+				suffix={
+					<InputLayout.Slot padding="minimal">
+						<IconButton
+							label={ show ? 'Hide password' : 'Show password' }
+							onClick={ () => setShow( ! show ) }
+							icon={ show ? unseen : seen }
+							size="small"
+							variant="minimal"
+						/>
+					</InputLayout.Slot>
+				}
+			/>
+		);
+	},
+	args: {
+		...Default.args,
+		defaultValue: 'password',
+	},
+};
+
+export const Date: Story = {
+	args: {
+		...Default.args,
+		type: 'date',
+	},
+};
+
+export const Number: Story = {
+	args: {
+		...Default.args,
+		placeholder: '0',
+		type: 'number',
+	},
+};
+
+export const NumberWithSteppers: Story = {
+	render: function Template( args ) {
+		const [ value, setValue ] = useState( 0 );
+
+		return (
+			<>
+				<style>
+					{ `
+					  .my-number-with-steppers input[type='number'] {
+							-moz-appearance: textfield;
+					  }
+						.my-number-with-steppers ::-webkit-inner-spin-button {
+							appearance: none;
+						}
+					` }
+				</style>
+				<InputControl
+					{ ...args }
+					value={ value }
+					onValueChange={ ( v ) => setValue( parseInt( v, 10 ) ) }
+					className="my-number-with-steppers"
+					suffix={
+						<InputLayout.Slot padding="minimal">
+							<Stack direction="row" gap="xs">
+								<IconButton
+									label="Increment"
+									icon={ plus }
+									onClick={ () => setValue( value + 1 ) }
+									size="small"
+									variant="minimal"
+								/>
+								<IconButton
+									label="Decrement"
+									icon={ reset }
+									onClick={ () => setValue( value - 1 ) }
+									size="small"
+									variant="minimal"
+								/>
+							</Stack>
+						</InputLayout.Slot>
+					}
+				/>
+			</>
+		);
+	},
+	args: {
+		...Number.args,
+		type: 'number',
+	},
+};
+
+export const Disabled: Story = {
+	args: {
+		...Default.args,
+		disabled: true,
+	},
+};

package/src/form/input-control/test/index.test.tsx

@@ -0,0 +1,53 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { InputControl } from '../index';
+
+describe( 'InputControl', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLInputElement >();
+
+		render( <InputControl ref={ ref } label="Username" /> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLInputElement );
+	} );
+
+	it( 'renders with a visible label', () => {
+		render( <InputControl label="Email" /> );
+
+		expect(
+			screen.getByRole( 'textbox', { name: 'Email' } )
+		).toBeVisible();
+		expect( screen.getByText( 'Email' ) ).toBeVisible();
+	} );
+
+	it( 'renders with a visually hidden label', () => {
+		render( <InputControl label="Search" hideLabelFromVision /> );
+
+		expect(
+			screen.getByRole( 'textbox', { name: 'Search' } )
+		).toBeVisible();
+	} );
+
+	it( 'renders with a description', () => {
+		render(
+			<InputControl label="Name" description="Enter your full name." />
+		);
+
+		expect( screen.getByText( 'Enter your full name.' ) ).toBeVisible();
+	} );
+
+	it( 'renders with details', () => {
+		render(
+			<InputControl
+				label="Website"
+				details={
+					<span>
+						Must start with <code>https://</code>
+					</span>
+				}
+			/>
+		);
+
+		expect( screen.getByText( /Must start with/ ) ).toBeVisible();
+	} );
+} );

package/src/form/input-control/types.ts

@@ -0,0 +1,5 @@
+import type { Input } from '../primitives';
+import type { ControlProps } from '../types';
+
+export type InputControlProps = React.ComponentProps< typeof Input > &
+	ControlProps;

package/src/form/primitives/field/description.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { Field as _Field } from '@base-ui/react/field';
 import { forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import fieldStyles from '../../../utils/css/field.module.css';
 import type { FieldDescriptionProps } from './types';
 
@@ -11,7 +12,11 @@ export const Description = forwardRef<
 	return (
 		<_Field.Description
 			ref={ ref }
-			className={ clsx( fieldStyles.description, className ) }
+			className={ clsx(
+				defenseStyles.p,
+				fieldStyles.description,
+				className
+			) }
 			{ ...restProps }
 		/>
 	);

package/src/form/primitives/field/details.tsx

@@ -22,9 +22,11 @@ export const Details = forwardRef< HTMLDivElement, FieldDetailsProps >(
 	function Details( { className, ...restProps }, ref ) {
 		return (
 			<>
-				<_Field.Description render={ <VisuallyHidden /> }>
+				{ /* VisuallyHidden is the host so that _Field.Description's
+				   semantic element is preserved. See VisuallyHidden docs. */ }
+				<VisuallyHidden render={ <_Field.Description /> }>
 					{ __( 'More details follow the field.' ) }
-				</_Field.Description>
+				</VisuallyHidden>
 				<div
 					ref={ ref }
 					className={ clsx( fieldStyles.description, className ) }

package/src/form/primitives/field/label.tsx

@@ -10,7 +10,7 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 		{ className, hideFromVision, variant, ...restProps },
 		ref
 	) {
-		return (
+		const label = (
 			<_Field.Label
 				ref={ ref }
 				className={ clsx(
@@ -18,12 +18,16 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 					variant && fieldStyles[ `is-${ variant }` ],
 					className
 				) }
-				{ ...( hideFromVision && {
-					render: <VisuallyHidden />,
-					nativeLabel: false,
-				} ) }
 				{ ...restProps }
 			/>
 		);
+
+		// VisuallyHidden is the host so that _Field.Label's semantic
+		// element is preserved. See VisuallyHidden docs for details.
+		if ( hideFromVision ) {
+			return <VisuallyHidden render={ label } />;
+		}
+
+		return label;
 	}
 );

package/src/form/primitives/field/stories/index.story.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId } from '@wordpress/element';
 import { Field } from '../../../..';
+import { DETAILS_EXAMPLE } from '../../../stories/shared';
 
 const meta: Meta< typeof Field.Root > = {
 	title: 'Design System/Components/Form/Primitives/Field',
@@ -135,13 +136,7 @@ export const WithDetails: StoryObj< typeof Field.Root > = {
 				<Field.Control
 					render={ <input type="text" placeholder="Placeholder" /> }
 				/>
-				<Field.Details>
-					Details can include{ '	' }
-					<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
-						links to more information
-					</a>{ ' ' }
-					and other semantic elements.
-				</Field.Details>
+				<Field.Details>{ DETAILS_EXAMPLE }</Field.Details>
 			</>
 		),
 	},

package/src/form/primitives/field/test/index.test.tsx

@@ -47,6 +47,17 @@ describe( 'Field', () => {
 		).toBeVisible();
 	} );
 
+	it( 'preserves the native label element when hideFromVision is enabled', () => {
+		render(
+			<Field.Root>
+				<Field.Label hideFromVision>Field Label</Field.Label>
+				<Field.Control render={ <input /> } />
+			</Field.Root>
+		);
+
+		expect( screen.getByText( 'Field Label' ).tagName ).toBe( 'LABEL' );
+	} );
+
 	it( 'renders details with a semantically associated description for the control', () => {
 		render(
 			<Field.Root>

package/src/form/primitives/fieldset/description.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { mergeProps, useRender } from '@base-ui/react';
 import { forwardRef, useEffect, useId } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import fieldStyles from '../../../utils/css/field.module.css';
 import { useFieldsetContext } from './context';
 import type { FieldsetDescriptionProps } from './types';
@@ -27,7 +28,14 @@ export const FieldsetDescription = forwardRef<
 		render,
 		ref,
 		props: mergeProps< 'p' >(
-			{ className: clsx( fieldStyles.description, className ), id },
+			{
+				className: clsx(
+					defenseStyles.p,
+					fieldStyles.description,
+					className
+				),
+				id,
+			},
 			restProps
 		),
 	} );

package/src/form/primitives/fieldset/legend.tsx

@@ -10,15 +10,20 @@ export const FieldsetLegend = forwardRef< HTMLDivElement, FieldsetLegendProps >(
 		{ className, hideFromVision, ...restProps },
 		ref
 	) {
-		return (
+		const legend = (
 			<_Fieldset.Legend
 				ref={ ref }
 				className={ clsx( fieldStyles.label, className ) }
-				{ ...( hideFromVision && {
-					render: <VisuallyHidden />,
-				} ) }
 				{ ...restProps }
 			/>
 		);
+
+		// VisuallyHidden is the host so that _Fieldset.Legend's semantic
+		// element is preserved. See VisuallyHidden docs for details.
+		if ( hideFromVision ) {
+			return <VisuallyHidden render={ legend } />;
+		}
+
+		return legend;
 	}
 );

package/src/form/primitives/fieldset/stories/index.story.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Fieldset } from '../../../..';
+import { DETAILS_EXAMPLE } from '../../../stories/shared';
 
 const meta: Meta< typeof Fieldset.Root > = {
 	title: 'Design System/Components/Form/Primitives/Fieldset',
@@ -74,13 +75,7 @@ export const WithDetails: Story = {
 						<input type="checkbox" /> { fruit }
 					</label>
 				) ) }
-				<Fieldset.Details>
-					Details can include{ ' ' }
-					<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
-						links to more information
-					</a>{ ' ' }
-					and other semantic elements.
-				</Fieldset.Details>
+				<Fieldset.Details>{ DETAILS_EXAMPLE }</Fieldset.Details>
 			</>
 		),
 	},

package/src/form/primitives/fieldset/test/index.test.tsx

@@ -43,6 +43,28 @@ describe( 'Fieldset', () => {
 		).toBeVisible();
 	} );
 
+	it( 'preserves the legend element type when hideFromVision is enabled', () => {
+		const { rerender } = render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		const tagWithout = screen.getByText( 'Choose your options' ).tagName;
+
+		rerender(
+			<Fieldset.Root>
+				<Fieldset.Legend hideFromVision>
+					Choose your options
+				</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		expect( screen.getByText( 'Choose your options' ).tagName ).toBe(
+			tagWithout
+		);
+	} );
+
 	it( 'accessibly associates description when Fieldset.Description is present', () => {
 		render(
 			<Fieldset.Root>

package/src/form/primitives/input/input.tsx

@@ -1,6 +1,7 @@
 import { Input as _Input } from '@base-ui/react/input';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import focusStyles from '../../../utils/css/focus.module.css';
 import styles from './style.module.css';
 import type { InputProps } from './types';
@@ -22,7 +23,11 @@ export const Input = forwardRef< HTMLElement, InputProps >( function Input(
 			prefix={ prefix }
 			suffix={ suffix }
 		>
-			<_Input ref={ ref } className={ styles.input } { ...restProps } />
+			<_Input
+				ref={ ref }
+				className={ clsx( defenseStyles.input, styles.input ) }
+				{ ...restProps }
+			/>
 		</InputLayout>
 	);
 } );

package/src/form/primitives/input/stories/index.story.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Input, InputLayout } from '../../../..';
+import { WithSuffixControl } from '../../input-layout/stories/index.story';
 
 const meta: Meta< typeof Input > = {
 	title: 'Design System/Components/Form/Primitives/Input',
@@ -32,6 +33,12 @@ export const WithPrefix: Story = {
 	},
 };
 
+WithSuffixControl.args = {
+	...WithSuffixControl.args,
+	children: undefined,
+};
+export { WithSuffixControl };
+
 export const Disabled: Story = {
 	args: {
 		...Default.args,

package/src/form/primitives/input/style.module.css

@@ -2,6 +2,10 @@
 
 @layer wp-ui-components {
 	.input {
+		--_gcd-input-padding:
+			var(--wp-ui-input-padding-block, 0)
+			var(--wp-ui-input-layout-padding-inline, 0);
+
 		padding-block: var(--wp-ui-input-padding-block, 0);
 		padding-inline: var(--wp-ui-input-layout-padding-inline, 0);
 		width: 100%;

package/src/form/primitives/input-layout/input-layout.tsx

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import { Children, forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import resetStyles from '../../../utils/css/resets.module.css';
 import styles from './style.module.css';
 import type { InputLayoutProps } from './types';
@@ -26,6 +27,7 @@ export const InputLayout = forwardRef< HTMLDivElement, InputLayoutProps >(
 			<div
 				ref={ ref }
 				className={ clsx(
+					defenseStyles.div,
 					resetStyles[ 'box-sizing' ],
 					styles[ 'input-layout' ],
 					styles[ `is-size-${ size }` ],

package/src/form/primitives/input-layout/slot.tsx

@@ -9,13 +9,17 @@ import type { InputLayoutSlotProps } from './types';
 export const InputLayoutSlot = forwardRef<
 	HTMLDivElement,
 	InputLayoutSlotProps
->( function InputLayoutSlot( { padding = 'default', ...restProps }, ref ) {
+>( function InputLayoutSlot(
+	{ padding = 'default', className, ...restProps },
+	ref
+) {
 	return (
 		<div
 			ref={ ref }
 			className={ clsx(
 				styles[ 'input-layout-slot' ],
-				styles[ `is-padding-${ padding }` ]
+				styles[ `is-padding-${ padding }` ],
+				className
 			) }
 			{ ...restProps }
 		/>