@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Switch/types.ts

@@ -1,50 +1,67 @@
 import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props common to both controlled and uncontrolled `Switch.Root` modes — the
- * native `<input type="checkbox">` attributes (minus the ones the component
- * owns). `className` / `style` style the **track** (the visible control), not
- * the hidden input; everything else spreads onto the input, because
- * semantically the Root *is* the switch.
+ * Shared base for both {@link SwitchRootProps} variants — the native
+ * `<input type="checkbox">` attributes (minus the ones the component owns:
+ * `type`, `role`, `checked`, and `defaultChecked`), plus `children` and a
+ * typed `ref`.
+ *
+ * Prop routing: `className` / `style` style the **track** (the visible
+ * `<label>`, since the input is visually hidden); every other prop — `name`,
+ * `value`, `id`, `aria-*`, `required`, `disabled`, `ref`, ... — spreads onto the
+ * hidden `<input>`, because semantically the Root *is* the switch.
  */
 export type SwitchRootBaseProps = Omit<
   ComponentProps<"input">,
   "type" | "role" | "checked" | "defaultChecked"
 > & {
-  /** Optional content (typically `Switch.Thumb`). */
+  /** Content of the switch — typically a single
+   * {@link SwitchThumbProps | `Switch.Thumb`}. */
   children?: ReactNode;
-  /** Ref to the underlying native `<input>` element. */
+  /** Forwarded to the underlying native `HTMLInputElement` (the real,
+   * visually-hidden checkbox), not the visible track. */
   ref?: Ref<HTMLInputElement>;
 };
 
 /**
- * Props for `Switch.Root` in uncontrolled mode — the **browser** owns the
- * checked state. Pass `defaultChecked` to set the initial value; `checked` is
- * forbidden.
+ * Uncontrolled variant of {@link SwitchRootProps}: the **browser** owns the
+ * checked state, so the switch participates in native form submission and
+ * reset. Pass `defaultChecked` (or omit it); `checked` is forbidden.
  */
 export type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
-  /** Initial checked state when uncontrolled. */
+  /** Checked state on first render. Defaults to `false` when omitted.
+   * @default false */
   defaultChecked?: boolean;
-  /** Forbidden in uncontrolled mode. */
+  /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
   checked?: never;
-  /** Called whenever the checked state changes. */
+  /** Called with the new boolean state whenever the switch toggles. Optional
+   * in uncontrolled mode. */
   onCheckedChange?: (checked: boolean) => void;
 };
 
 /**
- * Props for `Switch.Root` in controlled mode — the parent owns the checked
- * value. Pass `checked` and `onCheckedChange` together.
+ * Controlled variant of {@link SwitchRootProps}: the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together; `defaultChecked` is
+ * forbidden.
  */
 export type SwitchRootControlledProps = SwitchRootBaseProps & {
-  /** Forbidden in controlled mode. */
+  /** Forbidden in controlled mode — use `checked` instead. */
   defaultChecked?: never;
-  /** The controlled checked state. */
+  /** The controlled checked state. Must be kept in sync by the parent via
+   * `onCheckedChange`. */
   checked: boolean;
-  /** Called whenever the component requests a checked-state change. */
+  /** Called with the new boolean state whenever the user requests a toggle.
+   * Required in controlled mode. */
   onCheckedChange: (checked: boolean) => void;
 };
 
-/** Props for `Switch.Root` — discriminated controlled/uncontrolled union. */
+/**
+ * Props for {@link SwitchRoot | `Switch.Root`}.
+ *
+ * Resolves to either {@link SwitchRootUncontrolledProps} or
+ * {@link SwitchRootControlledProps} — only one shape is accepted by TypeScript
+ * at a time.
+ */
 export type SwitchRootProps =
   | SwitchRootUncontrolledProps
   | SwitchRootControlledProps;
@@ -56,11 +73,21 @@ export type SwitchRootProps =
  */
 export type SwitchProps = SwitchRootProps;
 
