@tangle-network/ui 11.12.0 → 11.13.0

package/src/primitives/page-header.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+import { PageHeader } from "./page-header";
+import { StatusPill } from "./status-pill";
+
+const meta = {
+  title: "Primitives/PageHeader",
+  component: PageHeader,
+  parameters: { layout: "padded" },
+  args: {
+    title: "Activity",
+    description: "Inspect recent work and the scope of the results below.",
+    actions: <Button type="button">Export</Button>,
+    meta: <><span>12 results · Last 24 hours</span><StatusPill tone="success">Up to date</StatusPill></>,
+  },
+} satisfies Meta<typeof PageHeader>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+export const Nested: Story = { args: { level: 2 } };
+export const SandboxInputs: Story = {
+  args: { actions: undefined, action: <Button type="button">Create item</Button>, eyebrow: "Workspace", titleAs: "h2" },
+};
+export const NarrowLongContent: Story = {
+  render: () => <div data-narrow-header style={{ width: 320, maxWidth: "100%" }}>
+    <PageHeader
+      title="Production activity for workspace-with-a-very-long-unbroken-identifier-012345678901234567890123456789"
+      description="Inspect the selected activity without clipping the title or hiding action names."
+      eyebrow="Production workspace"
+      titleId="long-page-title"
+      actions={<>
+        <Button type="button" className="h-auto whitespace-normal">Export all selected activity for this workspace</Button>
+        <Button type="button" variant="outline" className="h-auto whitespace-normal">Create another activity item</Button>
+      </>}
+      meta={<><span>0 matching results</span><StatusPill tone="neutral">No filter matches</StatusPill></>}
+    />
+  </div>,
+  // Executes when this story is opened in a real browser. Building Storybook
+  // alone does not run this layout assertion.
+  play: async ({ canvasElement }) => {
+    await canvasElement.ownerDocument.fonts.ready;
+    const root = canvasElement.querySelector<HTMLElement>("[data-narrow-header]")!;
+    if (root.scrollWidth > root.clientWidth + 1) throw new Error("PageHeader overflows its narrow container");
+    for (const button of root.querySelectorAll("button")) {
+      if (button.scrollWidth > button.clientWidth + 1 || button.scrollHeight > button.clientHeight + 1) {
+        throw new Error("A long action label is clipped");
+      }
+    }
+  },
+};

package/src/primitives/page-header.test.tsx

@@ -1,3 +1,4 @@
+import { createRef } from "react";
 import { render, screen } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
 import { PageHeader } from "./page-header";
@@ -54,4 +55,51 @@ describe("PageHeader", () => {
     expect(container.querySelector("p")).toBeNull();
     expect(screen.queryByRole("button")).toBeNull();
   });
