@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/input/input.stories.tsx

@@ -1,10 +1,19 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { Input } from "./input";
 
 const meta = {
   title: "Core/Input",
   component: Input,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The plain text field. A search box with a leading icon and a clear button is `Data/SearchInput`, which is built on this one; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
   args: { placeholder: "you@example.com" },
   argTypes: {
     type: {
@@ -42,3 +51,115 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {};
 export const Invalid: Story = { args: { "aria-invalid": true, defaultValue: "not-an-email" } };
 export const Disabled: Story = { args: { disabled: true, value: "Disabled" } };
+
+/**
+ * The element whose `data-theme` actually GOVERNS `el` — the nearest ancestor
+ * carrying the attribute, falling back to the document element.
+ *
+ * The earlier version of this helper guessed between `document.body` and
+ * `document.documentElement`. When the decorator wrote `data-theme` onto a
+ * wrapper closer to the story than either of those, flipping the far ancestor
+ * was a silent no-op: the nearer attribute still won the cascade, so BOTH
+ * branches of the loop below asserted in whatever theme the run had already
+ * chosen, and the docblock's "checked in both themes" claim was false. That
+ * stayed invisible until the suite was run under `STORYBOOK_THEME=dark`, where
+ * the same two branches both asserted in dark and the guard fired. Resolving
+ * the governing element from the input itself cannot drift that way.
+ */
+function themeHost(el: Element): HTMLElement {
+  return (el.closest("[data-theme]") as HTMLElement | null) ?? document.documentElement;
+}
+
+/**
+ * Regression lock for #49: `Input` must set its OWN text colour rather than
+ * inherit whatever ambient ink its container declares. Nested inside a
+ * `text-sidebar-foreground` wrapper (the `sidebar-04` mail search field's real
+ * shape), the input's resolved `color` must still match an un-nested `Input`'s
+ * — not the wrapper's near-invisible-on-`--background` sidebar ink. Runs in
+ * the Storybook browser project so `getComputedStyle` reflects the real
+ * Tailwind/token cascade (a jsdom unit test has none — `css: false` in
+ * `vitest.config.ts` — so it can only assert the class list, which would stay
+ * green even if a later change kept the class string but lost the cascade).
+ * Checked in BOTH themes via an in-place `data-theme` flip (no remount), so
+ * the fix is verified theme-safe rather than merely assumed to be from the
+ * class being additive.
+ */
+export const InAmbientTextContainer: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Input aria-label="reference input" placeholder="reference (no ambient wrapper)" />
+      <div className="text-sidebar-foreground">
+        <Input aria-label="nested input" placeholder="nested under text-sidebar-foreground" />
+      </div>
+      <div className="text-muted-foreground">
+        <Input aria-label="muted input" placeholder="nested under text-muted-foreground" />
+      </div>
+    </div>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const reference = canvas.getByLabelText<HTMLInputElement>("reference input");
+    const nested = canvas.getByLabelText<HTMLInputElement>("nested input");
+    const muted = canvas.getByLabelText<HTMLInputElement>("muted input");
+    await userEvent.type(nested, "search query");
+
+    const assertMatchesReference = async () => {
+      await waitFor(() => {
+        expect(getComputedStyle(nested).color).toBe(getComputedStyle(reference).color);
+        expect(getComputedStyle(muted).color).toBe(getComputedStyle(reference).color);
+      });
+      /*
+       * Guard against a vacuous pass: an ambient wrapper's ink must actually
+       * differ from the input's own, or this lock could never fail.
+       *
+       * The guard rides on the `text-muted-foreground` wrapper, NOT the
+       * sidebar one. `--sidebar-foreground` and `--foreground` are separate
+       * roles that happen to carry the same literal in the dark reference
+       * theme (both `oklch(0.95 0.004 257)`) — a legitimate coincidence, not
+       * an undeclared alias: light's sidebar ink is near-white because that
+       * theme's sidebar ground is DARK, and dark's is near-white because
+       * everything is. So in dark the sidebar wrapper cannot express a
+       * difference, and asserting one there is unsatisfiable.
+       * `--muted-foreground` differs from `--foreground` in both reference
+       * themes (light 0.5 vs 0.3, dark 0.72 vs 0.95), so it can carry the
+       * guard in either. The sidebar wrapper stays because it is the real
+       * shape this locks (the `sidebar-04` mail search field).
+       */
+      await expect(getComputedStyle(muted).color).not.toBe(
+        getComputedStyle(muted.parentElement!).color,
+      );
+    };
+
+    const host = themeHost(nested);
+    const original = host.getAttribute("data-theme");
+    /*
+     * Prove the flip actually took, rather than assuming it. A flip that lands
+     * on an element the cascade ignores turns the whole cross-theme claim into
+     * a no-op, which is precisely how this story passed for two themes while
+     * only ever measuring one.
+     */
+    const assertThemeApplied = async (expected: string) => {
+      await waitFor(() => {
+        expect(getComputedStyle(host).getPropertyValue("--foreground").trim()).not.toBe("");
+      });
+      expect(host.getAttribute("data-theme")).toBe(expected);
+      expect(nested.closest("[data-theme]")).toBe(host);
+    };
+
+    try {
+      host.setAttribute("data-theme", "light");
+      await assertThemeApplied("light");
+      const lightInk = getComputedStyle(nested).color;
+      await assertMatchesReference();
+
+      host.setAttribute("data-theme", "dark");
+      await assertThemeApplied("dark");
+      await assertMatchesReference();
+      // The two themes must actually resolve to different ink, or "checked in
+      // both themes" is a claim about an attribute nobody read.
+      expect(getComputedStyle(nested).color).not.toBe(lightInk);
+    } finally {
+      if (original === null) host.removeAttribute("data-theme");
+      else host.setAttribute("data-theme", original);
+    }
+  },
+};

package/src/components/input/input.test.tsx

@@ -16,4 +16,17 @@ describe("Input", () => {
     const el = screen.getByLabelText<HTMLInputElement>("email");
     expect(el).toBeDisabled();
   });
+
+  it("applies text-foreground class to ensure text color is not inherited from parent", () => {
+    // Render Input inside a container with a different text color (simulating sidebar)
+    render(
+      <div className="text-sidebar-foreground">
+        <Input aria-label="search" />
+      </div>,
+    );
+    const el = screen.getByLabelText<HTMLInputElement>("search");
+    // Verify that the Input element has the text-foreground class
+    // This ensures its text color is explicitly set and not inherited
+    expect(el.className).toContain("text-foreground");
+  });
 });

