@elabs-ai/components-ui 4.0.0

package/src/components/calendar/calendar.test.tsx

@@ -0,0 +1,140 @@
+import type { ReactElement } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import { Calendar } from "./calendar";
+import { Default as DefaultCalendarStory } from "./calendar.stories";
+
+/** Class list of an element, safe for SVG (whose `className` is not a string). */
+function classes(el: Element) {
+  return (el.getAttribute("class") ?? "").split(/\s+/);
+}
+
+/** Walks up from `el` looking for a `relative` ancestor at or below `root`. */
+function hasPositionedAncestorWithin(el: Element, root: Element) {
+  let node = el.parentElement;
+  while (node) {
+    if (classes(node).includes("relative")) return true;
+    if (node === root) return false;
+    node = node.parentElement;
+  }
+  return false;
+}
+
+describe("Calendar", () => {
+  it("renders a month grid", () => {
+    render(<Calendar mode="single" />);
+    expect(screen.getByRole("grid")).toBeInTheDocument();
+  });
+
+  it("renders both month-navigation buttons", () => {
+    render(<Calendar mode="single" />);
+    expect(screen.getByRole("button", { name: /previous month/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /next month/i })).toBeInTheDocument();
+  });
+
+  // react-day-picker v9 renders <nav> as a SIBLING of the month (not inside the
+  // caption, as v8 did). Any absolutely-positioned part must therefore be anchored
+  // by a `relative` ancestor INSIDE the calendar — otherwise it escapes to whatever
+  // positioned ancestor the page happens to have, and the nav buttons fly to the
+  // corners of the viewport / popover.
+  it("anchors every absolutely-positioned part inside the calendar", () => {
+    const { container } = render(<Calendar mode="single" />);
+    const root = container.firstElementChild as HTMLElement;
+    const absolute = [...root.querySelectorAll("*")].filter((el) =>
+      classes(el).includes("absolute"),
+    );
+
+    expect(absolute.length).toBeGreaterThan(0);
+    for (const el of absolute) {
+      expect(hasPositionedAncestorWithin(el, root)).toBe(true);
+    }
+  });
+
+  it("keeps the navigation in the caption row, not in the page flow above it", () => {
+    const { container } = render(<Calendar mode="single" />);
+    const nav = container.querySelector("nav");
+    expect(nav).not.toBeNull();
+    // The nav overlays the caption row; the buttons themselves stay in normal
+    // flow inside it, so they can never be positioned against an outside ancestor.
+    expect(nav?.className).toContain("absolute");
+    for (const button of nav?.querySelectorAll("button") ?? []) {
+      expect(classes(button)).not.toContain("absolute");
+    }
+  });
+});
+
+// #430 — `forms-calendar--default` used to seed its selected day from
+// `new Date()`, so the calendar cell axe scored for `color-contrast` had 1
+// character on days 1-9 and 2 characters on days 10-31 of the *host machine's*
+// calendar. axe-core's `color-contrast` rule reports single-character text as
+// `incomplete` (`shortTextContent`) rather than scoring it, and `incomplete`
+// results never fail `toHaveNoViolations()` — so the story was red on ~22 days
+// a month and green on ~9, entirely independent of any code change.
+//
+// This lock renders the STORY's actual `Default.render()` output (not a
+// hand-rolled `<Calendar>`) under two faked system clocks, so it fails against
+// the pre-fix story (whose `selected` tracked `new Date()`) and passes once
+// the story pins `selected`/`defaultMonth` instead. It proves the fixture is
+// what it claims to be: (a) genuinely independent of the wall clock, and (b)
+// pinned to a TWO-digit day specifically, so the a11y assertion stays capable
+// of failing rather than being silently routed into axe's unscoreable-text
+// path. The real, accepted 4.31:1 ink pair this cell renders
+// (`--primary-foreground` on `--primary`, light) is `INK_EXEMPT` in
+// `packages/tokens/src/themes-contrast.test.ts` (#180) — fixing that colour is
+// explicitly out of scope here.
+describe("Calendar — story fixture is clock-independent (#430)", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // CSF3 story `render` fns are typed `(args, context) => ReactNode`, but this
+  // one (like most in this repo) ignores both, calls `useState`, and reads only
+  // component state — i.e. it has the exact shape of a function component. It
+  // must be mounted as JSX (`<StoryComponent />`), not invoked directly:
+  // calling it as a plain function runs its hooks outside of React's render
+  // cycle ("Invalid hook call"), since Storybook itself always mounts `render`
+  // through the same component tree, never calls it as a helper.
+  const StoryComponent = DefaultCalendarStory.render as unknown as () => ReactElement;
+
+  function renderDefaultCalendarStory() {
+    const { container } = render(<StoryComponent />);
+    const scope = within(container);
+    const caption = scope.getByRole("status");
+    const selectedCell = container.querySelector('[role="gridcell"][aria-selected="true"]');
+    const selectedButton = selectedCell?.querySelector("button") ?? null;
+
+    return {
+      captionText: caption.textContent,
+      selectedAriaLabel: selectedButton?.getAttribute("aria-label") ?? null,
+      selectedDayText: selectedButton?.textContent ?? "",
+    };
+  }
+
+  it("renders identically whether the system clock reads a single- or a two-digit day", () => {
+    // Neither faked date is the pinned selected day (2026-08-17) itself — react-day-picker
+    // legitimately prefixes the selected cell's aria-label with "Today, " when the
+    // system clock's date happens to match it, which is correct "today" behavior, not
+    // the bug under test. Picking two dates that are never "today" isolates the thing
+    // this lock exists to catch: the rendered day/caption tracking the clock at all.
+    vi.setSystemTime(new Date(2026, 7, 5)); // single-digit "today" — must not matter
+    const fromSingleDigitToday = renderDefaultCalendarStory();
+
+    vi.setSystemTime(new Date(2026, 10, 10)); // two-digit "today", different month — must not matter either
+    const fromTwoDigitToday = renderDefaultCalendarStory();
+
+    expect(fromTwoDigitToday.captionText).toBe(fromSingleDigitToday.captionText);
+    expect(fromTwoDigitToday.selectedAriaLabel).toBe(fromSingleDigitToday.selectedAriaLabel);
+    expect(fromTwoDigitToday.selectedDayText).toBe(fromSingleDigitToday.selectedDayText);
+  });
+
+  // The load-bearing assertion: the check above alone would still pass if
+  // someone "fixed" the flake by pinning the selected day to the 5th instead
+  // of the 17th — two renders of a single-digit day also match each other.
+  // Only this digit-count check catches that regression.
+  it("pins the selected day's rendered text to 2+ digits (10-31), not 1", () => {
+    vi.setSystemTime(new Date(2026, 7, 5));
+    const { selectedDayText } = renderDefaultCalendarStory();
+
+    expect(selectedDayText.length).toBeGreaterThanOrEqual(2);
+  });
+});

