@wordpress/ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,21 @@
+import clsx from 'clsx';
+import { Field as _Field } from '@base-ui/react/field';
+import { forwardRef } from '@wordpress/element';
+import fieldStyles from '../../../utils/css/field.module.css';
+import type { FieldLabelProps } from './types';
+
+export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
+	function Label( { className, variant, ...restProps }, ref ) {
+		return (
+			<_Field.Label
+				ref={ ref }
+				className={ clsx(
+					fieldStyles.label,
+					variant && fieldStyles[ `is-${ variant }` ],
+					className
+				) }
+				{ ...restProps }
+			/>
+		);
+	}
+);

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

@@ -0,0 +1,33 @@
+import clsx from 'clsx';
+import { Field as _Field } from '@base-ui/react/field';
+import { forwardRef } from '@wordpress/element';
+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 > ) => (
+	<Stack { ...props } direction="column" gap="xs" />
+);
+
+/**
+ * A low-level component that associates an accessible label and description
+ * with a single form control element.
+ *
+ * To label a group of multiple form control elements, use the `Fieldset` component instead.
+ *
+ * Simply wrapping a control with this component does not guarantee
+ * 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 },
+	ref
+) {
+	return (
+		<_Field.Root
+			ref={ ref }
+			className={ clsx( resetStyles[ 'box-sizing' ], className ) }
+			render={ render }
+			{ ...restProps }
+		/>
+	);
+} );

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

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useId } from '@wordpress/element';
+import '@wordpress/theme/design-tokens.css';
+import { Field } from '../../../..';
+
+const meta: Meta< typeof Field.Root > = {
+	title: 'Design System/Components/Form/Primitives/Field',
+	component: Field.Root,
+	subcomponents: {
+		Item: Field.Item,
+		Label: Field.Label,
+		Control: Field.Control,
+		Description: Field.Description,
+		Details: Field.Details,
+	},
+};
+export default meta;
+
+/**
+ * If your control component forwards refs, as well as the `aria-labelledby` and `aria-describedby` props
+ * to the actual underlying HTML element to be labeled,
+ * you can simply place your control in the `render` prop of `Field.Control`.
+ */
+export const Default: StoryObj< typeof Field.Root > = {
+	args: {
+		children: (
+			<>
+				<Field.Label>Label</Field.Label>
+				<Field.Control
+					render={ <input type="text" placeholder="Placeholder" /> }
+				/>
+				<Field.Description>
+					The accessible description.
+				</Field.Description>
+			</>
+		),
+	},
+};
+
+const MyNonRefForwardingControl = (
+	props: React.ComponentProps< 'input' >
+) => {
+	return <input type="text" { ...props } />;
+};
+
+/**
+ * If your control component does not forward refs, but does forward the `id` prop
+ * to the actual underlying HTML element to be labeled, use the `htmlFor` prop
+ * of the `Field.Label` component to associate the label with the control.
+ *
+ * This is preferred over `aria-labelledby` because it allows users to click the
+ * label to focus the control.
+ */
+export const UsingHtmlFor: StoryObj< typeof Field.Root > = {
+	name: 'Using htmlFor',
+	render: ( args ) => {
+		const controlId = useId();
+		const descriptionId = useId();
+
+		return (
+			<Field.Root { ...args }>
+				<Field.Label htmlFor={ controlId }>Label</Field.Label>
+				<MyNonRefForwardingControl
+					placeholder="Placeholder"
+					id={ controlId }
+					aria-describedby={ descriptionId }
+				/>
+				<Field.Description id={ descriptionId }>
+					The accessible description.
+				</Field.Description>
+			</Field.Root>
+		);
+	},
+};
+
+/**
+ * If your control component does not forward refs nor the `id` prop, but does
+ * forward the `aria-labelledby` prop to the actual underlying HTML element to be
+ * labeled, use the `id` prop of the `Field.Label` component to associate the
+ * label with the control.
+ */
+export const UsingAriaLabelledby: StoryObj< typeof Field.Root > = {
+	name: 'Using aria-labelledby',
+	render: ( args ) => {
+		const labelId = useId();
+		const descriptionId = useId();
+
+		return (
+			<Field.Root { ...args }>
+				<Field.Label id={ labelId }>Label</Field.Label>
+				<MyNonRefForwardingControl
+					placeholder="Placeholder"
+					aria-labelledby={ labelId }
+					aria-describedby={ descriptionId }
+				/>
+				<Field.Description id={ descriptionId }>
+					The accessible description.
+				</Field.Description>{ ' ' }
+			</Field.Root>
+		);
+	},
+};
+
+/**
+ * To add rich content (such as links) to the description, use `Field.Details`.
+ *
+ * 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.
+ *
+ * If the content only includes plain text, use `Field.Description` instead,
+ * so the readout is not unnecessarily verbose for screen reader users.
+ */
+export const WithDetails: StoryObj< typeof Field.Root > = {
+	args: {
+		children: (
+			<>
+				<Field.Label>Label</Field.Label>
+				<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>
+			</>
+		),
+	},
+};

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