-/** Props for `Switch.Thumb`, the sliding indicator inside the track. */
+/**
+ * Props for {@link SwitchThumb | `Switch.Thumb`} — the decorative sliding
+ * indicator inside the track. All `HTMLSpanElement` attributes, plus the
+ * `asChild` escape hatch.
+ */
 export type SwitchThumbProps = ComponentProps<"span"> & {
-  /** Optional thumb content. */
+  /** Optional thumb content (rarely needed — the thumb is usually styled
+   * purely with CSS). */
   children?: ReactNode;
-  /** Render the child element instead of the default `<span>`. */
+  /**
+   * When `true`, render the consumer's own element as the thumb instead of the
+   * default `<span>`, merging `aria-hidden` and `data-state` onto it via the
+   * {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 

package/src/Table/README.md

@@ -51,6 +51,9 @@ import { Table } from "@primitiv-ui/react";
 | `Table.Cell`       | `<td>`      | Data cell. Accepts `colSpan` and `rowSpan`.                                                 |
 | `Table.ScrollArea` | `<div>`     | Horizontal-scroll wrapper — see [Responsive scrolling](#responsive-scrolling).              |
 | `Table.Caption`    | `<caption>` | Visible table label — see [Caption](#caption).                                              |
+| `Table.Expandable` | *nothing*   | Pairs a row with its detail row — see [Expandable rows](#expandable-rows).                   |
+| `Table.ExpandTrigger` | `<button>` | The row's disclosure control; owns `aria-expanded` / `aria-controls`.                     |
+| `Table.DetailRow`  | `<tr>`      | The revealed panel, as a `<td colSpan>`. `gutter` offsets it to the first data column.       |
 
 ## Accessible headers
 
@@ -96,14 +99,14 @@ the table via the CSS `caption-side` property. Defaults to `"bottom"`.
   /* Caption below table (default) */
 }
 <Table.Root>
-  <Table.Caption>Q1 sales by region</Table.Caption>…
+  <Table.Caption>Q1 sales by region</Table.Caption>...
 </Table.Root>;
 
 {
   /* Caption above table */
 }
 <Table.Root>
-  <Table.Caption captionSide="top">Q1 sales by region</Table.Caption>…
+  <Table.Caption captionSide="top">Q1 sales by region</Table.Caption>...
 </Table.Root>;
 ```
 
@@ -111,7 +114,7 @@ When a visible caption is not desirable, use `aria-label` directly on
 `Table.Root` instead:
 
 ```tsx
-<Table.Root aria-label="Q1 sales by region">…</Table.Root>
+<Table.Root aria-label="Q1 sales by region">...</Table.Root>
 ```
 
 ## Responsive scrolling
@@ -124,7 +127,7 @@ narrow viewports instead of overflowing or compressing columns.
 
 ```tsx
 <Table.ScrollArea>
-  <Table.Root>…</Table.Root>
+  <Table.Root>...</Table.Root>
 </Table.ScrollArea>
 ```
 
@@ -133,7 +136,7 @@ base scroll styles, so you can layer additional styles freely:
 
 ```tsx
 <Table.ScrollArea style={{ borderRadius: "8px" }}>
-  <Table.Root>…</Table.Root>
+  <Table.Root>...</Table.Root>
 </Table.ScrollArea>
 ```
 
@@ -144,14 +147,14 @@ separating logical row groups within a single table:
 
 ```tsx
 <Table.Root>
-  <Table.Head>…</Table.Head>
+  <Table.Head>...</Table.Head>
   <Table.Body>
     {/* Group 1 */}
-    <Table.Row>…</Table.Row>
+    <Table.Row>...</Table.Row>
   </Table.Body>
   <Table.Body>
     {/* Group 2 */}
