@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/Table/Table.js

@@ -0,0 +1,494 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo } from "react";
+import { useControllableState } from "../hooks/index.js";
+import { Slot } from "../Slot/index.js";
+import { deriveId } from "../utils/index.js";
+import { TableExpandableContext, useTableExpandableContext, } from "./TableExpandableContext.js";
+/**
+ * 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 ({@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
+ * <Table.Root>
+ *   <Table.Head>
+ *     <Table.Row>
+ *       <Table.Header scope="col">Name</Table.Header>
+ *       <Table.Header scope="col">Role</Table.Header>
+ *     </Table.Row>
+ *   </Table.Head>
+ *   <Table.Body>
+ *     <Table.Row>
+ *       <Table.Cell>Alice</Table.Cell>
+ *       <Table.Cell>Engineer</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table.Root>
+ * ```
+ */
+export function TableRoot({ children, ...rest }) {
+    return _jsx("table", { ...rest, children: children });
+}
+/** @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";
+/**
+ * Groups header rows inside a `<thead>` element.
+ *
+ * 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. 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
+ * <Table.Head>
+ *   <Table.Row>
+ *     <Table.Header scope="col">Name</Table.Header>
+ *     <Table.Header scope="col">Email</Table.Header>
+ *   </Table.Row>
+ * </Table.Head>
+ * ```
+ */
+export function TableHead({ children, ...rest }) {
+    return _jsx("thead", { ...rest, children: children });
+}
+/** @internal */
+TableHead.displayName = "TableHead";
+/**
+ * Groups data rows inside a `<tbody>` element.
+ *
+ * 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 — render more than one `Table.Body` as siblings for that case.
+ *
+ * @extends HTMLTableSectionElement
+ *
+ * @example
+ * ```tsx
+ * <Table.Body>
+ *   <Table.Row>
+ *     <Table.Cell>Alice</Table.Cell>
+ *     <Table.Cell>alice@example.com</Table.Cell>
+ *   </Table.Row>
+ * </Table.Body>
+ * ```
+ */
+export function TableBody({ children, ...rest }) {
+    return _jsx("tbody", { ...rest, children: children });
+}
+/** @internal */
+TableBody.displayName = "TableBody";
+/**
+ * Groups footer rows inside a `<tfoot>` element.
+ *
+ * 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. Renders as a sibling of
+ * {@link TableHead | `Table.Head`} and {@link TableBody | `Table.Body`}
+ * inside {@link TableRoot | `Table.Root`}.
+ *
+ * @extends HTMLTableSectionElement
+ *
+ * @example
+ * ```tsx
+ * <Table.Footer>
+ *   <Table.Row>
+ *     <Table.Cell>Total</Table.Cell>
+ *     <Table.Cell>£1,200</Table.Cell>
+ *   </Table.Row>
+ * </Table.Footer>
+ * ```
+ */
+export function TableFooter({ children, ...rest }) {
+    return _jsx("tfoot", { ...rest, children: children });
+}
+/** @internal */
+TableFooter.displayName = "TableFooter";
+/**
+ * An individual table row — renders a `<tr>` element.
+ *
+ * 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
+ * <Table.Row>
+ *   <Table.Header scope="row">Alice</Table.Header>
+ *   <Table.Cell>Engineer</Table.Cell>
+ *   <Table.Cell>London</Table.Cell>
+ * </Table.Row>
+ * ```
+ */
+export function TableRow({ children, ...rest }) {
+    return _jsx("tr", { ...rest, children: children });
+}
+/** @internal */
+TableRow.displayName = "TableRow";
+/**
+ * A header cell — renders a `<th>` element with an implicit
+ * `role="columnheader"` or `role="rowheader"` depending on context.
+ *
+ * **`scope` prop.** The `scope` attribute is the primary accessibility
+ * contract for table headers. Set it so assistive technology knows which data
+ * cells this header describes:
+ *
+ * | Value | Associates header with |
+ * | ----- | ---------------------- |
+ * | `"col"` | All cells in the same column |
+ * | `"row"` | All cells in the same row |
+ * | `"colgroup"` | All cells in the column group spanned by this header |
+ * | `"rowgroup"` | All cells in the row group spanned by this header |
+ *
+ * All `ThHTMLAttributes` (including `colSpan`, `rowSpan`, `abbr`) pass
+ * through to the DOM.
+ *
+ * @extends HTMLTableCellElement
+ *
+ * @example Column header
+ * ```tsx
+ * <Table.Header scope="col">Name</Table.Header>
+ * ```
+ *
+ * @example Row header
+ * ```tsx
+ * <Table.Header scope="row">Alice</Table.Header>
+ * ```
+ */
+export function TableHeader({ children, ...rest }) {
+    return _jsx("th", { ...rest, children: children });
+}
+/** @internal */
+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. 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
+ * <Table.Cell>alice@example.com</Table.Cell>
+ * ```
+ *
+ * @example Spanning two columns
+ * ```tsx
+ * <Table.Cell colSpan={2}>Full-width note</Table.Cell>
+ * ```
+ */
+export function TableCell({ children, ...rest }) {
+    return _jsx("td", { ...rest, children: children });
+}
+/** @internal */
+TableCell.displayName = "TableCell";
+/**
+ * A horizontal-scroll wrapper for tables wider than their container.
+ *
+ * Renders a `<div>` with `display: block`, `overflow-x: auto`, and
+ * `max-width: 100%` applied as inline styles, then wraps a `Table.Root`
+ * inside it. Use this when your table has many columns and you want it to
+ * scroll horizontally on narrow viewports instead of overflowing or
+ * compressing.
+ *
+ * **Custom styles.** Any `style` properties you pass are merged with (and take priority
+ * over) the base scroll styles, so you can layer additional styles freely without
+ * repeating the scroll declarations:
+ *
+ * ```tsx
+ * <Table.ScrollArea style={{ borderRadius: "8px" }}>
+ *   ...
+ * </Table.ScrollArea>
+ * ```
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Table.ScrollArea>
+ *   <Table.Root>
+ *     ...
+ *   </Table.Root>
+ * </Table.ScrollArea>
+ * ```
+ */
+export function TableScrollArea({ children, style, ...rest }) {
+    return (_jsx("div", { style: {
+            display: "block",
+            overflowX: "auto",
+            maxWidth: "100%",
+            ...style,
+        }, ...rest, children: children }));
+}
+/** @internal */
+TableScrollArea.displayName = "TableScrollArea";
+/**
+ * A visible caption for the table — renders a `<caption>` element.
+ *
+ * A visible `<caption>` is the preferred way to label a table for
+ * accessibility. It is programmatically associated with the `<table>` element
+ * by the browser, so assistive technology announces it when the user enters
+ * the table — no `aria-label` or `aria-labelledby` on the table itself is
+ * needed.
+ *
+ * **`captionSide` prop.** Controls whether the caption appears above or below
+ * the table via the CSS `caption-side` property. Defaults to `"bottom"`.
+ *
+ * | Value | Position |
+ * | ----- | -------- |
+ * | `"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>
+ * ```
+ *
+ * @example Caption above table
+ * ```tsx
+ * <Table.Root>
+ *   <Table.Caption captionSide="top">Q1 sales figures by region</Table.Caption>
+ *   ...
+ * </Table.Root>
+ * ```
+ */
+export function TableCaption({ children, captionSide = "bottom", ...rest }) {
+    return (_jsx("caption", { style: { captionSide }, ...rest, children: children }));
+}
+/** @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, }) {
+    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 (_jsx(TableExpandableContext.Provider, { value: value, children: children }));
+}
+/** @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 }) {
+    const { expanded, detailId, toggle } = useTableExpandableContext();
+    const wiring = {
+        "aria-expanded": expanded,
+        "aria-controls": detailId,
+        "data-state": expanded ? "open" : "closed",
+        onClick: (event) => {
+            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 ? (_jsx(Slot, { ...wiring, children: children })) : (_jsx("button", { type: "button", ...wiring, children: children }));
+}
+/** @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 }) {
+    const { expanded, detailId } = useTableExpandableContext();
+    const collapsed = !expanded;
+    return (_jsxs("tr", { id: detailId, "data-state": collapsed ? "closed" : "open", hidden: collapsed && !forceMount, "aria-hidden": collapsed && forceMount ? true : undefined, ...rest, children: [gutter > 0 ? _jsx("td", { colSpan: gutter }) : null, _jsx("td", { colSpan: colSpan - gutter, ...cellProps, children: children })] }));
+}
+/** @internal */
+TableDetailRow.displayName = "TableDetailRow";
+/**
+ * Headless, accessible **Table** — a compound component wrapping standard
+ * HTML table elements with zero styles.
+ *
+ * `Table` is both callable (it's an alias of {@link Table | `Table.Root`})
+ * and carries its sub-components as static properties. Prefer the namespaced
+ * form in application code for readability:
+ *
+ * - {@link Table | `Table.Root`} — `<table>`, implicit `role="table"`.
+ * - {@link TableHead | `Table.Head`} — `<thead>`, groups header rows.
+ * - {@link TableBody | `Table.Body`} — `<tbody>`, groups data rows.
+ * - {@link TableFooter | `Table.Footer`} — `<tfoot>`, groups footer/summary rows.
+ * - {@link TableRow | `Table.Row`} — `<tr>`, individual row.
+ * - {@link TableHeader | `Table.Header`} — `<th>`, header cell; use `scope` for accessibility.
+ * - {@link TableCell | `Table.Cell`} — `<td>`, data cell.
+ * - {@link TableScrollArea | `Table.ScrollArea`} — horizontal-scroll wrapper for wide tables.
+ * - {@link TableCaption | `Table.Caption`} — `<caption>`, visible accessible table label.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Table } from "@primitiv-ui/react";
+ *
+ * export function Demo() {
+ *   return (
+ *     <Table.Root>
+ *       <Table.Caption>Team members</Table.Caption>
+ *       <Table.Head>
+ *         <Table.Row>
+ *           <Table.Header scope="col">Name</Table.Header>
+ *           <Table.Header scope="col">Role</Table.Header>
+ *         </Table.Row>
+ *       </Table.Head>
+ *       <Table.Body>
+ *         <Table.Row>
+ *           <Table.Cell>Alice</Table.Cell>
+ *           <Table.Cell>Engineer</Table.Cell>
+ *         </Table.Row>
+ *       </Table.Body>
+ *     </Table.Root>
+ *   );
+ * }
+ * ```
+ *
+ * @example Responsive — horizontal scroll on narrow viewports
+ * ```tsx
+ * <Table.ScrollArea>
+ *   <Table.Root>...</Table.Root>
+ * </Table.ScrollArea>
+ * ```
+ *
+ * @example Styling with any system
+ * Because no styles ship with the component, target the rendered elements
+ * with whatever system you use (CSS, Tailwind, design tokens, etc.):
+ *
+ * ```css
+ * table   { border-collapse: collapse; width: 100%; }
+ * th, td  { padding: 0.5rem 1rem; border: 1px solid #e5e7eb; }
+ * thead   { background: #f9fafb; }
+ * ```
+ *
+ * @see {@link TableHeader} for the `scope` attribute and its accessibility contract.
+ * @see {@link TableCaption} for caption placement and why it beats `aria-label`.
+ * @see {@link TableScrollArea} for the horizontal-scroll style caveat.
+ */
+const TableCompound = Object.assign(TableRoot, {
+    Expandable: TableExpandable,
+    ExpandTrigger: TableExpandTrigger,
+    DetailRow: TableDetailRow,
+    Root: TableRoot,
+    Head: TableHead,
+    Body: TableBody,
+    Footer: TableFooter,
+    Row: TableRow,
+    Header: TableHeader,
+    Cell: TableCell,
+    ScrollArea: TableScrollArea,
+    Caption: TableCaption,
+});
+/** @internal */
+TableCompound.displayName = "Table";
+export { TableCompound as Table };

package/dist/Table/TableExpandableContext.d.ts

@@ -0,0 +1,2 @@
+import { TableExpandableContextValue } from "./types.js";
+export declare const TableExpandableContext: import("react").Context<TableExpandableContextValue | null>, useTableExpandableContext: () => TableExpandableContextValue;

package/dist/Table/TableExpandableContext.js

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

package/dist/Table/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Table.js";
+export * from "./types.js";

package/dist/Table/index.js

@@ -0,0 +1,2 @@
+export * from "./Table.js";
+export * from "./types.js";