package/src/components/calendar/calendar.tsx

@@ -0,0 +1,70 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { DayPicker } from "react-day-picker";
+import { cn } from "../../lib/cn";
+import { buttonVariants } from "../button";
+
+export type CalendarProps = React.ComponentProps<typeof DayPicker>;
+
+/** Date picker calendar (react-day-picker v9), themed with brand tokens. */
+export function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  ...props
+}: CalendarProps) {
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn("p-3", className)}
+      classNames={{
+        // `months` is the positioning context for the nav overlay below: in
+        // react-day-picker v9 the <nav> is a SIBLING of the month(s), not a child
+        // of the caption, so the caption cannot anchor it.
+        months: "relative flex flex-col gap-2 sm:flex-row",
+        month: "flex flex-col gap-4",
+        // `min-h-7` matches the nav button row so the two align; it can still grow
+        // for a taller caption (e.g. `captionLayout="dropdown"`), and `px-8` keeps
+        // the label clear of the buttons overlaying either edge.
+        month_caption: "flex min-h-7 items-center justify-center px-8",
+        caption_label: "text-sm font-medium",
+        // Overlays the caption row and pushes the buttons to either edge; the
+        // buttons themselves stay in normal flow inside it.
+        nav: "absolute inset-x-0 top-0 flex h-7 items-center justify-between",
+        button_previous: cn(
+          buttonVariants({ variant: "outline" }),
+          "size-7 bg-transparent p-0 opacity-50 hover:opacity-100",
+        ),
+        button_next: cn(
+          buttonVariants({ variant: "outline" }),
+          "size-7 bg-transparent p-0 opacity-50 hover:opacity-100",
+        ),
+        month_grid: "w-full border-collapse space-y-1",
+        weekdays: "flex",
+        weekday: "w-8 rounded-md text-[0.8rem] font-normal text-muted-foreground",
+        week: "mt-2 flex w-full",
+        day: "relative size-8 p-0 text-center text-sm focus-within:relative focus-within:z-20 [&:has([aria-selected])]:bg-accent [&:has([aria-selected].day-range-end)]:rounded-e-md first:[&:has([aria-selected])]:rounded-s-md last:[&:has([aria-selected])]:rounded-e-md",
+        day_button: cn(
+          buttonVariants({ variant: "ghost" }),
+          "size-8 p-0 font-normal aria-selected:opacity-100",
+        ),
+        range_start: "day-range-start rounded-s-md",
+        range_end: "day-range-end rounded-e-md",
+        range_middle: "aria-selected:bg-accent aria-selected:text-accent-foreground",
+        selected:
+          "bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground focus:bg-primary focus:text-primary-foreground",
+        today: "bg-accent text-accent-foreground",
+        outside: "day-outside text-muted-foreground aria-selected:text-muted-foreground",
+        disabled: "text-muted-foreground opacity-50",
+        hidden: "invisible",
+        ...classNames,
+      }}
+      components={{
+        Chevron: ({ orientation }) => {
+          const Icon = orientation === "left" ? ChevronLeft : ChevronRight;
+          return <Icon className="size-4" data-rtl-flip />;
+        },
+      }}
+      {...props}
+    />
+  );
+}

