@kinetixui/ui 0.23.3 → 0.24.0

package/src/components-selection.test.tsx

@@ -0,0 +1,207 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Checkbox } from "./components/checkbox";
+import { KinetixDirectionProvider } from "./components/direction-provider";
+import { RadioGroup, RadioGroupItem } from "./components/radio-group";
+import { Switch } from "./components/switch";
+import { Toggle } from "./components/toggle";
+import { ToggleGroup, ToggleGroupItem } from "./components/toggle-group";
+
+/**
+ * components-selection.test.tsx — the selection-control family's state contract.
+ *
+ * Checkbox, RadioGroup, Switch, Toggle and ToggleGroup are five thin wrappers over five different Radix
+ * primitives, and their prop vocabularies differ accordingly: `checked`, `value` and `pressed` are not an
+ * inconsistency to be tidied away, they are the primitives saying three different true things. What they
+ * DO share is a state contract — controlled stays controlled, uncontrolled keeps its own state, a change
+ * handler fires once, and disabled means disabled — and nothing was asserting it.
+ *
+ * Geometry is not here. jsdom has no layout, so the large-text behaviour this slice fixed is measured in a
+ * browser by `scripts/large-text.mjs`; what a unit test can hold is the class contract that makes the
+ * measurement come out right, which is why the RTL passage below asserts the mirrored class rather than a
+ * pixel offset.
+ */
+
+// kx-verify: interaction
+
+describe("controlled and uncontrolled", () => {
+  it("Checkbox: a controlled checkbox does not move on its own, and reports once", async () => {
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(<Checkbox checked={false} onCheckedChange={onCheckedChange} aria-label="Subscribe" />);
+    const box = screen.getByRole("checkbox", { name: "Subscribe" });
+
+    await user.click(box);
+    // The owner did not change `checked`, so the checkbox must still read false — a component that
+    // tracked its own state as well would flip here and then fight the next render.
+    expect(box).toHaveAttribute("aria-checked", "false");
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it("Checkbox: an uncontrolled checkbox keeps its own state from defaultChecked", async () => {
+    const user = userEvent.setup();
+    render(<Checkbox defaultChecked aria-label="Subscribe" />);
+    const box = screen.getByRole("checkbox", { name: "Subscribe" });
+    expect(box).toHaveAttribute("aria-checked", "true");
+    await user.click(box);
+    expect(box).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("Checkbox: indeterminate is a third state, not a styled false", () => {
+    render(<Checkbox checked="indeterminate" aria-label="All" />);
+    expect(screen.getByRole("checkbox", { name: "All" })).toHaveAttribute("aria-checked", "mixed");
+  });
+
+  it("Switch: controlled stays put and reports the requested value", async () => {
+    const user = userEvent.setup();
+    const onCheckedChange = vi.fn();
+    render(<Switch checked={false} onCheckedChange={onCheckedChange} aria-label="Airplane mode" />);
+    const sw = screen.getByRole("switch", { name: "Airplane mode" });
+    await user.click(sw);
+    expect(sw).toHaveAttribute("aria-checked", "false");
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it("Switch: an external update is reflected without an interaction", () => {
+    const { rerender } = render(<Switch checked={false} aria-label="Airplane mode" />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "false");
+    rerender(<Switch checked aria-label="Airplane mode" />);
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("RadioGroup: controlled selection does not move, and reports the value asked for", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <RadioGroup value="free" onValueChange={onValueChange} aria-label="Plan">
+        <RadioGroupItem value="free" aria-label="Free" />
+        <RadioGroupItem value="pro" aria-label="Pro" />
+      </RadioGroup>,
+    );
+    await user.click(screen.getByRole("radio", { name: "Pro" }));
+    expect(screen.getByRole("radio", { name: "Free" })).toBeChecked();
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith("pro");
+  });
+
+  it("ToggleGroup: uncontrolled multiple keeps a set, and reports the whole set", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <ToggleGroup type="multiple" defaultValue={["bold"]} onValueChange={onValueChange} aria-label="Formatting">
+        <ToggleGroupItem value="bold" aria-label="Bold" />
+        <ToggleGroupItem value="italic" aria-label="Italic" />
+      </ToggleGroup>,
+    );
+    expect(screen.getByRole("button", { name: "Bold" })).toHaveAttribute("aria-pressed", "true");
+    await user.click(screen.getByRole("button", { name: "Italic" }));
+    expect(onValueChange).toHaveBeenCalledWith(["bold", "italic"]);
+  });
+});
+
+describe("disabled", () => {
+  it("every control in the family refuses pointer interaction when disabled", async () => {
+    const user = userEvent.setup();
+    const spies = { checkbox: vi.fn(), switch: vi.fn(), radio: vi.fn(), toggle: vi.fn() };
+    render(
+      <>
+        <Checkbox disabled onCheckedChange={spies.checkbox} aria-label="Subscribe" />
+        <Switch disabled onCheckedChange={spies.switch} aria-label="Airplane mode" />
+        <RadioGroup disabled onValueChange={spies.radio} aria-label="Plan">
+          <RadioGroupItem value="free" aria-label="Free" />
+        </RadioGroup>
+        <Toggle disabled onPressedChange={spies.toggle} aria-label="Bold" />
+      </>,
+    );
+
+    for (const el of [
+      screen.getByRole("checkbox", { name: "Subscribe" }),
+      screen.getByRole("switch", { name: "Airplane mode" }),
+      screen.getByRole("radio", { name: "Free" }),
+      screen.getByRole("button", { name: "Bold" }),
+    ]) {
+      expect(el).toBeDisabled();
+      await user.click(el).catch(() => {
+        /* pointer-events: none on a disabled control is itself correct behaviour */
+      });
+    }
+    for (const [name, spy] of Object.entries(spies)) {
+      expect(spy, `${name} fired a change while disabled`).not.toHaveBeenCalled();
+    }
+  });
+});
+
+// kx-verify: interaction, rtl
+
+/**
+ * The Switch was the one control in the family whose movement depends on direction, and it was wrong.
+ *
+ * `translate-x` is physical. Under `dir="rtl"` the thumb starts against the right edge (correct — that is
+ * the start) and then `data-[state=checked]:translate-x-6` moved it further right: measured in Chromium,
+ * the thumb's left edge went from 26px to 50px on a 48px track, so a switch turned on in an RTL locale
+ * rendered as a filled pill with no thumb visible in it at all.
+ *
+ * The first fix flipped the translate with Tailwind's `rtl:`, which matches ANY rtl ancestor — so a switch
+ * in an LTR section of an RTL page was flipped as well, and its thumb landed 22px outside the track. The
+ * travel is now `inset-inline-start`, a logical offset the browser resolves against the switch's own
+ * direction.
+ *
+ * jsdom cannot see that, so what is held here is the class that makes the geometry right. The geometry
+ * itself — all four page/subtree direction pairs, checked and unchecked — is measured in Chromium by
+ * check:selection-visual; this is what fails first if the logical offset is dropped.
+ */
+describe("Switch under RTL", () => {
+  const thumbOf = (container: HTMLElement) =>
+    container.querySelector("[role=switch] > span") ?? container.querySelector("[role=switch] > *");
+
+  it("mirrors the thumb's travel instead of pushing it off the track", () => {
+    const { container } = render(
+      <KinetixDirectionProvider dir="rtl">
+        <Switch checked aria-label="Airplane mode" />
+      </KinetixDirectionProvider>,
+    );
+    const cls = thumbOf(container)?.getAttribute("class") ?? "";
+    // The travel is a logical offset, so the browser mirrors it against the switch's OWN direction — no
+    // ancestor selector decides it. A physical translate flipped by `rtl:` matched any rtl ancestor and pushed
+    // the thumb off the track in an LTR section of an RTL page (check:selection-visual, "direction").
+    expect(cls, "the thumb must travel along the inline axis").toContain("data-[state=checked]:start-6");
+    expect(cls).toContain("relative");
+    expect(cls, "no physical travel that rtl: would have to flip").not.toMatch(/translate-x|rtl:/);
+  });
+
+  it("still toggles from the keyboard under RTL", async () => {
+    const user = userEvent.setup();
+    render(
+      <KinetixDirectionProvider dir="rtl">
+        <Switch aria-label="Airplane mode" />
+      </KinetixDirectionProvider>,
+    );
+    const sw = screen.getByRole("switch", { name: "Airplane mode" });
+    await user.tab();
+    expect(sw).toHaveFocus();
+    await user.keyboard(" ");
+    expect(sw).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("RadioGroup arrow keys follow reading order under RTL", async () => {
+    const user = userEvent.setup();
+    render(
+      <KinetixDirectionProvider dir="rtl">
+        <RadioGroup aria-label="Plan">
+          <RadioGroupItem value="free" aria-label="Free" />
+          <RadioGroupItem value="pro" aria-label="Pro" />
+        </RadioGroup>
+      </KinetixDirectionProvider>,
+    );
+    await user.tab();
+    expect(screen.getByRole("radio", { name: "Free" })).toHaveFocus();
+    // In RTL the next item is to the LEFT, so ArrowLeft advances.
+    await user.keyboard("{ArrowLeft>}");
+    await user.keyboard("{/ArrowLeft}");
+    expect(screen.getByRole("radio", { name: "Pro" })).toHaveFocus();
+  });
+});

package/src/components-table-scroll.test.tsx

@@ -0,0 +1,363 @@
+import * as React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from "./components/table";
+
+/**
+ * components-table-scroll.test.tsx — Table's scroll container becomes keyboard reachable exactly when it
+ * can actually scroll, and stays out of the tab order when it cannot.
+ *
+ * WHAT IS MOCKED, AND WHY IT HAS TO BE
+ *
+ * jsdom does no layout: every element reports `scrollWidth === clientWidth === 0`, so the real condition
+ * this component branches on cannot occur here. Two things are therefore faked, and nothing else:
+ *
+ *   geometry        `scrollWidth` / `clientWidth` are defined per element, so a table can be declared
+ *                   wider than its wrapper. This is the input to the decision, not the decision.
+ *   ResizeObserver  the global stub in test/setup.ts silently does nothing, so it can never deliver a
+ *                   second measurement. It is replaced with one that records its callbacks and lets a
+ *                   test fire them, which is how the "dimensions changed" case is exercised at all.
+ *
+ * So what these tests prove is the COMPONENT'S CONTRACT: given an overflowing measurement, the wrapper
+ * becomes focusable and named; given a fitting one, it does not; and a later measurement is acted on.
+ * They do not and cannot prove that a real browser decides a real table overflows — that is what the
+ * `check:a11y-site` and `check:a11y-browser` gates measure in Chromium, at 320px and at 200% text, and
+ * the axe rule `scrollable-region-focusable` is the assertion there.
+ */
+
+type ROCallback = (entries: ResizeObserverEntry[], observer: ResizeObserver) => void;
+const callbacks: ROCallback[] = [];
+let realRO: typeof ResizeObserver;
+
+/** Re-measure everything, the way a real resize or a text-size change would. */
+const resize = () => {
+  for (const cb of callbacks) cb([], {} as ResizeObserver);
+};
+
+/** Declare a layout jsdom will never compute for us. */
+function setGeometry(el: Element, { scrollWidth, clientWidth }: { scrollWidth: number; clientWidth: number }) {
+  Object.defineProperty(el, "scrollWidth", { value: scrollWidth, configurable: true });
+  Object.defineProperty(el, "clientWidth", { value: clientWidth, configurable: true });
+}
+
+beforeEach(() => {
+  callbacks.length = 0;
+  realRO = window.ResizeObserver;
+  window.ResizeObserver = class {
+    constructor(cb: ROCallback) {
+      callbacks.push(cb);
+    }
+    observe() {}
+    unobserve() {}
+    disconnect() {
+      const i = callbacks.indexOf(this.cb);
+      if (i >= 0) callbacks.splice(i, 1);
+    }
+    declare cb: ROCallback;
+  } as unknown as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  window.ResizeObserver = realRO;
+});
+
+/** The wrapper is the scroll container: the element that owns `overflow-auto`. */
+const wrapperOf = (table: HTMLElement) => table.closest("div.overflow-auto") as HTMLElement;
+
+function Fixture({ caption }: { caption?: string } = {}) {
+  return (
+    <Table>
+      {caption ? <TableCaption>{caption}</TableCaption> : null}
+      <TableHeader>
+        <TableRow>
+          <TableHead>Invoice</TableHead>
+          <TableHead>Status</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow>
+          <TableCell>INV-001</TableCell>
+          <TableCell>Paid</TableCell>
+        </TableRow>
+      </TableBody>
+    </Table>
+  );
+}
+
+describe("Table keeps its semantics", () => {
+  it("still renders a real table, not a div with a role", () => {
+    render(<Fixture />);
+    const table = screen.getByRole("table");
+    expect(table.tagName).toBe("TABLE");
+    // The semantics a screen reader navigates by are the element's own, not ARIA stand-ins.
+    expect(table).not.toHaveAttribute("role");
+    expect(screen.getByRole("columnheader", { name: "Invoice" }).tagName).toBe("TH");
+    expect(screen.getByRole("cell", { name: "INV-001" }).tagName).toBe("TD");
+    expect(screen.getAllByRole("row")).toHaveLength(2);
+  });
+
+  it("puts a caption inside the table, where the table owns it", () => {
+    render(<Fixture caption="Q3 invoices" />);
+    const caption = screen.getByText("Q3 invoices");
+    expect(caption.tagName).toBe("CAPTION");
+    expect(caption.parentElement?.tagName).toBe("TABLE");
+  });
+});
+
+describe("the scroll container is reachable only when it scrolls", () => {
+  it("adds no tab stop when the table fits", async () => {
+    render(<Fixture />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 400, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).not.toHaveAttribute("tabindex"));
+    expect(wrapper).not.toHaveAttribute("role");
+    expect(wrapper).not.toHaveAttribute("aria-labelledby");
+  });
+
+  it("ignores a sub-pixel difference rather than minting a useless focus stop", async () => {
+    render(<Fixture />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    // Rounding routinely produces a fraction of a pixel on a table that cannot actually scroll.
+    setGeometry(wrapper, { scrollWidth: 400.6, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).not.toHaveAttribute("tabindex"));
+  });
+
+  it("becomes focusable when the table is wider than the container", async () => {
+    render(<Fixture />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("tabindex", "0"));
+  });
+
+  it("acts on a later measurement, so a resize or a text-size change is not missed", async () => {
+    render(<Fixture />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 400, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).not.toHaveAttribute("tabindex"));
+
+    // The reader doubles their text size: the table grows, the wrapper does not.
+    setGeometry(wrapper, { scrollWidth: 820, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("tabindex", "0"));
+
+    // …and back again, so the state is not one-way.
+    setGeometry(wrapper, { scrollWidth: 400, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).not.toHaveAttribute("tabindex"));
+  });
+
+  it("is reachable by Tab once scrollable, and does not trap focus", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <button type="button">before</button>
+        <Fixture />
+        <button type="button">after</button>
+      </>,
+    );
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("tabindex", "0"));
+
+    await user.tab();
+    expect(screen.getByRole("button", { name: "before" })).toHaveFocus();
+    await user.tab();
+    expect(wrapper).toHaveFocus();
+    // Focus order continues past it rather than being captured.
+    await user.tab();
+    expect(screen.getByRole("button", { name: "after" })).toHaveFocus();
+  });
+
+  it("stops being a tab stop again when it no longer scrolls", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <button type="button">before</button>
+        <Fixture />
+        <button type="button">after</button>
+      </>,
+    );
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 400, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).not.toHaveAttribute("tabindex"));
+
+    await user.tab();
+    await user.tab();
+    expect(screen.getByRole("button", { name: "after" })).toHaveFocus();
+  });
+});
+
+describe("the scroll container is named by the table's own caption", () => {
+  it("points aria-labelledby at the caption when there is one", async () => {
+    render(<Fixture caption="Q3 invoices" />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("tabindex", "0"));
+
+    const caption = screen.getByText("Q3 invoices");
+    expect(caption.id).toBeTruthy();
+    expect(wrapper).toHaveAttribute("aria-labelledby", caption.id);
+    // `group`, not `region`: a landmark per table would clutter the landmark list.
+    expect(wrapper).toHaveAttribute("role", "group");
+    expect(wrapper).toHaveAccessibleName("Q3 invoices");
+  });
+
+  it("invents no name when the table has no caption", async () => {
+    render(<Fixture />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("tabindex", "0"));
+    // Reachable, but not announced as a generic "scrollable table" region it cannot describe.
+    expect(wrapper).not.toHaveAttribute("role");
+    expect(wrapper).not.toHaveAttribute("aria-labelledby");
+  });
+
+  it("lets a caller's own caption id win", async () => {
+    render(
+      <Table>
+        <TableCaption id="mine">Q3 invoices</TableCaption>
+        <TableBody>
+          <TableRow>
+            <TableCell>INV-001</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("aria-labelledby", "mine"));
+    expect(screen.getByText("Q3 invoices").id).toBe("mine");
+  });
+
+  it("gives two tables on one page distinct caption ids", () => {
+    render(
+      <>
+        <Fixture caption="First" />
+        <Fixture caption="Second" />
+      </>,
+    );
+    const a = screen.getByText("First").id;
+    const b = screen.getByText("Second").id;
+    expect(a).toBeTruthy();
+    expect(b).toBeTruthy();
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("the existing public contract is unchanged", () => {
+  it("still forwards className to the table, not the wrapper", () => {
+    render(
+      <Table className="my-table">
+        <TableBody>
+          <TableRow>
+            <TableCell>x</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const table = screen.getByRole("table");
+    expect(table).toHaveClass("my-table");
+    // The wrapper keeps owning the scrolling, and does not absorb the caller's class.
+    expect(wrapperOf(table)).not.toHaveClass("my-table");
+    expect(wrapperOf(table)).toHaveClass("overflow-auto");
+  });
+
+  it("still forwards the ref to the table element", () => {
+    const ref = React.createRef<HTMLTableElement>();
+    render(
+      <Table ref={ref}>
+        <TableBody>
+          <TableRow>
+            <TableCell>x</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    expect(ref.current).toBeInstanceOf(HTMLTableElement);
+    expect(ref.current).toBe(screen.getByRole("table"));
+  });
+
+  it("still spreads arbitrary props onto the table", () => {
+    render(
+      <Table aria-label="Invoices" data-testid="t">
+        <TableBody>
+          <TableRow>
+            <TableCell>x</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const table = screen.getByRole("table", { name: "Invoices" });
+    expect(table).toHaveAttribute("data-testid", "t");
+  });
+
+  it("carries the library's focus ring rather than a new one", () => {
+    render(<Fixture />);
+    expect(wrapperOf(screen.getByRole("table")).className).toContain("focus-visible:ring-ring");
+  });
+});
+
+describe("the label reference survives a caption id change", () => {
+  it("follows a caller's id when it changes without the table resizing", async () => {
+    function Fixture2({ captionId }: { captionId: string }) {
+      return (
+        <Table>
+          <TableCaption id={captionId}>Q3 invoices</TableCaption>
+          <TableBody>
+            <TableRow>
+              <TableCell>INV-001</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      );
+    }
+    const { rerender } = render(<Fixture2 captionId="first" />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("aria-labelledby", "first"));
+
+    // The id changes but nothing moves — no resize, so no ResizeObserver callback. A cached id read
+    // only during measurement would be left pointing at an element that no longer exists.
+    rerender(<Fixture2 captionId="second" />);
+    await waitFor(() => expect(wrapper).toHaveAttribute("aria-labelledby", "second"));
+    expect(screen.getByText("Q3 invoices").id).toBe("second");
+    expect(wrapper).toHaveAccessibleName("Q3 invoices");
+  });
+
+  it("drops the name when the caption goes away without a resize", async () => {
+    function Fixture3({ withCaption }: { withCaption: boolean }) {
+      return (
+        <Table>
+          {withCaption ? <TableCaption>Q3 invoices</TableCaption> : null}
+          <TableBody>
+            <TableRow>
+              <TableCell>INV-001</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      );
+    }
+    const { rerender } = render(<Fixture3 withCaption />);
+    const wrapper = wrapperOf(screen.getByRole("table"));
+    setGeometry(wrapper, { scrollWidth: 900, clientWidth: 400 });
+    resize();
+    await waitFor(() => expect(wrapper).toHaveAttribute("role", "group"));
+
+    rerender(<Fixture3 withCaption={false} />);
+    // Still reachable — it still scrolls — but no longer claiming a name that is not in the document.
+    await waitFor(() => expect(wrapper).not.toHaveAttribute("aria-labelledby"));
+    expect(wrapper).not.toHaveAttribute("role");
+    expect(wrapper).toHaveAttribute("tabindex", "0");
+  });
+});

package/src/index.ts

@@ -26,6 +26,7 @@ export {
 export { AspectRatio } from "./components/aspect-ratio";
 export {
   KinetixDirectionProvider,
+  useKinetixPortalContainer,
   type KinetixDirectionProviderProps,
 } from "./components/direction-provider";
 export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, type AvatarGroupProps } from "./components/avatar";
@@ -46,6 +47,7 @@ export {
   CardTitle,
   CardDescription,
   CardContent,
+  type CardProps,
 } from "./components/card";
 export { Checkbox } from "./components/checkbox";
 export { Collapsible, CollapsibleTrigger, CollapsibleContent } from "./components/collapsible";

package/src/navigation-menu-focus.test.tsx

@@ -0,0 +1,35 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  NavigationMenu,
+  NavigationMenuItem,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+  navigationMenuTriggerStyle,
+} from "./components/navigation-menu";
+
+/**
+ * Audit P1-5. The trigger's only keyboard-focus cue was `focus:bg-accent`: measured in Chromium, accent is
+ * 1.08:1 on the light page and 1.24:1 on the dark one, and the text colour only moved in light. It now draws
+ * the `ring` role like every other ring-ring control. jsdom cannot compute a box-shadow, so this pins the
+ * class; the measurement itself is `check:theme-isolation` ("navigation menu: …").
+ */
+describe("NavigationMenu keyboard focus", () => {
+  it("draws a ring from the `ring` role on a trigger", () => {
+    render(
+      <NavigationMenu>
+        <NavigationMenuList>
+          <NavigationMenuItem>
+            <NavigationMenuTrigger>Getting started</NavigationMenuTrigger>
+          </NavigationMenuItem>
+        </NavigationMenuList>
+      </NavigationMenu>,
+    );
+    expect(screen.getByRole("button", { name: /getting started/i }).className).toMatch(/focus-visible:ring-2/);
+    expect(screen.getByRole("button", { name: /getting started/i }).className).toMatch(/focus-visible:ring-ring/);
+  });
+
+  it("draws it on a link too, which shares the trigger style", () => {
+    expect(navigationMenuTriggerStyle()).toMatch(/focus-visible:ring-ring/);
+  });
+});