@@ -0,0 +1,36 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import * as Field from '../index';
+
+describe( 'Field', () => {
+	it( 'forwards ref', () => {
+		const rootRef = createRef< HTMLDivElement >();
+		const itemRef = createRef< HTMLDivElement >();
+		const controlRef = createRef< HTMLInputElement >();
+		const labelRef = createRef< HTMLLabelElement >();
+		const descriptionRef = createRef< HTMLParagraphElement >();
+		const detailsRef = createRef< HTMLDivElement >();
+
+		render(
+			<Field.Root ref={ rootRef } name="test-field">
+				<Field.Item ref={ itemRef }>
+					<Field.Label ref={ labelRef }>Field Label</Field.Label>
+					<Field.Control ref={ controlRef } render={ <input /> } />
+					<Field.Description ref={ descriptionRef }>
+						Field description
+					</Field.Description>
+					<Field.Details ref={ detailsRef }>
+						Field <a href="#details">details</a>
+					</Field.Details>
+				</Field.Item>
+			</Field.Root>
+		);
+
+		expect( rootRef.current ).toBeInstanceOf( HTMLDivElement );
+		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
+		expect( controlRef.current ).toBeInstanceOf( HTMLInputElement );
+		expect( labelRef.current ).toBeInstanceOf( HTMLLabelElement );
+		expect( descriptionRef.current ).toBeInstanceOf( HTMLParagraphElement );
+		expect( detailsRef.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+} );

package/src/form/primitives/field/types.ts

@@ -0,0 +1,82 @@
+import type { Field } from '@base-ui/react/field';
+import type { ComponentProps } from '../../../utils/types';
+
+export type FieldRootProps = Omit<
+	ComponentProps< typeof Field.Root >,
+	| 'disabled'
+	// TODO: Maybe allow these when we have validation support ready.
+	| 'dirty'
+	| 'invalid'
+	| 'touched'
+	| 'validate'
+	| 'validationDebounceTime'
+	| 'validationMode'
+> & {
+	children?: Field.Root.Props[ 'children' ];
+	/**
+	 * Whether the field is disabled.
+	 *
+	 * @default false
+	 */
+	disabled?: Field.Root.Props[ 'disabled' ];
+};
+
+export type FieldItemProps = ComponentProps< typeof Field.Item > & {
+	children?: React.ReactNode;
+};
+
+export type FieldLabelProps = ComponentProps< typeof Field.Label > & {
+	/**
+	 * The label string, or the string and the element to associate it with.
+	 *
+	 * To keep things accessible, do not include other interactive
+	 * elements such as links or buttons.
+	 */
+	children?: Field.Label.Props[ 'children' ];
+	/**
+	 * The visual variant of the label.
+	 *
+	 * Use 'plain' for controls like checkboxes and radio buttons.
+	 *
+	 * @default 'default'
+	 */
+	variant?: 'default' | 'plain';
+};
+
+export type FieldControlProps = Omit<
+	ComponentProps< typeof Field.Control >,
+	'defaultValue'
+> & {
+	children?: Field.Control.Props[ 'children' ];
+	/**
+	 * The default value to use in uncontrolled mode.
+	 */
+	defaultValue?: Field.Control.Props[ 'defaultValue' ];
+};
+
+export type FieldDescriptionProps = ComponentProps<
+	typeof Field.Description
+> & {
+	/**
+	 * The accessible description, associated using `aria-describedby`.
+	 *
+	 * For screen reader accessibility, this should only contain plain text,
+	 * and no semantics such as links.
+	 */
+	children?: string;
+};
+
+export type FieldDetailsProps = ComponentProps< 'div' > & {
+	/**
+	 * Additional information about the field, which unlike a normal description,
+	 * can include links and other semantic elements.
+	 *
+	 * 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.
+	 *
+	 * Do not use this component when the details content is only plain text,
+	 * as it makes the readout unnecessarily verbose for screen reader users.
+	 */
+	children?: React.ReactNode;
+};

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

@@ -0,0 +1,13 @@
+import { createContext, useContext } from '@wordpress/element';
+
+type FieldsetContextType = {
+	registerDescriptionId: ( id: string ) => void;
+	unregisterDescriptionId: () => void;
+};
+
+export const FieldsetContext = createContext< FieldsetContextType >( {
+	registerDescriptionId: () => {},
+	unregisterDescriptionId: () => {},
+} );
+
+export const useFieldsetContext = () => useContext( FieldsetContext );

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

@@ -0,0 +1,36 @@
+import clsx from 'clsx';
+import { mergeProps, useRender } from '@base-ui/react';
+import { forwardRef, useEffect, useId } from '@wordpress/element';
+import fieldStyles from '../../../utils/css/field.module.css';
+import { useFieldsetContext } from './context';
+import type { FieldsetDescriptionProps } from './types';
+
+export const FieldsetDescription = forwardRef<
+	HTMLParagraphElement,
+	FieldsetDescriptionProps
+>( function FieldsetDescription(
+	{ className, id: idProp, render, ...restProps },
+	ref
+) {
+	const generatedId = useId();
+	const id = idProp ?? generatedId;
+	const { registerDescriptionId, unregisterDescriptionId } =
+		useFieldsetContext();
+
+	useEffect( () => {
+		registerDescriptionId( id );
+		return unregisterDescriptionId;
+	}, [ registerDescriptionId, unregisterDescriptionId, id ] );
+
+	const element = useRender( {
+		defaultTagName: 'p',
+		render,
+		ref,
+		props: mergeProps< 'p' >(
+			{ className: clsx( fieldStyles.description, className ), id },
+			restProps
+		),
+	} );
+
+	return element;
+} );

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

@@ -0,0 +1,46 @@
+import clsx from 'clsx';
+import { forwardRef, useEffect, useId } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import fieldStyles from '../../../utils/css/field.module.css';
+import { useFieldsetContext } from './context';
+import { VisuallyHidden } from '../../../visually-hidden';
+import type { FieldsetDetailsProps } from './types';
+
+/**
+ * A component for showing additional information about the fieldset,
+ * styled similarly to a normal `Fieldset.Description`.
+ * Unlike a normal description, it can include links and other semantic elements.
+ *
+ * Although this content is not associated with the fieldset 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.
+ *
+ * If the content only includes plain text, use `Fieldset.Description` instead,
+ * so the readout is not unnecessarily verbose for screen reader users.
+ */
+export const FieldsetDetails = forwardRef<
+	HTMLDivElement,
+	FieldsetDetailsProps
+>( function FieldsetDetails( { className, ...restProps }, ref ) {
+	const id = useId();
+	const { registerDescriptionId, unregisterDescriptionId } =
+		useFieldsetContext();
+
+	useEffect( () => {
+		registerDescriptionId( id );
+		return unregisterDescriptionId;
+	}, [ registerDescriptionId, unregisterDescriptionId, id ] );
+
+	return (
+		<>
+			<VisuallyHidden id={ id }>
+				{ __( 'More details follow.' ) }
+			</VisuallyHidden>
+			<div
+				ref={ ref }
+				className={ clsx( fieldStyles.description, className ) }
+				{ ...restProps }
+			/>
+		</>
+	);
+} );

package/src/form/primitives/fieldset/index.ts

@@ -0,0 +1,6 @@
+import { FieldsetRoot as Root } from './root';
+import { FieldsetLegend as Legend } from './legend';
+import { FieldsetDescription as Description } from './description';
+import { FieldsetDetails as Details } from './details';
+
+export { Root, Legend, Description, Details };

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

@@ -0,0 +1,17 @@
+import clsx from 'clsx';
+import { Fieldset as _Fieldset } from '@base-ui/react/fieldset';
+import { forwardRef } from '@wordpress/element';
+import fieldStyles from '../../../utils/css/field.module.css';
+import type { FieldsetLegendProps } from './types';
+
+export const FieldsetLegend = forwardRef< HTMLDivElement, FieldsetLegendProps >(
+	function FieldsetLegend( { className, ...restProps }, ref ) {
+		return (
+			<_Fieldset.Legend
+				ref={ ref }
+				className={ clsx( fieldStyles.label, className ) }
+				{ ...restProps }
+			/>
+		);
+	}
+);

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

@@ -0,0 +1,42 @@
+import clsx from 'clsx';
+import { Fieldset as _Fieldset } from '@base-ui/react/fieldset';
+import { forwardRef, useState, useMemo } from '@wordpress/element';
+import styles from './style.module.css';
+import { FieldsetContext } from './context';
+import type { FieldsetRootProps } from './types';
+
+/**
+ * A low-level component that associates an accessible legend and description with
+ * a group of multiple form control elements.
+ *
+ * To label a single form control element, use the `Field` component instead.
+ */
+export const FieldsetRoot = forwardRef<
+	HTMLFieldSetElement,
+	FieldsetRootProps
+>( function FieldsetRoot( { className, children, ...restProps }, ref ) {
+	const [ descriptionId, setDescriptionId ] = useState< string >();
+
+	const contextValue = useMemo(
+		() => ( {
+			registerDescriptionId: ( id: string ) => setDescriptionId( id ),
+			unregisterDescriptionId: () => setDescriptionId( undefined ),
+		} ),
+		[]
+	);
+
+	return (
+		<FieldsetContext.Provider value={ contextValue }>
+			<_Fieldset.Root
+				ref={ ref }
+				className={ clsx( styles.root, className ) }
+				// Certain screen readers may not read a fieldset's description
+				// https://w3c.github.io/using-aria/#label-support
+				aria-describedby={ descriptionId }
+				{ ...restProps }
+			>
+				{ children }
+			</_Fieldset.Root>
+		</FieldsetContext.Provider>
+	);
+} );

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

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Fieldset } from '../../../..';
+
+const meta: Meta< typeof Fieldset.Root > = {
+	title: 'Design System/Components/Form/Primitives/Fieldset',
+	component: Fieldset.Root,
+	subcomponents: {
+		Legend: Fieldset.Legend,
+		Description: Fieldset.Description,
+		Details: Fieldset.Details,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Fieldset.Root >;
+
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<Fieldset.Legend>Legend</Fieldset.Legend>
+				{ [ 'Apples', 'Bananas' ].map( ( fruit ) => (
+					// eslint-disable-next-line jsx-a11y/label-has-associated-control
+					<label key={ fruit }>
+						<input type="checkbox" /> { fruit }
+					</label>
+				) ) }
+				<Fieldset.Description>
+					This is a description for the entire fieldset.
+				</Fieldset.Description>
+			</>
+		),
+	},
+};
+
+/**
+ * To add rich content (such as links) to the description, use `Fieldset.Details`.
+ *
+ * Although this content is not associated with the fieldset 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.
+ *
+ * If the content only includes plain text, use `Fieldset.Description` instead,
+ * so the readout is not unnecessarily verbose for screen reader users.
+ */
+export const WithDetails: Story = {
+	args: {
+		children: (
+			<>
+				<Fieldset.Legend>Legend</Fieldset.Legend>
+				{ [ 'Apples', 'Bananas' ].map( ( fruit ) => (
+					// eslint-disable-next-line jsx-a11y/label-has-associated-control
+					<label key={ fruit }>
+						<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>
+			</>
+		),
+	},
+};

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

@@ -0,0 +1,12 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.root {
+		display: flex;
+		flex-direction: column;
+		gap: var(--wpds-dimension-gap-2xs);
+		border: 0;
+		margin: 0;
+		padding: 0;
+	}
+}

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

@@ -0,0 +1,135 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import * as Fieldset from '../';
+
+describe( 'Fieldset', () => {
+	it( 'forwards ref', () => {
+		const rootRef = createRef< HTMLFieldSetElement >();
+		const legendRef = createRef< HTMLDivElement >();
+		const descriptionRef = createRef< HTMLParagraphElement >();
+		const detailsRef = createRef< HTMLDivElement >();
+
+		render(
+			<Fieldset.Root ref={ rootRef }>
+				<Fieldset.Legend ref={ legendRef }>
+					Fieldset Legend
+				</Fieldset.Legend>
+				<Fieldset.Description ref={ descriptionRef }>
+					Fieldset description
+				</Fieldset.Description>
+				<Fieldset.Details ref={ detailsRef }>
+					Fieldset details
+				</Fieldset.Details>
+			</Fieldset.Root>
+		);
+
+		expect( rootRef.current ).toBeInstanceOf( HTMLFieldSetElement );
+		expect( legendRef.current ).toBeInstanceOf( HTMLDivElement );
+		expect( descriptionRef.current ).toBeInstanceOf( HTMLParagraphElement );
+		expect( detailsRef.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+
+	it( 'accessibly associates description when Fieldset.Description is present', () => {
+		render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+				<Fieldset.Description>
+					Select one or more options from the list below.
+				</Fieldset.Description>
+			</Fieldset.Root>
+		);
+
+		expect(
+			screen.getByRole( 'group', {
+				name: 'Choose your options',
+				description: 'Select one or more options from the list below.',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'does not add aria-describedby when Fieldset.Description is not present', () => {
+		render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		const fieldset = screen.getByRole( 'group', {
+			name: 'Choose your options',
+		} );
+
+		// Should not have aria-describedby
+		expect( fieldset ).not.toHaveAttribute( 'aria-describedby' );
+	} );
+
+	it( 'respects custom id on description', () => {
+		const customId = 'custom-description-id';
+
+		render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+				<Fieldset.Description id={ customId }>
+					Custom description with specific ID.
+				</Fieldset.Description>
+			</Fieldset.Root>
+		);
+
+		const description = screen.getByText(
+			'Custom description with specific ID.'
+		);
+		expect( description ).toHaveAttribute( 'id', customId );
+
+		expect(
+			screen.getByRole( 'group', {
+				name: 'Choose your options',
+				description: 'Custom description with specific ID.',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'forwards className to the description element', () => {
+		render(
+			<Fieldset.Root>
+				<Fieldset.Description className="custom-class">
+					Fieldset description
+				</Fieldset.Description>
+			</Fieldset.Root>
+		);
+
+		expect( screen.getByText( 'Fieldset description' ) ).toHaveClass(
+			'custom-class'
+		);
+	} );
+
+	it( 'announces additional details via a visually hidden description', () => {
+		render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+				<Fieldset.Details>
+					<a href="#more-info">Learn more about these options</a>
+				</Fieldset.Details>
+			</Fieldset.Root>
+		);
+
+		expect(
+			screen.getByRole( 'group', {
+				name: 'Choose your options',
+				description: 'More details follow.',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'forwards className to the details element', () => {
+		render(
+			<Fieldset.Root>
+				<Fieldset.Details className="custom-class">
+					Fieldset details
+				</Fieldset.Details>
+			</Fieldset.Root>
+		);
+
+		expect( screen.getByText( 'Fieldset details' ) ).toHaveClass(
+			'custom-class'
+		);
+	} );
+} );