package/src/components/input/input.tsx

@@ -12,12 +12,16 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
       ref={ref}
       type={type}
       className={cn(
-        "flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
+        "flex h-control w-full rounded-control border border-input bg-input-background text-foreground px-3 py-1 text-body shadow-input transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
         "placeholder:text-muted-foreground",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
-        "disabled:cursor-not-allowed disabled:opacity-50 disabled:bg-muted disabled:border-border",
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        // One disabled mechanism (opacity fade), matching every `Button`
+        // variant — `disabled:bg-muted` used to also fire here, stacking a
+        // fill swap on top of the fade (#286); `disabled:border-border` stays,
+        // it is the separate/subtle "not editable" edge, not a fill.
+        "disabled:cursor-not-allowed disabled:opacity-50 disabled:border-border",
         "aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive",
-        "file:border-0 file:bg-transparent file:text-sm file:font-medium",
+        "file:border-0 file:bg-transparent file:text-body file:font-medium",
         className,
       )}
       {...props}

package/src/components/input-group/input-group.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { Search } from "lucide-react";
 import {
   InputGroup,
@@ -85,3 +86,76 @@ export const Card: Story = {
     </div>
   ),
 };
+
+/**
+ * Regression lock for #67 (fix round 2) — the compound focus indicator must be
+ * ONE mark on ONE element.
+ *
+ * `InputGroup` delegates its indicator to the wrapper, because the control is
+ * borderless and full-bleed and a ring around IT would be drawn inside the
+ * well. Before this lock the delegation was only half done and the indicator
+ * split across two elements: the wrapper painted the brand ring and no contour
+ * (its own base `outline-none` set `--tw-outline-style: none`, and a following
+ * `outline-1` re-declared `outline-style` from that variable), while the inner
+ * control painted the contour and no ring, ~10px inside, at a different radius.
+ * On light that read as a stray dark rectangle across the composer, and the
+ * well kept the 1.23:1 un-contoured lime ring #67 exists to remove.
+ *
+ * THE ASSERTION IS ON COMPUTED STYLE, NOT ON THE CLASS STRING. The class string
+ * was already "correct" while the bug shipped — `has-[…]:focus-ring-static` was
+ * present and cancelled by a sibling utility — so a class-name assertion (or a
+ * jsdom unit test, which has no CSS at all: `css: false` in `vitest.config.ts`)
+ * stays green through the exact regression this locks. It therefore lives in
+ * the Storybook browser project, where `getComputedStyle` reflects the real
+ * Tailwind cascade.
+ */
+export const CompoundFocusIndicator: Story = {
+  tags: ["!autodocs"],
+  render: () => (
+    <InputGroup className="max-w-sm">
+      <InputGroupAddon>
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput aria-label="locked control" placeholder="Search…" />
+    </InputGroup>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const control = canvas.getByLabelText<HTMLInputElement>("locked control");
+    const wrapper = control.closest<HTMLElement>("[data-slot=input-group]")!;
+    await userEvent.tab();
+    await expect(control).toHaveFocus();
+
+    /*
+     * Settle past `transition-colors`: reading immediately after focus catches
+     * `outline-color` mid-transition and reports the element's own ink instead
+     * of the contour token. That artefact is why the utility now declares
+     * `outline-color` at rest (themes.css); the wait keeps this lock honest
+     * about which property it is measuring.
+     */
+    await waitFor(() => {
+      const w = getComputedStyle(wrapper);
+      // The wrapper owns BOTH layers.
+      expect(w.outlineStyle).not.toBe("none");
+      expect(w.outlineWidth).toBe("1px");
+      expect(ringSpread(w)).toBeGreaterThan(0);
+      // …and they are flush: the contour sits exactly on the ring's outer edge.
+      expect(parseFloat(w.outlineOffset)).toBe(ringSpread(w));
+    });
+
+    // The control paints NEITHER layer — no second mark inside the well.
+    const c = getComputedStyle(control);
+    await expect(c.outlineStyle).toBe("none");
+    await expect(ringSpread(c)).toBe(0);
+  },
+};
+
+/**
+ * `--tw-ring-shadow` is a `0 0 0 calc(<offset> + <width>) <colour>` string; the
+ * painted reach is that `calc`. Reading it (rather than `boxShadow`) keeps the
+ * measurement independent of whatever elevation rung the element also carries.
+ */
+function ringSpread(style: CSSStyleDeclaration): number {
+  const shadow = style.getPropertyValue("--tw-ring-shadow");
+  const match = /calc\(\s*([\d.]+)px\s*\+\s*([\d.]+)px\s*\)/.exec(shadow);
+  return match ? parseFloat(match[1]) + parseFloat(match[2]) : 0;
+}

