@wordpress/ui 0.5.1-next.v.0 → 0.6.0

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

@@ -0,0 +1,276 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import '@wordpress/theme/design-tokens.css';
+import { Select } from '../../../..';
+
+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,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Select.Root >;
+
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger />
+				<Select.Popup>
+					{ Array.from( { length: 6 }, ( _, index ) => (
+						<Select.Item
+							key={ index }
+							value={ `Item ${ index + 1 }` }
+						/>
+					) ) }
+				</Select.Popup>
+			</>
+		),
+	},
+};
+
+export const Compact: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger size="compact" />
+				<Select.Popup>
+					{ Array.from( { length: 6 }, ( _, index ) => (
+						<Select.Item
+							key={ index }
+							value={ `Item ${ index + 1 }` }
+							size="compact"
+						/>
+					) ) }
+				</Select.Popup>
+			</>
+		),
+		defaultValue: 'Item 1',
+	},
+};
+
+/**
+ * The `minimal` variant must be used judiciously, because in many
+ * contexts it can be unclear to users that it is a select trigger.
+ *
+ * Combined with the `small` size, `minimal` can be used to create a
+ * very low-profile `Select`, intended for rare use cases like
+ * a pagination control.
+ */
+export const Minimal: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger size="small" variant="minimal" />
+				<Select.Popup>
+					{ Array.from( { length: 6 }, ( _, index ) => (
+						<Select.Item
+							key={ index }
+							value={ `${ index + 1 }` }
+							size="small"
+						/>
+					) ) }
+				</Select.Popup>
+			</>
+		),
+		defaultValue: '1',
+	},
+};
+
+const withEmptyOptionItems = [
+	{
+		value: '',
+		label: 'Select',
+		disabled: true,
+	},
+	{
+		value: 'Item 2',
+		label: 'Item 2',
+	},
+];
+
+/**
+ * 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`.
+ */
+export const WithEmptyValueOption: Story = {
+	args: {
+		items: withEmptyOptionItems,
+		children: (
+			<>
+				<Select.Trigger />
+				<Select.Popup>
+					{ withEmptyOptionItems.map( ( item ) => (
+						<Select.Item
+							key={ item.value }
+							value={ item.value }
+							label={ item.label }
+							disabled={ item.disabled }
+						>
+							{ item.label }
+						</Select.Item>
+					) ) }
+				</Select.Popup>
+			</>
+		),
+		defaultValue: '',
+	},
+};
+
+/**
+ * When accessibly labeling a `Select`, note that the label must be associated with the `Select.Trigger`,
+ * not the `Select.Root`.
+ *
+ * Whether labeling with `aria-label`, `htmlFor`, or `aria-labelledby`, the association must be made to the `Select.Trigger`.
+ */
+export const Labeling: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger aria-label="User role" />
+				<Select.Popup>
+					<Select.Item value="Administrator" />
+					<Select.Item value="Editor" />
+				</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.';
+
+export const WithOverflow: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger />
+				<Select.Popup>
+					<Select.Item value={ longItemValue } />
+					<Select.Item value="Item 2" />
+				</Select.Popup>
+			</>
+		),
+		defaultValue: longItemValue,
+	},
+};
+
+export const Disabled: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger />
+				<Select.Popup>
+					<Select.Item value="Item 1" />
+					<Select.Item value="Item 2" />
+				</Select.Popup>
+			</>
+		),
+		defaultValue: 'Item 1',
+		disabled: true,
+	},
+};
+
+export const WithDisabledItem: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger />
+				<Select.Popup>
+					<Select.Item value="Item 1" />
+					<Select.Item value="Item 2" disabled />
+				</Select.Popup>
+			</>
+		),
+		defaultValue: 'Item 1',
+	},
+};
+
+const customOptions = [
+	{
+		value: 'User 1',
+		label: 'User 1 (Admin)',
+	},
+	{
+		value: 'User 2',
+		label: 'User 2 (Editor)',
+	},
+];
+
+/**
+ * For custom needs, a `Select.Trigger` can take a custom render function as its children,
+ * while `Select.Item` can take arbitrary content as children.
+ */
+export const WithCustomTriggerAndItem: Story = {
+	args: {
+		children: (
+			<>
+				<Select.Trigger>
+					{ ( value ) => (
+						<span
+							style={ {
+								display: 'flex',
+								alignItems: 'center',
+								gap: 8,
+							} }
+						>
+							<img
+								src={ `https://gravatar.com/avatar/?d=initials&name=${ value }` }
+								alt=""
+								width="20"
+								style={ {
+									borderRadius: '50%',
+								} }
+							/>
+							{ value }
+						</span>
+					) }
+				</Select.Trigger>
+				<Select.Popup>
+					{ customOptions.map( ( item ) => (
+						<Select.Item
+							key={ item.value }
+							value={ item.value }
+							label={ item.label }
+						>
+							{ item.label }
+						</Select.Item>
+					) ) }
+				</Select.Popup>
+			</>
+		),
+		defaultValue: 'User 1',
+	},
+};
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export const WithCustomZIndex: Story = {
+	name: 'With Custom z-index',
+	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>
+			</>
+		),
+		defaultValue: 'Item 1',
+	},
+};

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

