@elabs-ai/components-ui 4.1.0 → 5.0.0

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

@@ -66,6 +66,60 @@ describe("Combobox", () => {
     );
     expect(screen.getByRole("combobox")).toHaveTextContent("Custom Value");
   });
+
+  it("does not hard-fix the trigger width — fills its container by default", () => {
+    render(<Combobox options={[{ label: "A", value: "a" }]} />);
+    expect(screen.getByRole("combobox").className).not.toMatch(/\bw-56\b/);
+  });
+});
+
+// jsdom doesn't implement Element.scrollIntoView, which cmdk calls internally
+// to keep the auto-highlighted item visible — see the comment on the
+// `allowCustomValue` describe below for the full explanation.
+describe("Combobox (options interaction)", () => {
+  let originalScrollIntoView: typeof Element.prototype.scrollIntoView;
+
+  beforeEach(() => {
+    originalScrollIntoView = Element.prototype.scrollIntoView;
+    Element.prototype.scrollIntoView = vi.fn();
+  });
+
+  afterEach(() => {
+    Element.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  // #reviewed 1.7 — a hand-rolled `onValueChange ? onValueChange(v) : setInternal(v)`
+  // never updates internal state once a listener is attached, so an
+  // uncontrolled Combobox with an onValueChange handler never shows its own
+  // selection on the trigger.
+  it("updates the trigger's own displayed value when uncontrolled even with an onValueChange listener", async () => {
+    const onValueChange = vi.fn();
+    render(<Combobox options={[{ label: "Alpha", value: "a" }]} onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole("combobox"));
+    await userEvent.click(await screen.findByRole("option", { name: "Alpha" }));
+    expect(onValueChange).toHaveBeenCalledWith("a");
+    expect(screen.getByRole("combobox")).toHaveTextContent("Alpha");
+  });
+
+  // Duplicate labels used to collide because CommandItem's `value` (cmdk's
+  // identity/scoring key) was the LABEL, not the unique option value.
+  it("distinguishes options that share the same label", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        options={[
+          { label: "Production", value: "prod-us" },
+          { label: "Production", value: "prod-eu" },
+        ]}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("combobox"));
+    const options = await screen.findAllByRole("option", { name: "Production" });
+    expect(options).toHaveLength(2);
+    await userEvent.click(options[1]!);
+    expect(onValueChange).toHaveBeenCalledWith("prod-eu");
+  });
 });
 
 // #359 — allowCustomValue. A nested describe because these tests TYPE into the

package/src/components/combobox/combobox.tsx

@@ -1,7 +1,10 @@
+"use client";
+
 import { forwardRef, useState, type ComponentPropsWithoutRef } from "react";
 import { defaultFilter } from "cmdk";
 import { Check, ChevronsUpDown, Plus } from "lucide-react";
 import { cn } from "../../lib/cn";
+import { useControllableState } from "../../lib/use-controllable-state";
 import { Button } from "../button";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover";
 import { useLocale } from "../locale-provider";