package/src/components/input-group/input-group.tsx

@@ -7,12 +7,21 @@ import { Textarea } from "../textarea";
 
 export const inputGroupVariants = cva(
   cn(
-    "group/input-group relative flex w-full flex-wrap items-center rounded-md outline-none transition-[color,box-shadow] duration-fast ease-standard",
+    "group/input-group relative flex w-full flex-wrap items-center rounded-control transition-[color,box-shadow] duration-fast ease-standard",
     // Grow to fit a textarea even when it's nested (e.g. wrapped in a
     // `display:contents` body like PromptInputBody). `:has(>textarea)`
     // misses through that wrapper, so match any descendant textarea.
-    "h-9 has-[textarea]:h-auto",
-    "has-[[data-slot=input-group-control]:focus-visible]:ring-2 has-[[data-slot=input-group-control]:focus-visible]:ring-ring has-[[data-slot=input-group-control]:focus-visible]:ring-offset-1 has-[[data-slot=input-group-control]:focus-visible]:ring-offset-background",
+    "h-control has-[textarea]:h-auto",
+    // The compound indicator is the wrapper's, not the control's — the control
+    // is borderless and full-bleed, so a ring around IT would draw inside the
+    // well. `focus-ring-static` paints BOTH layers; the only geometry knob is
+    // `ring-offset-1`, which `outline-offset: calc(--tw-ring-offset-width + 2px)`
+    // tracks so ring and contour stay flush at the same radius. Do NOT add an
+    // `outline-*` utility here: `outline-1` re-declares
+    // `outline-style: var(--tw-outline-style)`, which `outline-none` on this
+    // same element used to pin to `none` — that pairing shipped, and it cancelled
+    // the contour on every composer, NumberInput and TagInput (#67 fix round 2).
+    "has-[[data-slot=input-group-control]:focus-visible]:focus-ring-static has-[[data-slot=input-group-control]:focus-visible]:ring-offset-1 has-[[data-slot=input-group-control]:focus-visible]:ring-offset-background",
     "has-[[data-slot=input-group-control][aria-invalid=true]]:ring-2 has-[[data-slot=input-group-control][aria-invalid=true]]:ring-destructive",
   ),
   {
@@ -20,7 +29,7 @@ export const inputGroupVariants = cva(
       variant: {
         // The form-field look: the strong `--input` boundary is the field's
         // sole structural cue, so it stays on the strong rung.
-        outline: "border border-input shadow-sm",
+        outline: "border border-input shadow-input",
         // The composer look (#194, research 08 §C.1/§D): a soft fill with the
         // focus-within ring carrying focus — NO hard border. Separation comes
         // from the fill (the chat footer already draws its own `border-t`).
@@ -59,7 +68,7 @@ export const InputGroup = forwardRef<HTMLDivElement, InputGroupProps>(function I
 });
 
 export const inputGroupAddonVariants = cva(
-  "flex h-auto cursor-text items-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none [&>svg:not([class*='size-'])]:size-4",
+  "flex h-auto cursor-text items-center gap-2 py-1.5 text-body font-medium text-muted-foreground select-none [&>svg:not([class*='size-'])]:size-4",
   {
     variants: {
       align: {
@@ -89,7 +98,7 @@ export const InputGroupAddon = forwardRef<
   );
 });
 
-const inputGroupButtonVariants = cva("flex items-center gap-2 text-sm shadow-none", {
+const inputGroupButtonVariants = cva("flex items-center gap-2 text-body shadow-none", {
   variants: {
     size: {
       xs: "h-6 gap-1 rounded-sm px-2 has-[>svg]:px-2 [&>svg:not([class*='size-'])]:size-3.5",
@@ -128,7 +137,7 @@ export const InputGroupText = forwardRef<HTMLSpanElement, ComponentProps<"span">
       <span
         ref={ref}
         className={cn(
-          "flex items-center gap-2 text-sm text-muted-foreground [&_svg:not([class*='size-'])]:size-4",
+          "flex items-center gap-2 text-body text-muted-foreground [&_svg:not([class*='size-'])]:size-4",
           className,
         )}
         {...props}
@@ -144,7 +153,7 @@ export const InputGroupInput = forwardRef<HTMLInputElement, ComponentProps<typeo
         ref={ref}
         data-slot="input-group-control"
         className={cn(
-          "flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:ring-0 focus-visible:ring-offset-0",
+          "flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
           className,
         )}
         {...props}
@@ -160,7 +169,7 @@ export const InputGroupTextarea = forwardRef<HTMLTextAreaElement, ComponentProps
         ref={ref}
         data-slot="input-group-control"
         className={cn(
-          "flex-1 resize-none rounded-none border-0 bg-transparent py-2.5 shadow-none focus-visible:ring-0 focus-visible:ring-offset-0",
+          "flex-1 resize-none rounded-none border-0 bg-transparent py-2.5 shadow-none focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
           className,
         )}
         {...props}

package/src/components/input-otp/input-otp.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { forwardRef, useContext, type ComponentPropsWithoutRef, type ElementRef } from "react";
 import { OTPInput, OTPInputContext } from "input-otp";
 import { Minus } from "lucide-react";
@@ -41,8 +43,12 @@ export const InputOTPSlot = forwardRef<
     <div
       ref={ref}
       className={cn(
-        "relative flex size-9 items-center justify-center border-y border-e border-input text-sm shadow-sm transition-[color,border-color,box-shadow] duration-fast ease-standard first:rounded-s-md first:border-s last:rounded-e-md",
-        isActive && "z-10 ring-2 ring-ring",
+        "relative flex size-9 items-center justify-center border-y border-e border-input text-body shadow-sm transition-[color,border-color,box-shadow] duration-fast ease-standard first:rounded-s-md first:border-s last:rounded-e-md",
+        // The OTP slot IS the field's focus indicator: the real focused element is
+        // InputOTP's visually-hidden <input>, and `isActive` is the caret's slot. It
+        // therefore carries the compound indicator (#67) — the state is JS-driven, so
+        // it is the `-static` flavour rather than a `:focus-visible` one.
+        isActive && "z-10 focus-ring-static",
         className,
       )}
       {...props}

package/src/components/keyboard-shortcuts/index.ts

@@ -0,0 +1,6 @@
+export {
+  KeyboardShortcuts,
+  type KeyboardShortcutsProps,
+  type Shortcut,
+  type ShortcutGroup,
+} from "./keyboard-shortcuts";

package/src/components/keyboard-shortcuts/keyboard-shortcuts.stories.tsx

@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { useState } from "react";
+import { KeyboardShortcuts, type ShortcutGroup } from "./keyboard-shortcuts";
+
+const groups: ShortcutGroup[] = [
+  {
+    id: "navigation",
+    label: "Navigation",
+    defaultOpen: true,
+    items: [
+      { action: "Open command palette", keys: ["⌘", "K"] },
+      { action: "Go to file", keys: ["⌘", "P"] },
+      { action: "Go to line", keys: ["⌘", "G"] },
+    ],
+  },
+  {
+    id: "general",
+    label: "General",
+    items: [
+      { action: "Close tab", keys: ["⌘", "W"] },
+      { action: "Save", keys: ["⌘", "S"] },
+      { action: "New window", keys: ["⌘", "⇧", "N"] },
+    ],
+  },
+  {
+    id: "editing",
+    label: "Editing",
+    items: [
+      { action: "Duplicate line", keys: ["⌘", "⇧", "D"] },
+      { action: "Comment line", keys: ["⌘", "/"] },
+    ],
+  },
+];
+
+const meta = {
+  title: "Disclosure/KeyboardShortcuts",
+  component: KeyboardShortcuts,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A grouped, searchable presentation of a shortcut set. Renders content only — " +
+          "the app supplies the Dialog/Sheet shell, so the same component works in a modal, " +
+          "a settings page or a sidebar. Group counts are always derived from `items.length` " +
+          "(or the number of matching items while filtering), never passed in.",
+      },
+    },
+  },
+  argTypes: {
+    groups: {
+      description:
+        "Shortcut groups (`ShortcutGroup[]`). Each group's displayed count is derived from `items.length`.",
+      control: false,
+      table: { category: "Content" },
+    },
+    searchable: {
+      description: "Show the built-in search field.",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    query: {
+      description: "Controlled search query, if the app owns it.",
+      control: "text",
+      table: { category: "State" },
+    },
+    onQueryChange: {
+      description: "Callback fired when the search query changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+  args: {
+    groups,
+  },
+} satisfies Meta<typeof KeyboardShortcuts>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} />
+    </div>
+  ),
+};
+
+/** Typing a query hides non-matching groups and re-derives the visible group's count. */
+export const Filtered: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} query="close" />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    // Only "General" contains a "Close tab" action — the other two groups hide entirely.
+    await expect(canvas.getByText("General")).toBeInTheDocument();
+    await expect(canvas.queryByText("Navigation")).not.toBeInTheDocument();
+    await expect(canvas.queryByText("Editing")).not.toBeInTheDocument();
+    // The visible group's badge reflects the single matching item, not its total (3).
+    await expect(canvas.getByText("1")).toBeInTheDocument();
+    await expect(canvas.getByText("Close tab")).toBeInTheDocument();
+  },
+};
+
+/** A query that matches nothing renders a designed empty message, not a blank area. */
+export const NoMatches: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} query="xyz-nonexistent" />
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("No shortcuts found")).toBeInTheDocument();
+  },
+};
+
+/** Uncontrolled search — the app doesn't own the query; the component manages it internally. */
+export const Uncontrolled: Story = {
+  args: {
+    groups,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} />
+    </div>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const input = canvas.getByLabelText("Search shortcuts");
+    await userEvent.type(input, "save");
+    await expect(canvas.getByText("General")).toBeInTheDocument();
+    await expect(canvas.queryByText("Navigation")).not.toBeInTheDocument();
+  },
+};
+
+/** The app owns the query — e.g. it lives alongside a `Dialog` header search field. */
+export const ControlledQuery: Story = {
+  render: () => {
+    function Demo() {
+      const [query, setQuery] = useState("");
+      return (
+        <div className="w-96">
+          <KeyboardShortcuts groups={groups} query={query} onQueryChange={setQuery} />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/** No search field — just the grouped, collapsible list. */
+export const NotSearchable: Story = {
+  args: {
+    groups,
+    searchable: false,
+  },
+  render: (args) => (
+    <div className="w-96">
+      <KeyboardShortcuts {...args} />
+    </div>
+  ),
+};

package/src/components/keyboard-shortcuts/keyboard-shortcuts.test.tsx

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { KeyboardShortcuts, type ShortcutGroup } from "./keyboard-shortcuts";
+
+const groups: ShortcutGroup[] = [
+  {
+    id: "navigation",
+    label: "Navigation",
+    items: [
+      { action: "Open command palette", keys: ["⌘", "K"] },
+      { action: "Go to file", keys: ["⌘", "P"] },
+    ],
+  },
+  {
+    id: "general",
+    label: "General",
+    items: [
+      { action: "Close tab", keys: ["⌘", "W"] },
+      { action: "Save", keys: ["⌘", "S"] },
+      { action: "New window", keys: ["⌘", "⇧", "N"] },
+    ],
+  },
+];
+
+describe("KeyboardShortcuts", () => {
+  it("renders every group with a count derived from items.length", () => {
+    render(<KeyboardShortcuts groups={groups} searchable={false} />);
+    expect(screen.getByText("Navigation")).toBeInTheDocument();
+    expect(screen.getByText("General")).toBeInTheDocument();
+    // "Navigation" has 2 items, "General" has 3 — neither count was passed in.
+    expect(screen.getByText("2")).toBeInTheDocument();
+    expect(screen.getByText("3")).toBeInTheDocument();
+  });
+
+  it("a query matching only one group hides the others, and derives the visible group's count from the matches", () => {
+    render(<KeyboardShortcuts groups={groups} query="close" />);
+
+    // Only "General" has an item matching "close" — "Navigation" is hidden entirely,
+    // not rendered empty.
+    expect(screen.getByText("General")).toBeInTheDocument();
+    expect(screen.queryByText("Navigation")).not.toBeInTheDocument();
+
+    // The visible group's displayed count is the number of MATCHING items (1),
+    // never its total item count (3) — this is the "count is derived" lock.
+    expect(screen.getByText("1")).toBeInTheDocument();
+    expect(screen.queryByText("3")).not.toBeInTheDocument();
+    expect(screen.getByText("Close tab")).toBeInTheDocument();
+  });
+
+  it("matches on key tokens as well as action text", () => {
+    render(<KeyboardShortcuts groups={groups} query="⇧" />);
+    expect(screen.getByText("General")).toBeInTheDocument();
+    expect(screen.queryByText("Navigation")).not.toBeInTheDocument();
+    expect(screen.getByText("New window")).toBeInTheDocument();
+  });
+
+  it("renders a designed empty message, not a blank area, when nothing matches", () => {
+    render(<KeyboardShortcuts groups={groups} query="does-not-exist" />);
+    expect(screen.queryByText("Navigation")).not.toBeInTheDocument();
+    expect(screen.queryByText("General")).not.toBeInTheDocument();
+    expect(screen.getByText("No shortcuts found")).toBeInTheDocument();
+  });
+
+  it("supports an uncontrolled query without a query prop", () => {
+    render(<KeyboardShortcuts groups={groups} />);
+    expect(screen.getByLabelText("Search shortcuts")).toHaveValue("");
+  });
+
+  it("renders no search field when searchable is false", () => {
+    render(<KeyboardShortcuts groups={groups} searchable={false} />);
+    expect(screen.queryByLabelText("Search shortcuts")).not.toBeInTheDocument();
+  });
+});