@primitiv-ui/react 0.1.29 → 0.1.30

package/src/Table/Table.tsx

@@ -1,9 +1,19 @@
-import type { ReactElement } from "react";
+import { useId, useMemo, type MouseEvent, type ReactElement } from "react";
 
+import { useControllableState } from "../hooks/index.ts";
+import { Slot } from "../Slot/index.ts";
+import { deriveId } from "../utils/index.ts";
+import {
+  TableExpandableContext,
+  useTableExpandableContext,
+} from "./TableExpandableContext";
 import {
   TableBodyProps,
   TableCaptionProps,
   TableCellProps,
+  TableDetailRowProps,
+  TableExpandableProps,
+  TableExpandTriggerProps,
   TableFooterProps,
   TableHeaderProps,
   TableHeadProps,
@@ -16,10 +26,16 @@ import {
  * The root of a Table widget — renders a plain `<table>` element and passes
  * all `TableHTMLAttributes` through to the DOM.
  *
- * Stateless: `Table` is a purely structural compound with no context, no
- * internal state, and no `data-*` attributes of its own (verified by
- * `Table.contract.test.tsx` against the registry contract) — every part
- * renders exactly what its native HTML element provides.
+ * Structural: every part below renders exactly what its native HTML element
+ * provides, with no context and no `data-*` attributes of its own (verified by
+ * `Table.contract.test.tsx` against the registry contract).
+ *
+ * The one exception is the expandable-row trio —
+ * {@link TableExpandable | `Table.Expandable`},
+ * {@link TableExpandTrigger | `Table.ExpandTrigger`} and
+ * {@link TableDetailRow | `Table.DetailRow`} — which share a context so the
+ * trigger's `aria-controls` can reach the detail row. They are opt-in: a table
+ * that does not use them is still entirely static.
  *
  * The `<table>` element carries an implicit `role="table"` in the accessibility
  * tree. Assistive technology will announce it as a table and report the number
@@ -56,6 +72,10 @@ export function TableRoot({ children, ...rest }: TableRootProps): ReactElement {
 }
 
 /** @internal */
+// `TableRoot` and the exported `Table` compound are the same object
+// (`Object.assign`), and the compound re-assigns this displayName at the bottom
+// of the file — so this assignment is unobservable and any value survives.
+// Stryker disable next-line StringLiteral: equivalent — overwritten by the compound.
 TableRoot.displayName = "Table";
 
 /**
@@ -254,7 +274,7 @@ TableCell.displayName = "TableCell";
  *
  * ```tsx
  * <Table.ScrollArea style={{ borderRadius: "8px" }}>
- *   …
+ *   ...
  * </Table.ScrollArea>
  * ```
  *
@@ -264,7 +284,7 @@ TableCell.displayName = "TableCell";
  * ```tsx
  * <Table.ScrollArea>
  *   <Table.Root>
- *     …
+ *     ...
  *   </Table.Root>
  * </Table.ScrollArea>
  * ```
@@ -315,7 +335,7 @@ TableScrollArea.displayName = "TableScrollArea";
  * ```tsx
  * <Table.Root>
  *   <Table.Caption>Q1 sales figures by region</Table.Caption>
- *   …
+ *   ...
  * </Table.Root>
  * ```
  *
@@ -323,7 +343,7 @@ TableScrollArea.displayName = "TableScrollArea";
  * ```tsx
  * <Table.Root>
  *   <Table.Caption captionSide="top">Q1 sales figures by region</Table.Caption>
- *   …
+ *   ...
  * </Table.Root>
  * ```
  */
@@ -342,11 +362,184 @@ export function TableCaption({
 /** @internal */
 TableCaption.displayName = "TableCaption";
 
+/**
+ * Pairs one expandable {@link TableRow | `Table.Row`} with its
+ * {@link TableDetailRow | `Table.DetailRow`}, sharing the id that wires the
+ * trigger's `aria-controls` to the detail row.
+ *
+ * Renders **no DOM of its own** — it is a context provider, so the two `<tr>`
+ * elements stay direct children of the `<tbody>` and the table's structure is
+ * untouched.
+ */
+export function TableExpandable({
+  children,
+  expanded: expandedProp,
+  defaultExpanded = false,
+  onExpandedChange,
+}: TableExpandableProps): ReactElement {
+  const reactId = useId();
+  const [expanded, setExpanded] = useControllableState(
+    expandedProp,
+    defaultExpanded,
+    onExpandedChange,
+  );
+
+  const value = useMemo(
+    () => ({
+      expanded,
+      // The id is opaque: the only contracts are that the trigger's
+      // aria-controls matches the detail row's id, and that two Expandables on
+      // one page differ — both of which `useId` alone guarantees. The suffixes
+      // are for legibility when inspecting the DOM, so emptying them yields an
+      // equally valid id.
+      // Stryker disable next-line StringLiteral: equivalent — see above.
+      detailId: deriveId(reactId, "detail", "row"),
+      toggle: () => setExpanded(!expanded),
+    }),
+    [expanded, reactId, setExpanded],
+  );
+
+  return (
+    <TableExpandableContext.Provider value={value}>
+      {children}
+    </TableExpandableContext.Provider>
+  );
+}
+
+/** @internal */
+TableExpandable.displayName = "TableExpandable";
+
+/**
+ * The disclosure control for an expandable row — renders a `<button>` inside
+ * one of the row's cells.
+ *
+ * The **button** carries the state, not the row. `role="row"` does list
+ * `aria-expanded` among its supported properties, but a button's expanded state
+ * is announced universally while a row's is only reliably announced inside a
+ * `role="treegrid"` — so the button owns `aria-expanded` and `aria-controls`.
+ *
+ * Give it a name that identifies its row ("Show details for Ada Lovelace", or
+ * visually-hidden text beside the glyph). A column of buttons all called
+ * "Expand" is the same defect as a column of checkboxes all called "Select":
+ * obvious on screen, useless in a screen reader's element list.
+ *
+ * @extends HTMLButtonElement
+ */
+export function TableExpandTrigger({
+  children,
+  asChild = false,
+  onClick,
+  ...rest
+}: TableExpandTriggerProps): ReactElement {
+  const { expanded, detailId, toggle } = useTableExpandableContext();
+
+  const wiring = {
+    "aria-expanded": expanded,
+    "aria-controls": detailId,
+    "data-state": expanded ? "open" : "closed",
+    onClick: (event: MouseEvent<HTMLButtonElement>) => {
+      onClick?.(event);
+      toggle();
+    },
+    ...rest,
+  };
+
+  // `type` is set only on the native button: a Slot child may not be a
+  // <button> at all, and `type` on a non-button element is invalid HTML.
+  return asChild ? (
+    <Slot {...wiring}>{children}</Slot>
+  ) : (
+    <button type="button" {...wiring}>
+      {children}
+    </button>
+  );
+}
+
+/** @internal */
+TableExpandTrigger.displayName = "TableExpandTrigger";
+
+/**
+ * The revealed panel for an expandable row — a `<tr>` holding a `<td colSpan>`,
+ * and the target of its {@link TableExpandTrigger | `Table.ExpandTrigger`}'s
+ * `aria-controls`. Must be rendered inside a
+ * {@link TableExpandable | `Table.Expandable`}, as the sibling of the data row.
+ *
+ * This is a **disclosure**, not a treegrid: the panel holds detail *about* the
+ * row (a summary, a form, a chart), not child rows. Expanding into hierarchical
+ * child rows is a different pattern with a different role and keyboard model.
+ *
+ * Two things it leaves to you, both because only the caller can know them:
+ * {@link TableDetailRowProps.colSpan | `colSpan`}, since counting columns would
+ * mean the table registering its own, and
+ * {@link TableDetailRowProps.gutter | `gutter`}, which aligns the panel with the
+ * first data column by spanning the control columns in front of it.
+ *
+ * Collapsed, the row is `hidden` — so it cannot be reached, and cannot inflate
+ * the table's announced row count. Pass
+ * {@link TableDetailRowProps.forceMount | `forceMount`} when you are animating
+ * it: `display: none` cannot transition, so the row stays in the layout and
+ * takes `aria-hidden` instead, which keeps the row count honest either way.
+ *
+ * @extends HTMLTableRowElement
+ *
+ * @example
+ * ```tsx
+ * <Table.Expandable>
+ *   <Table.Row>
+ *     <Table.Cell>
+ *       <Table.ExpandTrigger aria-label="Show details for harmoni-engine">
+ *         ▸
+ *       </Table.ExpandTrigger>
+ *     </Table.Cell>
+ *     <Table.Cell>harmoni-engine</Table.Cell>
+ *   </Table.Row>
+ *   <Table.DetailRow colSpan={2} gutter={1}>
+ *     <DeploymentSummary />
+ *   </Table.DetailRow>
+ * </Table.Expandable>
+ * ```
+ */
+export function TableDetailRow({
+  children,
+  colSpan,
+  gutter = 0,
+  forceMount = false,
+  cellProps,
+  ...rest
+}: TableDetailRowProps): ReactElement | null {
+  const { expanded, detailId } = useTableExpandableContext();
+  const collapsed = !expanded;
+
+  return (
+    <tr
+      id={detailId}
+      data-state={collapsed ? "closed" : "open"}
+      hidden={collapsed && !forceMount}
+      aria-hidden={collapsed && forceMount ? true : undefined}
+      {...rest}
+    >
+      {/* ONE spanning cell rather than `gutter` empty ones: a spanning cell
+          takes the full width of the columns it covers, so the alignment is
+          identical and the row gains a single blank cell instead of several. */}
+      {gutter > 0 ? <td colSpan={gutter} /> : null}
+      <td colSpan={colSpan - gutter} {...cellProps}>
+        {children}
+      </td>
+    </tr>
+  );
+}
+
+/** @internal */
+TableDetailRow.displayName = "TableDetailRow";
+
 /**
  * The shape of the exported `Table` value — callable as `Table.Root` and
  * carrying every sub-component as a static property.
  */
 export type TableCompound = typeof TableRoot & {
+  Expandable: typeof TableExpandable;
+  ExpandTrigger: typeof TableExpandTrigger;
+  DetailRow: typeof TableDetailRow;
   Root: typeof TableRoot;
   Head: typeof TableHead;
   Body: typeof TableBody;
@@ -404,7 +597,7 @@ export type TableCompound = typeof TableRoot & {
  * @example Responsive — horizontal scroll on narrow viewports
  * ```tsx
  * <Table.ScrollArea>
- *   <Table.Root>…</Table.Root>
+ *   <Table.Root>...</Table.Root>
  * </Table.ScrollArea>
  * ```
  *
@@ -423,6 +616,9 @@ export type TableCompound = typeof TableRoot & {
  * @see {@link TableScrollArea} for the horizontal-scroll style caveat.
  */
 const TableCompound: TableCompound = Object.assign(TableRoot, {
+  Expandable: TableExpandable,
+  ExpandTrigger: TableExpandTrigger,
+  DetailRow: TableDetailRow,
   Root: TableRoot,
   Head: TableHead,
   Body: TableBody,

package/src/Table/TableExpandableContext.ts

@@ -0,0 +1,7 @@
+import { createStrictContext } from "../utils/index.ts";
+import { TableExpandableContextValue } from "./types";
+
+export const [TableExpandableContext, useTableExpandableContext] =
+  createStrictContext<TableExpandableContextValue>(
+    "Table.ExpandTrigger and Table.DetailRow must be rendered inside a <Table.Expandable>.",
+  );

package/src/Table/__tests__/Table.DetailRow.test.tsx

@@ -0,0 +1,83 @@
+import { Table } from "../index.ts";
+import { render, screen } from "@testing-library/react";
+
+describe("Table.DetailRow rendering", () => {
+  it("should render a row whose single cell spans every column", () => {
+    // Arrange
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable expanded>
+            <Table.DetailRow colSpan={4}>Detail panel</Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+    const cell = screen.getByRole("cell");
+
+    // Assert
+    expect(cell).toHaveAttribute("colspan", "4");
+    expect(cell).toHaveTextContent("Detail panel");
+  });
+
+  it("should offset the panel behind an empty gutter cell, still spanning every column between them", () => {
+    // Arrange
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable expanded>
+            <Table.DetailRow colSpan={5} gutter={2}>
+              Detail panel
+            </Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+    const [gutter, panel] = screen.getAllByRole("cell");
+
+    // Assert — the gutter is what aligns the panel with the first DATA column
+    // at every size and density: it spans the control columns, so the browser's
+    // own table layout does the arithmetic and nothing has to be measured.
+    expect(gutter).toBeEmptyDOMElement();
+    expect(gutter).toHaveAttribute("colspan", "2");
+    expect(panel).toHaveAttribute("colspan", "3");
+    expect(panel).toHaveTextContent("Detail panel");
+  });
+
+  it("should hide the row while collapsed so it leaves the row count truthful", () => {
+    // Arrange
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable>
+            <Table.DetailRow colSpan={2}>Detail panel</Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+
+    // Assert
+    expect(screen.queryByRole("row")).not.toBeInTheDocument();
+  });
+
+  it("should stay mounted but aria-hidden while collapsed when forceMount is set", () => {
+    // Arrange
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable>
+            <Table.DetailRow colSpan={2} forceMount>
+              Detail panel
+            </Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+    const row = screen.getByRole("row", { hidden: true });
+
+    // Assert — no `hidden`, so CSS can transition it; `aria-hidden` instead, so
+    // a collapsed panel still does not inflate the table's announced row count.
+    expect(row).not.toHaveAttribute("hidden");
+    expect(row).toHaveAttribute("aria-hidden", "true");
+  });
+});

package/src/Table/__tests__/Table.ExpandTrigger.test.tsx

@@ -0,0 +1,102 @@
+import { Table } from "../index.ts";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+function renderPair(props?: { expanded?: boolean }) {
+  return render(
+    <table>
+      <tbody>
+        <Table.Expandable expanded={props?.expanded}>
+          <Table.Row>
+            <Table.Cell>
+              <Table.ExpandTrigger>Show details for Ada</Table.ExpandTrigger>
+            </Table.Cell>
+          </Table.Row>
+          <Table.DetailRow colSpan={2}>Detail panel</Table.DetailRow>
+        </Table.Expandable>
+      </tbody>
+    </table>,
+  );
+}
+
+describe("Table.ExpandTrigger accessibility", () => {
+  it("should own the expanded state on the button and point aria-controls at the detail row", () => {
+    // Arrange
+    renderPair({ expanded: true });
+    const trigger = screen.getByRole("button", {
+      name: /show details for ada/i,
+    });
+    const detailRow = screen.getAllByRole("row")[1];
+
+    // Assert — the button carries the state, because a button's expanded state
+    // is announced universally while a row's is only reliable in a treegrid.
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    expect(detailRow).toHaveAttribute("id");
+    expect(trigger).toHaveAttribute(
+      "aria-controls",
+      detailRow.getAttribute("id"),
+    );
+  });
+});
+
+describe("Table.ExpandTrigger composition", () => {
+  it("should hand its aria wiring to a consumer's own control when asChild is set", () => {
+    // Arrange — the styled layer composes a real ghost Button here rather than
+    // hand-rolling a bare <button>, which is what the Figma set models.
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable>
+            <Table.Row>
+              <Table.Cell>
+                <Table.ExpandTrigger asChild>
+                  <button type="button" className="my-button">
+                    Details
+                  </button>
+                </Table.ExpandTrigger>
+              </Table.Cell>
+            </Table.Row>
+            <Table.DetailRow colSpan={1}>Panel</Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+    const trigger = screen.getByRole("button", { name: "Details" });
+
+    // Assert — one button, the consumer's, carrying the wiring
+    expect(trigger).toHaveClass("my-button");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveAttribute("aria-controls");
+    expect(trigger).toHaveAttribute("data-state", "closed");
+    expect(screen.getAllByRole("button")).toHaveLength(1);
+  });
+});
+
+describe("Table.ExpandTrigger activation", () => {
+  it("should report the next expanded state and reveal the detail row when uncontrolled", async () => {
+    // Arrange
+    const onExpandedChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable onExpandedChange={onExpandedChange}>
+            <Table.Row>
+              <Table.Cell>
+                <Table.ExpandTrigger>Show details for Ada</Table.ExpandTrigger>
+              </Table.Cell>
+            </Table.Row>
+            <Table.DetailRow colSpan={2}>Detail panel</Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button"));
+
+    // Assert
+    expect(onExpandedChange).toHaveBeenCalledWith(true);
+    expect(screen.getByText("Detail panel")).toBeVisible();
+  });
+});

package/src/Table/__tests__/Table.Expandable.test.tsx

@@ -0,0 +1,121 @@
+import { Table } from "../index.ts";
+import { render, screen } from "@testing-library/react";
+
+describe("Table displayNames", () => {
+  it("sets a displayName on the compound and each sub-component", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `Table`, `Table.Root` and the underlying function are one object
+    // (Object.assign compound), so the compound's "Table" alias is the
+    // observable Root displayName; the sub-components are distinct objects.
+    expect(Table.displayName).toBe("Table");
+    expect(Table.Head.displayName).toBe("TableHead");
+    expect(Table.Body.displayName).toBe("TableBody");
+    expect(Table.Footer.displayName).toBe("TableFooter");
+    expect(Table.Row.displayName).toBe("TableRow");
+    expect(Table.Header.displayName).toBe("TableHeader");
+    expect(Table.Cell.displayName).toBe("TableCell");
+    expect(Table.ScrollArea.displayName).toBe("TableScrollArea");
+    expect(Table.Caption.displayName).toBe("TableCaption");
+    expect(Table.Expandable.displayName).toBe("TableExpandable");
+    expect(Table.ExpandTrigger.displayName).toBe("TableExpandTrigger");
+    expect(Table.DetailRow.displayName).toBe("TableDetailRow");
+  });
+});
+
+describe("Table.Expandable contract", () => {
+  it("should require its parts to be rendered inside a provider", () => {
+    // Assert — the strict context is what stops a trigger being wired to
+    // nothing. React logs the throw, so silence the expected console noise.
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => undefined);
+
+    expect(() =>
+      render(
+        <table>
+          <tbody>
+            <Table.DetailRow colSpan={2}>Orphan</Table.DetailRow>
+          </tbody>
+        </table>,
+      ),
+    ).toThrow(
+      "Table.ExpandTrigger and Table.DetailRow must be rendered inside a <Table.Expandable>.",
+    );
+
+    consoleError.mockRestore();
+  });
+
+  it("should apply the hidden attribute — not merely leave the row unannounced — while collapsed", () => {
+    // Arrange
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable>
+            <Table.DetailRow colSpan={2}>Detail panel</Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+
+    // Assert — pins the `forceMount` default. Without `hidden` the row is only
+    // missing from the accessibility tree, which an aria-hidden row would be too.
+    expect(screen.getByText("Detail panel").closest("tr")).toHaveAttribute(
+      "hidden",
+    );
+  });
+
+  it.each([
+    { expanded: true, state: "open" },
+    { expanded: false, state: "closed" },
+  ])(
+    "should publish data-state=$state on both parts for the styling layer",
+    ({ expanded, state }) => {
+      // Arrange
+      render(
+        <table>
+          <tbody>
+            <Table.Expandable expanded={expanded}>
+              <Table.Row>
+                <Table.Cell>
+                  <Table.ExpandTrigger>Toggle</Table.ExpandTrigger>
+                </Table.Cell>
+              </Table.Row>
+              <Table.DetailRow colSpan={2} forceMount>
+                Detail panel
+              </Table.DetailRow>
+            </Table.Expandable>
+          </tbody>
+        </table>,
+      );
+
+      // Assert — the registry stylesheet animates the panel off this attribute,
+      // because a CSS transition needs a selector, not an unmount.
+      expect(screen.getByRole("button", { name: "Toggle" })).toHaveAttribute(
+        "data-state",
+        state,
+      );
+      expect(
+        screen.getByText("Detail panel").closest("tr"),
+      ).toHaveAttribute("data-state", state);
+    },
+  );
+
+  it("should not aria-hide a force-mounted row once it is expanded", () => {
+    // Arrange
+    render(
+      <table>
+        <tbody>
+          <Table.Expandable expanded>
+            <Table.DetailRow colSpan={2} forceMount>
+              Detail panel
+            </Table.DetailRow>
+          </Table.Expandable>
+        </tbody>
+      </table>,
+    );
+
+    // Assert — aria-hidden belongs to "force-mounted AND collapsed" only; an
+    // expanded panel that is not announced would be invisible to a screen reader.
+    expect(screen.getByRole("row")).not.toHaveAttribute("aria-hidden");
+  });
+});