@wordpress/ui 0.12.0 → 0.13.1-next.v.202605131006.0

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>
+				) ) }
+			</>
+		),
+	},
+};

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

@@ -0,0 +1,196 @@
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef } from '@wordpress/element';
+import { SelectControl } from '../index';
+
+describe( 'SelectControl', () => {
+	const mockItems = [
+		{ value: '', label: 'Select' },
+		{ value: 'option1', label: 'Option 1' },
+		{ value: 'option2', label: 'Option 2' },
+		{ value: 'option3', label: 'Option 3' },
+	];
+
+	it( 'forwards ref to the visible trigger', () => {
+		const ref = createRef< HTMLButtonElement >();
+
+		render(
+			<SelectControl ref={ ref } label="Country" items={ mockItems } />
+		);
+
+		const trigger = screen.getByRole( 'combobox', { name: 'Country' } );
+
+		expect( ref.current ).toBe( trigger );
+		act( () => {
+			ref.current?.focus();
+		} );
+		expect( trigger ).toHaveFocus();
+	} );
+
+	it( 'renders accessible label and description', () => {
+		render(
+			<SelectControl
+				label="Country"
+				description="Choose your country"
+				items={ mockItems }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', {
+				name: 'Country',
+				description: 'Choose your country',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'renders custom placeholder text when no value is selected', () => {
+		render(
+			<SelectControl
+				label="Country"
+				items={ mockItems }
+				placeholder="Choose a country"
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', {
+				name: 'Country',
+			} )
+		).toHaveTextContent( 'Choose a country' );
+	} );
+
+	it( 'renders with a visually hidden label', () => {
+		render(
+			<SelectControl
+				label="Country"
+				hideLabelFromVision
+				items={ mockItems }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', { name: 'Country' } )
+		).toBeVisible();
+	} );
+
+	it( 'renders with details', () => {
+		render(
+			<SelectControl
+				label="Country"
+				items={ mockItems }
+				details={
+					<span>
+						Select the country where your store is registered.
+					</span>
+				}
+			/>
+		);
+
+		expect(
+			screen.getByText( /where your store is registered/ )
+		).toBeVisible();
+	} );
+
+	it( 'passes the current value to custom trigger content', async () => {
+		const user = userEvent.setup();
+
+		render(
+			<SelectControl
+				label="Country"
+				items={ mockItems }
+				defaultValue={ mockItems[ 1 ] }
+				triggerContent={ ( item ) => `Selected ${ item.label }` }
+			/>
+		);
+
+		const trigger = screen.getByRole( 'combobox', {
+			name: 'Country',
+		} );
+
+		expect( trigger ).toHaveTextContent( 'Selected Option 1' );
+
+		await user.click( trigger );
+		await user.click(
+			await screen.findByRole( 'option', {
+				name: 'Option 2',
+			} )
+		);
+
+		expect( trigger ).toHaveTextContent( 'Selected Option 2' );
+	} );
+
+	describe( 'Form data behavior', () => {
+		it( 'submits correct form data when option is selected with custom name', async () => {
+			const user = userEvent.setup();
+			const handleSubmit = jest.fn(
+				( event: React.FormEvent< HTMLFormElement > ) => {
+					event.preventDefault();
+					return new FormData( event.currentTarget );
+				}
+			);
+
+			render(
+				<form onSubmit={ handleSubmit }>
+					<SelectControl
+						label="Country"
+						name="country"
+						items={ mockItems }
+					/>
+					<button type="submit">Submit</button>
+				</form>
+			);
+
+			await user.click(
+				screen.getByRole( 'combobox', {
+					name: 'Country',
+				} )
+			);
+
+			const optionToSelect = await screen.findByRole( 'option', {
+				name: /Option 2/i,
+			} );
+			await user.click( optionToSelect );
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Submit',
+				} )
+			);
+
+			const formData = handleSubmit.mock.results[ 0 ].value;
+			expect( formData.get( 'country' ) ).toBe( 'option2' );
+		} );
+
+		it( 'submits form data with default value when no selection is made', async () => {
+			const user = userEvent.setup();
+			const handleSubmit = jest.fn(
+				( event: React.FormEvent< HTMLFormElement > ) => {
+					event.preventDefault();
+					return new FormData( event.currentTarget );
+				}
+			);
+
+			render(
+				<form onSubmit={ handleSubmit }>
+					<SelectControl
+						label="Country"
+						name="country"
+						items={ mockItems }
+						defaultValue={ mockItems[ 0 ] }
+					/>
+					<button type="submit">Submit</button>
+				</form>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Submit',
+				} )
+			);
+
+			const formData = handleSubmit.mock.results[ 0 ].value;
+			expect( formData.get( 'country' ) ).toBe( '' );
+		} );
+	} );
+} );

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

