@emara/ui 1.1.0

package/components/ui/combobox.tsx

@@ -0,0 +1,874 @@
+"use client";
+
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import {
+  RiArrowDownSLine,
+  RiCheckLine,
+  RiCloseLine,
+  RiLoader2Line,
+  RiSearchLine,
+} from "@remixicon/react";
+import { Command as CommandPrimitive, useCommandState } from "cmdk";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-2-components.md §5.
+// Modes: single (default) + multiple. + creatable + async loadOptions.
+
+/**
+ * Shape of options returned by `loadOptions`. Consumers can extend with extra
+ * fields — only `value` is required.
+ */
+export type ComboboxOption = {
+  value: string;
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+  icon?: React.ReactNode;
+  keywords?: string[];
+  disabled?: boolean;
+};
+
+// ----------------------------------------------------------------------------
+// Context — Combobox root tracks value(s), search, open, mode flag.
+// Discriminated union so children can branch on `mode` without ambiguity.
+// ----------------------------------------------------------------------------
+
+type ComboboxBaseContext = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  search: string;
+  setSearch: (v: string) => void;
+  disabled: boolean;
+  invalid: boolean;
+  /** Combined loading: explicit `loading` prop OR an in-flight `loadOptions` fetch. */
+  loading: boolean;
+  contentId: string;
+  creatable: boolean;
+  onCreate: ((query: string) => void) | undefined;
+  /** Options fetched by the latest `loadOptions(search)` call. Empty array if
+   *  `loadOptions` is not provided. */
+  loadedOptions: ComboboxOption[];
+  /** True when `loadOptions` is wired — children should not also render
+   *  static items via `<ComboboxList>` unless they want to mix. */
+  hasLoadOptions: boolean;
+  /** Optional grouping function applied to loaded options. */
+  groupBy: ((option: ComboboxOption) => string) | undefined;
+};
+
+type ComboboxSingleContext = ComboboxBaseContext & {
+  mode: "single";
+  value: string;
+  setValue: (v: string) => void;
+};
+
+type ComboboxMultipleContext = ComboboxBaseContext & {
+  mode: "multiple";
+  values: string[];
+  toggleValue: (v: string) => void;
+  setValues: (vs: string[]) => void;
+  maxSelected: number | undefined;
+};
+
+type ComboboxContextValue = ComboboxSingleContext | ComboboxMultipleContext;
+
+const ComboboxContext = createContext<ComboboxContextValue | null>(null);
+function useCombobox(): ComboboxContextValue {
+  const ctx = useContext(ComboboxContext);
+  if (!ctx) throw new Error("Combobox sub-component must be used inside <Combobox>.");
+  return ctx;
+}
+
+// ----------------------------------------------------------------------------
+// Combobox root
+// ----------------------------------------------------------------------------
+
+type ComboboxRootCommonProps = {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  required?: boolean;
+  name?: string;
+  invalid?: boolean;
+  loading?: boolean;
+  /** Allow creating a new option from the current search query. When set,
+   *  a "+ Create '{query}'" row is appended below filtered items. The
+   *  consumer is expected to add the new option to their data source +
+   *  selection state in `onCreate`. */
+  creatable?: boolean;
+  /** Fired when the user picks the "+ Create" row. Receives the current
+   *  search string; the component does not modify selection state itself
+   *  in response — that's the consumer's responsibility. */
+  onCreate?: (query: string) => void;
+  /**
+   * Async option fetcher. When provided, the component intercepts the
+   *  search input: it debounces ~200ms, calls `loadOptions(query)`, and
+   *  renders the returned options as items automatically (no need to
+   *  write `<ComboboxItem>` children). Stale responses are dropped via
+   *  a request-id guard so out-of-order fetches don't flicker the UI.
+   *  While a fetch is in flight, `loading` is `true` and cmdk's internal
+   *  filter is disabled.
+   */
+  loadOptions?: (query: string) => Promise<ComboboxOption[]>;
+  /** Debounce window for `loadOptions` in milliseconds. Default 200ms. */
+  loadOptionsDebounceMs?: number;
+  /**
+   * Auto-grouping for `loadOptions`-rendered items. When provided, the
+   * loaded options are partitioned by the function's return value and
+   * each group is rendered inside a `<ComboboxGroup heading>`. Groups
+   * preserve insertion order — sort your options array if you want a
+   * different order. No effect when `loadOptions` is not wired.
+   */
+  groupBy?: (option: ComboboxOption) => string;
+  children: React.ReactNode;
+};
+
+type ComboboxSingleProps = ComboboxRootCommonProps & {
+  multiple?: false;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+};
+
+type ComboboxMultipleProps = ComboboxRootCommonProps & {
+  multiple: true;
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?: (values: string[]) => void;
+  /** Cap on number of items that can be selected at once. Once reached,
+   *  additional items are disabled (can still deselect existing ones). */
+  maxSelected?: number;
+};
+
+type ComboboxRootProps = ComboboxSingleProps | ComboboxMultipleProps;
+
+const Combobox = function Combobox(props: ComboboxRootProps) {
+  const {
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    disabled = false,
+    invalid = false,
+    loading = false,
+    creatable = false,
+    onCreate,
+    loadOptions,
+    loadOptionsDebounceMs = 200,
+    groupBy,
+    children,
+  } = props;
+  const multiple = props.multiple === true;
+
+  const isOpenControlled = openProp !== undefined;
+  const [openInternal, setOpenInternal] = useState(defaultOpen);
+  const open = isOpenControlled ? openProp : openInternal;
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isOpenControlled) setOpenInternal(next);
+      onOpenChange?.(next);
+    },
+    [isOpenControlled, onOpenChange],
+  );
+
+  // ---- Single-mode value state ----
+  const singleValueProp = !multiple ? (props as ComboboxSingleProps).value : undefined;
+  const singleDefault = !multiple ? ((props as ComboboxSingleProps).defaultValue ?? "") : "";
+  const isSingleControlled = singleValueProp !== undefined;
+  const [singleInternal, setSingleInternal] = useState(singleDefault);
+  const singleValue = isSingleControlled ? (singleValueProp ?? "") : singleInternal;
+  const setSingleValue = useCallback(
+    (next: string) => {
+      if (!isSingleControlled) setSingleInternal(next);
+      if (!multiple) (props as ComboboxSingleProps).onValueChange?.(next);
+    },
+    // We deliberately do not depend on `props` (would re-create every render).
+    // Single-mode handlers don't change identity across renders in practice.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [isSingleControlled, multiple],
+  );
+
+  // ---- Multi-mode value state ----
+  const multiValueProp = multiple ? (props as ComboboxMultipleProps).value : undefined;
+  const multiDefault = multiple ? ((props as ComboboxMultipleProps).defaultValue ?? []) : [];
+  const isMultiControlled = multiValueProp !== undefined;
+  const [multiInternal, setMultiInternal] = useState<string[]>(multiDefault);
+  const multiValues = isMultiControlled ? (multiValueProp ?? []) : multiInternal;
+  const setValues = useCallback(
+    (next: string[]) => {
+      if (!isMultiControlled) setMultiInternal(next);
+      if (multiple) (props as ComboboxMultipleProps).onValueChange?.(next);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [isMultiControlled, multiple],
+  );
+  const toggleValue = useCallback(
+    (v: string) => {
+      const current = isMultiControlled ? (multiValueProp ?? []) : multiInternal;
+      const next = current.includes(v) ? current.filter((x) => x !== v) : [...current, v];
+      setValues(next);
+    },
+    [isMultiControlled, multiValueProp, multiInternal, setValues],
+  );
+
+  const [search, setSearch] = useState("");
+  const contentId = useId();
+
+  // ---- Async options state (loadOptions) ----
+  const [loadedOptions, setLoadedOptions] = useState<ComboboxOption[]>([]);
+  const [loadingInternal, setLoadingInternal] = useState(false);
+  const requestIdRef = useRef(0);
+  useEffect(() => {
+    if (!loadOptions) return;
+    const myRequestId = ++requestIdRef.current;
+    setLoadingInternal(true);
+    const timeoutId = window.setTimeout(() => {
+      Promise.resolve(loadOptions(search))
+        .then((opts) => {
+          // Drop stale response — a newer request has been issued.
+          if (myRequestId !== requestIdRef.current) return;
+          setLoadedOptions(opts);
+        })
+        .catch(() => {
+          // Swallow — consumer's fetcher is responsible for surfacing errors.
+          if (myRequestId !== requestIdRef.current) return;
+          setLoadedOptions([]);
+        })
+        .finally(() => {
+          if (myRequestId === requestIdRef.current) setLoadingInternal(false);
+        });
+    }, loadOptionsDebounceMs);
+    return () => window.clearTimeout(timeoutId);
+  }, [search, loadOptions, loadOptionsDebounceMs]);
+  const effectiveLoading = loading || (Boolean(loadOptions) && loadingInternal);
+
+  const ctx: ComboboxContextValue = useMemo(() => {
+    const base: ComboboxBaseContext = {
+      open,
+      setOpen,
+      search,
+      setSearch,
+      disabled,
+      invalid,
+      loading: effectiveLoading,
+      contentId,
+      creatable,
+      onCreate,
+      loadedOptions,
+      hasLoadOptions: Boolean(loadOptions),
+      groupBy,
+    };
+    if (multiple) {
+      return {
+        ...base,
+        mode: "multiple",
+        values: multiValues,
+        toggleValue,
+        setValues,
+        maxSelected: (props as ComboboxMultipleProps).maxSelected,
+      };
+    }
+    return { ...base, mode: "single", value: singleValue, setValue: setSingleValue };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    multiple,
+    open,
+    setOpen,
+    search,
+    disabled,
+    invalid,
+    effectiveLoading,
+    contentId,
+    creatable,
+    onCreate,
+    loadOptions,
+    loadedOptions,
+    groupBy,
+    singleValue,
+    setSingleValue,
+    multiValues,
+    toggleValue,
+    setValues,
+  ]);
+
+  return (
+    <ComboboxContext.Provider value={ctx}>
+      <PopoverPrimitive.Root open={open} onOpenChange={setOpen}>
+        {children}
+      </PopoverPrimitive.Root>
+    </ComboboxContext.Provider>
+  );
+};
+
+// ----------------------------------------------------------------------------
+// ComboboxTrigger
+// ----------------------------------------------------------------------------
+
+const triggerVariants = cva(
+  [
+    "flex items-center justify-between w-full gap-2",
+    "rounded-md border border-input bg-background text-foreground",
+    "transition-colors",
+    "focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+    "[&>span:first-child]:line-clamp-1 [&>span:first-child]:text-start",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        xs: "h-7 ps-2.5 pe-2 text-xs",
+        sm: "h-8 ps-3 pe-2 text-xs",
+        md: "h-9 ps-3 pe-2 text-sm",
+        lg: "h-10 ps-3.5 pe-2.5 text-base",
+        xl: "h-12 ps-4 pe-3 text-base",
+      },
+      invalid: {
+        true: "border-destructive focus-visible:ring-destructive",
+        false: "",
+      },
+    },
+    defaultVariants: { size: "md", invalid: false },
+  },
+);
+
+type ComboboxTriggerProps = Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "children"
+> &
+  VariantProps<typeof triggerVariants> & {
+    placeholder?: string;
+    clearable?: boolean;
+    onClear?: () => void;
+    /** Map a value to a display label. Used for pill text in multiple mode,
+     *  and as the trigger label in single mode when no `children` is given. */
+    getOptionLabel?: (value: string) => React.ReactNode;
+    /** Multi-mode only: max pills to render in the trigger before collapsing
+     *  the remainder into a "+N more" badge. Defaults to 3. */
+    maxVisiblePills?: number;
+    /**
+     * Single mode: what to render when the Combobox has a value. Consumers
+     * compute this from their own options array (matching shadcn's recipe).
+     * Ignored in multiple mode — pills are rendered instead.
+     */
+    children?: React.ReactNode;
+  };
+
+const ComboboxTrigger = forwardRef<HTMLButtonElement, ComboboxTriggerProps>(
+  function ComboboxTrigger(
+    {
+      className,
+      size,
+      invalid: invalidProp,
+      placeholder,
+      clearable = false,
+      onClear,
+      getOptionLabel,
+      maxVisiblePills = 3,
+      children,
+      ...props
+    },
+    ref,
+  ) {
+    const ctx = useCombobox();
+    const invalid = invalidProp ?? ctx.invalid;
+    const isMulti = ctx.mode === "multiple";
+    const hasSelection = isMulti ? ctx.values.length > 0 : Boolean(ctx.value);
+    const showClear = clearable && !ctx.disabled && !ctx.loading && hasSelection;
+
+    // ---- Multi-mode pill rendering ----
+    const visiblePills = isMulti ? ctx.values.slice(0, maxVisiblePills) : [];
+    const overflowCount = isMulti ? Math.max(0, ctx.values.length - maxVisiblePills) : 0;
+    const labelFor = (v: string): React.ReactNode => (getOptionLabel ? getOptionLabel(v) : v);
+
+    // ---- Single-mode display fallback ----
+    const singleDisplay =
+      !isMulti && ctx.value
+        ? (children ?? (getOptionLabel ? getOptionLabel(ctx.value) : ctx.value))
+        : (placeholder ?? "Select…");
+
+    // WAI-ARIA accessible name fallback.
+    const consumerLabelled =
+      props["aria-label"] !== undefined || props["aria-labelledby"] !== undefined;
+    const ariaLabelFallback = consumerLabelled
+      ? undefined
+      : isMulti
+        ? hasSelection
+          ? `${ctx.values.length} selected`
+          : (placeholder ?? "Select…")
+        : typeof singleDisplay === "string"
+          ? singleDisplay
+          : (placeholder ?? "Select…");
+
+    const handleClear = (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (ctx.mode === "multiple") ctx.setValues([]);
+      else ctx.setValue("");
+      onClear?.();
+    };
+
+    return (
+      <PopoverPrimitive.Trigger asChild>
+        <button
+          ref={ref}
+          type="button"
+          role="combobox"
+          aria-expanded={ctx.open}
+          aria-controls={ctx.open ? ctx.contentId : undefined}
+          aria-invalid={invalid || undefined}
+          aria-label={ariaLabelFallback}
+          disabled={ctx.disabled}
+          className={cn(
+            triggerVariants({ size, invalid }),
+            // In multi mode the trigger may grow to fit pills; relax height.
+            isMulti && hasSelection && "h-auto min-h-9 flex-wrap py-1",
+            className,
+          )}
+          {...props}
+        >
+          {isMulti ? (
+            <span className="flex flex-1 flex-wrap items-center gap-1">
+              {!hasSelection ? (
+                <span className="text-muted-foreground">{placeholder ?? "Select…"}</span>
+              ) : (
+                <>
+                  {visiblePills.map((v) => (
+                    <span
+                      key={v}
+                      className="bg-secondary text-secondary-foreground inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs"
+                    >
+                      <span>{labelFor(v)}</span>
+                      {!ctx.disabled ? (
+                        <button
+                          type="button"
+                          aria-label={`Remove ${typeof labelFor(v) === "string" ? labelFor(v) : v}`}
+                          onClick={(e) => {
+                            e.preventDefault();
+                            e.stopPropagation();
+                            if (ctx.mode === "multiple") ctx.toggleValue(v);
+                          }}
+                          className="focus-visible:ring-ring hover:text-foreground inline-flex items-center justify-center rounded-sm focus-visible:ring-2 focus-visible:outline-none"
+                        >
+                          <RiCloseLine className="size-3" />
+                        </button>
+                      ) : null}
+                    </span>
+                  ))}
+                  {overflowCount > 0 ? (
+                    <span className="bg-muted text-muted-foreground rounded px-1.5 py-0.5 text-xs">
+                      +{overflowCount} more
+                    </span>
+                  ) : null}
+                </>
+              )}
+            </span>
+          ) : (
+            <span className={cn(!hasSelection && "text-muted-foreground")}>{singleDisplay}</span>
+          )}
+          <span className="text-muted-foreground ms-auto inline-flex shrink-0 items-center gap-1 [&_svg]:size-4 [&_svg]:shrink-0">
+            {showClear ? (
+              <button
+                type="button"
+                aria-label="Clear"
+                onClick={handleClear}
+                className={cn(
+                  "inline-flex items-center justify-center rounded p-0.5",
+                  "hover:text-foreground",
+                  "focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none",
+                )}
+              >
+                <RiCloseLine />
+              </button>
+            ) : null}
+            {ctx.loading ? <RiLoader2Line className="size-4 animate-spin" /> : <RiArrowDownSLine />}
+          </span>
+        </button>
+      </PopoverPrimitive.Trigger>
+    );
+  },
+);
+ComboboxTrigger.displayName = "ComboboxTrigger";
+
+// ----------------------------------------------------------------------------
+// ComboboxContent — Popover content hosting the cmdk Command palette.
+// ----------------------------------------------------------------------------
+
+/**
+ * Screen-reader-only result counter. Mounted inside the Command tree so
+ * `useCommandState` can read cmdk's filtered count. Only renders while the
+ * user is actively searching — otherwise it would announce on every open.
+ * Spec: docs/emara-ui-phase-2-components.md §5 Accessibility ("Live region
+ * announces result count").
+ */
+/**
+ * Renders options fetched by `loadOptions` as ComboboxItems automatically.
+ * Mounted inside ComboboxContent only when the root has loadOptions wired.
+ * Consumers can still mix static items via a ComboboxList sibling — those
+ * are rendered alongside (with cmdk filtering disabled while loading so
+ * the async items never get hidden by the search input).
+ */
+function ComboboxAsyncOptions(): React.ReactElement | null {
+  const ctx = useCombobox();
+  if (!ctx.hasLoadOptions) return null;
+
+  const renderItem = (opt: ComboboxOption) => (
+    <ComboboxItem
+      key={opt.value}
+      value={opt.value}
+      {...(opt.description !== undefined && { description: opt.description })}
+      {...(opt.icon !== undefined && { icon: opt.icon })}
+      {...(opt.keywords !== undefined && { keywords: opt.keywords })}
+      {...(opt.disabled !== undefined && { disabled: opt.disabled })}
+    >
+      {opt.label ?? opt.value}
+    </ComboboxItem>
+  );
+
+  if (!ctx.groupBy) {
+    return (
+      <CommandPrimitive.List className="max-h-64 overflow-y-auto p-1">
+        {ctx.loadedOptions.map(renderItem)}
+      </CommandPrimitive.List>
+    );
+  }
+
+  // Partition into groups preserving first-seen insertion order.
+  const groups = new Map<string, ComboboxOption[]>();
+  for (const opt of ctx.loadedOptions) {
+    const key = ctx.groupBy(opt);
+    const arr = groups.get(key);
+    if (arr) arr.push(opt);
+    else groups.set(key, [opt]);
+  }
+
+  return (
+    <CommandPrimitive.List className="max-h-64 overflow-y-auto p-1">
+      {Array.from(groups.entries()).map(([heading, opts]) => (
+        <ComboboxGroup key={heading} heading={heading}>
+          {opts.map(renderItem)}
+        </ComboboxGroup>
+      ))}
+    </CommandPrimitive.List>
+  );
+}
+
+function ComboboxResultCount(): React.ReactElement | null {
+  const count = useCommandState((s) => s.filtered.count) ?? 0;
+  const search = useCommandState((s) => s.search) ?? "";
+  if (!search) return null;
+  const label = count === 0 ? "No results" : count === 1 ? "1 result" : `${count} results`;
+  return (
+    <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+      {label}
+    </div>
+  );
+}
+
+/**
+ * Renders a "+ Create '{search}'" row when the consumer has set `creatable`
+ * on the root. The row's cmdk `value` is the search string itself so it
+ * always survives cmdk's filter while the user is typing.
+ *
+ * On select: calls the consumer's `onCreate(search)` and clears the search.
+ * In single mode, the popover closes (matching ComboboxItem). In multi
+ * mode it stays open so the user can keep adding.
+ *
+ * The component does not mutate selection state itself — adding the new
+ * option to the data source AND the value array is the consumer's job
+ * inside `onCreate`. See Storybook for the canonical pattern.
+ */
+function ComboboxCreatable(): React.ReactElement | null {
+  const ctx = useCombobox();
+  const search = useCommandState((s) => s.search) ?? "";
+  if (!ctx.creatable || !search.trim()) return null;
+  return (
+    <CommandPrimitive.Item
+      // Use a sentinel value prefixed to avoid clashes with consumer options.
+      value={`__create__::${search}`}
+      // Always match — searches change as user types but cmdk filters by
+      // value vs. search. Forcing this item to match the current search is
+      // the cleanest way to keep it visible.
+      keywords={[search]}
+      onSelect={() => {
+        ctx.onCreate?.(search);
+        ctx.setSearch("");
+        if (ctx.mode === "single") ctx.setOpen(false);
+      }}
+      className={cn(
+        "relative flex w-full cursor-pointer items-center gap-2 rounded-sm py-1.5 ps-8 pe-2 text-sm outline-none select-none",
+        "transition-colors",
+        "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground",
+        "border-border/60 mt-1 border-t pt-2",
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className="absolute start-2 inline-flex h-4 w-4 items-center justify-center"
+      >
+        +
+      </span>
+      <span>
+        Create <span className="font-medium">&quot;{search}&quot;</span>
+      </span>
+    </CommandPrimitive.Item>
+  );
+}
+
+type ComboboxContentProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> & {
+  emptyMessage?: React.ReactNode;
+};
+
+const ComboboxContent = forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Content>,
+  ComboboxContentProps
+>(function ComboboxContent(
+  { className, align = "start", sideOffset = 4, emptyMessage, children, ...props },
+  ref,
+) {
+  const ctx = useCombobox();
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        ref={ref}
+        id={ctx.contentId}
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          "border-border bg-popover text-popover-foreground z-popover w-(--radix-popover-trigger-width) overflow-hidden rounded-md border shadow-md outline-none",
+          "data-[state=open]:animate-[scale-in_var(--duration-fast)_var(--ease-out)]",
+          "data-[state=closed]:animate-[scale-out_var(--duration-fast)_var(--ease-in)]",
+          className,
+        )}
+        {...props}
+      >
+        <CommandPrimitive shouldFilter={!ctx.loading && !ctx.hasLoadOptions}>
+          {children}
+          <ComboboxAsyncOptions />
+          {emptyMessage !== undefined ? (
+            <CommandPrimitive.Empty className="text-muted-foreground px-3 py-6 text-center text-sm">
+              {emptyMessage}
+            </CommandPrimitive.Empty>
+          ) : null}
+          <ComboboxCreatable />
+          <ComboboxResultCount />
+        </CommandPrimitive>
+      </PopoverPrimitive.Content>
+    </PopoverPrimitive.Portal>
+  );
+});
+ComboboxContent.displayName = "ComboboxContent";
+
+// ----------------------------------------------------------------------------
+// ComboboxInput — cmdk's input, wired to the root's search state.
+// ----------------------------------------------------------------------------
+
+const ComboboxInput = forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Input>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
+>(function ComboboxInput({ className, placeholder = "Search…", ...props }, ref) {
+  const ctx = useCombobox();
+  return (
+    <div className="border-border flex items-center gap-2 border-b ps-3 pe-2">
+      <RiSearchLine className="text-muted-foreground size-4 shrink-0" aria-hidden="true" />
+      <CommandPrimitive.Input
+        ref={ref}
+        value={ctx.search}
+        onValueChange={ctx.setSearch}
+        placeholder={placeholder}
+        dir="auto"
+        className={cn(
+          "text-foreground placeholder:text-muted-foreground h-9 flex-1 bg-transparent text-sm outline-none",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          className,
+        )}
+        {...props}
+      />
+    </div>
+  );
+});
+ComboboxInput.displayName = "ComboboxInput";
+
+// ----------------------------------------------------------------------------
+// ComboboxEmpty
+// ----------------------------------------------------------------------------
+
+const ComboboxEmpty = forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Empty>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Empty>
+>(function ComboboxEmpty({ className, ...props }, ref) {
+  return (
+    <CommandPrimitive.Empty
+      ref={ref}
+      className={cn("text-muted-foreground px-3 py-6 text-center text-sm", className)}
+      {...props}
+    />
+  );
+});
+ComboboxEmpty.displayName = "ComboboxEmpty";
+
+// ----------------------------------------------------------------------------
+// ComboboxList — the scrollable list region. Required by cmdk.
+// ----------------------------------------------------------------------------
+
+const ComboboxList = forwardRef<
+  React.ElementRef<typeof CommandPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
+>(function ComboboxList({ className, ...props }, ref) {
+  return (
+    <CommandPrimitive.List
+      ref={ref}
+      className={cn("max-h-64 overflow-y-auto p-1", className)}
+      {...props}
+    />
+  );
+});
+ComboboxList.displayName = "ComboboxList";
+
+// ----------------------------------------------------------------------------
+// ComboboxGroup / ComboboxLabel
+// ----------------------------------------------------------------------------
+
+const ComboboxGroup = forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Group>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Group>
+>(function ComboboxGroup({ className, ...props }, ref) {
+  return (
+    <CommandPrimitive.Group
+      ref={ref}
+      className={cn(
+        "text-foreground overflow-hidden",
+        "[&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-semibold [&_[cmdk-group-heading]]:tracking-wide [&_[cmdk-group-heading]]:uppercase",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+ComboboxGroup.displayName = "ComboboxGroup";
+
+// ----------------------------------------------------------------------------
+// ComboboxItem
+// ----------------------------------------------------------------------------
+
+type ComboboxItemProps = Omit<
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item>,
+  "onSelect" | "value"
+> & {
+  value: string;
+  description?: React.ReactNode;
+  icon?: React.ReactNode;
+  /** Extra search terms the item matches against, in addition to `value`
+   *  and rendered children. Example: a "New York" item with
+   *  `keywords={["nyc", "ny"]}` will match either abbreviation. */
+  keywords?: string[];
+};
+
+const ComboboxItem = forwardRef<React.ElementRef<typeof CommandPrimitive.Item>, ComboboxItemProps>(
+  function ComboboxItem(
+    { className, value, description, icon, disabled, children, ...props },
+    ref,
+  ) {
+    const ctx = useCombobox();
+    const selected = ctx.mode === "multiple" ? ctx.values.includes(value) : ctx.value === value;
+    // Multi mode: when at maxSelected, items not already selected are gated.
+    const blockedByMax =
+      ctx.mode === "multiple" &&
+      ctx.maxSelected !== undefined &&
+      !selected &&
+      ctx.values.length >= ctx.maxSelected;
+    const effectiveDisabled = disabled || blockedByMax;
+
+    return (
+      <CommandPrimitive.Item
+        ref={ref}
+        value={value}
+        disabled={effectiveDisabled}
+        onSelect={() => {
+          if (effectiveDisabled) return;
+          if (ctx.mode === "multiple") {
+            ctx.toggleValue(value);
+            // Keep popover open + clear search after a successful toggle so
+            // the user can pick another option immediately.
+            ctx.setSearch("");
+          } else {
+            ctx.setValue(value);
+            ctx.setSearch("");
+            ctx.setOpen(false);
+          }
+        }}
+        className={cn(
+          "relative flex w-full cursor-pointer items-start gap-2 rounded-sm py-1.5 ps-8 pe-2 text-sm outline-none select-none",
+          "transition-colors",
+          "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground",
+          "data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50",
+          className,
+        )}
+        aria-selected={selected || undefined}
+        {...props}
+      >
+        <span className="absolute start-2 inline-flex h-4 w-4 items-center justify-center">
+          {selected ? <RiCheckLine className="size-4" /> : null}
+        </span>
+        <span className="flex flex-1 flex-col gap-0.5 leading-none">
+          <span className="inline-flex items-center gap-2">
+            {icon ? (
+              <span
+                aria-hidden="true"
+                className="text-muted-foreground inline-flex shrink-0 [&_svg]:size-4 [&_svg]:shrink-0"
+              >
+                {icon}
+              </span>
+            ) : null}
+            <span>{children ?? value}</span>
+          </span>
+          {description ? (
+            <span className="text-muted-foreground text-xs">{description}</span>
+          ) : null}
+        </span>
+      </CommandPrimitive.Item>
+    );
+  },
+);
+ComboboxItem.displayName = "ComboboxItem";
+
+// ----------------------------------------------------------------------------
+// ComboboxSeparator
+// ----------------------------------------------------------------------------
+
+const ComboboxSeparator = forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Separator>
+>(function ComboboxSeparator({ className, ...props }, ref) {
+  return (
+    <CommandPrimitive.Separator
+      ref={ref}
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+});
+ComboboxSeparator.displayName = "ComboboxSeparator";
+
+export {
+  Combobox,
+  ComboboxTrigger,
+  ComboboxContent,
+  ComboboxInput,
+  ComboboxList,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxItem,
+  ComboboxSeparator,
+};
+export type { ComboboxRootProps, ComboboxTriggerProps, ComboboxContentProps, ComboboxItemProps };