@wordpress/ui 0.12.0 → 0.13.0

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

@@ -5,26 +5,39 @@ const meta: Meta< typeof Select.Root > = {
 	title: 'Design System/Components/Form/Primitives/Select',
 	component: Select.Root,
 	subcomponents: {
-		Trigger: Select.Trigger,
-		Popup: Select.Popup,
-		Item: Select.Item,
+		'Select.Trigger': Select.Trigger,
+		'Select.Portal': Select.Portal,
+		'Select.Popup': Select.Popup,
+		'Select.Item': Select.Item,
+	},
+	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`, overlays compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 };
 export default meta;
 
 type Story = StoryObj< typeof Select.Root >;
 
+const defaultItems = Array.from( { length: 6 }, ( _, index ) => ( {
+	value: `item-${ index + 1 }`,
+	label: `Item ${ index + 1 }`,
+} ) );
+
 export const Default: Story = {
 	args: {
+		items: defaultItems,
 		children: (
 			<>
 				<Select.Trigger />
 				<Select.Popup>
-					{ Array.from( { length: 6 }, ( _, index ) => (
-						<Select.Item
-							key={ index }
-							value={ `Item ${ index + 1 }` }
-						/>
+					{ defaultItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
 					) ) }
 				</Select.Popup>
 			</>
@@ -34,21 +47,23 @@ export const Default: Story = {
 
 export const Compact: Story = {
 	args: {
+		...Default.args,
 		children: (
 			<>
 				<Select.Trigger size="compact" />
 				<Select.Popup>
-					{ Array.from( { length: 6 }, ( _, index ) => (
+					{ defaultItems.map( ( item ) => (
 						<Select.Item
-							key={ index }
-							value={ `Item ${ index + 1 }` }
+							key={ item.value }
+							value={ item }
 							size="compact"
-						/>
+						>
+							{ item.label }
+						</Select.Item>
 					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'Item 1',
 	},
 };
 
@@ -71,7 +86,9 @@ export const Minimal: Story = {
 							key={ index }
 							value={ `${ index + 1 }` }
 							size="small"
-						/>
+						>
+							{ `${ index + 1 }` }
+						</Select.Item>
 					) ) }
 				</Select.Popup>
 			</>
@@ -80,38 +97,51 @@ export const Minimal: Story = {
 	},
 };
 
-const withEmptyOptionItems = [
-	{
-		value: '',
-		label: 'Select',
-		disabled: true,
-	},
-	{
-		value: 'Item 2',
-		label: 'Item 2',
+/**
+ * Use the `placeholder` prop on `Select.Trigger` to show text when no
+ * value is selected. The default placeholder is `"Select"`.
+ */
+export const WithCustomPlaceholder: Story = {
+	args: {
+		items: defaultItems,
+		children: (
+			<>
+				<Select.Trigger placeholder="Choose an item" />
+				<Select.Popup>
+					{ defaultItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
+					) ) }
+				</Select.Popup>
+			</>
+		),
 	},
+};
+
+const nullValueOptionItems = [
+	{ value: null, label: 'Select theme' },
+	{ value: 'system', label: 'System default' },
+	{ value: 'light', label: 'Light' },
+	{ value: 'dark', label: 'Dark' },
 ];
 
 /**
- * By passing an `items` array to `Select.Root`, the `Select.Trigger` will be able to
- * render a `label` string for each item rather than the raw `value` string. In this
- * case, the option with an empty string value has a `"Select"` label string.
- *
- * This may be easier than writing a custom render function for the `Select.Trigger`.
+ * Use a `null` item when users should be able to clear the selected value from
+ * the popup. When `items` includes a `null` item, its label is used as the
+ * placeholder text.
  */
-export const WithEmptyValueOption: Story = {
+export const WithNullValueOption: Story = {
 	args: {
-		items: withEmptyOptionItems,
+		items: nullValueOptionItems,
 		children: (
 			<>
 				<Select.Trigger />
 				<Select.Popup>
-					{ withEmptyOptionItems.map( ( item ) => (
+					{ nullValueOptionItems.map( ( item ) => (
 						<Select.Item
-							key={ item.value }
+							key={ item.value ?? 'null' }
 							value={ item.value }
-							label={ item.label }
-							disabled={ item.disabled }
 						>
 							{ item.label }
 						</Select.Item>
@@ -119,7 +149,6 @@ export const WithEmptyValueOption: Story = {
 				</Select.Popup>
 			</>
 		),
-		defaultValue: '',
 	},
 };
 
@@ -131,75 +160,117 @@ export const WithEmptyValueOption: Story = {
  */
 export const Labeling: Story = {
 	args: {
+		...Default.args,
 		children: (
 			<>
 				<Select.Trigger aria-label="User role" />
 				<Select.Popup>
-					<Select.Item value="Administrator" />
-					<Select.Item value="Editor" />
+					{ defaultItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
+					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'Administrator',
 	},
 };
 
 const longItemValue =
 	'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.';
 
+const overflowItems = [
+	{
+		value: 'long-item',
+		label: longItemValue,
+	},
+	{
+		value: 'item-2',
+		label: 'Item 2',
+	},
+];
+
 export const WithOverflow: Story = {
 	args: {
+		items: overflowItems,
 		children: (
 			<>
 				<Select.Trigger />
 				<Select.Popup>
-					<Select.Item value={ longItemValue } />
-					<Select.Item value="Item 2" />
+					{ overflowItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
+					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: longItemValue,
+		defaultValue: overflowItems[ 0 ],
 	},
 };
 
 export const Disabled: Story = {
 	args: {
+		...Default.args,
 		children: (
 			<>
 				<Select.Trigger />
 				<Select.Popup>
-					<Select.Item value="Item 1" />
-					<Select.Item value="Item 2" />
+					{ defaultItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
+					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'Item 1',
+		defaultValue: defaultItems[ 0 ],
 		disabled: true,
 	},
 };
 
+const disabledItemItems = [
+	{
+		value: 'item-1',
+		label: 'Item 1',
+	},
+	{
+		value: 'item-2',
+		label: 'Item 2',
+		disabled: true,
+	},
+];
+
 export const WithDisabledItem: Story = {
 	args: {
+		items: disabledItemItems,
 		children: (
 			<>
 				<Select.Trigger />
 				<Select.Popup>
-					<Select.Item value="Item 1" />
-					<Select.Item value="Item 2" disabled />
+					{ disabledItemItems.map( ( item ) => (
+						<Select.Item
+							key={ item.value }
+							value={ item }
+							disabled={ item.disabled }
+						>
+							{ item.label }
+						</Select.Item>
+					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'Item 1',
+		defaultValue: disabledItemItems[ 0 ],
 	},
 };
 
 const customOptions = [
 	{
-		value: 'User 1',
+		value: 'user-1',
 		label: 'User 1 (Admin)',
 	},
 	{
-		value: 'User 2',
+		value: 'user-2',
 		label: 'User 2 (Editor)',
 	},
 ];
@@ -210,10 +281,11 @@ const customOptions = [
  */
 export const WithCustomTriggerAndItem: Story = {
 	args: {
+		items: customOptions,
 		children: (
 			<>
 				<Select.Trigger>
-					{ ( value ) => (
+					{ ( item ) => (
 						<span
 							style={ {
 								display: 'flex',
@@ -222,31 +294,27 @@ export const WithCustomTriggerAndItem: Story = {
 							} }
 						>
 							<img
-								src={ `https://gravatar.com/avatar/?d=initials&name=${ value }` }
+								src={ `https://gravatar.com/avatar/?d=initials&name=${ item.value }` }
 								alt=""
 								width="20"
 								style={ {
 									borderRadius: '50%',
 								} }
 							/>
-							{ value }
+							{ item.label }
 						</span>
 					) }
 				</Select.Trigger>
 				<Select.Popup>
 					{ customOptions.map( ( item ) => (
-						<Select.Item
-							key={ item.value }
-							value={ item.value }
-							label={ item.label }
-						>
+						<Select.Item key={ item.value } value={ item }>
 							{ item.label }
 						</Select.Item>
 					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'User 1',
+		defaultValue: customOptions[ 0 ],
 	},
 };
 
@@ -269,6 +337,7 @@ export const WithCustomTriggerAndItem: Story = {
 export const WithCustomZIndex: Story = {
 	name: 'With Custom z-index',
 	args: {
+		...Default.args,
 		children: (
 			<>
 				<Select.Trigger />
@@ -279,11 +348,13 @@ export const WithCustomZIndex: Story = {
 						/>
 					}
 				>
-					<Select.Item value="Item 1" />
-					<Select.Item value="Item 2" />
+					{ defaultItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
+					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'Item 1',
 	},
 };

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>
 		);
@@ -49,7 +167,7 @@ describe( 'Select', () => {
 								<Select.Portal container={ containerRef } />
 							}
 						>
-							<Select.Item value="Item 1" />
+							<Select.Item value="Item 1">Item 1</Select.Item>
 						</Select.Popup>
 					</Select.Root>
 				</div>
@@ -75,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

@@ -7,8 +7,8 @@ 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'
 >;
 
@@ -25,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' ];
 };
@@ -53,7 +63,7 @@ export type SelectItemProps = Omit<
 	/**
 	 * A unique value that identifies this select item.
 	 */
-	value?: string;
+	value?: unknown;
 	/**
 	 * The size of the item.
 	 *
@@ -62,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 } />;
+	}
+);