@spunto/design-system 0.21.0 → 0.23.0

package/README.md

@@ -56,9 +56,43 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     `Separator`, `Spinner`, `Skeleton`, `Avatar` (+`AvatarImage`/`AvatarFallback`),
     `Kbd` — one keyboard cap, or a whole shortcut (`keys="mod+k"` → ⌘ K, Ctrl K off Apple),
     spelled out for screen readers.
+  - _AvatarGroup_ — the stack of overlapping avatars. `size` (`xs`…`xl`) sizes the whole
+    stack at once — on `Avatar` it sets the circle **and** its initials, because a 64 px
+    avatar with 14 px initials looks broken. **Compositional**: the group never reads a
+    `{ name, src }` shape, it wraps whatever you hand it (an `Avatar`, one inside a
+    `Tooltip`, a round `Skeleton` while the list loads) in its own span, so a loading
+    stack has exactly the geometry of the loaded one. It owns only what a caller can't
+    get right by hand: the overlap (a ratio of the diameter, `spacing` = ~40/29/20%), the
+    `ringClassName` that separates two faces (match the surface *behind* the stack —
+    `ring-card` inside a `Card`), the paint order, and the `+N`. Counting has two rules:
+    the counter adds the children `max` cut **and** the people never rendered
+    (`total` − children), so a paginated list shows `+38` without fabricating 38 ghost
+    avatars; and a `+1` never appears — one hidden child takes exactly the room its
+    counter would, saying less, so the face is drawn instead. `onOverflowClick` makes
+    the counter a real button.
   - _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.21.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/avatar.tsx

@@ -1,18 +1,54 @@
 "use client"
 
+import { Children, createContext, useContext, type ComponentProps, type ReactNode } from "react"
 import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
+import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "../utils"
 
+const avatarVariants = cva("relative flex shrink-0 overflow-hidden rounded-full bg-muted select-none", {
+  variants: {
+    // The font-size of each step lives here rather than on the fallback: the
+    // initials then *inherit* it, so one `size` sets the circle and its text
+    // together (a 64 px avatar with 14 px initials looks broken).
+    size: {
+      xs: "size-5 text-[0.5625rem]",
+      sm: "size-7 text-[0.6875rem]",
+      default: "size-9 text-sm",
+      lg: "size-12 text-base",
+      xl: "size-16 text-xl",
+    },
+  },
+  defaultVariants: {
+    size: "default",
+  },
+})
+
+export type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>
+
+/**
+ * The size an `AvatarGroup` imposes on the avatars inside it, so a stack is
+ * sized once instead of on every child. `null` = no group above.
+ */
+const AvatarGroupSizeContext = createContext<AvatarSize | null>(null)
+
+export interface AvatarProps extends AvatarPrimitive.Root.Props {
+  /**
+   * Diameter of the circle (20 / 28 / 36 / 48 / 64 px) — and the size of the
+   * fallback initials with it. Inside an `AvatarGroup`, defaults to the group's.
+   * @default "default"
+   */
+  size?: AvatarSize
+}
+
 /** Circular avatar container. Compose `AvatarImage` + `AvatarFallback` inside. */
-function Avatar({ className, ...props }: AvatarPrimitive.Root.Props) {
+function Avatar({ className, size, ...props }: AvatarProps) {
+  const groupSize = useContext(AvatarGroupSizeContext)
+
   return (
     <AvatarPrimitive.Root
       data-slot="avatar"
-      className={cn(
-        "relative flex size-9 shrink-0 overflow-hidden rounded-full bg-muted select-none",
-        className
-      )}
+      className={cn(avatarVariants({ size: size ?? groupSize ?? undefined }), className)}
       {...props}
     />
   )
@@ -29,7 +65,8 @@ function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props)
     <AvatarPrimitive.Fallback
       data-slot="avatar-fallback"
       className={cn(
-        "flex size-full items-center justify-center bg-muted text-sm font-medium text-muted-foreground",
+        // No text-size here on purpose — it comes from the root's `size`.
+        "flex size-full items-center justify-center bg-muted font-medium text-muted-foreground",
         className
       )}
       {...props}
@@ -37,4 +74,169 @@ function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props)
   )
 }
 