package/src/components/calendar/index.ts

@@ -0,0 +1 @@
+export { Calendar, type CalendarProps } from "./calendar";

package/src/components/card/card.stories.tsx

@@ -0,0 +1,438 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent } from "storybook/test";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./card";
+
+const meta = {
+  title: "Core/Card",
+  component: Card,
+  tags: ["autodocs"],
+  argTypes: {
+    interactive: {
+      description:
+        "Opt-in hover-lift for clickable cards (motion-tokened, respects reduced-motion).",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    detail: {
+      description: "Optional detail-panel content (ReactNode). Undefined = plain card.",
+      control: false,
+      table: { category: "Content" },
+    },
+    detailPlacement: {
+      description: "Which edge the detail panel sits on.",
+      control: { type: "radio" },
+      options: ["side", "bottom"],
+      table: { category: "Appearance" },
+    },
+    detailReveal: {
+      description: "`fixed` — always visible; `hover` — revealed on hover and focus-within.",
+      control: { type: "radio" },
+      options: ["fixed", "hover"],
+      table: { category: "Behavior" },
+    },
+    detailSize: {
+      description:
+        'CSS length for the detail track (e.g. `"16rem"`). Defaults to 16rem (side) / auto (bottom).',
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    detailLabel: {
+      description: 'Accessible label for the detail region (aria-label). Default: "Details".',
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn().",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Card>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Card className="max-w-sm">
+      <CardHeader>
+        <CardTitle>Monthly active users</CardTitle>
+        <CardDescription>Across all workspaces</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="text-display font-semibold">24,512</div>
+      </CardContent>
+      <CardFooter>
+        <span className="text-body text-muted-foreground">+12.4% vs last month</span>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+/** Opt-in hover-lift for clickable cards (gated by the motion system). */
+export const Interactive: Story = {
+  render: () => (
+    <Card interactive className="max-w-sm" tabIndex={0} role="button">
+      <CardHeader>
+        <CardTitle>Production pipeline</CardTitle>
+        <CardDescription>Hover or focus — lifts over the gated duration</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <span className="text-body text-muted-foreground">Last run 4m ago · 1.2M rows</span>
+      </CardContent>
+    </Card>
+  ),
+  play: async ({ canvas }) => {
+    const card = canvas.getByRole("button");
+    const cs = getComputedStyle(card);
+    // The lift uses Tailwind v4's standalone `translate` property — the
+    // transition MUST list `translate` (not the `transform` shorthand) or it
+    // snaps instead of gliding. Guards against the v4 transform-split gotcha.
+    await expect(cs.transitionProperty).toContain("translate");
+    await expect(parseFloat(cs.transitionDuration)).toBeGreaterThanOrEqual(0.2); // gated --t-base
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Detail panel stories (#118 DP-01)
+// Each story is wrapped in a sized parent so the grid layout has a defined
+// height/width to work with (side panels need a concrete height).
+// ---------------------------------------------------------------------------
+
+/** Side panel always visible (default detailReveal). */
+export const DetailSideFixed: Story = {
+  render: () => (
+    <div className="h-64 w-[480px]">
+      <Card
+        className="h-full"
+        detail={
+          <div className="flex flex-col gap-2">
+            <p className="text-meta font-semibold text-muted-foreground uppercase tracking-wide">
+              Metadata
+            </p>
+            <ul className="text-body text-foreground space-y-1">
+              <li className="flex justify-between">
+                <span className="text-muted-foreground">Owner</span>
+                <span>analytics-team</span>
+              </li>
+              <li className="flex justify-between">
+                <span className="text-muted-foreground">Updated</span>
+                <span>2 days ago</span>
+              </li>
+              <li className="flex justify-between">
+                <span className="text-muted-foreground">Rows</span>
+                <span>1.2M</span>
+              </li>
+            </ul>
+          </div>
+        }
+        detailPlacement="side"
+        detailReveal="fixed"
+      >
+        <CardHeader>
+          <CardTitle>Sales pipeline</CardTitle>
+          <CardDescription>Q2 2026 opportunities</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="text-display font-semibold">$4.7M</div>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+/** Side panel revealed on hover / keyboard focus-within (outer card size stays constant). */
+export const DetailSideHover: Story = {
+  render: () => (
+    <div className="h-64 w-[480px]">
+      <Card
+        className="h-full"
+        detail={
+          <div className="flex flex-col gap-2">
+            <p className="text-meta font-semibold text-muted-foreground uppercase tracking-wide">
+              Quick actions
+            </p>
+            <ul className="text-body space-y-1">
+              <li>
+                <button className="text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm px-1">
+                  View report
+                </button>
+              </li>
+              <li>
+                <button className="text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm px-1">
+                  Export CSV
+                </button>
+              </li>
+              <li>
+                <button className="text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm px-1">
+                  Share
+                </button>
+              </li>
+            </ul>
+          </div>
+        }
+        detailPlacement="side"
+        detailReveal="hover"
+      >
+        <CardHeader>
+          <CardTitle>Revenue report</CardTitle>
+          <CardDescription>Hover or tab into the card to reveal actions</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="text-display font-semibold">$182K</div>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+/** Bottom panel always visible. */
+export const DetailBottomFixed: Story = {
+  render: () => (
+    <div className="h-80 w-96">
+      <Card
+        className="h-full"
+        detail={
+          <div className="flex items-center gap-4">
+            <span className="text-body text-muted-foreground">Last synced 5 min ago</span>
+            <span className="ms-auto rounded-full bg-surface px-2 py-0.5 text-meta border border-border text-foreground">
+              Live
+            </span>
+          </div>
+        }
+        detailPlacement="bottom"
+        detailReveal="fixed"
+        detailSize="3.5rem"
+      >
+        <CardHeader>
+          <CardTitle>Active sessions</CardTitle>
+          <CardDescription>Across all regions</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="text-display font-semibold">8,340</div>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+/** Bottom panel revealed on hover / keyboard focus-within. */
+export const DetailBottomHover: Story = {
+  render: () => (
+    <div className="h-80 w-96">
+      <Card
+        className="h-full"
+        detail={
+          <div className="flex items-center gap-3">
+            <button className="text-body text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm px-1">
+              Drill down
+            </button>
+            <button className="text-body text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm px-1">
+              Download
+            </button>
+          </div>
+        }
+        detailPlacement="bottom"
+        detailReveal="hover"
+        detailSize="3rem"
+      >
+        <CardHeader>
+          <CardTitle>Ingest volume</CardTitle>
+          <CardDescription>Hover to reveal bottom actions</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="text-display font-semibold">94 GB/hr</div>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+/** Proves `interactive` (hover-lift) and `detail` panel coexist without conflict. */
+export const InteractiveWithDetail: Story = {
+  render: () => (
+    <div className="h-64 w-[480px]">
+      <Card
+        className="h-full"
+        interactive
+        tabIndex={0}
+        role="button"
+        detail={
+          <div className="flex flex-col gap-2">
+            <p className="text-meta font-semibold text-muted-foreground uppercase tracking-wide">
+              Details
+            </p>
+            <ul className="text-body space-y-1">
+              <li className="flex justify-between">
+                <span className="text-muted-foreground">Status</span>
+                <span className="text-foreground">Healthy</span>
+              </li>
+              <li className="flex justify-between">
+                <span className="text-muted-foreground">SLA</span>
+                <span className="text-foreground">99.9%</span>
+              </li>
+            </ul>
+          </div>
+        }
+        detailPlacement="side"
+        detailReveal="fixed"
+      >
+        <CardHeader>
+          <CardTitle>Data pipeline</CardTitle>
+          <CardDescription>Interactive card with a fixed side panel</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <span className="text-body text-muted-foreground">
+            Hover to lift · detail always visible
+          </span>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const card = canvas.getByRole("button");
+    // Both interactive lift AND detail panel are rendered — card is in the DOM.
+    await expect(card).toBeInTheDocument();
+    const cs = getComputedStyle(card);
+    await expect(cs.transitionProperty).toContain("translate");
+  },
+};
+
+/**
+ * `CardTitle` defaults to a `<div>` (unchanged) but accepts `as` to render a
+ * real heading (`h1`-`h6`) so a page built from cards contributes to the
+ * document outline (#328). Visual is identical across every tag — only the
+ * underlying element and its accessible heading level change.
+ */
+export const HeadingLevels: Story = {
+  render: () => (
+    <div className="flex max-w-sm flex-col gap-4">
+      <Card>
+        <CardHeader>
+          <CardTitle>Default — a plain div (no change)</CardTitle>
+          <CardDescription>Not reachable via heading navigation</CardDescription>
+        </CardHeader>
+      </Card>
+      <Card>
+        <CardHeader>
+          <CardTitle as="h2">as=&quot;h2&quot; — a real heading</CardTitle>
+          <CardDescription>Reachable via AT heading navigation at level 2</CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    // Default stays a div — no accessible heading for that title.
+    await expect(
+      canvas.queryByRole("heading", { name: /Default — a plain div/ }),
+    ).not.toBeInTheDocument();
+    // `as="h2"` produces a real, level-2 heading.
+    const heading = canvas.getByRole("heading", { level: 2, name: /a real heading/ });
+    await expect(heading.tagName).toBe("H2");
+  },
+};
+
+/**
+ * `CardDescription` gains an opt-in `measure` prop that caps genuine prose to
+ * a readable line length (`max-w-prose`, ~65ch) instead of running edge to
+ * edge in a wide card (#339). Off by default — short subtitle-style
+ * descriptions stay full width.
+ */
+export const DescriptionMeasure: Story = {
+  render: () => (
+    <div className="flex w-[1000px] flex-col gap-6">
+      <Card className="w-full">
+        <CardHeader>
+          <CardTitle>Uncapped (default)</CardTitle>
+          <CardDescription>
+            This paragraph runs the full width of a very wide card, which makes it materially harder
+            to read once a line gets long enough — there is no natural place for the eye to return
+            to the start of the next line, so reading speed and comprehension both suffer on wide
+            viewports.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+      <Card className="w-full">
+        <CardHeader>
+          <CardTitle>Capped via `measure`</CardTitle>
+          <CardDescription measure>
+            This paragraph is capped to a readable prose measure even inside a very wide card, so
+            each line stays short enough to read comfortably and the eye can find the start of the
+            next line without losing its place.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    const capped = canvas.getByText(/capped to a readable prose measure/);
+    await expect(capped).toHaveClass("max-w-prose");
+    const uncapped = canvas.getByText(/runs the full width/);
+    await expect(uncapped).not.toHaveClass("max-w-prose");
+  },
+};
+
+/**
+ * Keyboard path: tab into a side+hover card and assert the detail's focusable
+ * control is reachable. The `focus-within` CSS selector reveals the panel; DOM
+ * assertions confirm the control is present and accessible (layout is opaque to
+ * jsdom so we verify focusability, not visual appearance).
+ */
+export const DetailHoverKeyboardReveal: Story = {
+  render: () => (
+    <div className="h-64 w-[480px]">
+      {/* Sentinel button before the card so Tab lands inside the card next */}
+      <button className="sr-only" data-testid="before-sentinel">
+        Before card
+      </button>
+      <Card
+        className="h-full"
+        detail={
+          <div className="flex flex-col gap-2 pt-1">
+            <button
+              data-testid="detail-action"
+              className="text-body text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm px-1 text-start"
+            >
+              Open details
+            </button>
+          </div>
+        }
+        detailPlacement="side"
+        detailReveal="hover"
+      >
+        <CardHeader>
+          <CardTitle>Keyboard reveal demo</CardTitle>
+          <CardDescription>Tab into the card — focus-within opens the panel</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <span className="text-body text-muted-foreground">Press Tab to navigate in</span>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    // The detail button stays in the DOM even when the panel is visually collapsed
+    // (overflow-hidden clips it; display:none is NOT used so AT reaches it).
+    const detailBtn = canvas.getByTestId("detail-action");
+    await expect(detailBtn).toBeInTheDocument();
+
+    // Drive the keyboard path: focus the sentinel, then Tab to move into the card.
+    const sentinel = canvas.getByTestId("before-sentinel");
+    sentinel.focus();
+
+    // Tab through focusable elements inside the card until we reach the detail button.
+    const user = userEvent.setup({ delay: null });
+    // Tab once to enter the card area (the first tabbable element inside).
+    await user.tab();
+
+    // The detail button is always in the DOM (clipped, not removed), so focus can
+    // reach it via Tab — assert it is focusable and present.
+    await expect(detailBtn).toBeInTheDocument();
+    // Tab until we land on the detail button (at most a few extra tabs).
+    let attempts = 0;
+    while (document.activeElement !== detailBtn && attempts < 6) {
+      await user.tab();
+      attempts++;
+    }
+    await expect(document.activeElement).toBe(detailBtn);
+  },
+};