Add Combobox primitives

packages/ui/CHANGELOG.md

@@ -17,6 +17,7 @@
 -   `Card`: `Card.FullBleed` now supports edge-bumping in additional positions ([#77856](https://github.com/WordPress/gutenberg/pull/77856)):
     -   As the **first child of `Card.Header`**, it extends flush to the card's top and side edges — ideal for hero images. Inter-sibling spacing is consumer-managed: compose `Card.Header` with `Stack` via the `render` prop to add a gap between the hero and following siblings (e.g. `Card.Title`).
     -   As the **sole child of `Card.Content`**, it extends flush to the card's side edges and additionally to the top edge when `Content` is the first card child, or the bottom edge when it is the last. This enables full-bleed content panels with or without a header above them.
+-   Add `Combobox` primitive ([#78399](https://github.com/WordPress/gutenberg/pull/78399)).
 
 ### Enhancements
 

packages/ui/src/form/primitives/combobox/chip-with-remove.tsx

@@ -0,0 +1,50 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import { forwardRef } from '@wordpress/element';
+import clsx from 'clsx';
+import { __ } from '@wordpress/i18n';
+import { closeSmall } from '@wordpress/icons';
+import { IconButton } from '../../../icon-button';
+import type { ComboboxChipWithRemoveProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * A utility component that combines a chip and a remove button,
+ * with standard styling.
+ */
+export const ChipWithRemove = forwardRef<
+	HTMLDivElement,
+	ComboboxChipWithRemoveProps
+>( function ChipWithRemove(
+	{ className, children, prefix, removeLabel = __( 'Remove' ), ...restProps },
+	ref
+) {
+	return (
+		<_Combobox.Chip
+			ref={ ref }
+			className={ clsx( styles.chip, className ) }
+			{ ...restProps }
+		>
+			{ prefix && (
+				<span className={ styles[ 'chip-prefix' ] }>{ prefix }</span>
+			) }
+			<span className={ styles[ 'chip-content' ] }>{ children }</span>
+
+			<_Combobox.ChipRemove
+				className={ styles[ 'chip-remove' ] }
+				render={ ( props, { disabled } ) => (
+					<IconButton
+						icon={ closeSmall }
+						label={ removeLabel }
+						size="small"
+						variant="minimal"
+						tone="neutral"
+						focusableWhenDisabled={ false }
+						disabled={ disabled }
+						aria-hidden={ disabled || undefined }
+						{ ...props }
+					/>
+				) }
+			/>
+		</_Combobox.Chip>
+	);
+} );

packages/ui/src/form/primitives/combobox/chips.tsx

@@ -0,0 +1,9 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import { forwardRef } from '@wordpress/element';
+import type { ComboboxChipsProps } from './types';
+
+export const Chips = forwardRef< HTMLDivElement, ComboboxChipsProps >(
+	function Chips( props, ref ) {
+		return <_Combobox.Chips ref={ ref } { ...props } />;
+	}
+);

packages/ui/src/form/primitives/combobox/clear.tsx

@@ -0,0 +1,34 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import { forwardRef } from '@wordpress/element';
+import { closeSmall } from '@wordpress/icons';
+import { __ } from '@wordpress/i18n';
+import { IconButton } from '../../../icon-button';
+import type { ComboboxClearProps } from './types';
+
+const DEFAULT_RENDER = (
+	{ 'aria-label': ariaLabel = __( 'Clear' ), ...props }: ComboboxClearProps,
+	{ disabled }: _Combobox.Clear.State
+) => (
+	<IconButton
+		icon={ closeSmall }
+		focusableWhenDisabled={ false }
+		disabled={ disabled }
+		aria-hidden={ disabled || undefined }
+		size="small"
+		variant="minimal"
+		tone="neutral"
+		label={ ariaLabel }
+		{ ...props }
+	/>
+);
+
+/**
+ * A button that clears the selected value(s).
+ */
+export const Clear = forwardRef< HTMLButtonElement, ComboboxClearProps >(
+	function Clear( { render = DEFAULT_RENDER, ...restProps }, ref ) {
+		return (
+			<_Combobox.Clear ref={ ref } render={ render } { ...restProps } />
+		);
+	}
+);

packages/ui/src/form/primitives/combobox/collection.tsx

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

packages/ui/src/form/primitives/combobox/empty.tsx

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

packages/ui/src/form/primitives/combobox/index.ts

@@ -0,0 +1,16 @@
+export { Chips } from './chips';
+export { ChipWithRemove } from './chip-with-remove';
+export { Clear } from './clear';
+export { Collection } from './collection';
+export { Empty } from './empty';
+export { Input } from './input';
+export { Item } from './item';
+export { List } from './list';
+export { ListBody } from './list-body';
+export { ListFooter } from './list-footer';
+export { Portal } from './portal';
+export { Positioner } from './positioner';
+export { Popup } from './popup';
+export { Root } from './root';
+export { Trigger } from './trigger';
+export { Value } from './value';

packages/ui/src/form/primitives/combobox/input.tsx

@@ -0,0 +1,26 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import { forwardRef } from '@wordpress/element';
+import { search } from '@wordpress/icons';
+import { Icon } from '../../../icon';
+import { Input as InputPrimitive } from '../input';
+import { InputLayout } from '../input-layout';
+import type { ComboboxInputProps } from './types';
+
+const DEFAULT_RENDER = ( props: ComboboxInputProps ) => (
+	<InputPrimitive
+		prefix={
+			<InputLayout.Slot padding="minimal">
+				<Icon icon={ search } />
+			</InputLayout.Slot>
+		}
+		{ ...props }
+	/>
+);
+
+export const Input = forwardRef< HTMLInputElement, ComboboxInputProps >(
+	function Input( { render = DEFAULT_RENDER, ...restProps }, ref ) {
+		return (
+			<_Combobox.Input ref={ ref } render={ render } { ...restProps } />
+		);
+	}
+);

packages/ui/src/form/primitives/combobox/item.tsx

@@ -0,0 +1,45 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { check, plus } from '@wordpress/icons';
+import { Icon } from '../../../icon';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+import resetStyles from '../../../utils/css/resets.module.css';
+import type { ComboboxItemProps } from './types';
+
+export const Item = forwardRef< HTMLDivElement, ComboboxItemProps >(
+	function Item(
+		{
+			className,
+			children,
+			size = 'default',
+			variant = 'default',
+			...restProps
+		},
+		ref
+	) {
+		return (
+			<_Combobox.Item
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					itemPopupStyles.item,
+					itemPopupStyles[ `is-size-${ size }` ],
+					className
+				) }
+				ref={ ref }
+				{ ...restProps }
+			>
+				<Icon
+					icon={ variant === 'creatable' ? plus : check }
+					className={ clsx(
+						itemPopupStyles[ 'item-icon' ],
+						variant !== 'creatable' &&
+							itemPopupStyles[ 'item-indicator-icon' ]
+					) }
+					size={ 24 }
+				/>
+				{ children }
+			</_Combobox.Item>
+		);
+	}
+);

packages/ui/src/form/primitives/combobox/list-body.tsx

@@ -0,0 +1,23 @@
+import { forwardRef } from '@wordpress/element';
+import { mergeProps, useRender } from '@base-ui/react';
+import type { ComboboxListBodyProps } 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, ComboboxListBodyProps >(
+	function ListBody( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >(
+				{ className: itemPopupStyles[ 'list-scrollable-container' ] },
+				props
+			),
+		} );
+
+		return element;
+	}
+);

packages/ui/src/form/primitives/combobox/list-footer.tsx

@@ -0,0 +1,24 @@
+import { forwardRef } from '@wordpress/element';
+import { mergeProps, useRender } from '@base-ui/react';
+import type { ComboboxListFooterProps } from './types';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+
+/**
+ * A layout container for the footer row in the `List`,
+ * for holding a single `Item` that triggers the creation of a new item.
+ */
+export const ListFooter = forwardRef< HTMLDivElement, ComboboxListFooterProps >(
+	function ListFooter( { render, ...props }, ref ) {
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >(
+				{ className: itemPopupStyles[ 'list-footer' ] },
+				props
+			),
+		} );
+
+		return element;
+	}
+);