+
+  it("maps Sandbox inputs while keeping title, eyebrow and description separate", () => {
+    const { container } = render(<PageHeader title="Activity" titleAs="h3" eyebrow="Workspace" description="Recent events" action={<button type="button">Export</button>} />);
+    expect(screen.getByRole("heading", { level: 3 })).toHaveTextContent("Activity");
+    expect(screen.getAllByRole("heading")).toHaveLength(1);
+    expect(screen.getByText("Workspace").tagName).toBe("P");
+    expect(screen.getByRole("button", { name: "Export" })).toBeInTheDocument();
+    for (const attribute of ["action", "actions", "titleAs", "eyebrow", "level"]) {
+      expect(container.querySelector("header")).not.toHaveAttribute(attribute);
+    }
+  });
+
+  it("gives actions precedence without duplicating controls, including explicit null", () => {
+    const fallback = <button type="button">Legacy</button>;
+    const { rerender } = render(<PageHeader title="Activity" action={fallback} actions={<button type="button">Canonical</button>} />);
+    expect(screen.getByRole("button", { name: "Canonical" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Legacy" })).toBeNull();
+    rerender(<PageHeader title="Activity" action={fallback} actions={null} />);
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("lets titleAs override level's element but not its visual treatment", () => {
+    const { rerender } = render(<PageHeader title="Nested" level={2} />);
+    const classes = screen.getByRole("heading", { level: 2 }).className;
+    rerender(<PageHeader title="Nested" level={2} titleAs="h4" />);
+    expect(screen.getByRole("heading", { level: 4 }).className).toBe(classes);
+  });
+
+  it("preserves the header ref, native attributes and zero-valued metadata", () => {
+    const ref = createRef<HTMLElement>();
+    render(<PageHeader ref={ref} title="Activity" titleId="activity-title" id="masthead" aria-labelledby="activity-title" className="custom" meta={0} />);
+    expect(ref.current?.tagName).toBe("HEADER");
+    expect(ref.current).toHaveAttribute("id", "masthead");
+    expect(ref.current).toHaveAttribute("aria-labelledby", "activity-title");
+    expect(ref.current).toHaveClass("custom");
+    expect(screen.getByText("0")).toBeInTheDocument();
+  });
+
+  it("does not truncate long titles or put action labels inside the heading", () => {
+    const title = "A".repeat(180);
+    render(<PageHeader title={title} actions={<button type="button">Export the selected activity</button>} />);
+    const heading = screen.getByRole("heading", { name: title });
+    expect(heading).toHaveClass("[overflow-wrap:anywhere]");
+    expect(heading).not.toHaveClass("truncate");
+    expect(heading).not.toHaveTextContent("Export the selected activity");
+    expect(screen.getByRole("button").parentElement).toHaveClass("flex-wrap", "min-w-0", "max-w-full");
+  });
 });

package/src/primitives/page-header.tsx

@@ -1,39 +1,32 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { Heading } from "./heading";
 
 /**
- * The one masthead every console page opens with.
- *
- * A page identifies itself in three separate registers, and each gets its own
- * slot here so they cannot compete for the same one:
- *
- *   - `title` — what the page IS. The `<h1>`, and the only `<h1>`.
- *   - `description` — one line on what it is for. Prose belongs here, never in
- *     the title slot: a paragraph rendered where a heading goes reads as body
- *     copy to a sighted reader and as nothing at all to a screen reader, which
- *     is how a page ends up with no accessible name.
- *   - `actions` — what the reader can DO from here, right-aligned and wrapping
- *     under the title on a narrow viewport rather than squeezing it.
- *
- * `meta` is the fourth register and the one most often missing: the small facts
- * that qualify everything below (a count, a scope, a window). They sit on their
- * own line under the title so a reader can tell the difference between "this
- * page has nothing in it" and "this filter matches nothing".
- *
- * `titleId` is exposed so a page can point `aria-labelledby` at the heading
- * from a region further down without minting a second copy of the string.
+ * A page masthead with separate title, prose, actions and qualifying metadata.
+ * Brand's existing props and header ref are preserved. Sandbox's existing
+ * action/eyebrow/titleAs inputs map into the same renderer, not a second header.
  */
 export interface PageHeaderProps
   extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
   title: React.ReactNode;
   description?: React.ReactNode;
+  /** Canonical action slot. If supplied (even null), takes precedence over action. */
   actions?: React.ReactNode;
   meta?: React.ReactNode;
   titleId?: string;
-  /** Renders the title one step down for a nested/tab surface. */
+  /** Existing nested-surface treatment: h2 and section typography. */
   level?: 1 | 2;
+  /** Existing Sandbox action slot; used only when actions is undefined. */
+  action?: React.ReactNode;
+  eyebrow?: React.ReactNode;
+  /** Existing Sandbox semantic override; takes precedence over level's tag only. */
+  titleAs?: React.ElementType;
 }
 
+// A numeric zero is useful metadata, not an absent slot.
+const hasContent = (node: React.ReactNode) => Boolean(node) || node === 0;
+
 const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
   (
     {
@@ -41,39 +34,46 @@ const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
       title,
       description,
       actions,
+      action,
+      eyebrow,
       meta,
       titleId,
+      titleAs,
       level = 1,
       ...props
     },
     ref,
   ) => {
-    const Heading = level === 1 ? "h1" : "h2";
+    const resolvedActions = actions === undefined ? action : actions;
     return (
-      <header ref={ref} className={cn("mb-6", className)} {...props}>
-        <div className="flex flex-wrap items-start justify-between gap-x-6 gap-y-3">
-          <div className="min-w-0">
+      <header ref={ref} className={cn("mb-6 min-w-0", className)} {...props}>
+        <div className="flex min-w-0 flex-wrap items-start justify-between gap-x-6 gap-y-3">
+          <div className="min-w-0 flex-[1_1_16rem]">
+            {hasContent(eyebrow) && (
+              <Heading variant="eyebrow" className="mb-1.5">{eyebrow}</Heading>
+            )}
             <Heading
               id={titleId}
-              className={cn(
-                "text-balance font-semibold tracking-tight",
-                level === 1 ? "text-2xl" : "text-lg",
-              )}
+              variant={level === 1 ? "page" : "section"}
+              as={titleAs ?? (level === 1 ? "h1" : "h2")}
+              className="text-balance"
             >
               {title}
             </Heading>
-            {description && (
-              <p className="mt-1 max-w-prose text-muted-foreground text-sm">
+            {hasContent(description) && (
+              <p className="mt-1 max-w-prose text-muted-foreground text-sm [overflow-wrap:anywhere]">
                 {description}
               </p>
             )}
           </div>
-          {actions && (
-            <div className="flex flex-wrap items-center gap-2">{actions}</div>
+          {hasContent(resolvedActions) && (
+            <div className="flex min-w-0 max-w-full flex-wrap items-center gap-2 [overflow-wrap:anywhere] [&>*]:min-w-0 [&>*]:max-w-full">
+              {resolvedActions}
+            </div>
           )}
         </div>
-        {meta && (
-          <div className="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs">
+        {hasContent(meta) && (
+          <div className="mt-3 flex min-w-0 flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs [overflow-wrap:anywhere]">
             {meta}
           </div>
         )}

package/src/primitives/page-shell.stories.tsx

@@ -0,0 +1,89 @@
+import { useId, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+import { Card, CardContent, CardFooter, CardHeader, CardTitle } from "./card";
+import { EmptyState } from "./empty-state";
+import { Input } from "./input";
+import { Metric, MetricStrip } from "./metric-strip";
+import { PageHeader } from "./page-header";
+import { PageShell } from "./page-shell";
+import { StatusPill } from "./status-pill";
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from "./table";
+import { Toolbar } from "./toolbar";
+
+type PageState = "empty" | "loading" | "error" | "populated";
+const items = [{ name: "Documentation build", status: "Complete" }, { name: "Package validation", status: "Complete" }];
+
+/** Local example data and real state transitions; no auth, routing or fetching in PageShell. */
+function ActivityPage({ state, fluid = false }: { state: PageState; fluid?: boolean }) {
+  const titleId = useId();
+  const searchId = useId();
+  const [recovered, setRecovered] = useState(false);
+  const [query, setQuery] = useState("");
+  const current = recovered ? "populated" : state;
+  const available = current === "populated" ? items : [];
+  const matching = available.filter((item) => item.name.toLowerCase().includes(query.toLowerCase()));
+  const known = current === "empty" || current === "populated";
+  const recover = () => { setQuery(""); setRecovered(true); };
+
+  return <main>
+    <PageShell className={fluid ? "mx-0 max-w-none" : undefined}>
+      <PageHeader
+        title="Workspace activity"
+        eyebrow="Example workspace"
+        description="Search the example activity or add example items. State is owned by this story, not the layout."
+        actions={<Button type="button" disabled={current === "loading"} onClick={recover}>Add example items</Button>}
+        meta={known ? <span>{matching.length} matching of {available.length} available items</span> : <span>Activity is not available yet</span>}
+      />
+      <MetricStrip>
+        <Metric label="Available" value={known ? available.length : "—"} />
+        <Metric label="Matching" value={known ? matching.length : "—"} />
+        <Metric label="Completed" value={known ? available.length : "—"} />
+        <Metric label="Failed" value={known ? 0 : "—"} />
+      </MetricStrip>
+      <section aria-labelledby={titleId}>
+        <Toolbar search={<Input id={searchId} label="Search activity" value={query} disabled={!known} onChange={(event) => setQuery(event.target.value)} placeholder="Search by name" />} />
+        <Card>
+          <CardHeader>
+            <CardTitle as="h2" id={titleId}>Activity items</CardTitle>
+          </CardHeader>
+          <CardContent aria-busy={current === "loading"}>
+            {current === "loading" ? <p role="status">Loading activity…</p> :
+              current === "error" ? <div className="space-y-3">
+                <p role="alert">Activity could not be loaded. The last request failed; retry to restore the example results.</p>
+                <Button type="button" onClick={recover}>Retry</Button>
+              </div> : matching.length === 0 ?
+                <EmptyState
+                  title={query ? "No matching activity" : "No activity yet"}
+                  description={query ? "Try a different search or clear the current filter." : "Add example items to see the populated table."}
+                  action={<Button type="button" onClick={query ? () => setQuery("") : recover}>{query ? "Clear search" : "Add example items"}</Button>}
+                /> :
+                <Table wrapper={false}>
+                  <TableCaption>Matching workspace activity</TableCaption>
+                  <TableHeader><TableRow><TableHead scope="col">Item</TableHead><TableHead scope="col">State</TableHead></TableRow></TableHeader>
+                  <TableBody>{matching.map((item) => <TableRow key={item.name}>
+                    <TableHead scope="row" className="[overflow-wrap:anywhere]">{item.name}</TableHead>
+                    <TableCell><StatusPill tone="success">{item.status}</StatusPill></TableCell>
+                  </TableRow>)}</TableBody>
+                </Table>}
+          </CardContent>
+          <CardFooter className="text-sm text-muted-foreground">{known ? "Example data. Use search to exercise the filtered empty state." : "Missing data is not reported as zero activity."}</CardFooter>
+        </Card>
+      </section>
+    </PageShell>
+  </main>;
+}
+
+const meta = {
+  title: "Primitives/PageShell",
+  component: PageShell,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof PageShell>;
+export default meta;
+type Story = StoryObj<typeof PageShell>;
+
+export const Populated: Story = { render: () => <ActivityPage state="populated" /> };
+export const Empty: Story = { render: () => <ActivityPage state="empty" /> };
+export const Loading: Story = { render: () => <ActivityPage state="loading" /> };
+export const Error: Story = { render: () => <ActivityPage state="error" /> };
+export const FluidWidth: Story = { render: () => <ActivityPage state="populated" fluid /> };

package/src/primitives/page-shell.test.tsx

@@ -0,0 +1,24 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { PageShell } from "./page-shell";
+
+describe("PageShell", () => {
+  it("ports Sandbox's width, gutters and rhythm without imposing a landmark or grid", () => {
+    const { container } = render(<PageShell><p>Content</p></PageShell>);
+    const shell = container.firstElementChild;
+    expect(shell?.tagName).toBe("DIV");
+    expect(shell).toHaveClass("mx-auto", "max-w-6xl", "space-y-8", "px-6", "py-8", "lg:px-8");
+    expect(shell).not.toHaveAttribute("role");
+    expect(shell).not.toHaveClass("grid");
+    expect(screen.queryByRole("main")).toBeNull();
+    expect(screen.getByText("Content")).toBeInTheDocument();
+  });
+
+  it("allows a caller-owned fluid layout without introducing shell behavior", () => {
+    const { container } = render(<main><PageShell className="mx-0 max-w-none px-0 lg:px-0"><p>Workbench</p></PageShell></main>);
+    const shell = container.querySelector("main > div");
+    expect(shell).toHaveClass("mx-0", "max-w-none", "px-0", "lg:px-0");
+    expect(shell).not.toHaveClass("mx-auto", "max-w-6xl", "px-6", "lg:px-8");
+    expect(screen.getAllByRole("main")).toHaveLength(1);
+  });
+});

package/src/primitives/page-shell.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/utils";
+
+export interface PageShellProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Ported from sandbox-ui/src/primitives/page-shell.tsx. An optional bounded
+ * width, gutter and vertical rhythm, not an application shell or a card grid.
+ * The caller owns landmarks, routing, auth, navigation and data state. Use
+ * className to override the bound/gutters, or omit it for a workbench layout.
+ */
+export function PageShell({ children, className }: PageShellProps) {
+  return (
+    <div
+      className={cn(
+        "mx-auto min-w-0 w-full max-w-6xl space-y-8 px-6 py-8 lg:px-8",
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}

package/src/primitives/table-wrapper.stories.tsx

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { focusRing } from "../lib/focus";
+import { Heading } from "./heading";
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, type TableProps } from "./table";
+
+const meta = {
+  title: "Primitives/Table/Wrapper",
+  component: Table,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Table>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function WideTable(props: TableProps) {
+  return <Table className="min-w-[40rem]" {...props}>
+    <TableCaption>Build activity, including the full result identifier</TableCaption>
+    <TableHeader><TableRow><TableHead scope="col">Item</TableHead><TableHead scope="col">Result</TableHead><TableHead scope="col">Updated</TableHead></TableRow></TableHeader>
+    <TableBody><TableRow><TableHead scope="row">Documentation build</TableHead><TableCell>result_012345678901234567890123456789</TableCell><TableCell>Just now</TableCell></TableRow></TableBody>
+  </Table>;
+}
+
+const checkScrollOwner: NonNullable<Story["play"]> = ({ canvasElement }) => {
+  const regions = canvasElement.querySelectorAll<HTMLElement>('[role="region"]');
+  if (regions.length !== 1) throw new Error("Expected exactly one named scroll region");
+  const region = regions[0]!;
+  if (region.querySelector(".overflow-auto")) throw new Error("Table introduced a nested scroll container");
+  if (region.scrollWidth <= region.clientWidth) throw new Error("Wide-table fixture does not overflow");
+  region.focus();
+  if (region.ownerDocument.activeElement !== region) throw new Error("Scroll owner is not focusable");
+  region.scrollLeft = 24;
+  if (region.scrollLeft <= 0) throw new Error("Named scroll region cannot scroll");
+  region.scrollLeft = 0;
+  if (!region.querySelector("table > caption") || !region.querySelector('table > thead th[scope="col"]')) {
+    throw new Error("Native table semantics were lost");
+  }
+};
+
+export const AccessibleOverflow: Story = {
+  render: () => <div className="space-y-3" style={{ width: 320, maxWidth: "100%" }}>
+    <Heading variant="section">All activity columns</Heading>
+    <p className="text-sm text-muted-foreground">Tab to the named region and use the arrow keys to reveal the remaining columns.</p>
+    <WideTable wrapperProps={{ role: "region", "aria-label": "Activity columns", tabIndex: 0, className: focusRing }} />
+  </div>,
+  play: checkScrollOwner,
+};
+export const CallerOwnedScroll: Story = {
+  render: () => <div className="space-y-3" style={{ width: 320, maxWidth: "100%" }}>
+    <Heading variant="section">Caller-owned scrolling</Heading>
+    <div role="region" aria-label="Activity columns" tabIndex={0} className={`overflow-auto ${focusRing}`}>
+      <WideTable wrapper={false} />
+    </div>
+  </div>,
+  play: checkScrollOwner,
+};

package/src/primitives/table.test.tsx

@@ -0,0 +1,72 @@
+import { createRef } from "react";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, type TableProps } from "./table";
+
+function UsageTable(props: TableProps) {
+  return <Table {...props}>
+    <TableCaption>Usage</TableCaption>
+    <TableHeader><TableRow><TableHead scope="col" id="resource">Resource</TableHead><TableHead scope="col" id="count">Count</TableHead></TableRow></TableHeader>
+    <TableBody><TableRow><TableHead scope="row" id="builds">Builds</TableHead><TableCell headers="builds count">3</TableCell></TableRow></TableBody>
+    <TableFooter><TableRow><TableCell colSpan={2}>One resource</TableCell></TableRow></TableFooter>
+  </Table>;
+}
+
+describe("Table", () => {
+  it("preserves the default wrapper without imposing an unnamed region or tab stop", () => {
+    render(<UsageTable />);
+    const table = screen.getByRole("table", { name: "Usage" });
+    expect(table.parentElement?.tagName).toBe("DIV");
+    expect(table.parentElement).toHaveClass("relative", "w-full", "overflow-auto");
+    expect(table.parentElement).not.toHaveAttribute("role");
+    expect(table.parentElement).not.toHaveAttribute("tabindex");
+  });
+
+  it("retains native caption, table sections, headers, scope and spans", () => {
+    render(<UsageTable />);
+    const table = screen.getByRole("table", { name: "Usage" });
+    expect(Array.from(table.children).map((node) => node.tagName)).toEqual(["CAPTION", "THEAD", "TBODY", "TFOOT"]);
+    expect(screen.getByRole("columnheader", { name: "Resource" })).toHaveAttribute("scope", "col");
+    expect(screen.getByRole("rowheader", { name: "Builds" })).toHaveAttribute("scope", "row");
+    expect(screen.getByRole("cell", { name: "3" })).toHaveAttribute("headers", "builds count");
+    expect(screen.getByRole("cell", { name: "One resource" })).toHaveAttribute("colspan", "2");
+    expect(screen.queryByRole("grid")).toBeNull();
+  });
+
+  it("allows a caller-named keyboard-focusable wrapper separately from table attributes", async () => {
+    const user = userEvent.setup();
+    render(<><h2 id="usage-title">Resource usage</h2><UsageTable id="usage-table" className="min-w-[40rem]" wrapperProps={{ role: "region", "aria-labelledby": "usage-title", tabIndex: 0, className: "max-h-80" }} /></>);
+    const region = screen.getByRole("region", { name: "Resource usage" });
+    const table = within(region).getByRole("table", { name: "Usage" });
+    expect(region).toHaveClass("max-h-80", "overflow-auto");
+    expect(table).toHaveAttribute("id", "usage-table");
+    expect(table).not.toHaveAttribute("tabindex");
+    expect(table).not.toHaveClass("max-h-80");
+    await user.tab();
+    expect(region).toHaveFocus();
+  });
+
+  it("returns a bare table for a caller-owned scroll region, without leaking wrapper props", () => {
+    render(<div role="region" aria-label="Outer" className="overflow-auto">
+      <UsageTable wrapper={false} wrapperProps={{ id: "unused-wrapper" }} />
+    </div>);
+    const outer = screen.getByRole("region", { name: "Outer" });
+    const table = screen.getByRole("table", { name: "Usage" });
+    expect(outer.firstElementChild).toBe(table);
+    expect(outer.querySelectorAll(".overflow-auto")).toHaveLength(0);
+    expect(table).not.toHaveAttribute("wrapper");
+    expect(table).not.toHaveAttribute("wrapperProps");
+    expect(table).not.toHaveAttribute("id", "unused-wrapper");
+  });
+
+  it("keeps the public ref and native attributes/handlers on the table", async () => {
+    const ref = createRef<HTMLTableElement>();
+    const onClick = vi.fn();
+    render(<Table ref={ref} cellPadding={0} onClick={onClick} aria-label="Details"><TableBody><TableRow><TableCell>Open</TableCell></TableRow></TableBody></Table>);
+    expect(ref.current).toBe(screen.getByRole("table", { name: "Details" }));
+    expect(ref.current).toHaveAttribute("cellpadding", "0");
+    await userEvent.setup().click(screen.getByRole("cell", { name: "Open" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/primitives/table.tsx

@@ -1,18 +1,39 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
 
-const Table = React.forwardRef<
-  HTMLTableElement,
-  React.HTMLAttributes<HTMLTableElement>
->(({ className, ...props }, ref) => (
-  <div className="relative w-full overflow-auto">
-    <table
-      ref={ref}
-      className={cn("w-full caption-bottom text-sm", className)}
-      {...props}
-    />
-  </div>
-));
+export interface TableProps extends React.TableHTMLAttributes<HTMLTableElement> {
+  /** Keep the existing scroll wrapper by default; false returns only the native table. */
+  wrapper?: boolean;
+  /**
+   * Attributes for the wrapper, not the table (ignored when wrapper is false).
+   * For an overflowing table, supply tabIndex and an accessible region name.
+   * No extra tab stop or unnamed landmark is imposed on every small table.
+   */
+  wrapperProps?: Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "dangerouslySetInnerHTML">;
+}
+
+const Table = React.forwardRef<HTMLTableElement, TableProps>(
+  ({ className, wrapper = true, wrapperProps, ...props }, ref) => {
+    const table = (
+      <table
+        ref={ref}
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    );
+    if (!wrapper) return table;
+
+    const { className: wrapperClassName, ...attributes } = wrapperProps ?? {};
+    return (
+      <div
+        {...attributes}
+        className={cn("relative w-full overflow-auto", wrapperClassName)}
+      >
+        {table}
+      </div>
+    );
+  },
+);
 Table.displayName = "Table";
 
 const TableHeader = React.forwardRef<