@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/change-review/change-review.tsx

@@ -11,6 +11,27 @@
  * Design references: GitHub PR file-review (per-hunk viewed/comment),
  * Cursor/Copilot "review changes" panel, Graphite/Linear review UIs.
  *
+ * NOT a diff-line renderer, and deliberately never becoming one. A hunk's
+ * `before`/`after` are ordinary `ReactNode` prose, drawn as a quiet no-fill
+ * comparison; the `−`/`+` markers below mean "previous content"/"proposed
+ * content", which is not the same idea as `DiffLine`'s "removed line"/"added
+ * line" even though the glyphs coincide. Do NOT reach for `diffLineMarker` here:
+ * a coincidence stays a literal (theming.md, intentional-mirror rule).
+ *
+ * Structured `DiffLine[]` hunks reach this component by INJECTION, which is a
+ * binding decision, not an unfinished merge — see
+ * `docs/decisions/2026-09-01-brainless-adoption-architecture.md` § 3:
+ *   - `ChangeHunk` gains NO `lines` field and `DiffLine` never moves here.
+ *   - The app that depends on both packages passes a `<DiffView>`
+ *     (`@elabs-ai/components-ai`, Shiki-backed) through `renderHunk` or a hunk's
+ *     `after` slot. Neither package imports the other, in either direction.
+ *   - Re-litigated and re-ratified 2026-09-03: moving this component into
+ *     `@elabs-ai/components-ai` was rejected because it would push a
+ *     dependency-free component into a layer-2 leaf that `terminal`, `editor`
+ *     and `viewer` could then never reach.
+ * See the `InjectedHunkRenderer` story here, and `ChangeReviewComposition` in
+ * `packages/ai/src/diff-view.stories.tsx` for the real two-package wiring.
+ *
  * State grid: empty (no hunks → StatePanel), single hunk, mixed, all-approved,
  * all-rejected, very long hunk content. Approval state is signalled with color
  * AND icon/label (colorblind + high-decoration/high-contrast safe).
@@ -36,12 +57,16 @@ import {
   type HTMLAttributes,
   type ReactNode,
 } from "react";
-import { Check, X, CheckCheck, User, Bot, Clock } from "lucide-react";
+import { Check, X, CheckCheck, User, Bot, Clock, ChevronDown } from "lucide-react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
+import { type CheckResult } from "../../lib/check-result";
+import { formatElapsed } from "../../lib/format-duration";
 import { Button } from "../button/button";
 import { Badge } from "../badge/badge";
 import { StatePanel } from "../state-panel/state-panel";
+import { StatusIcon } from "../status-badge/status-badge";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../collapsible/collapsible";
 
 // ─── Public types ─────────────────────────────────────────────────────────────
 
@@ -74,6 +99,13 @@ export interface ChangeHunk {
   status?: ChangeHunkStatus;
   /** Per-hunk provenance override (overrides the review-level provenance). */
   provenance?: ChangeProvenance;
+  /**
+   * Verification results for this hunk (lint / types / tests / policy hooks).
+   * Purely informational — a failing check never blocks approval, it only
+   * informs the reviewer's decision. Grouped into "Before" / "After" sections
+   * when both phases are present.
+   */
+  checks?: CheckResult[];
 }
 
 /** State surface exposed by the ChangeReview context. */
@@ -334,6 +366,7 @@ export const ChangeReviewProvenance = forwardRef<HTMLDivElement, ChangeReviewPro
             "flex flex-wrap items-center gap-x-3 gap-y-1 text-caption text-muted-foreground pb-3",
             className,
           )}
+          role="group"
           aria-label="Change provenance"
           {...props}
         >
@@ -365,6 +398,7 @@ export const ChangeReviewProvenance = forwardRef<HTMLDivElement, ChangeReviewPro
       <div
         ref={ref}
         className={cn("pb-3 text-caption text-muted-foreground", className)}
+        role="group"
         aria-label="Change provenance"
         {...props}
       >