@@ -0,0 +1,7 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.positioner {
+		z-index: var(--wp-ui-select-z-index, initial);
+	}
+}

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

@@ -0,0 +1,35 @@
+import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef } from '@wordpress/element';
+import * as Select from '../index';
+
+jest.setTimeout( 10000 );
+
+describe( 'Select', () => {
+	it( 'forwards ref', async () => {
+		const user = userEvent.setup();
+		const triggerRef = createRef< HTMLButtonElement >();
+		const popupRef = createRef< HTMLDivElement >();
+		const itemRef = createRef< HTMLDivElement >();
+
+		render(
+			<Select.Root>
+				<Select.Trigger ref={ triggerRef } />
+				<Select.Popup ref={ popupRef }>
+					<Select.Item ref={ itemRef } value="Item 1" />
+					<Select.Item value="Item 2" />
+				</Select.Popup>
+			</Select.Root>
+		);
+
+		// Test trigger ref before interaction
+		expect( triggerRef.current ).toBeInstanceOf( HTMLButtonElement );
+
+		// Click on the trigger to open the select dropdown
+		await user.click( triggerRef.current! );
+
+		// Now test that the popup and item refs are also available
+		expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+} );

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

@@ -0,0 +1,58 @@
+import { Select as _Select } from '@base-ui/react/select';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { chevronDown } from '@wordpress/icons';
+import focusStyles from '../../../utils/css/focus.module.css';
+import selectTriggerStyles from '../../../utils/css/select-trigger.module.css';
+import { InputLayout } from '../input-layout';
+import { Icon } from '../../../icon';
+import type { SelectTriggerProps } from './types';
+
+export const Trigger = forwardRef< HTMLButtonElement, SelectTriggerProps >(
+	function Trigger(
+		{ className, size, variant, children, ...restProps },
+		ref
+	) {
+		return (
+			<InputLayout
+				className={ clsx(
+					focusStyles[ 'outset-ring--focus-within-except-active' ],
+					selectTriggerStyles[ 'trigger-wrapper' ],
+					variant === 'minimal' &&
+						selectTriggerStyles[ 'is-minimal' ],
+					className
+				) }
+				size={ size }
+				isBorderless={ variant === 'minimal' }
+			>
+				<_Select.Trigger
+					{ ...restProps }
+					className={ clsx(
+						selectTriggerStyles.trigger,
+						variant === 'minimal' &&
+							selectTriggerStyles[ 'is-minimal' ]
+					) }
+					data-can-disable-input-layout
+					ref={ ref }
+				>
+					<_Select.Value
+						className={ ( state ) =>
+							clsx(
+								selectTriggerStyles[ 'trigger-value' ],
+								state.value === '' &&
+									selectTriggerStyles[ 'is-placeholder' ]
+							)
+						}
+					>
+						{ children }
+					</_Select.Value>
+					<Icon
+						className={ selectTriggerStyles[ 'trigger-caret' ] }
+						icon={ chevronDown }
+						size={ 18 }
+					/>
+				</_Select.Trigger>
+			</InputLayout>
+		);
+	}
+);

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

@@ -0,0 +1,52 @@
+import type { Select as _Select } from '@base-ui/react/select';
+import type { InputLayoutProps } from '../input-layout/types';
+
+// The second type parameter is the `multiple` flag (currently disabled).
+export type SelectRootProps = Omit<
+	_Select.Root.Props< string, false >,
+	'multiple'
+>;
+
+export type SelectTriggerProps = Omit< _Select.Trigger.Props, 'children' > & {
+	/**
+	 * The size of the trigger.
+	 *
+	 * @default 'default'
+	 */
+	size?: InputLayoutProps[ 'size' ];
+	/**
+	 * The style variant of the trigger.
+	 *
+	 * @default 'default'
+	 */
+	variant?: 'default' | 'minimal';
+	/**
+	 * A function that gets called with the current value as an argument.
+	 * Use this to customize the trigger content.
+	 */
+	children?: _Select.Value.Props[ 'children' ];
+};
+
+export type SelectPopupProps = _Select.Popup.Props;
+
+export type SelectItemProps = Omit<
+	_Select.Item.Props,
+	'children' | 'value'
+> & {
+	/**
+	 * A unique value that identifies this select item.
+	 */
+	value?: string;
+	/**
+	 * The size of the item.
+	 *
+	 * @default 'default'
+	 */
+	size?: InputLayoutProps[ 'size' ];
+	/**
+	 * The content of the item.
+	 *
+	 * @default `value`
+	 */
+	children?: _Select.Item.Props[ 'children' ];
+};

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

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { wordpress } from '@wordpress/icons';
 import { Icon } from '../index';
 

package/src/index.ts

@@ -4,4 +4,5 @@ export * from './button';
 export * from './form/primitives';
 export * from './icon';
 export * from './stack';
+export * as Tooltip from './tooltip';
 export * from './visually-hidden';

package/src/lock-unlock.ts

@@ -0,0 +1,7 @@
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
+		'@wordpress/ui'
+	);

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

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Stack } from '../index';
 import { Box } from '../../box';
 

