@elabs-ai/components-ui 4.0.0

package/src/components/combobox/combobox.test.tsx

@@ -0,0 +1,246 @@
+import { createRef } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Combobox } from "./combobox";
+describe("Combobox", () => {
+  it("renders the placeholder on the trigger", () => {
+    render(<Combobox options={[{ label: "A", value: "a" }]} placeholder="Pick one" />);
+    // The trigger uses role="combobox"; that ARIA role does not take its
+    // accessible name from text content, so assert the visible placeholder text.
+    expect(screen.getByText("Pick one")).toBeInTheDocument();
+  });
+
+  // #343 — disabled prop
+  it("disables the trigger and never opens the popover when disabled", async () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(
+      <Combobox ref={ref} disabled options={[{ label: "A", value: "a" }]} placeholder="Pick one" />,
+    );
+    const trigger = screen.getByRole("combobox");
+    expect(trigger).toBeDisabled();
+    expect(ref.current).toBe(trigger);
+
+    await userEvent.click(trigger);
+    expect(screen.queryByPlaceholderText("Search…")).not.toBeInTheDocument();
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("is excluded from tab order when disabled (native disabled semantics)", () => {
+    render(<Combobox disabled options={[{ label: "A", value: "a" }]} />);
+    const trigger = screen.getByRole("combobox");
+    // A native `disabled` button is always excluded from the tab order —
+    // no `tabIndex` gymnastics needed.
+    expect(trigger).toBeDisabled();
+  });
+
+  // #347 — accessible-name passthrough
+  it("names the trigger via aria-label, distinct from the selected value", () => {
+    render(
+      <Combobox
+        aria-label="Session switcher"
+        options={[{ label: "Alpha", value: "a" }]}
+        value="a"
+      />,
+    );
+    const trigger = screen.getByRole("combobox", { name: "Session switcher" });
+    // The value is still visible as the control's current state.
+    expect(trigger).toHaveTextContent("Alpha");
+  });
+
+  it("spreads triggerProps onto the trigger without clobbering role/aria-expanded", () => {
+    render(
+      <Combobox
+        options={[{ label: "A", value: "a" }]}
+        triggerProps={{ "data-testid": "env-combobox" }}
+      />,
+    );
+    const trigger = screen.getByTestId("env-combobox");
+    expect(trigger).toHaveAttribute("role", "combobox");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("shows the selected custom value on the trigger even though it isn't in options", async () => {
+    render(
+      <Combobox allowCustomValue options={[{ label: "Alpha", value: "a" }]} value="Custom Value" />,
+    );
+    expect(screen.getByRole("combobox")).toHaveTextContent("Custom Value");
+  });
+});
+
+// #359 — allowCustomValue. A nested describe because these tests TYPE into the
+// cmdk-backed search input, which internally calls `Element.scrollIntoView` to
+// keep the auto-selected item visible — jsdom doesn't implement it, and the
+// project's global vitest setup deliberately provides no stub (see
+// packages/ui/vitest.setup.ts), so third-party libraries that don't
+// feature-detect need a local, scoped stub (same pattern as tree.test.tsx).
+describe("Combobox allowCustomValue", () => {
+  let originalScrollIntoView: typeof Element.prototype.scrollIntoView;
+
+  beforeEach(() => {
+    originalScrollIntoView = Element.prototype.scrollIntoView;
+    Element.prototype.scrollIntoView = vi.fn();
+  });
+
+  afterEach(() => {
+    Element.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  it("accepts a typed value not present in options when allowCustomValue is set (Enter)", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        allowCustomValue
+        options={[{ label: "Alpha", value: "a" }]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    await userEvent.type(input, "Custom Value{Enter}");
+    expect(onValueChange).toHaveBeenCalledWith("Custom Value");
+  });
+
+  it("accepts a typed value not present in options when allowCustomValue is set (click)", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        allowCustomValue
+        options={[{ label: "Alpha", value: "a" }]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    await userEvent.type(input, "Canary");
+    const customItem = await screen.findByRole("option", { name: /use.*canary/i });
+    await userEvent.click(customItem);
+    expect(onValueChange).toHaveBeenCalledWith("Canary");
+  });
+
+  it("does NOT emit an unlisted value when allowCustomValue is unset (regression guard)", async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={[{ label: "Alpha", value: "a" }]} onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    await userEvent.type(input, "Custom Value{Enter}");
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(screen.queryByRole("option", { name: /use/i })).not.toBeInTheDocument();
+  });
+
+  it("still filters real suggestions while allowCustomValue is set", async () => {
+    render(
+      <Combobox
+        allowCustomValue
+        options={[
+          { label: "Alpha", value: "a" },
+          { label: "Beta", value: "b" },
+        ]}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    await userEvent.type(input, "Alpha");
+    expect(await screen.findByRole("option", { name: "Alpha" })).toBeInTheDocument();
+    expect(screen.queryByRole("option", { name: "Beta" })).not.toBeInTheDocument();
+    // An exact match to an existing option must not also offer a redundant
+    // "Use…" custom-value entry.
+    expect(screen.queryByRole("option", { name: /use/i })).not.toBeInTheDocument();
+  });
+
+  it("keyboard: ArrowDown moves the highlight off the auto-selected top match, and Enter accepts it", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        allowCustomValue
+        options={[
+          { label: "Alpha", value: "alpha" },
+          { label: "Alphabet", value: "alphabet" },
+        ]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    // "Alpha" is an EXACT match (case-insensitive) for the typed text, so no
+    // custom-value item is offered — only the two real options are ranked.
+    await userEvent.type(input, "Alpha");
+    await screen.findByRole("option", { name: "Alpha" });
+    await screen.findByRole("option", { name: "Alphabet" });
+    expect(screen.queryByRole("option", { name: /use/i })).not.toBeInTheDocument();
+    // The exact match ("Alpha") auto-ranks first/highlighted; one ArrowDown
+    // moves the highlight to "Alphabet", and Enter accepts THAT option — not
+    // whatever was auto-selected by default.
+    await userEvent.keyboard("{ArrowDown}{Enter}");
+    expect(onValueChange).toHaveBeenCalledWith("alphabet");
+  });
+
+  // Regression lock: cmdk re-sorts items by score and auto-highlights the top
+  // one. Giving the synthetic "Use …" row the SEARCH TEXT as its `value` made
+  // it score a perfect 1, so it outranked every real PARTIAL match and stole
+  // the highlight — typing "Alp" and pressing Enter emitted "Alp" instead of
+  // selecting "Alpha". The row now carries a sentinel value scored just above
+  // zero, so it always renders but always sorts last.
+  it("ranks the custom-value row LAST, so Enter still selects a real partial match", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        allowCustomValue
+        options={[
+          { label: "Alpha", value: "alpha" },
+          { label: "Beta", value: "beta" },
+        ]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    // A PARTIAL match — "Alpha" is offered AND the custom row is offered.
+    await userEvent.type(input, "Alp");
+    const options = screen.getAllByRole("option");
+    expect(options.map((o) => o.textContent)).toEqual(["Alpha", 'Use "Alp"']);
+    // The real suggestion — not the custom row — is the auto-highlighted one.
+    expect(options[0]).toHaveAttribute("aria-selected", "true");
+    expect(options[1]).toHaveAttribute("aria-selected", "false");
+    await userEvent.keyboard("{Enter}");
+    expect(onValueChange).toHaveBeenCalledWith("alpha");
+    expect(onValueChange).not.toHaveBeenCalledWith("Alp");
+  });
+
+  it("still accepts the custom value from a partial match via ArrowDown + Enter", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        allowCustomValue
+        options={[{ label: "Alpha", value: "alpha" }]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const input = await screen.findByPlaceholderText("Search…");
+    await userEvent.type(input, "Alp");
+    // Move off the auto-highlighted "Alpha" onto the trailing custom row.
+    await userEvent.keyboard("{ArrowDown}{Enter}");
+    expect(onValueChange).toHaveBeenCalledWith("Alp");
+  });
+
+  it("Escape closes the popover without clearing the already-selected value", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        allowCustomValue
+        options={[{ label: "Alpha", value: "a" }]}
+        value="a"
+        onValueChange={onValueChange}
+      />,
+    );
+    const trigger = screen.getByRole("combobox");
+    await userEvent.click(trigger);
+    const input = await screen.findByPlaceholderText("Search…");
+    await userEvent.type(input, "something");
+    await userEvent.keyboard("{Escape}");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(trigger).toHaveTextContent("Alpha");
+  });
+});

package/src/components/combobox/combobox.tsx

@@ -0,0 +1,210 @@
+import { forwardRef, useState, type ComponentPropsWithoutRef } from "react";
+import { defaultFilter } from "cmdk";
+import { Check, ChevronsUpDown, Plus } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { useLocale } from "../locale-provider";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "../command";
+
+export interface ComboboxOption {
+  label: string;
+  value: string;
+}
+
+export interface ComboboxProps {
+  options: ComboboxOption[];
+  value?: string;
+  onValueChange?: (value: string) => void;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  /**
+   * Message shown when the search yields no results. Defaults to "No
+   * results." — or, when `allowCustomValue` is set, a message that also
+   * signals a custom value is acceptable.
+   */
+  emptyText?: string;
+  className?: string;
+  /** Disables the trigger and prevents the popover from opening. */
+  disabled?: boolean;
+  /**
+   * When `true`, typed text that doesn't match any option becomes a
+   * submittable value: a synthetic "Use…" suggestion is shown, and pressing
+   * Enter with no listed option highlighted accepts the typed text via
+   * `onValueChange`. Suggestions still filter as usual. Default `false`
+   * (selection-only, unchanged behavior) — #359.
+   */
+  allowCustomValue?: boolean;
+  /** `id` applied to the trigger button. */
+  id?: string;
+  /**
+   * The trigger's accessible name always defaults to the SELECTED VALUE (or
+   * the placeholder) — that tells AT what is currently chosen, never what the
+   * control is FOR. Pass `aria-label`/`aria-labelledby` to also name the
+   * control's purpose (e.g. "Session switcher").
+   */
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  /**
+   * Escape hatch spread onto the trigger `Button` (after the named props
+   * above, so it wins if both are set) for anything not covered by a named
+   * prop — `data-*`, `name`, `data-testid`, etc. `role`/`aria-expanded` stay
+   * component-owned and can't be passed here; disabling stays on the
+   * top-level `disabled` prop so the popover-open guard below can't drift
+   * out of sync with the trigger's actual disabled state.
+   */
+  triggerProps?: Omit<
+    ComponentPropsWithoutRef<typeof Button>,
+    "role" | "aria-expanded" | "disabled"
+  > & {
+    /** Arbitrary `data-*` attributes (test hooks, analytics, …). */
+    [key: `data-${string}`]: string | number | boolean | undefined;
+  };
+}
+
+/**
+ * Sentinel `value` for the synthetic "Use …" row (`allowCustomValue`).
+ *
+ * It must NOT be the search text. cmdk scores every item against the search and
+ * re-sorts the list by score, then auto-highlights the top one — so a row whose
+ * `value` IS the search text scores a perfect 1 and outranks every real partial
+ * match. Typing "Prod" against a "Production" option then highlighted
+ * `Use "Prod"`, and Enter emitted the raw string instead of selecting the
+ * option — the exact opposite of #359's "Enter accepts the highlighted
+ * suggestion, or the typed value if none is highlighted".
+ */
+const CUSTOM_VALUE_ITEM = "__brand-ui-combobox-custom-value__";
+
+/**
+ * Keeps the "Use …" row visible (score > 0) but always ranked LAST, behind
+ * every real suggestion, so the top match stays highlighted and Enter still
+ * selects it. When nothing else matches, the row is the only item and Enter
+ * accepts the typed value — which is the behavior #359 asks for.
+ */
+const customValueFilter = (value: string, search: string, keywords?: string[]) =>
+  value === CUSTOM_VALUE_ITEM ? Number.MIN_VALUE : defaultFilter(value, search, keywords);
+
+/** Single-select combobox (Popover + Command). Controlled or uncontrolled. */
+export const Combobox = forwardRef<HTMLButtonElement, ComboboxProps>(function Combobox(
+  {
+    options,
+    value,
+    onValueChange,
+    placeholder = "Select…",
+    searchPlaceholder = "Search…",
+    emptyText,
+    className,
+    disabled = false,
+    allowCustomValue = false,
+    id,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledby,
+    triggerProps,
+  },
+  ref,
+) {
+  const { t } = useLocale();
+  const [open, setOpen] = useState(false);
+  const [internal, setInternal] = useState("");
+  const [search, setSearch] = useState("");
+  const selected = value ?? internal;
+  const setValue = (v: string) => (onValueChange ? onValueChange(v) : setInternal(v));
+  const current = options.find((o) => o.value === selected);
+
+  const trimmedSearch = search.trim();
+  const hasExactMatch = options.some(
+    (o) => o.label.trim().toLowerCase() === trimmedSearch.toLowerCase(),
+  );
+  const showCustomValueItem = allowCustomValue && trimmedSearch.length > 0 && !hasExactMatch;
+  const resolvedEmptyText =
+    emptyText ?? (allowCustomValue ? t("ui.combobox.emptyAllowCustom") : t("noResults"));
+
+  return (
+    <Popover
+      open={disabled ? false : open}
+      onOpenChange={(o) => {
+        if (disabled) return;
+        setOpen(o);
+        // Reset the search text on close, matching the previous (uncontrolled
+        // cmdk-internal) behavior where the popover content unmounted and its
+        // own internal search state reset with it.
+        if (!o) setSearch("");
+      }}
+    >
+      <PopoverTrigger asChild>
+        <Button
+          ref={ref}
+          variant="outline"
+          id={id}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledby}
+          {...triggerProps}
+          role="combobox"
+          aria-expanded={open}
+          disabled={disabled}
+          data-slot="combobox"
+          className={cn("w-56 justify-between font-normal", triggerProps?.className, className)}
+        >
+          {current ? current.label : selected || placeholder}
+          <ChevronsUpDown className="ms-2 size-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent
+        className="w-56 p-0"
+        data-slot="combobox-content"
+        // Radix Popover.Content renders role="dialog"; without a name axe's
+        // aria-dialog-name rule (rightly) flags it. Reuse the trigger's own
+        // purpose label when the consumer set one, else fall back to the
+        // (already-translatable) search placeholder — no new hardcoded copy.
+        aria-label={ariaLabel ?? searchPlaceholder}
+      >
+        <Command filter={allowCustomValue ? customValueFilter : undefined}>
+          <CommandInput placeholder={searchPlaceholder} value={search} onValueChange={setSearch} />
+          <CommandList>
+            <CommandEmpty>{resolvedEmptyText}</CommandEmpty>
+            <CommandGroup>
+              {options.map((o) => (
+                <CommandItem
+                  key={o.value}
+                  value={o.label}
+                  onSelect={() => {
+                    setValue(o.value === selected ? "" : o.value);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn(
+                      "me-2 size-4",
+                      selected === o.value ? "opacity-100" : "opacity-0",
+                    )}
+                  />
+                  {o.label}
+                </CommandItem>
+              ))}
+              {showCustomValueItem ? (
+                <CommandItem
+                  value={CUSTOM_VALUE_ITEM}
+                  data-slot="combobox-custom-value"
+                  onSelect={() => {
+                    setValue(trimmedSearch);
+                    setOpen(false);
+                  }}
+                >
+                  <Plus className="me-2 size-4 shrink-0 opacity-50" />
+                  {t("ui.combobox.useCustomValue", { value: trimmedSearch })}
+                </CommandItem>
+              ) : null}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+});

package/src/components/combobox/index.ts

@@ -0,0 +1 @@
+export { Combobox, type ComboboxProps, type ComboboxOption } from "./combobox";