@seekalfred/primitives 0.7.1 → 0.7.4

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, RowKey, Table, TableProps, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, tableEmptyVariants, tableExpandButtonVariants, tableFooterVariants, tableGroupRowVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableSortButtonVariants, tableStickyCellVariants, tableVariants } from "./table.js";
+export { type Column, type RowKey, Table, type TableProps, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, 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, tableEmptyVariants, tableExpandButtonVariants, tableFooterVariants, tableGroupRowVariants, tableHeaderVariants, tablePaginationVariants, tableRowVariants, tableScrollVariants, tableSelectionBarVariants, tableSortButtonVariants, tableStickyCellVariants, tableVariants } from "./table.js";
+export { Table, createColumns, tableCardVariants, tableCellVariants, tableColumnVariants, 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,15 +101,44 @@ 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;
+/**
+ * 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;
+  variant?: "lined" | "plain" | null | undefined;
   striped?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 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
@@ -119,7 +150,7 @@ export declare const tableCellVariants: (props?: ({
  * marks where the frozen column ends.
  */
 export declare const tableStickyCellVariants: (props?: ({
-  part?: "header" | "body" | "bare" | null | undefined;
+  part?: "body" | "header" | "bare" | null | undefined;
   striped?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
@@ -150,6 +181,10 @@ 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;
@@ -192,7 +227,11 @@ export interface TableProps<T> extends VariantProps<typeof tableRowVariants> {
   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
@@ -358,6 +397,77 @@ 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;
+  /** 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;
 }