package/src/stories/introduction.mdx

@@ -1,5 +1,5 @@
 import { Meta, Markdown } from '@storybook/addon-docs/blocks';
-import Readme from '../../README.md';
+import Readme from '../../README.md?raw';
 
 <Meta title="Design System/Components/Introduction" />
 

package/src/tooltip/index.ts

@@ -0,0 +1,6 @@
+import { Popup } from './popup';
+import { Trigger } from './trigger';
+import { Root } from './root';
+import { Provider } from './provider';
+
+export { Provider, Root, Trigger, Popup };

package/src/tooltip/popup.tsx

@@ -0,0 +1,64 @@
+import clsx from 'clsx';
+import { Tooltip } from '@base-ui/react/tooltip';
+import { forwardRef } from '@wordpress/element';
+import {
+	type ThemeProvider as ThemeProviderType,
+	privateApis as themePrivateApis,
+} from '@wordpress/theme';
+import type { PopupProps } from './types';
+import { unlock } from '../lock-unlock';
+import resetStyles from '../utils/css/resets.module.css';
+import styles from './style.module.css';
+
+const ThemeProvider: typeof ThemeProviderType =
+	unlock( themePrivateApis ).ThemeProvider;
+
+const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
+	{
+		align = 'center',
+		side = 'bottom',
+		sideOffset = 4,
+		children,
+		className,
+		style,
+		...props
+	},
+	ref
+) {
+	return (
+		<Tooltip.Portal>
+			<Tooltip.Positioner
+				align={ align }
+				side={ side }
+				sideOffset={ sideOffset }
+				style={ style }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					className,
+					styles.positioner
+				) }
+			>
+				{ /* This should ideally use whatever dark color makes sense,
+				and not be hardcoded to #1e1e1e. The solutions would be to:
+				  - review the design of the tooltip, in case we want to stop
+				    hardcoding it to a dark background
+				  - create new semantic tokens as needed (aliasing either the "inverted
+					  bg" or "perma-dark bg" private tokens) and have Tooltip.Popup use
+				    them;
+				  - remove the hardcoded `bg` setting from the `ThemeProvider` below
+					*/ }
+				<ThemeProvider color={ { bg: '#1e1e1e' } }>
+					<Tooltip.Popup
+						ref={ ref }
+						className={ styles.popup }
+						{ ...props }
+					>
+						{ children }
+					</Tooltip.Popup>
+				</ThemeProvider>
+			</Tooltip.Positioner>
+		</Tooltip.Portal>
+	);
+} );
+
+export { Popup };

package/src/tooltip/provider.tsx

@@ -0,0 +1,8 @@
+import { Tooltip } from '@base-ui/react/tooltip';
+import type { ProviderProps } from './types';
+
+function Provider( { children, ...props }: ProviderProps ) {
+	return <Tooltip.Provider { ...props }>{ children }</Tooltip.Provider>;
+}
+
+export { Provider };

