@wordpress/ui 0.9.1-next.v.202603102151.0 → 0.10.0

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/root.tsx

@@ -5,7 +5,7 @@ import resetStyles from '../../../utils/css/resets.module.css';
 import type { FieldRootProps } from './types';
 import { Stack } from '../../../stack';
 
-const DEFAULT_RENDER = ( props: React.ComponentProps< typeof Stack > ) => (
+const defaultRender = ( props: React.ComponentProps< typeof Stack > ) => (
 	<Stack { ...props } direction="column" gap="sm" />
 );
 
@@ -19,7 +19,7 @@ const DEFAULT_RENDER = ( props: React.ComponentProps< typeof Stack > ) => (
  * accessible labeling. See examples for how to associate the label in different cases.
  */
 export const Root = forwardRef< HTMLDivElement, FieldRootProps >( function Root(
-	{ className, render = DEFAULT_RENDER, ...restProps },
+	{ className, render = defaultRender, ...restProps },
 	ref
 ) {
 	return (

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/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/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-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 }
 		/>

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

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { InputLayout } from '../../../..';
+import { copy } from '@wordpress/icons';
+import { IconButton, InputLayout } from '../../../..';
 
 const meta: Meta< typeof InputLayout > = {
 	title: 'Design System/Components/Form/Primitives/InputLayout',
@@ -50,6 +51,26 @@ export const WithPaddedPrefix: Story = {
 	},
 };
 
+/**
+ * The `padding="minimal"` setting on `InputLayout.Slot` will work best when
+ * the slot content is a button or icon.
+ */
+export const WithSuffixControl: Story = {
+	args: {
+		children: <div style={ { flex: 1 } } />,
+		suffix: (
+			<InputLayout.Slot padding="minimal">
+				<IconButton
+					size="small"
+					variant="minimal"
+					icon={ copy }
+					label="Copy"
+				/>
+			</InputLayout.Slot>
+		),
+	},
+};
+
 export const Compact: Story = {
 	args: {
 		size: 'compact',

package/src/form/primitives/stories/overview.mdx

@@ -0,0 +1,15 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+# Form Primitives
+
+<Meta title="Design System/Components/Form/Primitives" name="Overview" />
+
+These form primitives are the low-level building blocks for form-related components. Outside of rare, special use cases, a normal developer should not need to use these primitives directly.
+
+## When to use these primitives
+
+1. First check if there is a higher-level `*Control` component that meets your needs, either in this package, or if not, in [`@wordpress/components`](https://wordpress.github.io/gutenberg/?path=/docs/components-introduction--docs). Also consider using [`DataForm`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dataviews/#dataform), an even higher-level abstraction.
+2. If not, discuss with your designer whether the design can be altered to not require these primitives.
+3. If not, then these primitives are the next best option. Keep in mind that you are responsible for ensuring that your implementation is accessible, and adheres to Design System guidelines.
+
+Feel free to reach out to the `#design-system` channel on the [Make WordPress Slack](https://make.wordpress.org/chat/) for guidance.

package/src/form/primitives/textarea/textarea.tsx

@@ -9,7 +9,7 @@ const wrappedRender = (
 	render: NonNullable< TextareaProps[ 'render' ] >,
 	restProps: TextareaProps & { ref: React.Ref< HTMLTextAreaElement > }
 ) => {
-	return function Render(
+	return function textareaRender(
 		props: React.HTMLAttributes< HTMLTextAreaElement >
 	) {
 		return typeof render === 'function'

package/src/form/stories/shared.tsx

@@ -0,0 +1,19 @@
+export const WITH_DETAILS_DESCRIPTION = `\
+To add rich content (such as links) to the description, use the \`details\` prop.
+
+Although this content is not associated with the field using direct semantics,
+it is made discoverable to screen reader users via a visually hidden description,
+alerting them to the presence of additional information below.
+
+**Important:** If the content only includes plain text, use \`description\` instead,
+so the readout is not unnecessarily verbose for screen reader users.`;
+
+export const DETAILS_EXAMPLE = (
+	<>
+		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.
+	</>
+);

package/src/form/types.ts

@@ -0,0 +1,34 @@
+import type { Field } from './primitives';
+
+export type ControlProps = {
+	/**
+	 * The accessible label. All controls must be labeled.
+	 */
+	label: React.ComponentProps< typeof Field.Label >[ 'children' ];
+	/**
+	 * The accessible description, associated using `aria-describedby`.
+	 *
+	 * For screen reader accessibility, this should only contain plain text,
+	 * and no semantics such as links.
+	 */
+	description?: React.ComponentProps<
+		typeof Field.Description
+	>[ 'children' ];
+	/**
+	 * Additional information about the field, which unlike a normal description,
+	 * can include links and other semantic elements.
+	 *
+	 * Do not use this prop when the content is only plain text;
+	 * use `description` instead.
+	 */
+	details?: React.ComponentProps< typeof Field.Details >[ 'children' ];
+	/**
+	 * Whether to visually hide the label while keeping it accessible
+	 * to screen readers.
+	 *
+	 * @default false
+	 */
+	hideLabelFromVision?: React.ComponentProps<
+		typeof Field.Label
+	>[ 'hideFromVision' ];
+};

package/src/index.ts

@@ -1,9 +1,12 @@
 export * from './badge';
 export * from './button';
 export * as Card from './card';
+export * as Collapsible from './collapsible';
 export * as CollapsibleCard from './collapsible-card';
+export * as AlertDialog from './alert-dialog';
 export * as Dialog from './dialog';
-export * from './form/primitives';
+export * as EmptyState from './empty-state';
+export * from './form';
 export * from './icon';
 export * from './icon-button';
 export * from './link';

package/src/notice/index.ts

@@ -15,5 +15,3 @@ export {
 	ActionButton,
 	ActionLink,
 };
-
-export type { NoticeIntent } from './types';

package/src/notice/style.module.css

@@ -115,7 +115,7 @@
 		--wp-ui-notice-decorative-icon-color: var(--wpds-color-fg-content-error-weak);
 	}
 
-	/* TODO: Replace 320px with a measure token from the Theme package. */
+	/* Matches --wpds-dimension-surface-width-sm (container queries don't support custom properties). */
 	@container (max-width: 320px) {
 		.notice:has(.title) .description,
 		.notice:has(.title) .actions {

package/src/tabs/context.tsx

@@ -0,0 +1,170 @@
+import {
+	createContext,
+	useContext,
+	useCallback,
+	useMemo,
+	useRef,
+	useEffect,
+} from '@wordpress/element';
+
+type TabsValidationContextType = {
+	registerTab: () => () => void;
+	registerPanel: () => () => void;
+};
+
+/**
+ * Whether validation is enabled. This is a build-time constant that allows
+ * bundlers to tree-shake all validation code in production builds.
+ */
+const VALIDATION_ENABLED = process.env.NODE_ENV !== 'production';
+
+const TabsValidationContext = VALIDATION_ENABLED
+	? createContext< TabsValidationContextType | null >( null )
+	: ( null as unknown as React.Context< TabsValidationContextType | null > );
+
+function useRegisterTabDev() {
+	const context = useContext( TabsValidationContext );
+
+	useEffect( () => {
+		if ( context ) {
+			return context.registerTab();
+		}
+		return undefined;
+	}, [ context ] );
+}
+
+function useRegisterTabProd() {
+	// No-op in production.
+}
+
+/**
+ * Hook that registers a Tab for count validation in development mode.
+ */
+export const useRegisterTab = VALIDATION_ENABLED
+	? useRegisterTabDev
+	: useRegisterTabProd;
+
+function useRegisterPanelDev() {
+	const context = useContext( TabsValidationContext );
+
+	useEffect( () => {
+		if ( context ) {
+			return context.registerPanel();
+		}
+		return undefined;
+	}, [ context ] );
+}
+
+function useRegisterPanelProd() {
+	// No-op in production.
+}
+
+/**
+ * Hook that registers a Panel for count validation in development mode.
+ */
+export const useRegisterPanel = VALIDATION_ENABLED
+	? useRegisterPanelDev
+	: useRegisterPanelProd;
+
+/**
+ * Development-only provider that tracks the number of registered tabs and
+ * panels, and warns when the counts don't match.
+ */
+function TabsValidationProviderDev( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	const tabCountRef = useRef( 0 );
+	const panelCountRef = useRef( 0 );
+	const validationScheduledRef = useRef< ReturnType<
+		typeof setTimeout
+	> | null >( null );
+
+	const scheduleValidation = useCallback( () => {
+		if ( validationScheduledRef.current ) {
+			clearTimeout( validationScheduledRef.current );
+		}
+
+		// Schedule validation for the next tick to allow all
+		// registrations/unregistrations to complete.
+		validationScheduledRef.current = setTimeout( () => {
+			const tabCount = tabCountRef.current;
+			const panelCount = panelCountRef.current;
+
+			if ( tabCount !== panelCount ) {
+				throw new Error(
+					`Tabs: Tab/Panel count mismatch (${ tabCount } Tabs, ${ panelCount } Panels). ` +
+						`Each Tab must be associated with exactly one Panel. ` +
+						`Mismatched or missing associations can break screen reader navigation ` +
+						`and violate WAI-ARIA Tabs pattern requirements.`
+				);
+			}
+
+			validationScheduledRef.current = null;
+		}, 0 );
+	}, [] );
+
+	const registerTab = useCallback( () => {
+		tabCountRef.current += 1;
+		scheduleValidation();
+
+		return () => {
+			tabCountRef.current -= 1;
+			scheduleValidation();
+		};
+	}, [ scheduleValidation ] );
+
+	const registerPanel = useCallback( () => {
+		panelCountRef.current += 1;
+		scheduleValidation();
+
+		return () => {
+			panelCountRef.current -= 1;
+			scheduleValidation();
+		};
+	}, [ scheduleValidation ] );
+
+	useEffect( () => {
+		return () => {
+			if ( validationScheduledRef.current ) {
+				clearTimeout( validationScheduledRef.current );
+			}
+		};
+	}, [] );
+
+	const contextValue = useMemo(
+		() => ( {
+			registerTab,
+			registerPanel,
+		} ),
+		[ registerTab, registerPanel ]
+	);
+
+	return (
+		<TabsValidationContext.Provider value={ contextValue }>
+			{ children }
+		</TabsValidationContext.Provider>
+	);
+}
+
+/**
+ * Production no-op provider that just renders children.
+ */
+function TabsValidationProviderProd( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	return <>{ children }</>;
+}
+
+/**
+ * Provider component that validates the number of tabs matches the number
+ * of panels in development mode.
+ *
+ * In production, this component is a no-op and just renders children.
+ */
+export const TabsValidationProvider = VALIDATION_ENABLED
+	? TabsValidationProviderDev
+	: TabsValidationProviderProd;

package/src/tabs/panel.tsx

@@ -1,6 +1,7 @@
 import { forwardRef } from '@wordpress/element';
 import clsx from 'clsx';
 import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import { useRegisterPanel } from './context';
 import styles from './style.module.css';
 import type { TabPanelProps } from './types';
 
@@ -12,6 +13,8 @@ import type { TabPanelProps } from './types';
  */
 export const Panel = forwardRef< HTMLDivElement, TabPanelProps >(
 	function TabPanel( { className, ...otherProps }, forwardedRef ) {
+		useRegisterPanel();
+
 		return (
 			<_Tabs.Panel
 				ref={ forwardedRef }

package/src/tabs/root.tsx

@@ -1,5 +1,6 @@
 import { forwardRef } from '@wordpress/element';
 import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import { TabsValidationProvider } from './context';
 import type { TabRootProps } from './types';
 
 /**
@@ -10,6 +11,10 @@ import type { TabRootProps } from './types';
  */
 export const Root = forwardRef< HTMLDivElement, TabRootProps >(
 	function TabsRoot( { ...otherProps }, forwardedRef ) {
-		return <_Tabs.Root ref={ forwardedRef } { ...otherProps } />;
+		return (
+			<TabsValidationProvider>
+				<_Tabs.Root ref={ forwardedRef } { ...otherProps } />
+			</TabsValidationProvider>
+		);
 	}
 );