@@ -419,7 +453,11 @@ const HUNK_STATUS_ICONS: Record<ChangeHunkStatus, ReactNode> = {
     </span>
   ),
   removed: (
-    <span className="text-destructive font-bold text-meta" aria-hidden="true">
+    // #124: sibling of `added`/`modified` above — this glyph is a decorative
+    // aria-hidden marker beside a labelled span (see HUNK_STATUS_LABELS), and
+    // reads as running text at the type scale, so it takes the ink rung the
+    // other two already use.
+    <span className="text-destructive-text font-bold text-meta" aria-hidden="true">
       −
     </span>
   ),
@@ -436,6 +474,145 @@ const HUNK_STATUS_LABELS: Record<ChangeHunkStatus, string> = {
   modified: "modified",
 };
 
+// ─── Checks (verification evidence) ────────────────────────────────────────────
+
+/**
+ * A check's `detail` collapses behind a disclosure once it's long enough that
+ * showing it inline would dominate the hunk row. Short details always render
+ * in place.
+ */
+const CHECK_DETAIL_COLLAPSE_THRESHOLD = 80;
+
+function isLongCheckDetail(detail: string): boolean {
+  return detail.length > CHECK_DETAIL_COLLAPSE_THRESHOLD || detail.includes("\n");
+}
+
+const CHECK_PHASE_LABELS: Record<"before" | "after", string> = {
+  before: "Before",
+  after: "After",
+};
+
+/**
+ * Group checks for display. Phase headers ("Before" / "After") appear ONLY
+ * when both phases are present in the same hunk — a single-phase or
+ * unphased list of checks renders flat, with no header noise.
+ */
+function groupChecksByPhase(
+  checks: CheckResult[],
+): { phase?: "before" | "after"; items: CheckResult[] }[] {
+  const before = checks.filter((c) => c.phase === "before");
+  const after = checks.filter((c) => c.phase === "after");
+  const showPhaseLabels = before.length > 0 && after.length > 0;
+
+  if (!showPhaseLabels) {
+    return [{ items: checks }];
+  }
+
+  const rest = checks.filter((c) => c.phase !== "before" && c.phase !== "after");
+  const groups: { phase?: "before" | "after"; items: CheckResult[] }[] = [];
+  if (rest.length > 0) groups.push({ items: rest });
+  groups.push({ phase: "before", items: before });
+  groups.push({ phase: "after", items: after });
+  return groups;
+}
+
+/**
+ * A single verification result row: icon + label + accessible status word +
+ * optional duration, with an optional collapsed detail line below.
+ *
+ * The pass/fail signal is carried by TWO non-color cues — the icon (distinct
+ * glyph per `StatusIcon`'s canonical vocabulary) and the visible "Passed"/
+ * "Failed" text — so it survives in greyscale (WCAG 1.4.1). `StatusIcon` is
+ * decorative (`aria-hidden`); the status word is what reaches assistive tech.
+ */
+function ChangeCheckRow({ check }: { check: CheckResult }) {
+  const [detailOpen, setDetailOpen] = useState(false);
+  const { label, ok, detail, durationMs } = check;
+  const statusWord = ok ? "Passed" : "Failed";
+  const hasDetail = detail !== undefined && detail !== "";
+  const longDetail = hasDetail && isLongCheckDetail(detail);
+
+  return (
+    <div data-slot="change-review-hunk-check" data-ok={ok} className="flex flex-col gap-1">
+      <div className="flex flex-wrap items-center gap-x-1.5 gap-y-0.5 min-w-0">
+        <StatusIcon status={ok ? "complete" : "failed"} className="size-3.5 shrink-0" />
+        <span className="text-caption font-medium text-foreground truncate">{label}</span>
+        <span className={cn("text-caption", ok ? "text-success-text" : "text-destructive-text")}>
+          {statusWord}
+        </span>
+        {durationMs !== undefined && (
+          <span className="text-caption text-muted-foreground tabular-nums shrink-0">
+            {formatElapsed(durationMs)}
+          </span>
+        )}
+      </div>
+
+      {hasDetail &&
+        (longDetail ? (
+          <Collapsible open={detailOpen} onOpenChange={setDetailOpen}>
+            <CollapsibleTrigger
+              className={cn(
+                "flex items-center gap-1 self-start rounded-sm pl-5 text-caption text-muted-foreground",
+                "hover:text-foreground focus-ring",
+              )}
+            >
+              <ChevronDown
+                aria-hidden="true"
+                className={cn(
+                  "size-3 transition-transform duration-fast motion-reduce:transition-none",
+                  detailOpen ? "rotate-180" : "rotate-0",
+                )}
+              />
+              {detailOpen ? "Hide detail" : "Show detail"}
+            </CollapsibleTrigger>
+            <CollapsibleContent data-slot="change-review-hunk-check-detail">
+              <p className="pl-5 pt-1 text-caption text-muted-foreground break-words">{detail}</p>
+            </CollapsibleContent>
+          </Collapsible>
+        ) : (
+          <p
+            data-slot="change-review-hunk-check-detail"
+            className="pl-5 text-caption text-muted-foreground break-words"
+          >
+            {detail}
+          </p>
+        ))}
+    </div>
+  );
+}
+
+/** The full checks section for one hunk — grouped by phase when applicable. */
+function ChangeReviewChecks({ checks }: { checks: CheckResult[] }) {
+  const groups = groupChecksByPhase(checks);
+  const showPhaseLabels = groups.some((g) => g.phase !== undefined);
+
+  return (
+    <div
+      data-slot="change-review-hunk-checks"
+      className="flex flex-col gap-2 border-t border-border pt-3"
+    >
+      {groups.map((group, index) => (
+        <div
+          key={group.phase ?? `_${index}`}
+          data-slot="change-review-hunk-checks-phase"
+          className="flex flex-col gap-1.5"
+        >
+          {showPhaseLabels && group.phase && (
+            <span className="text-meta font-medium text-muted-foreground">
+              {CHECK_PHASE_LABELS[group.phase]}
+            </span>
+          )}
+          <div className="flex flex-col gap-1.5">
+            {group.items.map((check, itemIndex) => (
+              <ChangeCheckRow key={`${check.label}-${itemIndex}`} check={check} />
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
 export interface ChangeReviewHunkProps
   extends
     Omit<HTMLAttributes<HTMLLIElement>, "children">,
@@ -454,13 +631,13 @@ export interface ChangeReviewHunkProps
  * Approval state is signalled with TWO non-color cues:
  * - icon: Check (approved) vs plain toggle (pending)
  * - label: "Approved" badge vs "Approve" button text
- * This ensures the state is clear in all three themes including the low-chroma
+ * This ensures the state is clear in every theme including the low-chroma
  * monochrome surfaces (colorblind-safe).
  */
 export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>(
   function ChangeReviewHunk({ hunk, renderHunk, className, ...props }, ref) {
     const { state, actions } = useChangeReview();
-    const { id, title, before, after, status = "modified", provenance } = hunk;
+    const { id, title, before, after, status = "modified", provenance, checks } = hunk;
     const approved = state.approved.has(id);
 
     const statusLabel = HUNK_STATUS_LABELS[status];
@@ -513,6 +690,7 @@ export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>
           <div className="flex items-center gap-2 min-w-0">
             {/* Status indicator: NON-color cue via symbol + color together */}
             <span
+              role="img"
               aria-label={`Change type: ${statusLabel}`}
               className="shrink-0 inline-flex items-center justify-center size-5"
             >
@@ -561,6 +739,9 @@ export const ChangeReviewHunk = forwardRef<HTMLLIElement, ChangeReviewHunkProps>
 
         {/* Content area: before / after or custom renderHunk */}
         {defaultContent && <div>{defaultContent}</div>}
+
+        {/* Verification evidence — informational only, never blocks approval */}
+        {checks && checks.length > 0 && <ChangeReviewChecks checks={checks} />}
       </li>
     );
   },

package/src/components/checkbox/checkbox.tsx

@@ -12,7 +12,7 @@ export const Checkbox = forwardRef<
       ref={ref}
       className={cn(
         "peer size-4 shrink-0 rounded-sm border border-input shadow-sm transition-colors duration-fast ease-standard",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
         "disabled:cursor-not-allowed disabled:opacity-50",
         "data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
         className,

package/src/components/color-picker/color-picker.tsx

@@ -120,7 +120,7 @@ const Swatch = forwardRef<HTMLButtonElement, SwatchProps>(function Swatch(
         selected
           ? "border-foreground ring-2 ring-ring ring-offset-1 ring-offset-background"
           : "border-transparent hover:border-foreground/40",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
         className,
       )}
       {...props}
@@ -266,7 +266,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
               "inline-flex items-center gap-2 rounded-md border border-input bg-background px-3 py-1.5 text-sm shadow-sm",
               "transition-[color,box-shadow] duration-fast",
               "hover:bg-accent hover:text-accent-foreground",
-              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+              "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
               "disabled:pointer-events-none disabled:opacity-50",
             )}
           >
@@ -297,7 +297,8 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
             <div className="mt-3 border-t border-border pt-3">
               {/* Custom hex is NOT theme-aware — it will not adapt to theme changes. */}
               <p className="mb-1.5 text-xs text-muted-foreground">
-                Custom hex <span className="text-warning">(not theme-aware)</span>
+                {/* #124: inline running text — ink rung, not the 3:1 mark rung. */}
+                Custom hex <span className="text-warning-text">(not theme-aware)</span>
               </p>
               <div className="flex gap-2">
                 <input
@@ -316,7 +317,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
                   }}
                   className={cn(
                     "h-8 w-28 rounded-md border border-input bg-background px-2 text-sm",
-                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                    "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
                     "placeholder:text-muted-foreground",
                   )}
                 />
@@ -326,7 +327,7 @@ export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function
                   className={cn(
                     "h-8 rounded-md border border-input bg-background px-2 text-sm",
                     "hover:bg-accent hover:text-accent-foreground",
-                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                    "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
                   )}
                 >
                   Apply

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

@@ -3,7 +3,6 @@ import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent }
 import { expect, waitFor, within } from "storybook/test";
 import { Calculator, Calendar, CreditCard, Settings, Smile, User } from "lucide-react";
 import { Button } from "../button";
-import { DialogTitle } from "../dialog";
 import {
   Command,
   CommandDialog,
@@ -19,6 +18,20 @@ const meta = {
   title: "Overlays/Command",
   component: Command,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A grouped, searchable, keyboard-driven list (cmdk). Render it inline, or wrap it " +
+          "in `CommandDialog` for a full ⌘K palette — pass `CommandDialog`'s optional `title` " +
+          "for the dialog's `sr-only` accessible name.\n\n" +
+          "**Choosing between the two model/target pickers.** A full ⌘K palette → compose " +
+          "`CommandDialog` + `Command*` from `@elabs-ai/components-ui` directly; there is no " +
+          "separate selector component. An inline pill in a composer footer that opens the " +
+          "same grouped list anchored under itself → `ModelPicker`.",
+      },
+    },
+  },
   argTypes: {
     label: {
       description: "Accessible label for the command palette (cmdk `label` prop).",
@@ -113,10 +126,7 @@ function CommandPaletteDemo() {
         Open command palette
       </Button>
 
-      <CommandDialog open={open} onOpenChange={setOpen}>
-        {/* CommandDialog doesn't ship a built-in title, so supply an sr-only one
-            for the dialog's accessible name. */}
-        <DialogTitle className="sr-only">Command palette</DialogTitle>
+      <CommandDialog open={open} onOpenChange={setOpen} title="Command palette">
         <CommandInput placeholder="Type a command or search…" />
         <CommandList>
           <CommandEmpty>No results found.</CommandEmpty>
@@ -291,7 +301,7 @@ function ExternalInputComboboxDemo() {
         role="combobox"
         onKeyDown={forwardKey}
         placeholder="Type @ to mention…"
-        className="flex h-10 w-full rounded-md border border-input bg-background px-3 text-body outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        className="flex h-10 w-full rounded-md border border-input bg-background px-3 text-body focus-ring"
       />
       <Command
         id="mention-list"

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

@@ -4,12 +4,15 @@ import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import {
   Command,
+  CommandDialog,
   CommandGroup,
   CommandInput,
   CommandItem,
   CommandList,
+  CommandSeparator,
   useCommandActiveItemId,
 } from "./command";
+import { DialogTitle } from "../dialog";
 
 // jsdom does not implement `Element.prototype.scrollIntoView`, and `cmdk`
 // calls it unconditionally (not feature-detected — it's a third-party
@@ -278,3 +281,73 @@ describe("Command — external combobox input wiring (integration)", () => {
     });
   });
 });
+
+/**
+ * RM-010 — `CommandDialog` grew a `title` prop when the `ModelSelector` alias
+ * shell in `@elabs-ai/components-ai` was deleted; the `sr-only` `DialogTitle`
+ * was the one capability that shell had and `ui` lacked.
+ *
+ * It MUST stay optional. `@elabs-ai/components-ai`'s `VoiceSelectorDialog`
+ * spreads `ComponentProps<typeof CommandDialog>` straight through, and callers
+ * that already render their own `DialogTitle` in `children` must not be forced
+ * to move it. Both branches are asserted so a later "make it required" change
+ * fails here rather than in a downstream package.
+ */
+describe("CommandDialog — optional title (RM-010)", () => {
+  it("names the dialog from `title`, rendered sr-only", () => {
+    render(
+      <CommandDialog open title="Command palette">
+        <CommandList>
+          <CommandItem>Calendar</CommandItem>
+        </CommandList>
+      </CommandDialog>,
+    );
+
+    const dialog = screen.getByRole("dialog");
+    expect(dialog).toHaveAccessibleName("Command palette");
+    expect(screen.getByText("Command palette")).toHaveClass("sr-only");
+  });
+
+  it("renders no title of its own when `title` is omitted — a caller's own DialogTitle still wins", () => {
+    render(
+      <CommandDialog open>
+        <DialogTitle>Caller-owned title</DialogTitle>
+        <CommandList>
+          <CommandItem>Calendar</CommandItem>
+        </CommandList>
+      </CommandDialog>,
+    );
+
+    expect(screen.getByRole("dialog")).toHaveAccessibleName("Caller-owned title");
+    // Exactly one heading — CommandDialog did not add a second, competing one.
+    expect(screen.getAllByText(/title/i)).toHaveLength(1);
+  });
+});
+
+/** #157 — `CommandSeparator` is `cmdk`'s divider between groups, rendered as a
+ * direct child of `CommandList`'s `role="listbox"`. A listbox may only own
+ * `option`/`group` children (WCAG 1.3.1); a bare `role="separator"` there is
+ * neither. */
+describe("Command — CommandSeparator a11y (#157)", () => {
+  it("stays in the DOM for sighted users but is removed from the accessibility tree", () => {
+    render(
+      <Command>
+        <CommandList>
+          <CommandGroup heading="Fruit">
+            <CommandItem value="apple">Apple</CommandItem>
+          </CommandGroup>
+          <CommandSeparator />
+          <CommandGroup heading="Veg">
+            <CommandItem value="carrot">Carrot</CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>,
+    );
+
+    // Still rendered — cmdk owns the visual divider.
+    expect(document.querySelector("[cmdk-separator]")).not.toBeNull();
+    // Never exposed with its `role="separator"` — a listbox can't own one.
+    expect(screen.queryByRole("separator")).toBeNull();
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+  });
+});

package/src/components/command/command.tsx

@@ -16,7 +16,7 @@ import { Command as CommandPrimitive, useCommandState } from "cmdk";
 import { Search } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { mergeRefs } from "../../lib/merge-refs";
-import { Dialog, DialogContent } from "../dialog";
+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"]';
@@ -149,17 +149,34 @@ export function useCommandActiveItemId(): string | undefined {
   return id === NO_COMMAND_PROVIDER ? undefined : id;
 }
 
-export function CommandDialog({
-  children,
-  filter,
-  ...props
-}: ComponentPropsWithoutRef<typeof Dialog> & {
+export type CommandDialogProps = ComponentPropsWithoutRef<typeof Dialog> & {
   /** Custom cmdk ranking (e.g. strict substring instead of fuzzy). */
   filter?: ComponentPropsWithoutRef<typeof CommandPrimitive>["filter"];
-}) {
+  /**
+   * The dialog's accessible name, rendered `sr-only`.
+   *
+   * OPTIONAL, and deliberately so: callers that already render their own
+   * `DialogTitle` in `children` must not be forced to move it, and
+   * `@elabs-ai/components-ai`'s `VoiceSelectorDialog` passes this whole prop
+   * type straight through. Supply it when you have no visible title — a
+   * `Dialog` with no accessible name is a Radix warning and an axe violation.
+   */
+  title?: ReactNode;
+};
+
+/**
+ * A ⌘K command palette in a modal `Dialog`.
+ *
+ * This IS the palette presentation of `Command` — there is no separate
+ * "selector" component. For an inline pill that opens the same grouped,
+ * searchable list anchored under itself (a composer footer), reach for
+ * `ModelPicker` instead.
+ */
+export function CommandDialog({ children, filter, title, ...props }: CommandDialogProps) {
   return (
     <Dialog {...props}>
       <DialogContent className="overflow-hidden p-0">
+        {title === undefined ? null : <DialogTitle className="sr-only">{title}</DialogTitle>}
         <Command
           filter={filter}
           className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-input-wrapper]_svg]:size-5 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3"
@@ -244,6 +261,12 @@ export const CommandSeparator = forwardRef<
     <CommandPrimitive.Separator
       ref={ref}
       data-slot="command-separator"
+      // `cmdk` renders this as a direct child of its `role="listbox"`
+      // (`CommandList`), which may only own `option`/`group` (WCAG 1.3.1,
+      // #157) — a purely visual divider between groups, so `aria-hidden`
+      // removes it from the accessibility tree instead of asking the listbox
+      // to own a role it can't. `{...props}` still lets a caller override it.
+      aria-hidden="true"
       className={cn("-mx-1 h-px bg-border", className)}
       {...props}
     />

package/src/components/command/index.ts

@@ -10,4 +10,5 @@ export {
   CommandShortcut,
   useCommandActiveItemId,
   type CommandProps,
+  type CommandDialogProps,
 } from "./command";

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

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { CommandTrigger } from "./command-trigger";
+
+const meta = {
+  title: "Navigation/CommandTrigger",
+  component: CommandTrigger,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The command-palette opener a top bar reaches for: shaped like a search field, " +
+          "collapsing to just the icon under `sm`. The visible label and the shortcut `Kbd` are " +
+          "both decorative — the accessible name is authored with `aria-label` so the shortcut " +
+          "glyph never concatenates into it (#117).",
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof CommandTrigger>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default label and platform-detected shortcut. */
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const button = within(canvasElement).getByRole("button");
+    // #117: the Kbd's shortcut glyph must not pollute the computed name.
+    await expect(button).toHaveAccessibleName("Search");
+  },
+};
+
+/** A caller-supplied label and shortcut — useful when the platform guess is wrong. */
+export const WithCustomShortcut: Story = {
+  args: {
+    label: "Find anything",
+    shortcut: "Ctrl K",
+  },
+};

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

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { CommandTrigger } from "./command-trigger";
+
+describe("CommandTrigger", () => {
+  it("announces only its label — the shortcut glyph must not pollute the accessible name", () => {
+    render(<CommandTrigger />);
+    // #117: a Kbd inside a control concatenates into the computed name. Assert the
+    // EXACT name; a regex match would happily pass on the polluted string.
+    expect(screen.getByRole("button")).toHaveAccessibleName("Search");
+  });
+
+  it("takes a custom label and shortcut", () => {
+    render(<CommandTrigger label="Find anything" shortcut="Ctrl K" />);
+    expect(screen.getByRole("button")).toHaveAccessibleName("Find anything");
+    expect(screen.getByText("Ctrl K")).toBeInTheDocument();
+  });
+});

package/src/components/command-trigger/command-trigger.tsx

@@ -0,0 +1,70 @@
+import { forwardRef, type ComponentProps } from "react";
+import { Search } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Kbd } from "../kbd";
+
+export interface CommandTriggerProps extends ComponentProps<"button"> {
+  /** The visible and announced label. Defaults to "Search". */
+  label?: string;
+  /** The shortcut hint. Defaults to the platform-correct ⌘ K / Ctrl K. */
+  shortcut?: string;
+}
+
+function platformShortcut(): string {
+  if (typeof navigator === "undefined") return "Ctrl K";
+  // `userAgentData.platform` where available, else the legacy string. Both are
+  // hints, not guarantees — the trigger is a hint too, so a wrong guess is cosmetic.
+  const platform =
+    (navigator as { userAgentData?: { platform?: string } }).userAgentData?.platform ??
+    navigator.platform ??
+    "";
+  return /mac|iphone|ipad/i.test(platform) ? "⌘ K" : "Ctrl K";
+}
+
+/**
+ * The command-palette opener, shaped like a search field: label left, shortcut
+ * pinned right, collapsing to the icon alone under `sm`.
+ *
+ * The button’s accessible name comes entirely from `aria-label` — that is what
+ * stops the `Kbd`’s shortcut glyph from concatenating into it (#117); a
+ * non-empty `aria-label` short-circuits accessible-name computation before the
+ * DOM is ever consulted. The visible label and the `Kbd` are ALSO marked
+ * `aria-hidden`, per `accessibility.md`, as defence in depth: if `aria-label`
+ * is ever dropped, that turns a silent regression into a loud one — an empty
+ * accessible name rather than a plausible wrong one. They do not do the work
+ * themselves.
+ *
+ * `shortcut` reads `navigator` at render time when omitted, which can differ
+ * between server and client — a consumer that server-renders this component
+ * should pass `shortcut` explicitly to avoid a hydration mismatch.
+ */
+export const CommandTrigger = forwardRef<HTMLButtonElement, CommandTriggerProps>(
+  function CommandTrigger({ label = "Search", shortcut, className, ...props }, ref) {
+    const hint = shortcut ?? platformShortcut();
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-slot="command-trigger"
+        aria-label={label}
+        className={cn(
+          "inline-flex h-8 items-center gap-2 rounded-md border border-input bg-background px-2 text-body text-muted-foreground",
+          "hover:bg-accent hover:text-accent-foreground focus-ring",
+          "sm:w-56 sm:justify-between sm:ps-2 sm:pe-1.5",
+          className,
+        )}
+        {...props}
+      >
+        <span className="flex min-w-0 items-center gap-2">
+          <Search aria-hidden="true" className="size-4 shrink-0" />
+          <span aria-hidden="true" className="hidden truncate sm:inline">
+            {label}
+          </span>
+        </span>
+        <Kbd aria-hidden="true" className="hidden sm:inline-flex">
+          {hint}
+        </Kbd>
+      </button>
+    );
+  },
+);

package/src/components/command-trigger/index.ts

@@ -0,0 +1 @@
+export * from "./command-trigger";