-export { Avatar, AvatarImage, AvatarFallback }
+export type AvatarGroupSpacing = "tight" | "default" | "loose"
+
+// How far each avatar slides under the previous one. Expressed per size because
+// an overlap is a *ratio* of the circle (~29% at default), and Tailwind needs
+// whole class names — hence a table rather than a computed `-ml-${n}`.
+const OVERLAP: Record<AvatarSize, Record<AvatarGroupSpacing, string>> = {
+  xs: { tight: "-ml-2", default: "-ml-1.5", loose: "-ml-1" },
+  sm: { tight: "-ml-3", default: "-ml-2", loose: "-ml-1.5" },
+  default: { tight: "-ml-3.5", default: "-ml-2.5", loose: "-ml-2" },
+  lg: { tight: "-ml-5", default: "-ml-3.5", loose: "-ml-2.5" },
+  xl: { tight: "-ml-6", default: "-ml-5", loose: "-ml-3.5" },
+}
+
+// The ring is what separates two overlapping circles — it has to grow with them.
+const RING: Record<AvatarSize, string> = {
+  xs: "ring-[1.5px]",
+  sm: "ring-2",
+  default: "ring-2",
+  lg: "ring-2",
+  xl: "ring-[3px]",
+}
+
+export interface AvatarGroupProps extends Omit<ComponentProps<"div">, "children"> {
+  /** The avatars, in reading order. Each one paints over its left neighbour. */
+  children?: ReactNode
+  /**
+   * Size applied to every avatar in the stack (a child's own `size` still wins).
+   * @default "default"
+   */
+  size?: AvatarSize
+  /**
+   * Show at most this many avatars; the rest collapse into a `+N` counter.
+   * Left unset, everything is drawn.
+   */
+  max?: number
+  /**
+   * Real number of people, when the caller only renders a sample of them (a
+   * members list that fetched 5 avatars out of 40 → `total={40}` counts the 35
+   * it never received). Defaults to the number of children.
+   */
+  total?: number
+  /**
+   * How much of each avatar the next one covers — ~40%, ~29%, ~20%.
+   * @default "default"
+   */
+  spacing?: AvatarGroupSpacing
+  /**
+   * Ring color punched between overlapping avatars: it must match the surface
+   * *behind* the stack, so inside a `Card` it's `ring-card`.
+   * @default "ring-background"
+   */
+  ringClassName?: string
+  /**
+   * Hovering an avatar brings it to the front (and lifts it a hair), which is
+   * how a covered face becomes readable without a click.
+   * @default true
+   */
+  revealOnHover?: boolean
+  /** Makes the `+N` counter a real button — "see all members". */
+  onOverflowClick?: () => void
+  /** Accessible name of that button. @default "Voir tout" */
+  overflowLabel?: string
+}
+
+/**
+ * A stack of overlapping avatars — the compact way to say "these people".
+ *
+ * ```tsx
+ * <AvatarGroup size="sm" max={4} total={members.length}>
+ *   {members.map((m) => (
+ *     <Avatar key={m.id}>
+ *       <AvatarImage src={m.avatarUrl} alt={m.name} />
+ *       <AvatarFallback>{initials(m.name)}</AvatarFallback>
+ *     </Avatar>
+ *   ))}
+ * </AvatarGroup>
+ * ```
+ *
+ * Purely presentational, and deliberately **compositional**: the group never
+ * reads a `{ name, src }` shape, it wraps whatever you put in it — an `Avatar`,
+ * one inside a `Tooltip`, a `Skeleton` while the list loads. It only owns what
+ * a caller can't get right by hand: the overlap, the ring that separates two
+ * faces, the paint order, and the `+N`.
+ */
+function AvatarGroup({
+  className,
+  children,
+  size = "default",
+  max,
+  total,
+  spacing = "default",
+  ringClassName = "ring-background",
+  revealOnHover = true,
+  onOverflowClick,
+  overflowLabel = "Voir tout",
+  ...props
+}: AvatarGroupProps) {
+  const items = Children.toArray(children)
+  const limit = max != null && max > 0 ? max : items.length
+
+  let shown = items.slice(0, limit)
+  // People the caller knows about but didn't render at all.
+  const unrendered = Math.max(0, (total ?? items.length) - items.length)
+  let overflow = items.length - shown.length + unrendered
+
+  // A single hidden child costs exactly the room a "+1" would take, and says
+  // strictly less. Draw the face instead.
+  if (overflow === 1 && unrendered === 0) {
+    shown = items
+    overflow = 0
+  }
+
+  const item = (node: ReactNode, index: number) => (
+    <span
+      key={index}
+      data-slot="avatar-group-item"
+      className={cn(
+        "relative inline-flex rounded-full",
+        RING[size],
+        ringClassName,
+        index > 0 && OVERLAP[size][spacing],
+        revealOnHover && "transition-transform duration-150 hover:z-10 hover:-translate-y-0.5"
+      )}
+    >
+      {node}
+    </span>
+  )
+
+  const counter = `+${overflow}`
+  const counterClass = cn(
+    avatarVariants({ size }),
+    "items-center justify-center font-medium text-muted-foreground"
+  )
+
+  return (
+    <AvatarGroupSizeContext.Provider value={size}>
+      <div data-slot="avatar-group" className={cn("flex items-center", className)} {...props}>
+        {shown.map(item)}
+        {overflow > 0 &&
+          item(
+            onOverflowClick ? (
+              <button
+                type="button"
+                data-slot="avatar-group-overflow"
+                aria-label={overflowLabel}
+                onClick={onOverflowClick}
+                className={cn(
+                  counterClass,
+                  "cursor-pointer transition-colors hover:bg-primary/15 hover:text-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+                )}
+              >
+                {counter}
+              </button>
+            ) : (
+              <span data-slot="avatar-group-overflow" className={counterClass}>
+                {counter}
+              </span>
+            ),
+            shown.length
+          )}
+      </div>
+    </AvatarGroupSizeContext.Provider>
+  )
+}
+
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup }

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

@@ -23,7 +23,11 @@ export { RadioGroup, RadioGroupItem } from "./components/radio-group"
 export { Separator } from "./components/separator"
 export { Skeleton } from "./components/skeleton"
 export { Spinner, spinnerVariants } from "./components/spinner"
-export { Avatar, AvatarImage, AvatarFallback } from "./components/avatar"
+// Avatar + the stack of overlapping avatars (`AvatarGroup`) — compositional:
+// the group wraps whatever you put in it and owns the overlap, the ring, the
+// paint order and the `+N`.
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from "./components/avatar"
+export type { AvatarProps, AvatarSize, AvatarGroupProps, AvatarGroupSpacing } from "./components/avatar"
 
 // xterm.js surface — theme + fit-on-resize, transport-agnostic (feed it via
 // the write/writeln ref handle).
@@ -66,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"