@seekalfred/primitives 0.7.3 → 0.8.0

package/dist/table/index.d.ts

@@ -1,2 +1,2 @@
-import { Column, RowKey, Table, TableProps, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableEmptyVariants, tableFooterVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableStickyCellVariants, tableVariants } from "./table.js";
-export { type Column, type RowKey, Table, type TableProps, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableEmptyVariants, tableFooterVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableStickyCellVariants, tableVariants };
+import { Column, RowAttributes, RowKey, Table, TableProps, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableDetailCellVariants, tableDetailRowVariants, tableEmptyVariants, tableExpandButtonVariants, tableFooterVariants, tableGroupRowVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableSortButtonVariants, tableStickyCellVariants, tableVariants } from "./table.js";
+export { type Column, type RowAttributes, type RowKey, Table, type TableProps, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableDetailCellVariants, tableDetailRowVariants, tableEmptyVariants, tableExpandButtonVariants, tableFooterVariants, tableGroupRowVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableSortButtonVariants, tableStickyCellVariants, tableVariants };

package/dist/table/index.js

@@ -1,2 +1,2 @@
-import { Table, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableEmptyVariants, tableFooterVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableStickyCellVariants, tableVariants } from "./table.js";
-export { Table, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableEmptyVariants, tableFooterVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableStickyCellVariants, tableVariants };
+import { Table, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableDetailCellVariants, tableDetailRowVariants, tableEmptyVariants, tableExpandButtonVariants, tableFooterVariants, tableGroupRowVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableSortButtonVariants, tableStickyCellVariants, tableVariants } from "./table.js";
+export { Table, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableDetailCellVariants, tableDetailRowVariants, tableEmptyVariants, tableExpandButtonVariants, tableFooterVariants, tableGroupRowVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableSortButtonVariants, tableStickyCellVariants, tableVariants };

package/dist/table/table.d.ts