package/src/tooltip/root.tsx

@@ -0,0 +1,8 @@
+import { Tooltip } from '@base-ui/react/tooltip';
+import type { RootProps } from './types';
+
+function Root( props: RootProps ) {
+	return <Tooltip.Root { ...props } />;
+}
+
+export { Root };

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

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Tooltip } from '../..';
+
+const meta: Meta< typeof Tooltip.Root > = {
+	title: 'Design System/Components/Tooltip',
+	component: Tooltip.Root,
+	subcomponents: {
+		Provider: Tooltip.Provider,
+		Trigger: Tooltip.Trigger,
+		Popup: Tooltip.Popup,
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof Tooltip.Root > = {
+	args: {
+		children: (
+			<>
+				<Tooltip.Trigger>Hover me</Tooltip.Trigger>
+				<Tooltip.Popup>Tooltip text</Tooltip.Popup>
+			</>
+		),
+	},
+};
+
+/**
+ * The `disabled` prop prevents the tooltip from showing, and can be used to
+ * show the tooltip conditionally without rendering the underlying react
+ * component conditionally (which could cause reconciliation issues).
+ */
+export const Disabled: StoryObj< typeof Tooltip.Root > = {
+	...Default,
+	args: {
+		...Default.args,
+		disabled: true,
+	},
+};
+
+/**
+ * Use the `side` prop to control where the tooltip appears relative to the
+ * trigger element.
+ */
+export const Positioning: StoryObj< typeof Tooltip.Root > = {
+	render: () => (
+		<div
+			style={ {
+				display: 'flex',
+				gap: '2rem',
+				padding: '4rem',
+				justifyContent: 'center',
+			} }
+		>
+			<Tooltip.Root>
+				<Tooltip.Trigger>Top</Tooltip.Trigger>
+				<Tooltip.Popup side="top">Tooltip on top</Tooltip.Popup>
+			</Tooltip.Root>
+
+			<Tooltip.Root>
+				<Tooltip.Trigger>Right</Tooltip.Trigger>
+				<Tooltip.Popup side="right">Tooltip on right</Tooltip.Popup>
+			</Tooltip.Root>
+
+			<Tooltip.Root>
+				<Tooltip.Trigger>Bottom</Tooltip.Trigger>
+				<Tooltip.Popup side="bottom">Tooltip on bottom</Tooltip.Popup>
+			</Tooltip.Root>
+
+			<Tooltip.Root>
+				<Tooltip.Trigger>Left</Tooltip.Trigger>
+				<Tooltip.Popup side="left">Tooltip on left</Tooltip.Popup>
+			</Tooltip.Root>
+		</div>
+	),
+};
+
+/**
+ * Use `Tooltip.Provider` to control the delay before tooltips appear.
+ * This is useful when you have multiple tooltips and want them to share
+ * the same delay configuration.
+ */
+export const WithProvider: StoryObj< typeof Tooltip.Root > = {
+	render: () => (
+		<Tooltip.Provider delay={ 0 }>
+			<div style={ { display: 'flex', gap: '1rem' } }>
+				<Tooltip.Root>
+					<Tooltip.Trigger>First</Tooltip.Trigger>
+					<Tooltip.Popup>First tooltip</Tooltip.Popup>
+				</Tooltip.Root>
+
+				<Tooltip.Root>
+					<Tooltip.Trigger>Second</Tooltip.Trigger>
+					<Tooltip.Popup>Second tooltip</Tooltip.Popup>
+				</Tooltip.Root>
+			</div>
+		</Tooltip.Provider>
+	),
+};

package/src/tooltip/style.module.css

@@ -0,0 +1,20 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.positioner {
+		z-index: var(--wp-ui-tooltip-z-index, initial);
+	}
+
+	.popup {
+		background-color: var(--wpds-color-bg-surface-neutral-strong);
+		padding:
+			var(--wpds-dimension-padding-surface-2xs)
+			var(--wpds-dimension-padding-surface-xs);
+		border-radius: var(--wpds-border-radius-sm);
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wpds-font-size-sm);
+		line-height: 1.4; /* TODO: use DS token for line height */
+		color: var(--wpds-color-fg-content-neutral);
+		box-shadow: var(--wpds-elevation-small);
+	}
+}