@@ -0,0 +1,50 @@
+import type React from 'react';
+import type { ControlProps } from '../types';
+import type {
+	SelectRootProps,
+	SelectTriggerProps,
+} from '../primitives/select/types';
+
+export type SelectItem = {
+	label: string;
+	value: string | null;
+	disabled?: boolean;
+};
+
+export type SelectControlProps = Omit<
+	SelectRootProps< SelectItem >,
+	'items' | 'inputRef'
+> &
+	ControlProps & {
+		/**
+		 * CSS class to apply.
+		 */
+		className?: string;
+		/**
+		 * The array of option items to render in the select.
+		 */
+		items?: SelectItem[];
+		/**
+		 * Text to show when no value is selected. This is overridden by `triggerContent`
+		 * if specified, or by a null item's label in `items`.
+		 *
+		 * @default __( 'Select' )
+		 */
+		placeholder?: SelectTriggerProps[ 'placeholder' ];
+		/**
+		 * The custom trigger content to use instead of the default.
+		 *
+		 * ```jsx
+		 * triggerContent={ ( item ) => item.label }
+		 * ```
+		 */
+		triggerContent?:
+			| ( ( item: SelectItem ) => React.ReactNode )
+			| React.ReactNode;
+		/**
+		 * The size of the control.
+		 *
+		 * @default 'default'
+		 */
+		size?: Exclude< SelectTriggerProps[ 'size' ], 'small' >;
+	};

package/src/form/types.ts

@@ -4,7 +4,7 @@ export type ControlProps = {
 	/**
 	 * The accessible label. All controls must be labeled.
 	 */
-	label: React.ComponentProps< typeof Field.Label >[ 'children' ];
+	label: string;
 	/**
 	 * The accessible description, associated using `aria-describedby`.
 	 *

package/src/icon/stories/index.story.tsx

@@ -18,6 +18,13 @@ const meta: Meta< typeof Icon > = {
 			);
 		},
 	],
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending a general readiness review. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/icon-button/icon-button.tsx

@@ -22,6 +22,7 @@ export const IconButton = forwardRef< HTMLButtonElement, IconButtonProps >(
 			icon,
 			size,
 			shortcut,
+			positioner,
 			...restProps
 		}: IconButtonProps & { children?: unknown },
 		ref
@@ -52,7 +53,7 @@ export const IconButton = forwardRef< HTMLButtonElement, IconButtonProps >(
 							className={ styles.icon }
 						/>
 					</Tooltip.Trigger>
-					<Tooltip.Popup>
+					<Tooltip.Popup positioner={ positioner }>
 						{ label }
 						{ shortcut && (
 							<>

package/src/icon-button/stories/index.story.tsx

@@ -11,6 +11,7 @@ import {
 } from '@wordpress/icons';
 import { displayShortcut, ariaKeyShortcut } from '@wordpress/keycodes';
 import { IconButton } from '../index';
+import * as Tooltip from '../../tooltip';
 
 const meta: Meta< typeof IconButton > = {
 	title: 'Design System/Components/IconButton',
@@ -20,6 +21,13 @@ const meta: Meta< typeof IconButton > = {
 			control: { type: 'boolean' },
 		},
 	},
+	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`, text overflow behavior, and overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 
@@ -126,3 +134,15 @@ export const WithShortcut: Story = {
 		shortcut: EXAMPLE_SHORTCUT_OBJECT,
 	},
 };
+
+/**
+ * Customize where the tooltip appears relative to the button by passing a
+ * `<Tooltip.Positioner />` element with a `side` to the `positioner` prop.
+ */
+export const WithCustomPositioner: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		positioner: <Tooltip.Positioner side="right" />,
+	},
+};

package/src/icon-button/types.ts

@@ -1,5 +1,6 @@
 import { type ButtonProps } from '../button/types';
 import { type IconProps } from '../icon/types';
+import { type PopupProps as TooltipPopupProps } from '../tooltip/types';
 
 export type IconButtonProps = Omit< ButtonProps, 'children' > & {
 	/**
@@ -35,4 +36,12 @@ export type IconButtonProps = Omit< ButtonProps, 'children' > & {
 		 */
 		ariaKeyShortcut: string;
 	};
+
+	/**
+	 * Customize how the tooltip is positioned relative to the button. Accepts
+	 * a `<Tooltip.Positioner />` element with custom positioning props
+	 * (`side`, `align`, `sideOffset`, collision settings, etc.). When omitted,
+	 * the tooltip uses the default placement.
+	 */
+	positioner?: TooltipPopupProps[ 'positioner' ];
 };

package/src/link/stories/index.story.tsx

@@ -7,6 +7,12 @@ const meta: Meta< typeof Link > = {
 	title: 'Design System/Components/Link',
 	component: Link,
 	tags: [ 'manifest' ],
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/link/style.module.css

@@ -50,6 +50,7 @@
 	 * inline-block so the link underline stays scoped to the text. */
 
 	.link-icon {
+		line-height: 1;
 		display: inline-block;
 		margin-inline-start: var(--wpds-dimension-padding-xs);
 		font-weight: var(--wpds-typography-font-weight-regular);

package/src/notice/stories/index.story.tsx

@@ -12,6 +12,13 @@ const meta: Meta< typeof Notice.Root > = {
 		'Notice.ActionButton': Notice.ActionButton,
 		'Notice.ActionLink': Notice.ActionLink,
 	},
+	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`. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/popover/popup.tsx

@@ -9,7 +9,7 @@ import {
 import { unlock } from '../lock-unlock';
 import resetStyles from '../utils/css/resets.module.css';
 import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
-import { renderPortalWithChildren } from '../utils/render-portal-with-children';
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import { PopoverValidationProvider } from './context';
 import { Portal } from './portal';
 import styles from './style.module.css';
@@ -102,7 +102,7 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 		</>
 	);
 
-	return renderPortalWithChildren( portal, <Portal />, portalChildren );
+	return renderSlotWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };

package/src/popover/stories/index.story.tsx

@@ -23,6 +23,13 @@ const meta: Meta< typeof Popover.Root > = {
 	argTypes: {
 		children: { control: false },
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;