@@ -20,6 +23,12 @@ export interface ComboboxOption {
 }
 
 export interface ComboboxProps {
+  /**
+   * The option list — every option is mounted in the DOM (cmdk has no built-in
+   * windowing), so this is fine for typical form/menu-sized lists but not for
+   * open-ended data. For thousands of options, use `VirtualSelect` instead,
+   * which windows rendering via `@tanstack/react-virtual`.
+   */
   options: ComboboxOption[];
   value?: string;
   onValueChange?: (value: string) => void;
@@ -97,8 +106,8 @@ export const Combobox = forwardRef<HTMLButtonElement, ComboboxProps>(function Co
     options,
     value,
     onValueChange,
-    placeholder = "Select…",
-    searchPlaceholder = "Search…",
+    placeholder,
+    searchPlaceholder,
     emptyText,
     className,
     disabled = false,
@@ -111,11 +120,11 @@ export const Combobox = forwardRef<HTMLButtonElement, ComboboxProps>(function Co
   ref,
 ) {
   const { t } = useLocale();
+  const resolvedPlaceholder = placeholder ?? t("ui.combobox.placeholder");
+  const resolvedSearchPlaceholder = searchPlaceholder ?? t("ui.combobox.searchPlaceholder");
   const [open, setOpen] = useState(false);
-  const [internal, setInternal] = useState("");
+  const [selected, setValue] = useControllableState(value, "", onValueChange);
   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();
@@ -150,30 +159,35 @@ export const Combobox = forwardRef<HTMLButtonElement, ComboboxProps>(function Co
           aria-expanded={open}
           disabled={disabled}
           data-slot="combobox"
-          className={cn("w-56 justify-between font-normal", triggerProps?.className, className)}
+          className={cn("w-full justify-between font-normal", triggerProps?.className, className)}
         >
-          {current ? current.label : selected || placeholder}
+          {current ? current.label : selected || resolvedPlaceholder}
           <ChevronsUpDown className="ms-2 size-4 shrink-0 opacity-50" />
         </Button>
       </PopoverTrigger>
       <PopoverContent
-        className="w-56 p-0"
+        className="w-[var(--radix-popover-trigger-width)] min-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}
+        aria-label={ariaLabel ?? resolvedSearchPlaceholder}
       >
         <Command filter={allowCustomValue ? customValueFilter : undefined}>
-          <CommandInput placeholder={searchPlaceholder} value={search} onValueChange={setSearch} />
+          <CommandInput
+            placeholder={resolvedSearchPlaceholder}
+            value={search}
+            onValueChange={setSearch}
+          />
           <CommandList>
             <CommandEmpty>{resolvedEmptyText}</CommandEmpty>
             <CommandGroup>
               {options.map((o) => (
                 <CommandItem
                   key={o.value}
-                  value={o.label}
+                  value={o.value}
+                  keywords={[o.label]}
                   onSelect={() => {
                     setValue(o.value === selected ? "" : o.value);
                     setOpen(false);

package/src/components/command/command.stories.tsx

@@ -321,8 +321,71 @@ function ExternalInputComboboxDemo() {
   );
 }
 
+/* -------------------------------------------------------------------------- */
+/*  Below the fold — mount-time auto-select must never scroll the page (#541) */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Reproduces #541: cmdk auto-selects the first item on mount and calls its
+ * native `scrollIntoView({ block: "nearest" })` — unpatched, that walks every
+ * scrollable ancestor including the window. A tall spacer pushes the list
+ * below the fold so a regression here scrolls `window.scrollY` away from 0.
+ */
+export const BelowTheFold: Story = {
+  name: "Inline list below the fold never scrolls the page",
+  parameters: { layout: "fullscreen" },
+  render: () => (
+    <div>
+      <div className="flex h-[150vh] items-end justify-center p-6 text-body text-muted-foreground">
+        Scroll spacer — the command list below starts off-screen.
+      </div>
+      <div className="flex justify-center pb-24">
+        <Command className="w-80 rounded-lg shadow-ring-md">
+          <CommandInput placeholder="Search framework…" />
+          <CommandList>
+            <CommandEmpty>No results found.</CommandEmpty>
+            <CommandGroup heading="Frameworks">
+              {FRAMEWORKS.map((framework) => (
+                <CommandItem key={framework}>{framework}</CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </div>
+    </div>
+  ),
+  play: async ({ canvasElement, userEvent }) => {
+    const canvas = within(canvasElement);
+
+    // Mount-time auto-select must never move the page — even though the list
+    // starts entirely below the fold.
+    await waitFor(() => {
+      expect(canvasElement.querySelector('[aria-selected="true"]')).not.toBeNull();
+    });
+    expect(window.scrollY).toBe(0);
+
+    // Bring the list into view the way a real visitor would — by scrolling
+    // the page themselves. `scrollIntoView` on the INPUT (an element this
+    // fix never touches) is an ordinary, expected page scroll, not the bug
+    // under test.
+    const list = canvasElement.querySelector('[data-slot="command-list"]') as HTMLElement;
+    const input = canvas.getByPlaceholderText("Search framework…");
+    input.scrollIntoView();
+    const scrollYOnceVisible = window.scrollY;
+    expect(scrollYOnceVisible).toBeGreaterThan(0);
+
+    // Keyboard navigation in the now-visible, overflowing list must keep the
+    // active item visible by scrolling the LIST itself — never nudging the
+    // page any further.
+    await userEvent.type(input, "{ArrowDown}".repeat(12));
+
+    await waitFor(() => expect(list.scrollTop).toBeGreaterThan(0));
+    expect(window.scrollY).toBe(scrollYOnceVisible);
+  },
+};
+
 export const ExternalInputCombobox: Story = {
-  name: "External input combobox (aria-activedescendant, #365)",
+  name: "External input combobox (aria-activedescendant)",
   parameters: {
     docs: {
       description: {

package/src/components/command/command.test.tsx

@@ -5,6 +5,7 @@ import userEvent from "@testing-library/user-event";
 import {
   Command,
   CommandDialog,
+  CommandEmpty,
   CommandGroup,
   CommandInput,
   CommandItem,
@@ -184,6 +185,79 @@ describe("Command — onActiveItemIdChange (#365)", () => {
   });
 });
 
+/**
+ * #541 — cmdk auto-highlights the first item on mount and calls the native
+ * `Element.prototype.scrollIntoView({ block: "nearest" })` on it, which walks
+ * every scrollable ancestor including the window. `overrideItemScrollIntoView`
+ * (`command.tsx`) shadows `scrollIntoView` as an OWN property on each item, so
+ * the file-level `beforeEach` stub above — standing in for the native,
+ * jsdom-less method on `Element.prototype` — must never be reached at all:
+ * own-property lookups win over the prototype every time.
+ */
+describe("Command — inline list never scrolls the page (#541)", () => {
+  function TallHarness() {
+    return (
+      <div>
+        <div style={{ height: 2000 }} data-testid="spacer" />
+        <Command>
+          <CommandInput placeholder="Search…" />
+          <CommandList>
+            <CommandGroup heading="Fruit">
+              {Array.from({ length: 20 }, (_, i) => (
+                <CommandItem key={i} value={`fruit-${i}`}>{`Fruit ${i}`}</CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </div>
+    );
+  }
+
+  it("never reaches the native scrollIntoView on mount, and leaves window.scrollY at 0", async () => {
+    const { container } = render(<TallHarness />);
+
+    await waitFor(() => {
+      expect(container.querySelector('[aria-selected="true"]')).not.toBeNull();
+    });
+
+    expect(Element.prototype.scrollIntoView).not.toHaveBeenCalled();
+    expect(window.scrollY).toBe(0);
+  });
+
+  it("keyboard navigation scrolls the CommandList itself, never the window", async () => {
+    const { container } = render(<TallHarness />);
+    const list = container.querySelector('[data-slot="command-list"]') as HTMLElement;
+    const input = screen.getByPlaceholderText("Search…");
+
+    // jsdom has no layout engine (every rect is 0,0,0,0) — fake an
+    // overflowing list so the "nearest" edge math this fix replicates has
+    // something real to compute against.
+    const fakeRect = (top: number, height: number): DOMRect =>
+      ({
+        top,
+        bottom: top + height,
+        left: 0,
+        right: 300,
+        width: 300,
+        height,
+        x: 0,
+        y: top,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    vi.spyOn(list, "getBoundingClientRect").mockReturnValue(fakeRect(0, 300));
+    const items = Array.from(container.querySelectorAll('[cmdk-item=""]'));
+    items.forEach((item, i) => {
+      vi.spyOn(item as HTMLElement, "getBoundingClientRect").mockReturnValue(fakeRect(i * 32, 32));
+    });
+
+    await userEvent.type(input, "{ArrowDown}".repeat(15));
+
+    await waitFor(() => expect(list.scrollTop).toBeGreaterThan(0));
+    expect(window.scrollY).toBe(0);
+  });
+});
+
 describe("CommandItem — dev-only warning for cmdk-overridden props", () => {
   it("warns when a consumer passes id, role, or aria-selected", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
@@ -351,3 +425,17 @@ describe("Command — CommandSeparator a11y (#157)", () => {
     expect(screen.getByRole("listbox")).toBeInTheDocument();
   });
 });
+
+describe("CommandEmpty — merges className instead of replacing it", () => {
+  it("keeps the base py-6/text-center classes alongside a caller className", () => {
+    render(
+      <Command>
+        <CommandList>
+          <CommandEmpty className="custom-empty">No results</CommandEmpty>
+        </CommandList>
+      </Command>,
+    );
+    const empty = screen.getByText("No results");
+    expect(empty).toHaveClass("py-6", "text-center", "custom-empty");
+  });
+});

package/src/components/command/command.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createContext,
   forwardRef,
@@ -21,6 +23,68 @@ import { Dialog, DialogContent, DialogTitle } from "../dialog";
 /** cmdk's own marker attribute on an item row — the scope for the id lookup. */
 const CMDK_ITEM_SELECTOR = '[cmdk-item=""][aria-selected="true"]';
 
+/**
+ * Brings `element` fully into view within its nearest `CommandList` ancestor
+ * — and ONLY that ancestor — by writing `scrollTop` directly. Replicates the
+ * minimal-movement edge math `Element.scrollIntoView({ block: "nearest" })`
+ * itself uses, without ever calling the native method (which walks every
+ * further scrollable ancestor, the window included — see
+ * `overrideItemScrollIntoView` below for why that matters). A no-op when
+ * `element` has no `CommandList` ancestor: never falls back to the native
+ * call, which would reopen #541.
+ */
+function scrollElementIntoCommandList(element: HTMLElement) {
+  const list = element.closest<HTMLElement>('[data-slot="command-list"]');
+  if (!list) return;
+  const elementRect = element.getBoundingClientRect();
+  const listRect = list.getBoundingClientRect();
+  if (elementRect.top < listRect.top) {
+    list.scrollTop -= listRect.top - elementRect.top;
+  } else if (elementRect.bottom > listRect.bottom) {
+    list.scrollTop += elementRect.bottom - listRect.bottom;
+  }
+}
+
+/**
+ * cmdk auto-highlights the first item on mount, on every filter keystroke
+ * and on every keyboard navigation (ArrowDown/ArrowUp/Home/End), then calls
+ * the highlighted item's — and, when it is the first item in a group, that
+ * group's heading's — native `Element.prototype.scrollIntoView({ block:
+ * "nearest" })` to keep it visible. See `cmdk@1.1.1`'s
+ * `node_modules/cmdk/dist/index.mjs:1` (and the CJS twin
+ * `dist/index.js:1` — esbuild minifies each entire module onto a single
+ * line), function `ne` (`ce` in the CJS build): every `setState("value", …)`
+ * call that does not pass the internal "don't scroll" flag (pointer hover
+ * selection is the one call site that does) schedules it, and the root
+ * component's own mount effect schedules it unconditionally too.
+ *
+ * `{ block: "nearest" }` walks EVERY scrollable ancestor, the window
+ * included — so mounting a `Command` whose list sits below the fold scrolls
+ * the whole page (#541), for every consumer of an inline list, not only a
+ * modal `CommandDialog`. cmdk has no prop to opt out (checked its public
+ * API — no `scrollBehavior`/`disableScroll`/similar).
+ *
+ * The fix shadows `scrollIntoView` as an OWN property on the specific
+ * item/heading element cmdk will call it on — never `Element.prototype`,
+ * which would silently change the behaviour of every OTHER element on the
+ * page, not just cmdk's — with `scrollElementIntoCommandList` above. A ref
+ * callback runs during React's DOM-mutation commit phase, which always
+ * completes (for the whole tree) before any layout effect fires — including
+ * cmdk's own scheduled scroll — so the override is guaranteed to be in place
+ * before cmdk can ever reach the native method.
+ */
+function overrideItemScrollIntoView(node: HTMLElement | null) {
+  if (node) node.scrollIntoView = () => scrollElementIntoCommandList(node);
+}
+
+/** Same override as `overrideItemScrollIntoView`, for a group's heading —
+ * the DOM node cmdk creates internally for `CommandGroup`'s `heading` prop,
+ * so unlike an item it isn't a ref target we're handed directly. */
+function overrideGroupHeadingScrollIntoView(node: HTMLElement | null) {
+  const heading = node?.querySelector<HTMLElement>("[cmdk-group-heading]");
+  if (heading) heading.scrollIntoView = () => scrollElementIntoCommandList(heading);
+}
+
 /** Distinguishes "no `<Command>` ancestor" from "nothing is highlighted". */
 const NO_COMMAND_PROVIDER = Symbol("no-command-provider");
 
@@ -199,7 +263,7 @@ export const CommandInput = forwardRef<
         ref={ref}
         data-slot="command-input"
         className={cn(
-          "flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50",
+          "flex h-10 w-full rounded-md bg-transparent py-3 text-body outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50",
           className,
         )}
         {...props}
@@ -225,12 +289,12 @@ export const CommandList = forwardRef<
 export const CommandEmpty = forwardRef<
   ElementRef<typeof CommandPrimitive.Empty>,
   ComponentPropsWithoutRef<typeof CommandPrimitive.Empty>
->(function CommandEmpty(props, ref) {
+>(function CommandEmpty({ className, ...props }, ref) {
   return (
     <CommandPrimitive.Empty
       ref={ref}
       data-slot="command-empty"
-      className="py-6 text-center text-sm"
+      className={cn("py-6 text-center text-body", className)}
       {...props}
     />
   );
@@ -240,12 +304,16 @@ export const CommandGroup = forwardRef<
   ElementRef<typeof CommandPrimitive.Group>,
   ComponentPropsWithoutRef<typeof CommandPrimitive.Group>
 >(function CommandGroup({ className, ...props }, ref) {
+  const mergedRef = useMemo(
+    () => mergeRefs<HTMLDivElement>(ref, overrideGroupHeadingScrollIntoView),
+    [ref],
+  );
   return (
     <CommandPrimitive.Group
-      ref={ref}
+      ref={mergedRef}
       data-slot="command-group"
       className={cn(
-        "overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground",
+        "overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-meta [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground",
         className,
       )}
       {...props}
@@ -285,6 +353,11 @@ export const CommandItem = forwardRef<
   ElementRef<typeof CommandPrimitive.Item>,
   ComponentPropsWithoutRef<typeof CommandPrimitive.Item>
 >(function CommandItem({ className, ...props }, ref) {
+  const mergedRef = useMemo(
+    () => mergeRefs<HTMLDivElement>(ref, overrideItemScrollIntoView),
+    [ref],
+  );
+
   if (process.env.NODE_ENV !== "production") {
     for (const key of CMDK_OVERRIDDEN_ITEM_PROPS) {
       if (key in props && !warnedAboutOverriddenItemProps.has(key)) {
@@ -302,10 +375,10 @@ export const CommandItem = forwardRef<
 
   return (
     <CommandPrimitive.Item
-      ref={ref}
+      ref={mergedRef}
       data-slot="command-item"
       className={cn(
-        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors duration-fast data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:size-4",
+        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:size-4",
         className,
       )}
       {...props}
@@ -317,7 +390,7 @@ export function CommandShortcut({ className, ...props }: HTMLAttributes<HTMLSpan
   return (
     <span
       data-slot="command-shortcut"
-      className={cn("ms-auto text-xs tracking-widest text-muted-foreground", className)}
+      className={cn("ms-auto text-meta tracking-widest text-muted-foreground", className)}
       {...props}
     />
   );

package/src/components/command-chip/command-chip.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
+import { CommandChip, type CommandChipHost } from "./command-chip";
+
+const HOSTS: CommandChipHost[] = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    command: "claude mcp add --transport http brand-ui https://elabs-ai.com/mcp",
+  },
+  { id: "cursor", label: "Cursor", command: "npx -y @elabs-ai/components-cli mcp" },
+  { id: "any", label: "Any MCP host (URL)", command: "https://elabs-ai.com/mcp" },
+];
+
+const meta = {
+  title: "Display/CommandChip",
+  component: CommandChip,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "An install command in a monospace chip: pick the host from the menu, copy the exact command. Without clipboard access the command is selected for a manual copy; both outcomes are announced.",
+      },
+    },
+  },
+  args: { hosts: HOSTS, onCopyCommand: fn() },
+  decorators: [
+    (Story) => (
+      <div className="w-full max-w-xl">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof CommandChip>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** A host picked up front (uncontrolled `defaultValue`). */
+export const CursorSelected: Story = { args: { defaultValue: "cursor" } };
+
+/** One host only: no menu, just the command and the copy button. */
+export const SingleHost: Story = { args: { hosts: [HOSTS[0]!] } };
+
+/** Copy writes the exact command and announces “Copied”. */
+export const CopyCommand: Story = {
+  play: async ({ canvasElement, args }) => {
+    const writeText = fn(() => Promise.resolve());
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText },
+      configurable: true,
+      writable: true,
+    });
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: "Copy command" }));
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith(HOSTS[0]!.command));
+    await waitFor(() => expect(canvas.getByRole("status")).toHaveTextContent("Copied"));
+    await expect(args.onCopyCommand).toHaveBeenCalledWith(HOSTS[0]!.command, true);
+  },
+};
+
+/** Choosing another host swaps the command. */
+export const SwitchHost: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Install for/ }));
+    const body = within(canvasElement.ownerDocument.body);
+    await userEvent.click(await body.findByRole("menuitemradio", { name: "Cursor" }));
+    await waitFor(() => expect(canvas.getByText(HOSTS[1]!.command)).toBeInTheDocument());
+    // The menu hides the rest of the page from assistive tech while it is open. Wait for it to
+    // close fully, so the post-play axe check sees the page a user sees, not the exit frame.
+    await waitFor(() => expect(body.queryByRole("menu")).toBeNull());
+    await waitFor(() => expect(canvasElement.closest('[aria-hidden="true"]')).toBeNull());
+  },
+};

package/src/components/command-chip/command-chip.test.tsx

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { CommandChip, type CommandChipHost } from "./command-chip";
+
+const HOSTS: CommandChipHost[] = [
+  { id: "claude-code", label: "Claude Code", command: "claude mcp add brand-ui" },
+  { id: "cursor", label: "Cursor", command: "npx -y @elabs-ai/components-cli mcp" },
+];
+
+function stubClipboard(impl: () => Promise<void> = () => Promise.resolve()) {
+  const writeText = vi.fn(impl);
+  Object.defineProperty(navigator, "clipboard", {
+    value: { writeText },
+    configurable: true,
+    writable: true,
+  });
+  return writeText;
+}
+
+describe("CommandChip", () => {
+  it("shows the first host's command with its data-slot", () => {
+    const { container } = render(<CommandChip hosts={HOSTS} />);
+    expect(container.querySelector('[data-slot="command-chip"]')).not.toBeNull();
+    expect(screen.getByText(HOSTS[0]!.command)).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Install for: Claude Code" })).toBeInTheDocument();
+  });
+
+  it("honours defaultValue", () => {
+    render(<CommandChip hosts={HOSTS} defaultValue="cursor" />);
+    expect(screen.getByText(HOSTS[1]!.command)).toBeInTheDocument();
+  });
+
+  it("copies the exact command and announces it", async () => {
+    const writeText = stubClipboard();
+    const onCopyCommand = vi.fn();
+    render(<CommandChip hosts={HOSTS} onCopyCommand={onCopyCommand} />);
+    const status = screen.getByRole("status");
+    expect(status).toHaveTextContent("");
+    fireEvent.click(screen.getByRole("button", { name: "Copy command" }));
+    await waitFor(() => expect(status).toHaveTextContent("Copied"));
+    expect(writeText).toHaveBeenCalledWith(HOSTS[0]!.command);
+    expect(onCopyCommand).toHaveBeenCalledWith(HOSTS[0]!.command, true);
+  });
+
+  it("selects the command when the clipboard is unavailable", async () => {
+    stubClipboard(() => Promise.reject(new Error("denied")));
+    render(<CommandChip hosts={HOSTS} />);
+    fireEvent.click(screen.getByRole("button", { name: "Copy command" }));
+    await waitFor(() => expect(screen.getByRole("status")).toHaveTextContent("Command selected"));
+    expect(window.getSelection()?.toString()).toBe(HOSTS[0]!.command);
+  });
+
+  it("renders no menu for a single host", () => {
+    render(<CommandChip hosts={[HOSTS[0]!]} />);
+    expect(screen.queryByRole("button", { name: /Install for/ })).toBeNull();
+  });
+});