@wordpress/ui 0.11.1-next.v.202604091042.0 → 0.12.0

package/src/drawer/title.tsx

@@ -0,0 +1,53 @@
+import { Drawer as _Drawer } from '@base-ui/react/drawer';
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useEffect, useRef } from '@wordpress/element';
+import { Text } from '../text';
+import { useDrawerValidationContext } from './context';
+import styles from './style.module.css';
+import type { TitleProps } from './types';
+
+/**
+ * Renders the drawer title. This component is required for accessibility
+ * and serves as both the visible heading and the accessible label for
+ * the drawer.
+ *
+ * **Required** — every drawer must include a `Drawer.Title`, even if
+ * visually hidden. The rendered element is linked to the popup via
+ * `aria-labelledby`. Renders an `<h2>` by default.
+ *
+ * To visually hide the title while keeping it accessible, wrap it with
+ * `VisuallyHidden` using the `render` prop:
+ *
+ * ```jsx
+ * <VisuallyHidden render={ <Drawer.Title /> }>
+ *   Accessible title text
+ * </VisuallyHidden>
+ * ```
+ */
+const Title = forwardRef< HTMLHeadingElement, TitleProps >(
+	function DrawerTitle( { children, ...props }, forwardedRef ) {
+		const validationContext = useDrawerValidationContext();
+		const internalRef = useRef< HTMLHeadingElement >( null );
+		const mergedRef = useMergeRefs( [ internalRef, forwardedRef ] );
+
+		useEffect( () => {
+			if ( validationContext ) {
+				return validationContext.registerTitle( internalRef.current );
+			}
+			return undefined;
+		}, [ validationContext ] );
+
+		return (
+			<Text
+				ref={ mergedRef }
+				variant="heading-xl"
+				render={ <_Drawer.Title { ...props } /> }
+				className={ styles.title }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);
+
+export { Title };

package/src/drawer/trigger.tsx

@@ -0,0 +1,14 @@
+import { Drawer as _Drawer } from '@base-ui/react/drawer';
+import { forwardRef } from '@wordpress/element';
+import type { TriggerProps } from './types';
+
+/**
+ * Renders a button that opens the drawer popup when clicked.
+ */
+const Trigger = forwardRef< HTMLButtonElement, TriggerProps >(
+	function DrawerTrigger( props, ref ) {
+		return <_Drawer.Trigger ref={ ref } { ...props } />;
+	}
+);
+
+export { Trigger };

package/src/drawer/types.ts

@@ -0,0 +1,174 @@
+import type { Drawer as _Drawer } from '@base-ui/react/drawer';
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+import type { Button } from '../button';
+import type { IconButton } from '../icon-button';
+import type { ComponentProps } from '../utils/types';
+
+export type PortalProps = ComponentPropsWithoutRef< typeof _Drawer.Portal >;
+
+export interface RootProps
+	extends Pick<
+		_Drawer.Root.Props,
+		| 'open'
+		| 'onOpenChange'
+		| 'onOpenChangeComplete'
+		| 'defaultOpen'
+		| 'modal'
+		| 'disablePointerDismissal'
+	> {
+	/**
+	 * The edge the drawer slides in from, and the direction used to dismiss it
+	 * via swipe gesture.
+	 *
+	 * - `'left'` / `'right'`: side drawers; swipe horizontally to dismiss.
+	 * - `'down'`: bottom sheet; swipe down to dismiss.
+	 * - `'up'`: top drawer; swipe up to dismiss.
+	 *
+	 * @default 'left'
+	 */
+	swipeDirection?: _Drawer.Root.Props[ 'swipeDirection' ];
+
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface TriggerProps extends ComponentProps< 'button' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface PopupProps
+	extends ComponentProps< 'div' >,
+		Pick< _Drawer.Popup.Props, 'initialFocus' | 'finalFocus' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * Optional portal element, typically `<Drawer.Portal />` with custom
+	 * `container`, `className`, or `style`. The backdrop and inner viewport
+	 * are rendered as this portal's children (do not pass `children` on the
+	 * portal element; they would be ignored).
+	 *
+	 * When omitted, `Drawer.Popup` uses `Drawer.Portal` with default props,
+	 * rendering the portal in the current document's `<body>`.
+	 */
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
+
+	/**
+	 * Controls the size of the drawer along its relevant axis (width for
+	 * left/right drawers, height for up/down drawers).
+	 *
+	 * When not specified, left/right drawers use a default medium width
+	 * and up/down drawers fit their content.
+	 *
+	 * - `'small'` — narrow/short.
+	 * - `'medium'` — moderate.
+	 * - `'large'` — wide/tall.
+	 * - `'stretch'` — fills available space, respecting the viewport inset.
+	 * - `'auto'` — fit content along the relevant axis.
+	 *
+	 * @default 'medium' for left/right drawers, 'auto' for up/down drawers
+	 */
+	size?: 'small' | 'medium' | 'large' | 'stretch' | 'auto';
+}
+
+export interface ActionProps extends ComponentProps< typeof Button > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface FooterProps extends ComponentProps< 'footer' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface HeaderProps extends ComponentProps< 'header' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface ContentProps extends ComponentProps< 'div' > {
+	/**
+	 * The body content to be rendered inside the scroll container.
+	 */
+	children?: ReactNode;
+	/**
+	 * The scroll region automatically becomes a keyboard-reachable tab
+	 * stop (`tabindex="0"`) whenever the body overflows, so keyboard
+	 * users can arrow-scroll the region (WCAG 2.1.1). It becomes
+	 * non-tabbable again as soon as the content no longer overflows.
+	 *
+	 * If you supply `tabIndex` explicitly, your value wins and is never
+	 * overwritten — including `tabIndex={ -1 }` to opt out of the
+	 * automatic tab stop entirely, and including overrides applied
+	 * after the component had already managed the value.
+	 *
+	 * Two narrow edge cases:
+	 * - If you later *remove* an explicit `tabIndex` at runtime, the
+	 *   component will resume managing it on the next overflow tick; it
+	 *   can't distinguish a previous explicit opt-out from an
+	 *   unconfigured state.
+	 * - Passing `tabIndex={ 0 }` while the body overflows produces a
+	 *   value identical to the auto-managed one, so the component can
+	 *   no longer tell the two apart and may strip it on the next
+	 *   non-overflow tick. Pick a different value (or rely on the
+	 *   default behavior, which is already `0` while overflowing).
+	 *
+	 * Note: the scroll region is intentionally rendered without
+	 * `role` / `aria-label`, so screen readers don't announce a
+	 * generic "scrollable" landmark on top of the drawer's existing
+	 * heading + body; the surrounding `Drawer.Title` and body content
+	 * provide the context.
+	 */
+	tabIndex?: number;
+}
+
+export interface TitleProps extends ComponentProps< 'h2' > {
+	/**
+	 * The title content to be rendered. This serves as both the visible
+	 * heading and the accessible label for the drawer.
+	 *
+	 * When `Drawer.Title` is passed as a render element (e.g. to
+	 * `VisuallyHidden`), children can be provided by the wrapper instead.
+	 */
+	children?: ReactNode;
+}
+
+export interface DescriptionProps extends ComponentProps< 'p' > {
+	/**
+	 * The description content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface CloseIconProps
+	extends Omit<
+		ComponentProps< typeof IconButton >,
+		'label' | 'icon' | 'loading' | 'loadingAnnouncement'
+	> {
+	/**
+	 * A label describing the button's action, shown as a tooltip and to
+	 * assistive technology.
+	 *
+	 * @default __( 'Close' )
+	 */
+	label?: ComponentProps< typeof IconButton >[ 'label' ];
+	/**
+	 * The icon to display in the button.
+	 *
+	 * @default the `close` icon from `@wordpress/icons`
+	 */
+	icon?: ComponentProps< typeof IconButton >[ 'icon' ];
+}

package/src/empty-state/description.tsx

@@ -4,6 +4,8 @@ import { Text } from '../text';
 import type { EmptyStateDescriptionProps } from './types';
 import styles from './style.module.css';
 
+const DEFAULT_TAG = <p />;
+
 /**
  * The description text for an empty state, providing additional context and
  * guidance on what the user should do next.
@@ -12,14 +14,16 @@ export const Description = forwardRef<
 	HTMLParagraphElement,
 	EmptyStateDescriptionProps
 >( function EmptyStateDescription(
-	{ render, className, children, ...props },
+	{ render = DEFAULT_TAG, className, children, ...props },
 	ref
 ) {
 	return (
 		<Text
+			ref={ ref }
 			variant="body-md"
-			render={ render ?? <p ref={ ref } { ...props } /> }
+			render={ render }
 			className={ clsx( styles.description, className ) }
+			{ ...props }
 		>
 			{ children }
 		</Text>

package/src/empty-state/stories/index.story.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { search } from '@wordpress/icons';
-import { Button, EmptyState } from '../..';
+import { Button } from '../../button';
+import * as EmptyState from '../';
 
 const meta: Meta< typeof EmptyState.Root > = {
 	title: 'Design System/Components/EmptyState',

package/src/empty-state/style.module.css

@@ -8,7 +8,7 @@
 		text-align: center;
 		max-width: var(--wpds-dimension-surface-width-sm);
 		gap: var(--wpds-dimension-gap-xs);
-		font-family: var(--wpds-font-family-body);
+		font-family: var(--wpds-typography-font-family-body);
 		color: var(--wpds-color-fg-content-neutral);
 		text-wrap: balance;
 	}

package/src/empty-state/test/description.test.tsx

@@ -10,4 +10,17 @@ describe( 'EmptyState.Description', () => {
 
 		expect( ref.current ).toBeInstanceOf( HTMLParagraphElement );
 	} );
+
+	it( 'forwards ref to custom render element', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render(
+			<Description ref={ ref } render={ <div /> }>
+				Description text
+			</Description>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+		expect( ref.current?.tagName ).toBe( 'DIV' );
+	} );
 } );

package/src/empty-state/test/title.test.tsx

@@ -10,4 +10,17 @@ describe( 'EmptyState.Title', () => {
 
 		expect( ref.current ).toBeInstanceOf( HTMLHeadingElement );
 	} );
+
+	it( 'forwards ref to custom render element', () => {
+		const ref = createRef< HTMLHeadingElement >();
+
+		render(
+			<Title ref={ ref } render={ <h3 /> }>
+				No results found
+			</Title>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLHeadingElement );
+		expect( ref.current?.tagName ).toBe( 'H3' );
+	} );
 } );

package/src/empty-state/title.tsx

@@ -4,16 +4,23 @@ import { Text } from '../text';
 import type { EmptyStateTitleProps } from './types';
 import styles from './style.module.css';
 
+const DEFAULT_TAG = <h2 />;
+
 /**
  * The title is a short heading that communicates the empty state.
  */
 export const Title = forwardRef< HTMLHeadingElement, EmptyStateTitleProps >(
-	function EmptyStateTitle( { render, className, children, ...props }, ref ) {
+	function EmptyStateTitle(
+		{ render = DEFAULT_TAG, className, children, ...props },
+		ref
+	) {
 		return (
 			<Text
+				ref={ ref }
 				variant="heading-lg"
-				render={ render ?? <h2 ref={ ref } { ...props } /> }
+				render={ render }
 				className={ clsx( styles.title, className ) }
+				{ ...props }
 			>
 				{ children }
 			</Text>

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

@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from '@wordpress/element';
 import { plus, reset, seen, unseen } from '@wordpress/icons';
-import { IconButton, InputControl, InputLayout, Stack } from '../../..';
+import { InputControl } from '../';
+import { IconButton } from '../../../icon-button';
+import { InputLayout } from '../../primitives/input-layout';
+import { Stack } from '../../../stack';
 import {
 	WithPrefix,
 	WithSuffixControl,

package/src/form/primitives/autocomplete/clear.tsx

@@ -0,0 +1,35 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import { forwardRef } from '@wordpress/element';
+import { closeSmall } from '@wordpress/icons';
+import { __ } from '@wordpress/i18n';
+import { IconButton } from '../../../icon-button';
+import type { AutocompleteClearProps } from './types';
+
+const DEFAULT_RENDER = ( {
+	'aria-label': ariaLabel = __( 'Clear' ),
+	...props
+}: AutocompleteClearProps ) => (
+	<IconButton
+		icon={ closeSmall }
+		size="small"
+		variant="minimal"
+		tone="neutral"
+		label={ ariaLabel }
+		{ ...props }
+	/>
+);
+
+/**
+ * A button that clears the input value.
+ */
+export const Clear = forwardRef< HTMLButtonElement, AutocompleteClearProps >(
+	function Clear( { render = DEFAULT_RENDER, ...restProps }, ref ) {
+		return (
+			<_Autocomplete.Clear
+				ref={ ref }
+				render={ render }
+				{ ...restProps }
+			/>
+		);
+	}
+);

package/src/form/primitives/autocomplete/collection.tsx

@@ -0,0 +1,13 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import type { AutocompleteCollectionProps } from './types';
+
+export function Collection( {
+	children,
+	...restProps
+}: AutocompleteCollectionProps ) {
+	return (
+		<_Autocomplete.Collection { ...restProps }>
+			{ children }
+		</_Autocomplete.Collection>
+	);
+}

package/src/form/primitives/autocomplete/empty.tsx

@@ -0,0 +1,17 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import type { AutocompleteEmptyProps } from './types';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+
+export const Empty = forwardRef< HTMLDivElement, AutocompleteEmptyProps >(
+	function Empty( { className, ...restProps }, ref ) {
+		return (
+			<_Autocomplete.Empty
+				className={ clsx( itemPopupStyles.empty, className ) }
+				ref={ ref }
+				{ ...restProps }
+			/>
+		);
+	}
+);

package/src/form/primitives/autocomplete/index.ts

@@ -0,0 +1,12 @@
+export { Clear } from './clear';
+export { Collection } from './collection';
+export { Empty } from './empty';
+export { InputGroup } from './input-group';
+export { Input } from './input';
+export { Item } from './item';
+export { List } from './list';
+export { ListBody } from './list-body';
+export { Portal } from './portal';
+export { Popup } from './popup';
+export { Root } from './root';
+export { Value } from './value';

package/src/form/primitives/autocomplete/input-group.tsx

@@ -0,0 +1,16 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import { forwardRef } from '@wordpress/element';
+import type { AutocompleteInputGroupProps } from './types';
+
+/**
+ * Wrapper around `Autocomplete.Input` that defines the visual control
+ * boundary when the input is composed with prefix/suffix slots or other
+ * elements. Without this wrapper, the popup anchors to the bare `<input>`
+ * instead of the full control. Also adds `role="group"`.
+ */
+export const InputGroup = forwardRef<
+	HTMLDivElement,
+	AutocompleteInputGroupProps
+>( function InputGroup( props, ref ) {
+	return <_Autocomplete.InputGroup ref={ ref } { ...props } />;
+} );

package/src/form/primitives/autocomplete/input.tsx

@@ -0,0 +1,20 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import { forwardRef } from '@wordpress/element';
+import { Input as InputPrimitive } from '../input';
+import type { AutocompleteInputProps } from './types';
+
+const DEFAULT_RENDER = ( props: AutocompleteInputProps ) => (
+	<InputPrimitive { ...props } />
+);
+
+export const Input = forwardRef< HTMLInputElement, AutocompleteInputProps >(
+	function Input( { render = DEFAULT_RENDER, ...restProps }, ref ) {
+		return (
+			<_Autocomplete.Input
+				ref={ ref }
+				render={ render }
+				{ ...restProps }
+			/>
+		);
+	}
+);

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

@@ -0,0 +1,24 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+import resetStyles from '../../../utils/css/resets.module.css';
+import type { AutocompleteItemProps } from './types';
+
+export const Item = forwardRef< HTMLDivElement, AutocompleteItemProps >(
+	function Item( { className, children, ...restProps }, ref ) {
+		return (
+			<_Autocomplete.Item
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					itemPopupStyles.item,
+					className
+				) }
+				ref={ ref }
+				{ ...restProps }
+			>
+				{ children }
+			</_Autocomplete.Item>
+		);
+	}
+);

package/src/form/primitives/autocomplete/list-body.tsx

@@ -0,0 +1,23 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import { forwardRef } from '@wordpress/element';
+import type { AutocompleteListBodyProps } from './types';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+
+/**
+ * A layout container for the main scrolling area in the `List`, for holding `Item`s.
+ */
+export const ListBody = forwardRef< HTMLDivElement, AutocompleteListBodyProps >(
+	function ListBody( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >(
+				{ className: itemPopupStyles[ 'list-scrollable-container' ] },
+				props
+			),
+		} );
+
+		return element;
+	}
+);

package/src/form/primitives/autocomplete/list.tsx

@@ -0,0 +1,17 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import type { AutocompleteListProps } from './types';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+
+export const List = forwardRef< HTMLDivElement, AutocompleteListProps >(
+	function List( { className, ...restProps }, ref ) {
+		return (
+			<_Autocomplete.List
+				className={ clsx( itemPopupStyles.list, className ) }
+				ref={ ref }
+				{ ...restProps }
+			/>
+		);
+	}
+);

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

@@ -0,0 +1,42 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import {
+	type ThemeProvider as ThemeProviderType,
+	privateApis as themePrivateApis,
+} from '@wordpress/theme';
+import { unlock } from '../../../lock-unlock';
+import { renderPortalWithChildren } from '../../../utils/render-portal-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';
+import { Portal } from './portal';
+import type { AutocompletePopupProps } from './types';
+import { ITEM_POPUP_POSITIONER_PROPS } from '../constants';
+
+const ThemeProvider: typeof ThemeProviderType =
+	unlock( themePrivateApis ).ThemeProvider;
+
+export const Popup = forwardRef< HTMLDivElement, AutocompletePopupProps >(
+	function Popup( { className, portal, ...restProps }, ref ) {
+		const portalChildren = (
+			<_Autocomplete.Positioner
+				{ ...ITEM_POPUP_POSITIONER_PROPS }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner
+				) }
+			>
+				<ThemeProvider>
+					<_Autocomplete.Popup
+						ref={ ref }
+						className={ clsx( itemPopupStyles.popup, className ) }
+						{ ...restProps }
+					/>
+				</ThemeProvider>
+			</_Autocomplete.Positioner>
+		);
+
+		return renderPortalWithChildren( portal, <Portal />, portalChildren );
+	}
+);

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

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

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

