@spunto/design-system 0.22.0 → 0.23.0

package/README.md

@@ -73,6 +73,26 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   - _Forms_ — `Input`, `Textarea`, `Label`, `Switch`, `Checkbox`,
     `RadioGroup` (+`RadioGroupItem`), `Select` (+`SelectTrigger`/`SelectValue`/
     `SelectContent`/`SelectItem`/`SelectGroup`/`SelectGroupLabel`/`SelectSeparator`).
+  - _Combobox_ — `Combobox` (+`ComboboxInput`/`Clear`/`Trigger`/`Value`/`Search`/`Chips`/
+    `Chip`/`ChipsInput`/`Content`/`List`/`Group`/`GroupLabel`/`Separator`/`Item`/`Empty`/
+    `Loading`), the `Select` you can type into — for the list nobody wants to scroll
+    (branches, repos, model ids, members, tags). Base UI's `Combobox` underneath, and
+    compositional like `Select`: items are children. Three things it adds. (1) **Items
+    filter themselves**, with the same collator `CommandPalette` uses, so no caller
+    re-`.filter()`s its options and "deploi" finds "déploiement"; groups hide themselves
+    through `:has()` (no more `if (items.length === 0) return null`), and so does a
+    separator with nothing left after it. (2) **A query is only a query when someone
+    typed it** — Base UI writes the selected item's label into the input, and taken at
+    face value that text filters the list down to the row you just picked; the filter
+    keys off the `input-change` reason and ignores anything the component wrote itself.
+    (3) In multi-select **the chips field registers itself as the popup's anchor**, so
+    the list opens under the whole field instead of the caret-sized `<input>` — no ref
+    to remember, no `anchor` prop to pass. Two field shapes, two components rather than
+    a flag: `ComboboxInput` (the combobox *is* the field, same 32 px/border/ring as
+    `Input`, chevron out of the tab order) or `ComboboxTrigger` + `ComboboxValue` with a
+    `ComboboxSearch` at the top of the popup, for when the value is rendered rather than
+    typed. Presentational only: `loading` is a prop and a server-side search is
+    `onInputValueChange` + `filter={null}`.
   - _Navigation & feedback_ — `Tabs` (+`TabsList`/`TabsIndicator`/`TabsTab`/`TabsPanel`),
     `Alert` (+`AlertTitle`/`AlertDescription`, +`alertVariants`) — an **inline, persistent,
     declarative** status banner, the counterpart to the ephemeral imperative `toast()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/combobox.tsx

@@ -0,0 +1,706 @@
+"use client"
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type ReactNode,
+} from "react"
+import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox"
+import { CheckIcon, ChevronDownIcon, SearchIcon, XIcon } from "lucide-react"
+
+import { cn } from "../utils"
+import { highlightMatch, type CommandFilter, type CommandFilterItem } from "./command-shared"
+import { Skeleton } from "./skeleton"
+import { Spinner } from "./spinner"
+import { useOverlayContainer } from "./spunto-provider"
+
+// ---------------------------------------------------------------------------
+// Why it's built this way
+//
+// A `Select` where you can type. Base UI's `Combobox` brings the hard parts —
+// roles, `aria-activedescendant`, ↑↓ highlight, scroll-into-view, chips and
+// their backspace behaviour — and this file brings three things it doesn't:
+//
+// 1. ITEMS FILTER THEMSELVES, with the same collator the ⌘K palette uses.
+//    Base UI filters from an `items` array; like `CommandPalette`, this
+//    component is compositional (the app writes `<ComboboxItem>` children, the
+//    way it writes `<SelectItem>`), so each item decides for itself whether it
+//    matches and renders nothing when it doesn't. Groups hide themselves
+//    through `:has()`. Nobody has to re-`.filter()` their options by hand, and
+//    "déploiement" is found by "deploi" here exactly like it is in the palette
+//    — one definition of "matching" for the whole package (`command-shared`).
+//
+// 2. A QUERY IS ONLY A QUERY WHEN SOMEONE TYPED IT. Base UI writes the selected
+//    item's label into the input on selection; taken at face value that text
+//    would filter the list down to the single row you just picked, which is how
+//    a combobox ends up looking broken on reopen. Every input change carries a
+//    `reason`, so the filter keys off `input-change` — a keystroke or a paste —
+//    and ignores everything the component wrote itself.
+//
+// 3. THE POPUP FINDS ITS OWN ANCHOR IN MULTI-SELECT. `ComboboxChips` registers
+//    itself, `ComboboxContent` reads it. Without that the popup anchors to the
+//    bare `<input>` — a caret-sized box that moves to the end of the last chip
+//    row — and the caller has to remember a ref and an `anchor` prop to avoid it.
+//
+// Purely presentational: nothing here calls an API. `loading` is a prop, items
+// are children, and a server-side search sets `filter={null}` and feeds the
+// already-filtered items in.
+// ---------------------------------------------------------------------------
+
+/** What the filter gets to look at for one item. Shared with `CommandPalette`. */
+export type ComboboxFilterItem = CommandFilterItem
+
+export type ComboboxFilter = CommandFilter
+
+interface ComboboxContextValue {
+  /** The *typed* query — empty whenever the text in the input isn't the user's. */
+  query: string
+  loading: boolean
+  matches: (item: ComboboxFilterItem) => boolean
+  /** The chips field, when there is one: the popup anchors to it, not to the input. */
+  chipsElement: HTMLElement | null
+  setChipsElement: (element: HTMLElement | null) => void
+}
+
+const ComboboxContext = createContext<ComboboxContextValue | null>(null)
+
+/** How the empty state and the group find the rendered items. */
+const ITEM_SELECTOR = "[data-slot='combobox-item']"
+
+function useCombobox(part: string): ComboboxContextValue {
+  const context = useContext(ComboboxContext)
+  if (!context) throw new Error(`<${part}> must be rendered inside <Combobox>.`)
+  return context
+}
+
+// --- root -------------------------------------------------------------------
+
+export type ComboboxProps<Value, Multiple extends boolean | undefined = false> = Omit<
+  ComboboxPrimitive.Root.Props<Value, Multiple>,
+  // Base UI's own filtering works off an `items` array. Here items are children
+  // and filter themselves (see the note at the top), so these three would only
+  // filter the same list a second time.
+  "filter" | "items" | "filteredItems"
+> & {
+  /**
+   * Local filtering. Default: accent- and case-insensitive "contains" over the
+   * item's label, keywords and value. Pass `null` to filter nothing (results
+   * already come filtered from an API), or your own predicate.
+   */
+  filter?: ComboboxFilter | null
+  /** Draws a spinner in the field, shows `ComboboxLoading`, silences `ComboboxEmpty`. */
+  loading?: boolean
+}
+
+/**
+ * A listbox you can type into: the `Select` for lists nobody wants to scroll —
+ * branches, repositories, model ids, members. Domain-free, and compositional
+ * like `Select`: the parts you write are the list.
+ *
+ * ```tsx
+ * <Combobox value={branch} onValueChange={(v) => setBranch(v ?? "")}>
+ *   <ComboboxInput placeholder="main" />
+ *   <ComboboxContent>
+ *     <ComboboxList>
+ *       <ComboboxEmpty>Aucune branche</ComboboxEmpty>
+ *       {branches.map((b) => (
+ *         <ComboboxItem key={b} value={b} icon={<GitBranch />}>{b}</ComboboxItem>
+ *       ))}
+ *     </ComboboxList>
+ *   </ComboboxContent>
+ * </Combobox>
+ * ```
+ *
+ * `multiple` swaps the field for `ComboboxChips`; everything below it is the same.
+ */
+function Combobox<Value, Multiple extends boolean | undefined = false>({
+  filter,
+  loading = false,
+  inputValue,
+  onInputValueChange,
+  children,
+  ...props
+}: ComboboxProps<Value, Multiple>) {
+  const { contains } = ComboboxPrimitive.useFilter({ sensitivity: "base" })
+  const [observed, setObserved] = useState("")
+  const [typed, setTyped] = useState(false)
+  const [chipsElement, setChipsElement] = useState<HTMLElement | null>(null)
+
+  // The input text is Base UI's to own — this only watches it go by, so no
+  // controlled/uncontrolled seam is introduced where there wasn't one. What
+  // matters is the `reason`: only `input-change` — a keystroke or a paste — makes
+  // the text a query.
+  // Anything the component wrote itself (the label of the item just selected,
+  // a sync with an external `value`) leaves the list whole.
+  function handleInputValueChange(next: string, details: ComboboxPrimitive.Root.ChangeEventDetails) {
+    setObserved(next)
+    setTyped(details.reason === "input-change")
+    onInputValueChange?.(next, details)
+  }
+
+  const text = inputValue !== undefined ? String(inputValue ?? "") : observed
+  const query = typed ? text : ""
+
+  const context: ComboboxContextValue = {
+    query,
+    loading,
+    chipsElement,
+    setChipsElement,
+    matches: (item) => {
+      if (!query.trim()) return true
+      if (filter === null) return true
+      if (filter) return filter(item, query)
+      return [item.label, item.value ?? "", ...item.keywords].some((text) => text && contains(text, query))
+    },
+  }
+
+  return (
+    <ComboboxPrimitive.Root
+      data-slot="combobox"
+      inputValue={inputValue}
+      onInputValueChange={handleInputValueChange}
+      {...(props as ComboboxPrimitive.Root.Props<Value, Multiple>)}
+    >
+      <ComboboxContext.Provider value={context}>{children}</ComboboxContext.Provider>
+    </ComboboxPrimitive.Root>
+  )
+}
+
+// --- field: the combobox *is* the input -------------------------------------
+
+/** The shell every field shape shares — same 32 px, same border, same ring as `Input`. */
+const fieldClassName =
+  "flex w-full items-center rounded-lg border border-input bg-transparent text-sm transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 has-disabled:cursor-not-allowed has-disabled:opacity-50 has-aria-invalid:border-destructive has-aria-invalid:ring-3 has-aria-invalid:ring-destructive/20 dark:bg-input/30 dark:has-aria-invalid:border-destructive/50 dark:has-aria-invalid:ring-destructive/40"
+
+export interface ComboboxInputProps
+  extends Omit<ComponentProps<"input">, "value" | "defaultValue" | "size"> {
+  /** Leading icon inside the field (a `lucide-react` glyph, a status dot…). */
+  icon?: ReactNode
+  /**
+   * Draws the ✕ that clears the selection. It appears only when there *is*
+   * something to clear — Base UI decides that, not the caller.
+   * @default true
+   */
+  clearable?: boolean
+}
+
+/**
+ * The field, for the shape where the combobox **is** the input: you read the
+ * current value by reading the text, and typing filters in place. The chevron
+ * isn't a tab stop — the input already opens the list with ↓, and a field that
+ * costs two tabs to leave is a field people complain about.
+ *
+ * For the other shape — a button that shows the value, with the search box
+ * inside the popup — use `ComboboxTrigger` + `ComboboxSearch`.
+ */
+function ComboboxInput({ className, icon, clearable = true, ...props }: ComboboxInputProps) {
+  const { loading } = useCombobox("ComboboxInput")
+  return (
+    <div data-slot="combobox-field" className={cn("group/field h-8", fieldClassName, className)}>
+      {icon != null && (
+        <span className="ml-2.5 flex shrink-0 items-center text-muted-foreground [&_svg]:size-3.5" aria-hidden>
+          {icon}
+        </span>
+      )}
+      <ComboboxPrimitive.Input
+        data-slot="combobox-input"
+        // `md:text-sm` — below 16px, iOS zooms the page when the field takes focus.
+        className="h-full min-w-0 flex-1 bg-transparent px-2.5 text-base outline-none placeholder:text-muted-foreground disabled:pointer-events-none md:text-sm"
+        {...props}
+      />
+      <span className="flex shrink-0 items-center gap-0.5 pr-1.5">
+        {loading && <Spinner size="xs" className="mr-0.5 text-muted-foreground" />}
+        {clearable && <ComboboxClear />}
+        {/* Hidden while the ✕ is there: two buttons in a 32 px field is one too
+            many, and the input itself still opens the list. */}
+        <ComboboxPrimitive.Trigger
+          data-slot="combobox-chevron"
+          tabIndex={-1}
+          aria-label="Ouvrir la liste"
+          className="flex size-5 shrink-0 items-center justify-center rounded text-muted-foreground transition-colors outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50 disabled:pointer-events-none group-has-[[data-slot=combobox-clear]]/field:hidden"
+        >
+          <ChevronDownIcon className="size-3.5" />
+        </ComboboxPrimitive.Trigger>
+      </span>
+    </div>
+  )
+}
+
+/**
+ * The ✕ that empties the field. Mounted by Base UI only when there's a value to
+ * clear, so it needs no `visible`/`showClear` prop — asking the caller for one
+ * is asking them to recompute what the component already knows.
+ */
+function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
+  return (
+    <ComboboxPrimitive.Clear
+      data-slot="combobox-clear"
+      aria-label="Effacer"
+      className={cn(
+        "flex size-5 shrink-0 items-center justify-center rounded text-muted-foreground transition-colors outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50",
+        className
+      )}
+      {...props}
+    >
+      <XIcon className="size-3.5" />
+    </ComboboxPrimitive.Clear>
+  )
+}
+
+// --- field: a trigger, and the search inside the popup -----------------------
+
+/**
+ * The other field shape: a button showing the selected value, exactly like
+ * `SelectTrigger`. Put a `ComboboxValue` inside it and a `ComboboxSearch` at the
+ * top of the popup — that's the shape to reach for when the value is long, or
+ * rendered (an avatar, a badge) rather than typed.
+ */
+function ComboboxTrigger({ className, children, ...props }: ComboboxPrimitive.Trigger.Props) {
+  return (
+    <ComboboxPrimitive.Trigger
+      data-slot="combobox-trigger"
+      className={cn(
+        "flex h-8 w-full items-center justify-between gap-2 rounded-lg border border-input bg-transparent px-2.5 py-1 text-sm whitespace-nowrap transition-colors outline-none select-none data-[popup-open]:border-ring focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:bg-input/30 [&>span]:truncate",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <ComboboxPrimitive.Icon className="shrink-0 text-muted-foreground">
+        <ChevronDownIcon className="size-3.5" />
+      </ComboboxPrimitive.Icon>
+    </ComboboxPrimitive.Trigger>
+  )
+}
+
+/**
+ * The selected value, or `placeholder` when there's none. Goes inside
+ * `ComboboxTrigger`. With no children it prints the raw value: the package never
+ * receives the list of options (they're children, and a closed popup hasn't
+ * rendered them), so anything prettier than the value itself — a label, an
+ * avatar, a badge — is the app's to render here.
+ */
+function ComboboxValue({ placeholder, children, ...props }: ComboboxPrimitive.Value.Props) {
+  return (
+    <span data-slot="combobox-value" className="truncate">
+      <ComboboxPrimitive.Value
+        placeholder={
+          placeholder != null ? <span className="text-muted-foreground">{placeholder}</span> : undefined
+        }
+        {...props}
+      >
+        {children}
+      </ComboboxPrimitive.Value>
+    </span>
+  )
+}
+
+export interface ComboboxSearchProps
+  extends Omit<ComponentProps<"input">, "value" | "defaultValue" | "size"> {
+  /** Leading icon. Defaults to a magnifier; pass `null` for none. */
+  icon?: ReactNode
+}
+
+/**
+ * The search row **inside** the popup, for the `ComboboxTrigger` shape. Flush
+ * against the popup's edges rather than a bordered box: it isn't the field, it's
+ * the top of the list — the same row `CommandPaletteInput` draws.
+ */
+function ComboboxSearch({ className, placeholder = "Rechercher…", icon, ...props }: ComboboxSearchProps) {
+  const { loading } = useCombobox("ComboboxSearch")
+  return (
+    <div
+      data-slot="combobox-search"
+      className={cn("flex h-9 shrink-0 items-center gap-2 border-b border-border px-2.5", className)}
+    >
+      {icon !== null && (
+        <span className="shrink-0 text-muted-foreground [&_svg]:size-3.5" aria-hidden>
+          {icon ?? <SearchIcon className="size-3.5" />}
+        </span>
+      )}
+      <ComboboxPrimitive.Input
+        className="h-full min-w-0 flex-1 bg-transparent text-base text-foreground outline-none placeholder:text-muted-foreground md:text-sm"
+        placeholder={placeholder}
+        aria-label={props["aria-label"] ?? placeholder}
+        {...props}
+      />
+      {loading && <Spinner size="xs" className="shrink-0 text-muted-foreground" />}
+    </div>
+  )
+}
+
+// --- field: chips (multi-select) --------------------------------------------
+
+/**
+ * The multi-select field: the selected values as chips, with the input sharing
+ * the box. It registers itself as the popup's anchor, so `ComboboxContent` opens
+ * under the *whole* field and matches its width — without it, the popup hangs off
+ * the caret-sized `<input>`, which sits wherever the last chip left it.
+ */
+function ComboboxChips({ className, ...props }: ComboboxPrimitive.Chips.Props) {
+  const { setChipsElement } = useCombobox("ComboboxChips")
+  return (
+    <ComboboxPrimitive.Chips
+      ref={setChipsElement}
+      data-slot="combobox-chips"
+      className={cn(
+        "min-h-8 flex-wrap gap-1 py-1 pr-1.5 pl-1 has-[[data-slot=combobox-chip]]:pl-1",
+        fieldClassName,
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export interface ComboboxChipProps extends ComboboxPrimitive.Chip.Props {
+  /**
+   * Draws the ✕ on the chip.
+   * @default true
+   */
+  removable?: boolean
+}
+
+/** One selected value. Backspace from the input removes the last one — Base UI's doing. */
+function ComboboxChip({ className, children, removable = true, ...props }: ComboboxChipProps) {
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="combobox-chip"
+      className={cn(
+        "flex h-5.5 items-center gap-1 rounded-md bg-muted pr-1 pl-1.5 text-xs font-medium whitespace-nowrap text-foreground outline-none data-highlighted:bg-accent data-highlighted:text-accent-foreground",
+        !removable && "pr-1.5",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {removable && (
+        <ComboboxPrimitive.ChipRemove
+          data-slot="combobox-chip-remove"
+          aria-label="Retirer"
+          className="flex size-3.5 items-center justify-center rounded-sm text-muted-foreground transition-colors outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
+        >
+          <XIcon className="size-3" />
+        </ComboboxPrimitive.ChipRemove>
+      )}
+    </ComboboxPrimitive.Chip>
+  )
+}
+
+/** The text field that lives among the chips. Flush — `ComboboxChips` draws the box. */
+function ComboboxChipsInput({ className, ...props }: ComboboxPrimitive.Input.Props) {
+  return (
+    <ComboboxPrimitive.Input
+      data-slot="combobox-chips-input"
+      className={cn(
+        "h-6 min-w-24 flex-1 bg-transparent px-1.5 text-base outline-none placeholder:text-muted-foreground md:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+// --- popup ------------------------------------------------------------------
+
+export interface ComboboxContentProps extends ComboboxPrimitive.Popup.Props {
+  side?: ComboboxPrimitive.Positioner.Props["side"]
+  align?: ComboboxPrimitive.Positioner.Props["align"]
+  sideOffset?: ComboboxPrimitive.Positioner.Props["sideOffset"]
+  alignOffset?: ComboboxPrimitive.Positioner.Props["alignOffset"]
+  /** Override the element the popup hangs off. Defaults to the field. */
+  anchor?: ComboboxPrimitive.Positioner.Props["anchor"]
+}
+
+/**
+ * Portal + positioned popup, rendered into the `SpuntoProvider`'s overlay
+ * container like every other overlay here — which is what keeps it above a
+ * `Dialog` instead of behind it.
+ */
+function ComboboxContent({
+  className,
+  children,
+  side = "bottom",
+  align = "start",
+  sideOffset = 4,
+  alignOffset = 0,
+  anchor,
+  ...props
+}: ComboboxContentProps) {
+  const container = useOverlayContainer()
+  const { chipsElement } = useCombobox("ComboboxContent")
+  return (
+    <ComboboxPrimitive.Portal container={container ?? undefined}>
+      <ComboboxPrimitive.Positioner
+        data-slot="combobox-positioner"
+        className="z-50 outline-none"
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        anchor={anchor ?? chipsElement ?? undefined}
+      >
+        <ComboboxPrimitive.Popup
+          data-slot="combobox-content"
+          className={cn(
+            "flex max-h-[min(20rem,var(--available-height))] w-[var(--anchor-width)] max-w-[var(--available-width)] min-w-[max(8rem,var(--anchor-width))] flex-col overflow-hidden rounded-lg border border-border bg-popover text-popover-foreground shadow-lg shadow-black/[0.06] outline-none",
+            "origin-[var(--transform-origin)] transition-[transform,opacity] duration-150 data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+            className
+          )}
+          {...props}
+        >
+          {children}
+        </ComboboxPrimitive.Popup>
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  )
+}
+
+/**
+ * The scrollable results area. Groups, items, `ComboboxEmpty` and
+ * `ComboboxLoading` all go in it — the empty state keys off `:has()` on this
+ * element, so it only works from inside.
+ */
+function ComboboxList({ className, children, ...props }: ComboboxPrimitive.List.Props) {
+  const { loading } = useCombobox("ComboboxList")
+  const ref = useRef<HTMLDivElement>(null)
+  const [count, setCount] = useState(0)
+
+  // Counting the rendered items is the one thing CSS can't do for us, and the
+  // announcement below needs it. Reading the DOM after the commit is cheaper
+  // (and more accurate) than making every item report in.
+  useEffect(() => {
+    const rendered = ref.current?.querySelectorAll(ITEM_SELECTOR).length ?? 0
+    setCount((prev) => (prev === rendered ? prev : rendered))
+  })
+
+  return (
+    <>
+      <ComboboxPrimitive.List
+        ref={ref}
+        data-slot="combobox-list"
+        className={cn("group/combobox-list min-h-0 flex-1 overflow-y-auto overscroll-contain p-1", className)}
+        {...props}
+      >
+        {children}
+      </ComboboxPrimitive.List>
+      {/* Must stay mounted to announce reliably — only its text changes. */}
+      <ComboboxPrimitive.Status className="sr-only">
+        {loading ? "Recherche en cours…" : count === 0 ? "Aucun résultat" : `${count} résultat${count > 1 ? "s" : ""}`}
+      </ComboboxPrimitive.Status>
+    </>
+  )
+}
+
+// --- group / separator ------------------------------------------------------
+
+export interface ComboboxGroupProps extends ComboboxPrimitive.Group.Props {
+  heading?: ReactNode
+}
+
+/**
+ * A titled block of items. It hides itself when none of its items survived the
+ * filter — through `:has()` rather than a JS count, so no caller ever writes
+ * `if (items.length === 0) return null` again, and the heading never flashes for
+ * a frame above an empty group.
+ */
+function ComboboxGroup({ heading, className, children, ...props }: ComboboxGroupProps) {
+  return (
+    <ComboboxPrimitive.Group
+      data-slot="combobox-group"
+      className={cn("hidden has-[[data-slot=combobox-item]]:block", className)}
+      {...props}
+    >
+      {heading != null && <ComboboxGroupLabel>{heading}</ComboboxGroupLabel>}
+      {children}
+    </ComboboxPrimitive.Group>
+  )
+}
+
+/** The heading of a group. `ComboboxGroup`'s `heading` prop renders one for you. */
+function ComboboxGroupLabel({ className, ...props }: ComboboxPrimitive.GroupLabel.Props) {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      data-slot="combobox-group-label"
+      className={cn("px-2 pt-1.5 pb-1 text-xs font-medium text-muted-foreground select-none", className)}
+      {...props}
+    />
+  )
+}
+
+/**
+ * A thin rule between blocks. It disappears when nothing survives *after* it —
+ * neither an item of its own nor a group still holding one — because the whole
+ * point of filtering the list is that the rule between two blocks stops making
+ * sense before the blocks do. A separator left alone at the bottom of a popup is
+ * the tell that someone wrote the condition by hand and forgot a case.
+ *
+ * What it can't see is what comes *before* it (CSS has no previous-sibling
+ * `:has()`), so a rule rendered first in the list is the app's to hold back.
+ */
+function ComboboxSeparator({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="combobox-separator"
+      role="separator"
+      className={cn(
+        "-mx-1 my-1 hidden h-px bg-border",
+        "[&:has(~:is([data-slot=combobox-item],:has([data-slot=combobox-item])))]:block",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+// --- item -------------------------------------------------------------------
+
+export interface ComboboxItemProps extends Omit<ComboboxPrimitive.Item.Props, "value" | "children"> {
+  /** What gets committed. Objects work too — Base UI stringifies them for the input. */
+  value?: unknown
+  children?: ReactNode
+  /** Leading icon (a `lucide-react` glyph, an avatar, a status dot…). */
+  icon?: ReactNode
+  /** Secondary text, right-aligned: type, org, version… */
+  meta?: ReactNode
+  /** Second line under the label. */
+  description?: ReactNode
+  /** Extra search terms, never displayed. */
+  keywords?: string[]
+  /**
+   * Text the filter matches on. Defaults to the children when they're a plain
+   * string — pass it explicitly as soon as they aren't (an item that renders
+   * "Créer « foo »" still searches on `foo`).
+   */
+  label?: string
+}
+
+/**
+ * One option. Renders nothing when it doesn't match the query — that's the whole
+ * filtering mechanism, and what keeps a long list cheap once the user types.
+ *
+ * The ✓ sits on the **right**, unlike `SelectItem`: the left slot belongs to the
+ * item's own icon here (a repo, a branch, an avatar), and in multi-select a
+ * right-hand column of ticks reads as the checkbox column it is.
+ */
+function ComboboxItem({
+  value,
+  icon,
+  meta,
+  description,
+  keywords = [],
+  label: labelProp,
+  className,
+  children,
+  ...props
+}: ComboboxItemProps) {
+  const { matches, query } = useCombobox("ComboboxItem")
+  // Plain-string children are the label, and the label is what gets a `<mark>`.
+  // Anything else the caller wrote is rendered verbatim — `label` then only
+  // feeds the filter, so an item can match on "foo" while reading "Créer « foo »".
+  const text = typeof children === "string" ? children : undefined
+  const label = labelProp ?? text
+
+  if (!matches({ label: label ?? "", keywords, value: typeof value === "string" ? value : undefined })) {
+    return null
+  }
+
+  return (
+    <ComboboxPrimitive.Item
+      data-slot="combobox-item"
+      value={value}
+      className={cn(
+        "group/combobox-item flex scroll-my-1 cursor-default items-center gap-2 rounded-md py-1.5 pr-2 pl-2 text-sm text-foreground outline-none select-none",
+        "data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    >
+      {icon != null && (
+        <span
+          className="flex size-4 shrink-0 items-center justify-center text-muted-foreground group-data-highlighted/combobox-item:text-foreground [&_svg]:size-3.5"
+          aria-hidden
+        >
+          {icon}
+        </span>
+      )}
+      <span className="min-w-0 flex-1">
+        <span className="block truncate">{text != null ? highlightMatch(text, query) : children}</span>
+        {description != null && <span className="block truncate text-xs text-muted-foreground">{description}</span>}
+      </span>
+      {meta != null && <span className="shrink-0 truncate text-xs text-muted-foreground tabular-nums">{meta}</span>}
+      <ComboboxPrimitive.ItemIndicator className="flex size-4 shrink-0 items-center justify-center text-primary">
+        <CheckIcon className="size-3.5" />
+      </ComboboxPrimitive.ItemIndicator>
+    </ComboboxPrimitive.Item>
+  )
+}
+
+// --- empty / loading --------------------------------------------------------
+
+/**
+ * Shown only when no item survived the filter, and never while `loading` (a
+ * pending search isn't an empty result). Must live inside `ComboboxList`.
+ */
+function ComboboxEmpty({ className, children = "Aucun résultat", ...props }: ComponentProps<"div">) {
+  const { loading } = useCombobox("ComboboxEmpty")
+  if (loading) return null
+  return (
+    <div
+      data-slot="combobox-empty"
+      role="presentation"
+      className={cn(
+        "px-3 py-6 text-center text-sm text-muted-foreground group-has-[[data-slot=combobox-item]]/combobox-list:hidden",
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
+export interface ComboboxLoadingProps extends ComponentProps<"div"> {
+  /** Number of skeleton rows. @default 3 */
+  rows?: number
+}
+
+/** Skeleton rows while an async search is in flight. Renders nothing unless the root is `loading`. */
+function ComboboxLoading({ rows = 3, className, ...props }: ComboboxLoadingProps) {
+  const { loading } = useCombobox("ComboboxLoading")
+  if (!loading) return null
+  return (
+    <div data-slot="combobox-loading" role="presentation" className={cn("space-y-1", className)} {...props}>
+      {Array.from({ length: rows }, (_, i) => (
+        <div key={i} className="flex items-center gap-2 px-2 py-1.5">
+          <Skeleton className="size-3.5 shrink-0 rounded" />
+          <Skeleton className="h-3" style={{ width: `${55 - i * 10}%` }} />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxClear,
+  ComboboxTrigger,
+  ComboboxValue,
+  ComboboxSearch,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxSeparator,
+  ComboboxItem,
+  ComboboxEmpty,
+  ComboboxLoading,
+}

package/src/index.ts

@@ -70,6 +70,45 @@ export {
   SelectSeparator,
 } from "./components/select"
 
+// Combobox — the Select you can type into, on Base UI. Compositional like
+// Select (items are children), but the items **filter themselves** with the
+// same collator the ⌘K palette uses, so no caller re-`.filter()`s its options;
+// groups hide themselves when empty; and in multi-select the chips field
+// registers itself as the popup's anchor. Two field shapes, two components:
+// `ComboboxInput` (the combobox IS the field) or `ComboboxTrigger` + a
+// `ComboboxSearch` inside the popup.
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxClear,
+  ComboboxTrigger,
+  ComboboxValue,
+  ComboboxSearch,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxSeparator,
+  ComboboxItem,
+  ComboboxEmpty,
+  ComboboxLoading,
+} from "./components/combobox"
+export type {
+  ComboboxProps,
+  ComboboxInputProps,
+  ComboboxSearchProps,
+  ComboboxChipProps,
+  ComboboxContentProps,
+  ComboboxGroupProps,
+  ComboboxItemProps,
+  ComboboxLoadingProps,
+  ComboboxFilter,
+  ComboboxFilterItem,
+} from "./components/combobox"
+
 // Overlays that plug into the `SpuntoProvider` umbrella (portal container +
 // tooltip delay group).
 export { Tooltip } from "./components/tooltip"