@wordpress/ui 0.12.1-next.v.202604201441.0 → 0.13.0

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

@@ -1,9 +1,125 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
 import * as Select from '../index';
 
 describe( 'Select', () => {
+	it( 'supports object item values', async () => {
+		const user = userEvent.setup();
+		const onValueChange = jest.fn();
+		const users = [
+			{ value: '1', label: 'User 1' },
+			{ value: '2', label: 'User 2' },
+		];
+
+		render(
+			<Select.Root
+				defaultValue={ users[ 0 ] }
+				items={ users }
+				onValueChange={ onValueChange }
+			>
+				<Select.Trigger>{ ( value ) => value?.label }</Select.Trigger>
+				<Select.Popup>
+					{ users.map( ( option ) => (
+						<Select.Item key={ option.value } value={ option }>
+							{ option.label }
+						</Select.Item>
+					) ) }
+				</Select.Popup>
+			</Select.Root>
+		);
+
+		const trigger = screen.getByRole( 'combobox' );
+
+		expect( trigger ).toHaveTextContent( 'User 1' );
+
+		await user.click( trigger );
+		await user.click(
+			await screen.findByRole( 'option', { name: 'User 2' } )
+		);
+
+		expect( trigger ).toHaveTextContent( 'User 2' );
+		expect( onValueChange ).toHaveBeenCalledTimes( 1 );
+		expect( onValueChange ).toHaveBeenLastCalledWith(
+			users[ 1 ],
+			expect.objectContaining( { reason: expect.any( String ) } )
+		);
+	} );
+
+	it( 'auto-resolves trigger label from items when value is an object', () => {
+		const users = [
+			{ value: '1', label: 'User 1' },
+			{ value: '2', label: 'User 2' },
+		];
+
+		render(
+			<Select.Root defaultValue={ users[ 0 ] } items={ users }>
+				<Select.Trigger />
+				<Select.Popup>
+					{ users.map( ( option ) => (
+						<Select.Item key={ option.value } value={ option }>
+							{ option.label }
+						</Select.Item>
+					) ) }
+				</Select.Popup>
+			</Select.Root>
+		);
+
+		expect( screen.getByRole( 'combobox' ) ).toHaveTextContent( 'User 1' );
+	} );
+
+	it( 'renders a default placeholder when no value is selected', () => {
+		render(
+			<Select.Root>
+				<Select.Trigger />
+				<Select.Popup>
+					<Select.Item value="Item 1" />
+				</Select.Popup>
+			</Select.Root>
+		);
+
+		const placeholder = screen.getByText( 'Select' );
+
+		expect( screen.getByRole( 'combobox' ) ).toHaveTextContent( 'Select' );
+		expect( placeholder ).toHaveAttribute( 'data-placeholder' );
+	} );
+
+	it( 'supports custom placeholder text', () => {
+		render(
+			<Select.Root>
+				<Select.Trigger placeholder="Choose an item" />
+				<Select.Popup>
+					<Select.Item value="Item 1" />
+				</Select.Popup>
+			</Select.Root>
+		);
+
+		const placeholder = screen.getByText( 'Choose an item' );
+
+		expect( screen.getByRole( 'combobox' ) ).toHaveTextContent(
+			'Choose an item'
+		);
+		expect( placeholder ).toHaveAttribute( 'data-placeholder' );
+	} );
+
+	it( 'does not use placeholder styling when a value is selected', () => {
+		render(
+			<Select.Root defaultValue="Item 1">
+				<Select.Trigger />
+				<Select.Popup>
+					<Select.Item value="Item 1" />
+				</Select.Popup>
+			</Select.Root>
+		);
+
+		const trigger = screen.getByRole( 'combobox' );
+
+		expect( trigger ).toHaveTextContent( 'Item 1' );
+		expect( within( trigger ).getByText( 'Item 1' ) ).not.toHaveAttribute(
+			'data-placeholder'
+		);
+	} );
+
 	it( 'forwards ref', async () => {
 		const user = userEvent.setup();
 		const triggerRef = createRef< HTMLButtonElement >();
@@ -14,8 +130,10 @@ describe( 'Select', () => {
 			<Select.Root>
 				<Select.Trigger ref={ triggerRef } />
 				<Select.Popup ref={ popupRef }>
-					<Select.Item ref={ itemRef } value="Item 1" />
-					<Select.Item value="Item 2" />
+					<Select.Item ref={ itemRef } value="Item 1">
+						Item 1
+					</Select.Item>
+					<Select.Item value="Item 2">Item 2</Select.Item>
 				</Select.Popup>
 			</Select.Root>
 		);
@@ -31,8 +149,8 @@ describe( 'Select', () => {
 		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
 
-	describe( 'container', () => {
-		it( 'should render inside the container when provided', async () => {
+	describe( 'portal', () => {
+		it( 'should render inside the portal container when a custom target is provided', async () => {
 			const user = userEvent.setup();
 			const containerRef = createRef< HTMLDivElement >();
 
@@ -44,8 +162,12 @@ describe( 'Select', () => {
 							ref={ containerRef }
 							data-testid="custom-container"
 						/>
-						<Select.Popup container={ containerRef }>
-							<Select.Item value="Item 1" />
+						<Select.Popup
+							portal={
+								<Select.Portal container={ containerRef } />
+							}
+						>
+							<Select.Item value="Item 1">Item 1</Select.Item>
 						</Select.Popup>
 					</Select.Root>
 				</div>
@@ -71,7 +193,7 @@ describe( 'Select', () => {
 					<Select.Root>
 						<Select.Trigger />
 						<Select.Popup>
-							<Select.Item value="Item 1" />
+							<Select.Item value="Item 1">Item 1</Select.Item>
 						</Select.Popup>
 					</Select.Root>
 				</div>

package/src/form/primitives/select/trigger.tsx

@@ -2,6 +2,7 @@ import { Select as _Select } from '@base-ui/react/select';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { chevronDown } from '@wordpress/icons';
+import { __ } from '@wordpress/i18n';
 import focusStyles from '../../../utils/css/focus.module.css';
 import selectTriggerStyles from '../../../utils/css/select-trigger.module.css';
 import { InputLayout } from '../input-layout';
@@ -10,7 +11,14 @@ import type { SelectTriggerProps } from './types';
 
 export const Trigger = forwardRef< HTMLButtonElement, SelectTriggerProps >(
 	function Trigger(
-		{ className, size, variant, children, ...restProps },
+		{
+			className,
+			size,
+			variant,
+			children,
+			placeholder = __( 'Select' ),
+			...restProps
+		},
 		ref
 	) {
 		return (
@@ -36,13 +44,8 @@ export const Trigger = forwardRef< HTMLButtonElement, SelectTriggerProps >(
 					ref={ ref }
 				>
 					<_Select.Value
-						className={ ( state ) =>
-							clsx(
-								selectTriggerStyles[ 'trigger-value' ],
-								state.value === '' &&
-									selectTriggerStyles[ 'is-placeholder' ]
-							)
-						}
+						placeholder={ placeholder }
+						className={ selectTriggerStyles[ 'trigger-value' ] }
 					>
 						{ children }
 					</_Select.Value>

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

@@ -1,10 +1,14 @@
 import type { Select as _Select } from '@base-ui/react/select';
+import type { ComponentPropsWithoutRef, ReactElement } from 'react';
+
 import type { ComponentProps } from '../../../utils/types';
 import type { InputLayoutProps } from '../input-layout/types';
 
+export type PortalProps = ComponentPropsWithoutRef< typeof _Select.Portal >;
+
 // The second type parameter is the `multiple` flag (currently disabled).
-export type SelectRootProps = Omit<
-	_Select.Root.Props< string, false >,
+export type SelectRootProps< Value = unknown > = Omit<
+	_Select.Root.Props< Value, false >,
 	'multiple'
 >;
 
@@ -21,9 +25,19 @@ export type SelectTriggerProps = ComponentProps< typeof _Select.Trigger > & {
 	 * @default 'default'
 	 */
 	variant?: 'default' | 'minimal';
+	/**
+	 * Text to show when no value is selected.
+	 * This is overridden by `children` if specified, or by a null item's label in `items`.
+	 *
+	 * @default __( 'Select' )
+	 */
+	placeholder?: _Select.Value.Props[ 'placeholder' ];
 	/**
 	 * A function that gets called with the current value as an argument.
 	 * Use this to customize the trigger content.
+	 *
+	 * When no value is selected, the rendered content inherits the
+	 * placeholder text color.
 	 */
 	children?: _Select.Value.Props[ 'children' ];
 };
@@ -34,9 +48,12 @@ export type SelectPopupProps = ComponentProps< typeof _Select.Popup > & {
 	 */
 	children?: React.ReactNode;
 	/**
-	 * A parent element to render the portal into.
+	 * Optional portal element, typically `<Select.Portal />` with custom
+	 * `container`. When omitted, `Select.Popup` uses `Select.Portal` with
+	 * default props. Do not pass `children` on the portal element; they would
+	 * be ignored.
 	 */
-	container?: _Select.Portal.Props[ 'container' ];
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
 };
 
 export type SelectItemProps = Omit<
@@ -46,7 +63,7 @@ export type SelectItemProps = Omit<
 	/**
 	 * A unique value that identifies this select item.
 	 */
-	value?: string;
+	value?: unknown;
 	/**
 	 * The size of the item.
 	 *
@@ -55,8 +72,6 @@ export type SelectItemProps = Omit<
 	size?: InputLayoutProps[ 'size' ];
 	/**
 	 * The content of the item.
-	 *
-	 * @default `value`
 	 */
 	children?: _Select.Item.Props[ 'children' ];
 };

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

@@ -4,6 +4,13 @@ import { Textarea } from '../index';
 const meta: Meta< typeof Textarea > = {
 	title: 'Design System/Components/Form/Primitives/Textarea',
 	component: Textarea,
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components` and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/form/select-control/context.tsx

@@ -0,0 +1,9 @@
+import { createContext, useContext } from '@wordpress/element';
+import type { SelectTriggerProps } from '../primitives/select/types';
+
+export const SelectControlSizeContext =
+	createContext< SelectTriggerProps[ 'size' ] >( undefined );
+
+export const useSelectControlSizeContext = () => {
+	return useContext( SelectControlSizeContext );
+};

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

@@ -0,0 +1,14 @@
+import { SelectControl as _SelectControl } from './select-control';
+import { Item } from './item';
+
+Item.displayName = 'SelectControl.Item';
+
+/**
+ * A complete select field with integrated label and description.
+ */
+export const SelectControl = Object.assign( _SelectControl, {
+	/**
+	 * An item rendered inside a `SelectControl` popup.
+	 */
+	Item,
+} );

package/src/form/select-control/item.tsx

@@ -0,0 +1,13 @@
+import { forwardRef } from '@wordpress/element';
+import { Select } from '../primitives';
+import { useSelectControlSizeContext } from './context';
+import type { SelectItemProps } from '../primitives/select/types';
+
+export const Item = forwardRef< HTMLDivElement, SelectItemProps >(
+	function Item( { size: sizeProp, ...restProps }, ref ) {
+		const contextSize = useSelectControlSizeContext();
+		const size = sizeProp ?? contextSize;
+
+		return <Select.Item size={ size } ref={ ref } { ...restProps } />;
+	}
+);

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

@@ -0,0 +1,65 @@
+import { forwardRef } from '@wordpress/element';
+import { Field, Select } from '../primitives';
+import { SelectControlSizeContext } from './context';
+import { Item } from './item';
+import type { SelectControlProps } from './types';
+
+/**
+ * A complete select field with integrated label and description.
+ */
+export const SelectControl = forwardRef<
+	HTMLButtonElement,
+	SelectControlProps
+>( function SelectControl(
+	{
+		className,
+		children,
+		items,
+		label,
+		description,
+		details,
+		hideLabelFromVision,
+		placeholder,
+		size = 'default',
+		triggerContent,
+		...restProps
+	},
+	ref
+) {
+	return (
+		<Field.Root className={ className }>
+			<Field.Label hideFromVision={ hideLabelFromVision }>
+				{ label }
+			</Field.Label>
+			<Select.Root items={ items } { ...restProps }>
+				<Select.Trigger
+					ref={ ref }
+					placeholder={ placeholder }
+					size={ size }
+				>
+					{ triggerContent }
+				</Select.Trigger>
+				<Select.Popup>
+					<SelectControlSizeContext.Provider value={ size }>
+						{ children !== undefined
+							? children
+							: items?.map( ( item ) => (
+									<Item
+										key={ item.value ?? 'null' }
+										value={ item }
+										label={ item.label }
+										disabled={ item.disabled }
+									>
+										{ item.label }
+									</Item>
+							  ) ) }
+					</SelectControlSizeContext.Provider>
+				</Select.Popup>
+			</Select.Root>
+			{ description && (
+				<Field.Description>{ description }</Field.Description>
+			) }
+			{ details && <Field.Details>{ details }</Field.Details> }
+		</Field.Root>
+	);
+} );

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

@@ -0,0 +1,220 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { SelectControl } from '../';
+import {
+	WITH_DETAILS_DESCRIPTION,
+	DETAILS_EXAMPLE,
+} from '../../stories/shared';
+
+const meta: Meta< typeof SelectControl > = {
+	title: 'Design System/Components/Form/SelectControl',
+	component: SelectControl,
+	subcomponents: {
+		'SelectControl.Item': SelectControl.Item,
+	},
+	argTypes: {
+		onValueChange: { action: 'onValueChange' },
+	},
+};
+
+export default meta;
+
+type Story = StoryObj< typeof SelectControl >;
+
+const defaultItems = [
+	{
+		value: '1',
+		label: 'Item 1',
+	},
+	{
+		value: '2',
+		label: 'Item 2',
+	},
+];
+
+export const Default: Story = {
+	args: {
+		items: defaultItems,
+		label: 'Label',
+		description: 'This is the description.',
+	},
+};
+
+/**
+ * When no value is selected, the trigger shows the default placeholder text.
+ *
+ * Use the `placeholder` prop to customize text shown.
+ * Prefer a concise label without a trailing ellipsis.
+ */
+export const WithCustomPlaceholder: Story = {
+	args: {
+		...Default.args,
+		placeholder: 'Choose an item',
+	},
+};
+
+const nullValueOptionItems = [
+	{
+		value: null,
+		label: 'Select theme',
+	},
+	{
+		value: 'system',
+		label: 'System default',
+	},
+	{
+		value: 'light',
+		label: 'Light',
+	},
+	{
+		value: 'dark',
+		label: 'Dark',
+	},
+];
+
+/**
+ * Use a `null` item value when users should be able to clear the selected value
+ * from the popup.
+ */
+export const WithNullValueOption: Story = {
+	args: {
+		items: nullValueOptionItems,
+		label: 'Theme',
+		description: 'Choose a theme preference.',
+		defaultValue: nullValueOptionItems[ 0 ],
+	},
+};
+
+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,
+	},
+};
+
+const disabledOptionItems = [
+	{
+		value: '1',
+		label: 'Item 1',
+	},
+	{
+		value: '2',
+		label: 'Item 2',
+		disabled: true,
+	},
+];
+
+export const WithDisabledOption: Story = {
+	args: {
+		items: disabledOptionItems,
+		label: 'Label',
+		description: 'This is the description.',
+		defaultValue: disabledOptionItems[ 0 ],
+	},
+};
+
+const userOptions: React.ComponentProps< typeof SelectControl >[ 'items' ] = [
+	{
+		value: '1',
+		label: 'User 1 (Admin)',
+	},
+	{
+		value: '2',
+		label: 'User 2 (Editor)',
+	},
+	{
+		value: '3',
+		label: 'User 3 (Author)',
+	},
+];
+
+const User = ( { user }: { user: ( typeof userOptions )[ number ] } ) => (
+	<span
+		style={ {
+			display: 'flex',
+			alignItems: 'center',
+			gap: 8,
+		} }
+	>
+		<img
+			src={ `https://gravatar.com/avatar/?d=initials&name=${
+				user.value ?? 'null'
+			}` }
+			alt=""
+			width="20"
+			style={ {
+				borderRadius: '50%',
+			} }
+		/>
+		{ user.label }
+	</span>
+);
+
+/**
+ * To customize what is rendered inside the trigger element, pass a
+ * render function to the `triggerContent` prop.
+ *
+ * The item list can be customized by passing an array of
+ * `SelectControl.Item` as children. Note that the `label` prop of a `SelectControl.Item`
+ * is used as the string to match against in the typeahead functionality, while the
+ * item content is determined by `children`.
+ */
+export const WithCustomTriggerAndItems: Story = {
+	args: {
+		items: userOptions,
+		label: 'Label',
+		description: 'This is the description.',
+		triggerContent: ( item ) => <User user={ item } />,
+		children: (
+			<>
+				{ userOptions.map( ( item ) => (
+					<SelectControl.Item
+						key={ item.value }
+						value={ item }
+						label={ item.label }
+					>
+						<User user={ item } />
+					</SelectControl.Item>
+				) ) }
+			</>
+		),
+		defaultValue: userOptions[ 0 ],
+	},
+};
+
+/**
+ * By default, the `items` array is used to render both the Trigger
+ * and the Item list. Passing a custom `triggerContent` or `children` in addition
+ * to `items` will override that particular aspect of the behavior.
+ * In other words, if you pass both an `items` array and a custom `triggerContent`,
+ * the Item list in the popover will still be rendered based on the `items` array.
+ */
+export const WithItemsArrayAndPartialCustomization: Story = {
+	args: {
+		...Default.args,
+		children: (
+			<>
+				{ Default.args?.items?.map( ( item ) => (
+					<SelectControl.Item
+						key={ item.value ?? 'null' }
+						value={ item }
+						label={ item.label }
+						disabled={ item.disabled }
+					>
+						✨ { item.label }
+					</SelectControl.Item>
+				) ) }
+			</>
+		),
+	},
+};