@@ -64,11 +64,13 @@ import { Selection, SortDescriptor } from "react-aria-components";
  * shadow stays off and the sticky column's own divider does that job.
  */
 export declare const tableCardVariants: (props?: ({
-  frame?: "none" | "card" | null | undefined;
+  frame?: "card" | "none" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /** The horizontal scroll container. The table owns it; 5 of 6 consumers built one by hand. */
 export declare const tableScrollVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
-export declare const tableVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const tableVariants: (props?: ({
+  density?: "default" | "compact" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
  * The header is near-white, not a grey band.
  *
@@ -99,8 +101,45 @@ export declare const tableEmptyVariants: (props?: import("class-variance-authori
 export declare const tableFooterVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
 export declare const tableColumnVariants: (props?: ({
   align?: "center" | "start" | "end" | null | undefined;
+  density?: "default" | "compact" | null | undefined;
+  hidden?: boolean | null | undefined;
   headerType?: "sentence" | "caps" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * The disclosure button that opens a row's sub-rows (`getSubRows`).
+ *
+ * A real button in the first cell, named by that cell's own content and
+ * carrying `aria-expanded`, so a reader hears "Meta, button, collapsed"
+ * without the library inventing copy. 24px square: the WCAG 2.2 target-size
+ * floor (2.5.8), and the step each level of sub-rows is indented by, so a
+ * child's text lines up one button-width in from its parent's. The chevron
+ * turns a quarter when the row opens; with reduced motion it simply flips.
+ */
+export declare const tableExpandButtonVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * A group header row (`isGroupRow`): one cell spanning the row, naming the rows
+ * under it ("Mobile" / "Desktop"). The header band's fill and label type, so it
+ * reads as a heading of the rows that follow rather than as one of them.
+ */
+export declare const tableGroupRowVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * A detail row (`renderExpandedRow`): one cell spanning the row, under the row it
+ * belongs to. Not interactive, so it takes no hover, focus or selection fill and
+ * no rule of its own: it reads as part of the row above, and the next row's rule
+ * closes it.
+ */
+export declare const tableDetailRowVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/** The cell of a detail row. The table's own inset, so the content is not flush against the edge. */
+export declare const tableDetailCellVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * The sort control of a column header in a plain table (`keyboardModel="table"`).
+ *
+ * In the grid the header cell is the control; in a plain table a cell cannot
+ * take focus, so the label sits in a real button that Tab reaches. It wears
+ * the header's own type and colour, and is at least 24px tall so a compact
+ * header still clears the WCAG 2.2 target size (2.5.8).
+ */
+export declare const tableSortButtonVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
 export declare const tableRowVariants: (props?: ({
   variant?: "plain" | "lined" | null | undefined;
   striped?: boolean | null | undefined;
@@ -108,6 +147,7 @@ export declare const tableRowVariants: (props?: ({
 export declare const tableCellVariants: (props?: ({
   align?: "center" | "start" | "end" | null | undefined;
   numeric?: boolean | null | undefined;
+  density?: "default" | "compact" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
  * The first cell of every row, held in place while the rest scroll under it
@@ -150,11 +190,26 @@ type Column$1<T, V = unknown> = {
    * bivariantly, which is precisely the semantics a heterogeneous collection
    * needs. The alternative is `Column<T, any>`, and this package has no
    * eslint-disable in it anywhere.
+   *
+   * `index` is the row's position among its siblings (on the current page, in
+   * the current sort order), so with `getSubRows` a sub-row counts from 0 under
+   * its parent and opening a row never renumbers the rows below it.
    */
   cell?(ctx: {
     value: V;
     row: T;
     index: number;
+    /**
+     * Whether the row is in the table's expanded set (`expandedKeys`). True for a
+     * row opened onto sub-rows or onto a detail row (`renderExpandedRow`).
+     */
+    isExpanded: boolean;
+    /**
+     * Opens the row if it is closed and closes it if it is open, through the same
+     * set as `expandedKeys` / `onExpandedChange`. For a trigger of your own in a
+     * cell (a "History" button), which is how a detail row is opened.
+     */
+    toggleExpanded: () => void;
   }): ReactNode;
   /**
    * Value to string. Deliberately separate from `cell`: this is what CSV
@@ -186,13 +241,60 @@ type Column$1<T, V = unknown> = {
   numeric?: boolean;
   /** Opts this column into sorting. Off by default. */
   sortable?: boolean;
+  /**
+   * Makes this cell span the columns after it, per row: return how many columns
+   * the row's cell in this column covers (1 or nothing is the usual single
+   * cell). The cells it covers are not rendered, so `cell` renders for THIS
+   * column alone and its content is what fills the span ("No impressions yet"
+   * across clicks and CTR; "Not enough data" across five figure columns).
+   *
+   * The span is clamped to the columns that are left, so it can never run past
+   * the row. A row's span never touches the header, which keeps one cell per
+   * column, so columns stay named and sortable. It is ignored on the first
+   * column while `stickyFirstColumn` is on (the frozen pane stays one column
+   * wide) and on group rows (`isGroupRow`), whose first cell already spans the
+   * row.
+   *
+   * Method syntax, for the same reason as `cell`.
+   */
+  colSpan?(row: T): number | undefined;
+  /**
+   * Content after the header label that is NOT part of the sort control: an
+   * info icon with a tooltip, a help link. It sits beside the label, so on a
+   * sortable column clicking or pressing Enter or Space on it does not sort,
+   * and in a plain table (`keyboardModel="table"`) it is a sibling of the sort
+   * button rather than inside it. It must name itself (`aria-label`) and be at
+   * least 24px square, like any control. Not rendered with `headerHidden`.
+   */
+  headerAddon?: ReactNode;
+  /**
+   * Marks this column as the one to look at (the latest run, the current
+   * plan): its header and every cell wear the library's highlight tint and
+   * carry `data-highlighted`, and the header takes the stronger text colour.
+   * The tint is not the message, so the column should say why in its own
+   * content, as with `isRowHighlighted`. Off by default.
+   */
+  highlighted?: boolean;
 };
+/**
+ * What `getRowProps` may return: `data-*` attributes. Anything else is ignored.
+ *
+ * Not `aria-*`: React Aria's Row filters its props down to `data-*` and its own
+ * labelling, so an `aria-current` handed to a grid row is dropped with no error
+ * -- the same silent loss as `Column.width`. A type that allowed it would lie.
+ * Not `onClick` either -- see `onRowAction`.
+ */
+export type RowAttributes = { [K in `data-${string}`]?: string | number | boolean | undefined; };
 export interface TableProps<T> extends VariantProps<typeof tableRowVariants> {
   /** The rows to render. */
   data: readonly T[];
   /** The columns, in display order. */
   columns: readonly Column$1<T, unknown>[];
-  /** Stable identity for a row. Used as its key and to resolve `onRowAction`. */
+  /**
+   * Stable identity for a row. Used as its key and to resolve `onRowAction`.
+   * Pass a stable reference (a module-level function or `useCallback`): the row
+   * index is memoised on it, so an inline arrow recomputes it every render.
+   */
   getRowId: (row: T) => RowKey;
   /**
    * Required. React Aria's Table renders no `<caption>`, so this is the
@@ -230,6 +332,22 @@ export interface TableProps<T> extends VariantProps<typeof tableRowVariants> {
   isRowHighlighted?: (row: T) => boolean;
   /** Extra classes per row, for styling that depends on row DATA. */
   rowClassName?: (row: T) => string;
+  /**
+   * Extra `data-*` attributes per row, for what depends on row DATA and has to
+   * reach the `<tr>`: a `data-testid`, a `data-name` for a script. Only `data-*`
+   * keys are read (React Aria's grid row drops any `aria-*`). The library's own
+   * attributes (`data-slot`, `data-highlighted`, `data-depth`, `data-flip`, the
+   * row id and the grid's own roles and states) are applied after yours and
+   * win a clash.
+   *
+   * There is deliberately no `onClick`. In the grid a row is a React Aria
+   * control and its press is `onRowAction`, which receives the row; in a plain
+   * table a row is not a control, so put the action in a cell.
+   *
+   * Applies to data rows, not to a detail row. Called on every render for every
+   * shown row, so keep it cheap.
+   */
+  getRowProps?: (row: T) => RowAttributes | undefined;
   /**
    * Rendered in place of the rows when `data` is empty.
    *
@@ -358,6 +476,96 @@ export interface TableProps<T> extends VariantProps<typeof tableRowVariants> {
    * real footer rather than one more row of data, so it is announced as one.
    */
   totalRow?: (column: Column$1<T, unknown>) => ReactNode;
+  /**
+   * The rows nested under a row, shown while it is expanded. Return nothing
+   * (or an empty array) for a row with none. Sub-rows are rows like any other
+   * -- the same columns, `getRowId`, `onRowAction` and selection -- and may
+   * have sub-rows of their own.
+   *
+   * A row with sub-rows gets a disclosure button in its first cell, named by
+   * that cell's content and carrying `aria-expanded`; every row's first cell
+   * is indented one step per level. Sorting orders each level on its own, so
+   * sub-rows stay under their parent, and `pageSize` counts top-level rows,
+   * so a group is never split across pages.
+   *
+   * Pass a stable reference (a module-level function or `useCallback`) so the
+   * row index is memoised; an inline arrow function recomputes it on every
+   * render.
+   */
+  getSubRows?: (row: T) => readonly T[] | null | undefined;
+  /**
+   * A full-width row under a row, shown while the row is expanded: arbitrary
+   * content (a history, a log, a form) rather than more rows. Return nothing
+   * (null, undefined or false) for a row that has no detail.
+   *
+   * This is NOT `getSubRows`. Sub-rows are data rows with the table's own
+   * columns, selection and actions, drawn with a disclosure button; a detail row
+   * is one cell spanning every column, holds anything, is never selected,
+   * sorted, counted or acted on, and has no built-in button. Open it with a
+   * trigger of your own in a cell, using `toggleExpanded` and `isExpanded` from
+   * the `cell` context (give it `aria-expanded`), or with `defaultExpandedKeys`
+   * / `expandedKeys`. It uses the same expanded set as `getSubRows`, so a row
+   * with both opens both: the detail row comes first, directly under its row,
+   * then the sub-rows.
+   *
+   * Called only for expanded rows, never for collapsed ones. Still return elements
+   * rather than doing work here, as it runs on every render while a row is open.
+   */
+  renderExpandedRow?: (row: T) => ReactNode;
+  /** The expanded rows, CONTROLLED: their `getRowId` values. */
+  expandedKeys?: Iterable<RowKey>;
+  /** The rows expanded at the start, when uncontrolled. Nothing is, by default. */
+  defaultExpandedKeys?: Iterable<RowKey>;
+  /** Fires with the new set of expanded rows, controlled or not. */
+  onExpandedChange?: (keys: Set<RowKey>) => void;
+  /**
+   * Marks a row as a group header: its first column's content spans the
+   * whole row, in the header's type, and its other cells are not rendered.
+   * For grouped tables ("Mobile" / "Desktop") whose groups are headed rather
+   * than summed; a group with totals is a row with `getSubRows` instead.
+   * Combine the two for a group that opens and closes.
+   *
+   * A group header only heads the rows under it, so it is not actionable:
+   * `onRowAction` does not fire for it and it shows no pointer cursor.
+   */
+  isGroupRow?: (row: T) => boolean;
+  /**
+   * Row height and type size. `default` takes its padding from the ambient
+   * density scope (`--density-row-pad-y`) in body type; `compact` is the
+   * product's tight report table, `py-2` rows in small type.
+   */
+  density?: "default" | "compact";
+  /**
+   * Hides the header row from sight and keeps it for assistive tech, for a
+   * key/value table whose first column already says what each row is
+   * ("Plan" | "Growth"). Every column still needs a `header`: it is the
+   * column's accessible name, announced as a reader moves across a row.
+   *
+   * The header cells keep their widths, so `Column.width` still lays the
+   * columns out. A hidden header has no sort control, so `sortable` is
+   * ignored here (`defaultSortDescriptor` still orders the rows). In the grid
+   * a header cell opens up while it holds keyboard focus; with
+   * `keyboardModel="table"` nothing in it is focusable.
+   */
+  headerHidden?: boolean;
+  /**
+   * How the keyboard moves through the table.
+   *
+   * `grid` (the default) is React Aria's grid: a composite widget with a
+   * tab stop of its own, where the arrow keys move focus between rows and
+   * cells and a screen reader switches to its application/grid handling.
+   * Row selection and `onRowAction` need it, because the row itself is the
+   * control.
+   *
+   * `table` renders a plain `role="table"`: no row or cell takes focus, the
+   * arrow keys are left to the browser and the screen reader's own table
+   * commands, and Tab goes straight from one link or button in a cell to the
+   * next, in reading order. For tables whose cells hold the actions. A
+   * sortable header becomes a button in that Tab order, with `aria-sort` on
+   * its column header. A row cannot be a control here, so `selectionMode`
+   * and `onRowAction` are ignored: put a link or button in a cell instead.
+   */
+  keyboardModel?: "grid" | "table";
   /** Extra classes for the table. Merged last, so they win conflicts with ours. */
   className?: string;
 }