@@ -0,0 +1,11 @@
+import { Autocomplete as _Autocomplete } from '@base-ui/react/autocomplete';
+import type { AutocompleteRootProps } from './types';
+
+/**
+ * Low-level primitive for an autocomplete input that suggests options as
+ * you type. Unlike `Combobox`, the input can contain free-form text and
+ * suggestions only optionally autocomplete the text.
+ */
+export function Root( props: AutocompleteRootProps ) {
+	return <_Autocomplete.Root { ...props } />;
+}

package/src/form/primitives/autocomplete/stories/fixtures.ts

@@ -0,0 +1,35 @@
+export interface FixtureItem {
+	id: string;
+	value: string;
+}
+
+export const COMMANDS: FixtureItem[] = [
+	{ id: 'c1', value: 'Add new page' },
+	{ id: 'c2', value: 'Add new post' },
+	{ id: 'c3', value: 'Edit site' },
+	{ id: 'c4', value: 'View site' },
+	{ id: 'c5', value: 'Manage plugins' },
+	{ id: 'c6', value: 'Manage users' },
+	{ id: 'c7', value: 'Open settings' },
+	{ id: 'c8', value: 'Toggle dark mode' },
+];
+
+export const USERS: FixtureItem[] = [
+	{ id: 'm1', value: 'alice' },
+	{ id: 'm2', value: 'bob' },
+	{ id: 'm3', value: 'carol' },
+	{ id: 'm4', value: 'dave' },
+	{ id: 'm5', value: 'eve' },
+	{ id: 'm6', value: 'frank' },
+	{ id: 'm7', value: 'grace' },
+];
+
+export const URLS: FixtureItem[] = [
+	{ id: 'u1', value: 'wordpress.org' },
+	{ id: 'u2', value: 'developer.wordpress.org/plugins/' },
+	{ id: 'u3', value: 'developer.wordpress.org/themes/' },
+	{ id: 'u4', value: 'developer.wordpress.org/block-editor/' },
+	{ id: 'u5', value: 'github.com/WordPress/gutenberg' },
+	{ id: 'u6', value: 'make.wordpress.org/core/' },
+	{ id: 'u7', value: 'make.wordpress.org/design/' },
+];