-    <Table.Row>…</Table.Row>
+    <Table.Row>...</Table.Row>
   </Table.Body>
 </Table.Root>
 ```
@@ -203,3 +206,102 @@ caption {
 ---
 
 [Back to @primitiv-ui/react](../../README.md)
+
+## Expandable rows
+
+A row can open onto a detail panel. This is a **disclosure**, not a
+[treegrid](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/): expanding into
+hierarchical child *rows* is a different pattern with a full cell-navigation
+keyboard model, and is deliberately out of scope here.
+
+`Table.Expandable` renders no DOM of its own — it is a context provider, so both
+`<tr>`s stay direct children of the `<tbody>` and the table's structure is
+untouched.
+
+```tsx
+<Table.Body>
+  <Table.Expandable expanded={open} onExpandedChange={setOpen}>
+    <Table.Row>
+      <Table.Cell>
+        <Table.ExpandTrigger>
+          <ChevronIcon aria-hidden="true" />
+          <span className="sr-only">Show details for Ada Lovelace</span>
+        </Table.ExpandTrigger>
+      </Table.Cell>
+      <Table.Cell>Ada Lovelace</Table.Cell>
+    </Table.Row>
+
+    <Table.DetailRow colSpan={2}>
+      <ContributorDetail />
+    </Table.DetailRow>
+  </Table.Expandable>
+</Table.Body>
+```
+
+Controlled via `expanded` + `onExpandedChange` (what an external table engine
+drives), or uncontrolled with `defaultExpanded`.
+
+### Why the state is on the button
+
+`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`, and the detail row publishes the matching
+`id`.
+
+Give the trigger a name that identifies **its row**. 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.
+
+### `colSpan` is required
+
+It must cover every column the table renders, control columns included. It is a
+prop rather than a count taken from context on purpose: counting would mean the
+table registering its own columns, and an external engine already knows the
+number (TanStack Table: `table.getVisibleLeafColumns().length`).
+
+### `gutter` aligns the panel with the first data column
+
+A panel that starts at the table's edge, under the checkbox, reads as a new
+section of the table rather than as an opened row. `gutter` is how many leading
+columns to leave empty — the control columns in front of the data:
+
+```tsx
+{/* select + expand columns, then eight data columns */}
+<Table.DetailRow colSpan={10} gutter={2}>
+```
+
+The panel spans what remains, so `colSpan` keeps its meaning: the table's full
+column count, gutter included.
+
+It renders **one** empty `<td colSpan={gutter}>`, not `gutter` of them — 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.
+
+Aligning by empty cell rather than by a CSS indent is the point: the browser's
+own table layout resolves the width, so it stays exact across every size,
+density and control-column set. Indenting instead means summing control widths
+and paddings by hand, which is right at one size and wrong at the other four —
+measured drift of 7-21px across xs...xl before this existed.
+
+### `forceMount` and the row count
+
+By default a collapsed detail row is `hidden`, so it is absent from the
+accessibility tree — which matters more here than on a `<div>`-based disclosure,
+because a mounted `<tr>` is still a **row**: 24 data rows each with a
+force-mounted detail row would announce 48.
+
+Pass `forceMount` to keep it mounted so CSS can transition it. While collapsed it
+then carries `aria-hidden="true"`, so the announced row count stays truthful
+either way.
+
+### Styling hooks
+
+`data-state="open" | "closed"` on both the trigger and the detail row.
+
+Note that the `display: grid` 0fr↔1fr open/close technique used by Accordion and
+Collapsible **cannot** go on the `<tr>` or the `<td>` — `display: grid` on either
+takes it out of the table layout algorithm and column alignment collapses with
+it. Put the animated wrapper inside the cell, and zero the cell's block padding
+so a closed row leaves no padded band. The registry `data-table` component does
+this for you.

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,13 +26,28 @@ import {
  * The root of a Table widget — renders a plain `<table>` element and passes
  * all `TableHTMLAttributes` through to the DOM.
  *
+ * 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
  * of rows and columns to the user.
  *
- * Always pair column headers (`Table.Header`) with the correct
- * {@link TableHeaderProps.scope | `scope`} attribute so screen readers can
- * associate data cells with their headers.
+ * Always pair column headers ({@link TableHeader | `Table.Header`}) with the
+ * correct {@link TableHeaderProps.scope | `scope`} attribute so screen
+ * readers can associate data cells with their headers. Wrap the whole table
+ * in {@link TableScrollArea | `Table.ScrollArea`} when it has many columns
+ * and needs to scroll horizontally on narrow viewports.
+ *
+ * @extends HTMLTableElement
  *
  * @example
  * ```tsx