packages/ui/src/form/primitives/combobox/list.tsx

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

packages/ui/src/form/primitives/combobox/popup.tsx

@@ -0,0 +1,38 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+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 { Portal } from './portal';
+import { Positioner } from './positioner';
+import { renderSlotWithChildren } from '../../../utils/render-slot-with-children';
+import itemPopupStyles from '../../../utils/css/item-popup.module.css';
+import type { ComboboxPopupProps } from './types';
+
+const ThemeProvider: typeof ThemeProviderType =
+	unlock( themePrivateApis ).ThemeProvider;
+
+export const Popup = forwardRef< HTMLDivElement, ComboboxPopupProps >(
+	function Popup( { className, portal, positioner, ...restProps }, ref ) {
+		const popupContent = (
+			<ThemeProvider>
+				<_Combobox.Popup
+					ref={ ref }
+					className={ clsx( itemPopupStyles.popup, className ) }
+					{ ...restProps }
+				/>
+			</ThemeProvider>
+		);
+
+		const positionedPopup = renderSlotWithChildren(
+			positioner,
+			<Positioner />,
+			popupContent
+		);
+
+		return renderSlotWithChildren( portal, <Portal />, positionedPopup );
+	}
+);

packages/ui/src/form/primitives/combobox/portal.tsx

@@ -0,0 +1,24 @@
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+import { getWpCompatOverlaySlot } from '../../../utils/wp-compat-overlay-slot';
+
+/**
+ * Root element that portals `Combobox` popup content. Pass to
+ * `Combobox.Popup`'s `portal` prop. When `portal` is omitted,
+ * `Combobox.Popup` uses this component with default props.
+ * `container` defaults to the `@wordpress/ui` compat overlay slot.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function ComboboxPortal( { container, ...restProps }, ref ) {
+		return (
+			<_Combobox.Portal
+				container={ container ?? getWpCompatOverlaySlot() }
+				{ ...restProps }
+				ref={ ref }
+			/>
+		);
+	}
+);
+
+export { Portal };

packages/ui/src/form/primitives/combobox/positioner.tsx

@@ -0,0 +1,29 @@
+import clsx from 'clsx';
+import { Combobox as _Combobox } from '@base-ui/react/combobox';
+import { forwardRef } from '@wordpress/element';
+import type { PositionerProps } from './types';
+import resetStyles from '../../../utils/css/resets.module.css';
+import styles from './style.module.css';
+import { ITEM_POPUP_POSITIONER_PROPS } from '../constants';
+
+/**
+ * Used to apply custom positioning to `Combobox`'s popup content.
+ */
+const Positioner = forwardRef< HTMLDivElement, PositionerProps >(
+	function ComboboxPositioner( { className, ...props }, ref ) {
+		return (
+			<_Combobox.Positioner
+				{ ...ITEM_POPUP_POSITIONER_PROPS }
+				{ ...props }
+				ref={ ref }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner,
+					className
+				) }
+			/>
+		);
+	}
+);
+
+export { Positioner };