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

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

@@ -7,11 +7,18 @@ 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,
+		'Field.Item': Field.Item,
+		'Field.Label': Field.Label,
+		'Field.Control': Field.Control,
+		'Field.Description': Field.Description,
+		'Field.Details': Field.Details,
+	},
+	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/primitives/fieldset/stories/index.story.tsx

@@ -6,9 +6,16 @@ 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,
+		'Fieldset.Legend': Fieldset.Legend,
+		'Fieldset.Description': Fieldset.Description,
+		'Fieldset.Details': Fieldset.Details,
+	},
+	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/primitives/index.ts

@@ -1,3 +1,4 @@
+export * as Autocomplete from './autocomplete';
 export * as Field from './field';
 export * as Fieldset from './fieldset';
 export { Input } from './input';

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

@@ -12,6 +12,13 @@ const meta: Meta< typeof Input > = {
 		value: { control: false },
 		type: { control: 'text' },
 	},
+	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/primitives/input-layout/stories/index.story.tsx

@@ -7,7 +7,14 @@ const meta: Meta< typeof InputLayout > = {
 	title: 'Design System/Components/Form/Primitives/InputLayout',
 	component: InputLayout,
 	subcomponents: {
-		Slot: InputLayout.Slot,
+		'InputLayout.Slot': InputLayout.Slot,
+	},
+	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/primitives/select/index.ts

@@ -1,4 +1,5 @@
 export { Item } from './item';
+export { Portal } from './portal';
 export { Popup } from './popup';
 export { Root } from './root';
 export { Trigger } from './trigger';

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

@@ -9,7 +9,7 @@ import type { SelectItemProps } from './types';
 
 export const Item = forwardRef< HTMLDivElement, SelectItemProps >(
 	function Item(
-		{ className, value, size = 'default', children = value, ...restProps },
+		{ className, value, size = 'default', children, ...restProps },
 		ref
 	) {
 		return (
@@ -27,7 +27,6 @@ export const Item = forwardRef< HTMLDivElement, SelectItemProps >(
 				<Icon
 					icon={ check }
 					className={ clsx(
-						itemPopupStyles[ 'item-indicator' ],
 						itemPopupStyles[ 'item-indicator-icon' ]
 					) }
 					size={ size === 'small' ? 20 : 24 }

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

@@ -6,6 +6,8 @@ import {
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 import { unlock } from '../../../lock-unlock';
+import { Portal } from './portal';
+import { renderSlotWithChildren } from '../../../utils/render-slot-with-children';
 import itemPopupStyles from '../../../utils/css/item-popup.module.css';
 import resetStyles from '../../../utils/css/resets.module.css';
 import styles from './style.module.css';
@@ -16,43 +18,38 @@ const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
-	function Popup(
-		{ className, container, children, style, ...restProps },
-		ref
-	) {
-		return (
-			<_Select.Portal container={ container }>
-				<_Select.Positioner
-					{ ...ITEM_POPUP_POSITIONER_PROPS }
-					alignItemWithTrigger={ false }
-					style={ style }
-					className={ clsx(
-						resetStyles[ 'box-sizing' ],
-						styles.positioner,
-						className
-					) }
-				>
-					<ThemeProvider>
-						<_Select.Popup
-							ref={ ref }
-							className={ itemPopupStyles.popup }
-							{ ...restProps }
-						>
-							<_Select.List className={ itemPopupStyles.list }>
-								<div
-									className={
-										itemPopupStyles[
-											'list-scrollable-container'
-										]
-									}
-								>
-									{ children }
-								</div>
-							</_Select.List>
-						</_Select.Popup>
-					</ThemeProvider>
-				</_Select.Positioner>
-			</_Select.Portal>
+	function Popup( { className, portal, children, ...restProps }, ref ) {
+		const portalChildren = (
+			<_Select.Positioner
+				{ ...ITEM_POPUP_POSITIONER_PROPS }
+				alignItemWithTrigger={ false }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner
+				) }
+			>
+				<ThemeProvider>
+					<_Select.Popup
+						ref={ ref }
+						className={ clsx( itemPopupStyles.popup, className ) }
+						{ ...restProps }
+					>
+						<_Select.List className={ itemPopupStyles.list }>
+							<div
+								className={
+									itemPopupStyles[
+										'list-scrollable-container'
+									]
+								}
+							>
+								{ children }
+							</div>
+						</_Select.List>
+					</_Select.Popup>
+				</ThemeProvider>
+			</_Select.Positioner>
 		);
+
+		return renderSlotWithChildren( portal, <Portal />, portalChildren );
 	}
 );

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

@@ -0,0 +1,16 @@
+import { Select as _Select } from '@base-ui/react/select';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * Root element that portals `Select` listbox content. Pass to
+ * `Select.Popup`'s `portal` prop. When `portal` is omitted, `Select.Popup`
+ * uses this component with default props.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function SelectPortal( props, ref ) {
+		return <_Select.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

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

@@ -1,6 +1,17 @@
 import { Select as _Select } from '@base-ui/react/select';
 import type { SelectRootProps } from './types';
 
-export function Root( props: SelectRootProps ) {
-	return <_Select.Root< string, false > { ...props } />;
+/**
+ * A component that lets users choose one option from a list.
+ *
+ * When using object values, pass an `items` array so `Select.Trigger` can
+ * auto-resolve the selected item's label. By default, items should use a
+ * `{ value, label }` shape, or provide `itemToStringLabel` for a custom shape.
+ *
+ * Object values are compared with `Object.is` by default, so use the same
+ * object references for `value` / `defaultValue` and `Select.Item` values, or
+ * provide `isItemEqualToValue`.
+ */
+export function Root< Value = unknown >( props: SelectRootProps< Value > ) {
+	return <_Select.Root< Value, false > { ...props } />;
 }

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,54 +294,67 @@ 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 ],
 	},
 };
 
 /**
- * Popovers in Gutenberg are managed with explicit z-index values, which can create
- * situations where a popover renders below another popover, when you want it to be rendered above.
+ * Popovers in Gutenberg are managed with explicit z-index values, which can
+ * create situations where a select popup renders below another popover when
+ * you want it above.
+ *
+ * The `--wp-ui-select-z-index` CSS variable controls the z-index of the
+ * `Select` positioner. Override it either:
  *
- * The `--wp-ui-select-z-index` CSS variable, available on the `Select.Popup` component,
- * is an escape hatch that can be used to override the z-index of a given `Select` popover
- * on a case-by-case basis.
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   `Select` popover in the page), or
+ * - **Per instance**, by passing a `Select.Portal` with a `style` (or
+ *   `className`) to `Select.Popup`'s `portal` prop. The variable cascades
+ *   from the portal wrapper to everything rendered inside it.
+ *
+ * This story demonstrates the per-instance approach.
  */
 export const WithCustomZIndex: Story = {
 	name: 'With Custom z-index',
 	args: {
+		...Default.args,
 		children: (
 			<>
 				<Select.Trigger />
-				<Select.Popup style={ { '--wp-ui-select-z-index': '1000001' } }>
-					<Select.Item value="Item 1" />
-					<Select.Item value="Item 2" />
+				<Select.Popup
+					portal={
+						<Select.Portal
+							style={ { '--wp-ui-select-z-index': '9999' } }
+						/>
+					}
+				>
+					{ defaultItems.map( ( item ) => (
+						<Select.Item key={ item.value } value={ item }>
+							{ item.label }
+						</Select.Item>
+					) ) }
 				</Select.Popup>
 			</>
 		),
-		defaultValue: 'Item 1',
 	},
 };