@@ -47,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";
 
 /**
@@ -54,7 +83,12 @@ TableRoot.displayName = "Table";
  *
  * Browsers and assistive technology treat rows inside `<thead>` as column
  * headers. When a table is printed across multiple pages, the browser may
- * repeat the `<thead>` content at the top of each page.
+ * repeat the `<thead>` content at the top of each page. Renders as a direct
+ * child of {@link TableRoot | `Table.Root`}'s `<table>`, typically
+ * containing a single {@link TableRow | `Table.Row`} of
+ * {@link TableHeader | `Table.Header`}s.
+ *
+ * @extends HTMLTableSectionElement
  *
  * @example
  * ```tsx
@@ -79,7 +113,9 @@ TableHead.displayName = "TableHead";
  * Using `<tbody>` explicitly improves accessibility and allows browsers to
  * scroll the body independently of a fixed header. Multiple `<tbody>` elements
  * are valid and useful for visually separating logical row groups within a
- * single table.
+ * single table — render more than one `Table.Body` as siblings for that case.
+ *
+ * @extends HTMLTableSectionElement
  *
  * @example
  * ```tsx
@@ -103,7 +139,11 @@ TableBody.displayName = "TableBody";
  *
  * Typically used for summary rows — totals, averages, counts. When a table is
  * printed across multiple pages some browsers repeat the `<tfoot>` content at
- * the bottom of each page.
+ * the bottom of each page. Renders as a sibling of
+ * {@link TableHead | `Table.Head`} and {@link TableBody | `Table.Body`}
+ * inside {@link TableRoot | `Table.Root`}.
+ *
+ * @extends HTMLTableSectionElement
  *
  * @example
  * ```tsx
@@ -128,9 +168,13 @@ TableFooter.displayName = "TableFooter";
 /**
  * An individual table row — renders a `<tr>` element.
  *
- * May contain `Table.Header` (`<th>`) or `Table.Cell` (`<td>`) children, or a
- * mix of both when the row contains both header and data cells (e.g. the first
- * column of each row is a row header).
+ * May contain {@link TableHeader | `Table.Header`} (`<th>`) or
+ * {@link TableCell | `Table.Cell`} (`<td>`) children, or a mix of both when
+ * the row contains both header and data cells (e.g. the first column of each
+ * row is a row header). Lives inside {@link TableHead | `Table.Head`},
+ * {@link TableBody | `Table.Body`}, or {@link TableFooter | `Table.Footer`}.
+ *
+ * @extends HTMLTableRowElement
  *
  * @example
  * ```tsx
@@ -166,6 +210,8 @@ TableRow.displayName = "TableRow";
  * All `ThHTMLAttributes` (including `colSpan`, `rowSpan`, `abbr`) pass
  * through to the DOM.
  *
+ * @extends HTMLTableCellElement
+ *
  * @example Column header
  * ```tsx
  * <Table.Header scope="col">Name</Table.Header>
@@ -190,7 +236,11 @@ TableHeader.displayName = "TableHeader";
  * A data cell — renders a `<td>` element.
  *
  * All `TdHTMLAttributes` pass through to the DOM, including `colSpan` and
- * `rowSpan` for spanning multiple columns or rows.
+ * `rowSpan` for spanning multiple columns or rows. Use
+ * {@link TableHeader | `Table.Header`} instead when a cell's content is a
+ * label for a row or column rather than data.
+ *
+ * @extends HTMLTableCellElement
  *
  * @example Basic cell
  * ```tsx
@@ -224,15 +274,17 @@ TableCell.displayName = "TableCell";
  *
  * ```tsx
  * <Table.ScrollArea style={{ borderRadius: "8px" }}>
- *   …
+ *   ...
  * </Table.ScrollArea>
  * ```
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Table.ScrollArea>
  *   <Table.Root>
- *     …
+ *     ...
  *   </Table.Root>
  * </Table.ScrollArea>
  * ```
@@ -277,11 +329,13 @@ TableScrollArea.displayName = "TableScrollArea";
  * | `"bottom"` (default) | Below the table |
  * | `"top"` | Above the table |
  *
+ * @extends HTMLTableCaptionElement
+ *
  * @example Default (caption below table)
  * ```tsx
  * <Table.Root>
  *   <Table.Caption>Q1 sales figures by region</Table.Caption>
- *   …
+ *   ...
  * </Table.Root>
  * ```
  *
@@ -289,7 +343,7 @@ TableScrollArea.displayName = "TableScrollArea";
  * ```tsx
  * <Table.Root>
  *   <Table.Caption captionSide="top">Q1 sales figures by region</Table.Caption>
- *   …
+ *   ...
  * </Table.Root>
  * ```
  */
@@ -308,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;
@@ -370,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>
  * ```
  *
@@ -389,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>.",
+  );