@skdx/react 0.26.0 → 0.28.0

package/dist/table/types.d.cts

@@ -1,213 +1,274 @@
+import type * as React from 'react';
 import type { CheckboxProps } from '../checkbox/types.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
-/** Direction a {@link Table} column is sorted in: ascending or descending. */
+/** Column sort direction: ascending or descending. */
 export type SortDirection = 'asc' | 'desc';
-/** The currently sorted column and its direction, as tracked by {@link Table}. */
+/** Currently sorted column and its sort direction. */
 export interface TableSortState {
     columnKey: string;
     direction: SortDirection;
 }
-/**
- * A whole table's sort state: one column (single sort, the default), an ordered
- * list of columns (`multiSort`, most significant first), or nothing sorted.
- *
- * Single-sort tables are given and handed back the bare object — the array form
- * only appears once `multiSort` is on, so existing single-sort code is unaffected.
- */
-export type TableSort = TableSortState | TableSortState[] | null;
-/**
- * Which rows a {@link TableSelectAllCheckbox} covers: only the ids it was
- * handed (`'page'`) or the entire dataset (`'all'`). There is no default — the
- * two behave identically until the table is paginated or virtualized, at which
- * point picking the wrong one is a bug found in production.
- */
+/** Array of sorted columns, most significant first. Always an array even with `multiSort` off. */
+export type TableSort = TableSortState[];
+/** Whether `TableSelectAllCheckbox` covers the page or entire dataset. */
 export type TableSelectAllScope = 'page' | 'all';
-/** How many rows a {@link Table} allows selected at once: one, many, or no selection. */
+/** How many rows can be selected: one, many, or none. */
 export type TableSelectionMode = 'single' | 'multiple' | 'none';
-/** Per-column pixel widths, keyed by a header cell's `columnKey` (falling back to its `sortKey`). */
+/** Per-column pixel widths keyed by `columnKey`. */
 export type TableColumnWidths = Record<string, number>;
-/** @internal Shared sort/selection state distributed from {@link Table} to its parts via context. Not part of the public API. */
+/** Shared sort/selection state distributed from `Table` to its parts. */
 export interface TableContextValue {
-    /** Unique per-table id, used to derive stable `id`/`aria-controls` pairs for detail rows. */
+    /** Unique per-table id for stable detail row `id`/`aria-controls` pairs. */
     tableId: string;
-    /** The most significant sorted column, or `null`. Equivalent to `sortList[0] ?? null`. */
-    sort: TableSortState | null;
-    /** Every sorted column, most significant first. At most one entry unless `multiSort` is on. */
+    /** Every sorted column, most significant first. */
     sortList: TableSortState[];
-    /** Whether activating a second column adds to the sort rather than replacing it. */
+    /** Whether a second sorted column appends or replaces the first. */
     multiSort: boolean;
     selected: Set<string>;
     selectionMode: TableSelectionMode;
-    /** Row ids whose detail row is currently expanded. */
+    /** Row ids whose detail row is expanded. */
     expandedRows: Set<string>;
     toggleRowExpanded: (rowId: string) => void;
     isRowExpanded: (rowId: string) => boolean;
-    /** Current per-column widths in pixels; columns absent from it are left to the browser. */
+    /** Current per-column pixel widths. */
     columnWidths: TableColumnWidths;
     setColumnWidth: (columnKey: string, width: number) => void;
-    /**
-     * Cycles the given column through asc → desc → unsorted; switching to a
-     * different column always starts at asc. `columnLabel` is the header cell's
-     * own text, used only for the live-region announcement.
-     */
+    /** Commit column widths, fires `onColumnWidthsCommit` once. */
+    commitColumnWidths: () => void;
+    /** Cycle column sort asc → desc → unsorted; switch columns always start at asc. */
     toggleSort: (columnKey: string, columnLabel?: string) => void;
-    /**
-     * Toggles a row's selection. In `'single'` mode, selecting a new row replaces
-     * the current selection. Passing `extend` (a Shift-click) selects every row
-     * between the last row toggled and this one, in `'multiple'` mode only.
-     */
+    /** Toggle a row's selection; `extend` selects range in `'multiple'` mode. */
     toggleRow: (id: string, extend?: boolean) => void;
     isRowSelected: (id: string) => boolean;
-    /** Toggles all given row ids: selects every id unless all are already selected, in which case it deselects them. */
+    /** Deselect all or select all given row ids. */
     toggleAll: (allIds: string[]) => void;
     isAllSelected: (allIds: string[]) => boolean;
     isSomeSelected: (allIds: string[]) => boolean;
 }
-/**
- * @internal Column-scoped defaults a {@link TableHeaderCell} publishes to the
- * sort/resize parts nested inside it, so those parts don't repeat the column's
- * key and bounds. Every field is optional — the parts also work standalone,
- * given their own props. Not part of the public API.
- */
+/** @internal Column-scoped defaults `TableHeaderCell` publishes to its nested parts. */
 export interface TableHeaderCellContextValue {
-    sortKey?: string;
+    /** The column's single identifier for sort and resize. */
     columnKey?: string;
+    /** Whether this column can be sorted. */
+    sortable?: boolean;
     minWidth?: number;
     maxWidth?: number;
     resizeLabel?: string;
     resizeStep?: number;
 }
-/** Props for the {@link Table} root, a native `<table>` with optional headless sorting and selection state. */
-export interface TableProps extends Omit<PrimitivePropsWithRef<'table'>, 'onChange'> {
+/** Props for `TableRoot`, a native table with optional sorting and selection state. */
+export interface TableRootProps extends Omit<PrimitivePropsWithRef<'table'>, 'onChange'> {
     /**
-     * Current sort state, for controlled usage. Pair with `onSortChange`. A bare
-     * object (or `null`) for single sort, an array — most significant column
-     * first — when `multiSort` is on.
-     * @default undefined — uncontrolled, the table tracks its own sort state.
+     * Hand-composed table sections.
+     * @default undefined
+     */
+    children?: React.ReactNode;
+    /**
+     * Sorted columns, most significant first, for controlled usage.
+     * @default undefined
      */
     sort?: TableSort;
     /**
-     * Initial sort state, for uncontrolled usage.
-     * @default null — nothing sorted, so every header reports `aria-sort="none"`.
+     * Initially sorted columns for uncontrolled usage.
+     * @default []
      */
     defaultSort?: TableSort;
     /**
-     * Fires with the new sort state whenever a sortable `TableHeaderCell` is
-     * activated, controlled or not. Handed the same shape `sort` takes: a bare
-     * object or `null` while `multiSort` is off, an array once it is on.
-     * @default undefined — no-op if omitted; the table still tracks sort internally.
+     * Total rows in the full dataset; set when DOM rows don't represent all.
+     * @default undefined
+     */
+    rowCount?: number;
+    /**
+     * Total number of columns in the full dataset.
+     * @default undefined
+     */
+    columnCount?: number;
+    /**
+     * Fires with the new sort state on sortable header activation.
+     * @default undefined
      */
     onSortChange?: (sort: TableSort) => void;
     /**
-     * Lets several columns be sorted at once: activating a second column appends
-     * it to the sort instead of replacing the first, and `sort` becomes an array
-     * ordered most-significant-first. Off, exactly one column can carry
-     * `aria-sort="ascending" | "descending"` at a time.
-     * @default false — a second column replaces the first, and `sort` stays a bare object.
+     * Whether a second sorted column appends or replaces the first.
+     * @default false
      */
     multiSort?: boolean;
     /**
-     * Selected row ids, for controlled usage. Pair with `onSelectedChange`. Accepts a `Set` or an array.
+     * Selected row ids for controlled usage.
      * @default undefined
      */
     selected?: Set<string> | string[];
     /**
-     * Initially selected row ids, for uncontrolled usage. Accepts a `Set` or an array.
+     * Initially selected row ids for uncontrolled usage.
      * @default undefined
      */
     defaultSelected?: Set<string> | string[];
     /**
-     * Fires with the new selected ids (as an array) whenever selection changes, controlled or not.
+     * Fires with the new selected ids on selection change.
      * @default undefined
      */
     onSelectedChange?: (selected: string[]) => void;
     /**
-     * Whether rows can be selected at all, and if so, whether one or many at
-     * once. `'none'` disables row-click and checkbox selection entirely.
+     * Whether rows can be selected: one, many, or none.
      * @default 'none'
      */
     selectionMode?: TableSelectionMode;
     /**
-     * Formats the message announced (through the shared `LiveAnnouncer`) when a
-     * sortable `TableHeaderCell` is activated — a changed `aria-sort` is not
-     * itself re-announced by screen readers. `column` is the header cell's own
-     * text. Return an empty string to announce nothing.
-     * @default defaultGetSortLabel — e.g. `"Amount sorted ascending"`
+     * Format the message announced on sortable header activation.
+     * @default defaultGetSortLabel
      */
     getSortLabel?: (column: string, direction: SortDirection | null) => string;
     /**
-     * Row ids whose `TableExpandedRow` detail row is open, for controlled usage.
-     * Pair with `onExpandedRowIdsChange`.
+     * Row ids whose detail row is expanded for controlled usage.
      * @default undefined
      */
     expandedRowIds?: string[];
     /**
-     * Initially expanded detail rows, for uncontrolled usage.
+     * Initially expanded detail rows for uncontrolled usage.
      * @default []
      */
     defaultExpandedRowIds?: string[];
     /**
-     * Fires with the new set of expanded row ids whenever a `TableExpandTrigger`
-     * is activated, controlled or not.
+     * Fires with new expanded row ids on expand trigger activation.
      * @default undefined
      */
     onExpandedRowIdsChange?: (rowIds: string[]) => void;
     /**
-     * Per-column pixel widths keyed by `columnKey`, for controlled usage. Pair
-     * with `onColumnWidthsChange`.
+     * Per-column pixel widths keyed by `columnKey` for controlled usage.
      * @default undefined
      */
     columnWidths?: TableColumnWidths;
     /**
-     * Initial per-column pixel widths, for uncontrolled usage. Columns left out
-     * size themselves until the user resizes them.
+     * Initial per-column pixel widths for uncontrolled usage.
      * @default {}
      */
     defaultColumnWidths?: TableColumnWidths;
     /**
-     * Fires with the full width map whenever a resizable column is dragged or
-     * keyboard-resized, controlled or not.
+     * Fires during column resize via drag or keyboard, continuously.
      * @default undefined
      */
     onColumnWidthsChange?: (widths: TableColumnWidths) => void;
+    /**
+     * Fires once per gesture when column resizing settles.
+     * @default undefined
+     */
+    onColumnWidthsCommit?: (widths: TableColumnWidths) => void;
+}
+/** One column in a derived table. */
+export interface TableColumn<T = unknown> {
+    /** This column's identifier for sorting and resizing. */
+    key: string;
+    /**
+     * The derived header cell's content.
+     * @default column's `key`
+     */
+    header?: React.ReactNode;
+    /**
+     * Render a cell for this column.
+     * @default falls back to `renderCell`, then `String(row[key])`
+     */
+    cell?: (row: T) => React.ReactNode;
+    /**
+     * Override the root's `sortable` for this column alone.
+     * @default inherits root's `sortable`
+     */
+    sortable?: boolean;
+    /**
+     * Override the root's `resizable` for this column alone.
+     * @default inherits root's `resizable`
+     */
+    resizable?: boolean;
+    /** @default 40 */
+    minWidth?: number;
+    /** @default 1000 */
+    maxWidth?: number;
 }
-/** Props for {@link TableHeader}, the `<thead>` section. */
+/** Props for the Table recipe, generic over row datum `T`. No `children`: use TableRoot for manual composition. */
+export interface TableProps<T = unknown> extends Omit<TableRootProps, 'children'> {
+    /** Columns to derive header cells and row cells from. */
+    columns: TableColumn<T>[];
+    /** Rows to render — one per entry. */
+    data: T[];
+    /**
+     * Default `sortable` for every column that doesn't set its own.
+     * @default false
+     */
+    sortable?: boolean;
+    /**
+     * Derive a leading selection checkbox column.
+     * Defaults `selectionMode` to `'multiple'`.
+     * @default false
+     */
+    selectable?: boolean;
+    /**
+     * Derive a leading expand trigger column and detail row per row.
+     * @default false
+     */
+    expandable?: boolean;
+    /**
+     * Render a derived detail row's content for one row.
+     * @default detail row renders empty
+     */
+    renderExpanded?: (row: T) => React.ReactNode;
+    /**
+     * Default `resizable` for every column that doesn't set its own.
+     * @default false
+     */
+    resizable?: boolean;
+    /**
+     * Content for a derived empty row shown when data is empty.
+     * @default no empty row
+     */
+    empty?: React.ReactNode;
+    /**
+     * Content for the derived `<caption>`, which names the table for assistive technology.
+     * @default no caption
+     */
+    caption?: React.ReactNode;
+    /**
+     * Cell renderer for columns without their own `cell`.
+     * @default `String(row[column.key])`
+     */
+    renderCell?: (row: T, column: TableColumn<T>) => React.ReactNode;
+    /**
+     * Derive each row's identity for selection, expansion and keys.
+     * @default (row, index) => String(row.id ?? index)
+     */
+    rowId?: (row: T, index: number) => string;
+}
+/** Props for the table header section. */
 export interface TableHeaderProps extends PrimitivePropsWithRef<'thead'> {
 }
-/** Props for {@link TableBody}, the `<tbody>` section. */
+/** Props for the table body section. */
 export interface TableBodyProps extends PrimitivePropsWithRef<'tbody'> {
 }
-/** Props for {@link TableFooter}, the `<tfoot>` section. */
+/** Props for the table footer section. */
 export interface TableFooterProps extends PrimitivePropsWithRef<'tfoot'> {
 }
-/** Props for a single selectable, sortable-aware row inside a {@link Table}. */
+/** Props for a selectable, sortable-aware table row. */
 export interface TableRowProps extends PrimitivePropsWithRef<'tr'> {
     /**
-     * This row's identifier within the table's selection state. Required for
-     * the row to be selectable (via click or its own checkbox); rows without
-     * it are never selected or clickable-to-select.
+     * This row's identifier within the table's selection state.
+     * Required for the row to be selectable.
      * @default undefined
      */
     rowId?: string;
 }
-/** Props for a single column header cell inside a {@link Table}, optionally sortable and resizable. */
+/** Props for a column header cell, optionally sortable and resizable. */
 export interface TableHeaderCellProps extends PrimitivePropsWithRef<'th'> {
     /**
-     * Column identifier used for sorting. Presence of this prop is what makes
-     * the header cell sortable — omit it for a non-sortable column header.
+     * This column's identifier for sorting and resizing.
      * @default undefined
      */
-    sortKey?: string;
+    columnKey?: string;
     /**
-     * Column identifier used for resizing, when it differs from `sortKey`.
-     * Defaults to `sortKey`; a resizable column needs one of the two.
-     * @default sortKey
+     * Whether this column can be sorted.
+     * @default undefined
      */
-    columnKey?: string;
+    sortable?: boolean;
     /**
-     * Renders a focusable `role="separator"` resize handle at the cell's inline
-     * end. Drag it, or focus it and press Arrow Left/Right (Home/End jump to the
-     * bounds) to resize the column.
+     * Render a focusable resize handle.
+     * Drag or focus and press Arrow Left/Right.
      * @default false
      */
     resizable?: boolean;
@@ -222,133 +283,111 @@ export interface TableHeaderCellProps extends PrimitivePropsWithRef<'th'> {
      */
     maxWidth?: number;
     /**
-     * Accessible name for the resize handle — a `role="separator"` widget needs
-     * its own name, distinct from the column header's.
+     * Accessible name for the resize handle.
      * @default 'Resize column'
      */
     resizeLabel?: string;
     /**
-     * Pixels one Arrow keypress moves the column edge by. Also inherited by a
-     * `TableColumnResizeTrigger` rendered as a child of this cell.
-     * @default 8 — matches the handle's own default, small enough to land on a
-     * precise width without a hundred presses.
+     * Pixels one Arrow keypress moves the column edge by.
+     * @default 8
      */
     resizeStep?: number;
 }
-/**
- * Props for {@link TableColumnHeaderSortTrigger}, the button inside a `<th>`
- * that cycles that column's sort.
- */
+/** Props for the button inside a header cell that cycles column sort. */
 export interface TableColumnHeaderSortTriggerProps extends PrimitivePropsWithRef<'button'> {
     /**
-     * Column this trigger sorts. Inherited from the enclosing `TableHeaderCell`'s
-     * `sortKey`, so you only pass it when rendering the trigger outside one.
-     * @default the enclosing `TableHeaderCell`'s `sortKey` — the trigger renders nothing without either.
+     * Column this trigger sorts.
+     * Inherited from enclosing `TableHeaderCell`'s `columnKey`.
+     * @default enclosing `TableHeaderCell`'s `columnKey`
      */
-    sortKey?: string;
+    columnKey?: string;
 }
-/**
- * Props for {@link TableSortIndicator}, the decorative arrow reflecting a
- * column's sort direction.
- */
+/** Props for the decorative sort direction arrow. */
 export interface TableSortIndicatorProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Column whose direction this indicator reflects. Inherited from the
-     * enclosing `TableHeaderCell`'s `sortKey`.
-     * @default the enclosing `TableHeaderCell`'s `sortKey`.
+     * Column whose direction this indicator reflects.
+     * Inherited from enclosing `TableHeaderCell`'s `columnKey`.
+     * @default enclosing `TableHeaderCell`'s `columnKey`
      */
-    sortKey?: string;
+    columnKey?: string;
 }
-/** Props for {@link TableSelectAllCheckbox}, the tri-state header checkbox. */
+/** Props for the tri-state header select-all checkbox. */
 export interface TableSelectAllCheckboxProps extends Omit<CheckboxProps, 'checked' | 'defaultChecked' | 'onCheckedChange'> {
     /**
-     * The ids this checkbox selects and reports on. Must be the *whole dataset's*
-     * ids when `scope` is `'all'`, and only the rendered page's when it is
-     * `'page'` — the table stores no row registry, so this list is the only thing
-     * that decides which.
+     * The row ids this checkbox selects.
+     * Must be whole dataset when `scope='all'`, page only when `scope='page'`.
      */
     rowIds: string[];
     /**
-     * Whether `rowIds` is the current page/window or the entire dataset. Required
-     * and unset by default: the two are indistinguishable until the table
-     * paginates or virtualizes, and guessing produces a "select all" that quietly
-     * selects only what is on screen.
+     * Whether `rowIds` is the page or entire dataset.
+     * Required to avoid selecting only on-screen rows when paginating.
      */
     scope: TableSelectAllScope;
     /**
-     * Words the checkbox's accessible name. `count` is `rowIds.length`, so the
-     * name can keep saying how many rows and which scope — which is the reason a
-     * plain `aria-label` is not enough here.
-     * @default defaultSelectAllLabel — e.g. `"Select all 40 rows on this page"`
+     * Formats the checkbox's accessible name, given the current scope and how many rows it affects.
+     * @default defaultSelectAllLabel
      */
     getSelectAllLabel?: (scope: TableSelectAllScope, count: number) => string;
 }
-/** Props for {@link TableRowSelectCheckbox}, one row's selection checkbox. */
+/** Props for a single row's selection checkbox. */
 export interface TableRowSelectCheckboxProps extends Omit<CheckboxProps, 'checked' | 'defaultChecked' | 'onCheckedChange'> {
-    /** Id of the row this checkbox selects. Must match the enclosing `TableRow`'s `rowId`. */
+    /** Id of the row this checkbox selects. */
     rowId: string;
 }
-/** Props for {@link TableColumnResizeTrigger}, the draggable/keyboard-operable column edge. */
+/** Props for the draggable/keyboard-operable column resize handle. */
 export interface TableColumnResizeTriggerProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Column whose width this handle writes. Inherited from the enclosing
-     * `TableHeaderCell`'s `columnKey` (which itself falls back to `sortKey`); a
-     * handle with neither has nowhere to store a width and renders nothing.
-     * @default the enclosing `TableHeaderCell`'s `columnKey ?? sortKey`.
+     * Column whose width this handle resizes.
+     * Inherited from enclosing `TableHeaderCell`'s `columnKey`.
+     * @default enclosing `TableHeaderCell`'s `columnKey`
      */
     columnKey?: string;
     /**
-     * Smallest width in pixels the column can be dragged or stepped to; also the
-     * width **Home** snaps to.
-     * @default the enclosing `TableHeaderCell`'s `minWidth`, otherwise `40`.
+     * Smallest width in pixels; **Home** snaps to this.
+     * @default enclosing `TableHeaderCell`'s `minWidth` or `40`
      */
     minWidth?: number;
     /**
-     * Largest width in pixels the column can be dragged or stepped to; also the
-     * width **End** snaps to.
-     * @default the enclosing `TableHeaderCell`'s `maxWidth`, otherwise `1000`.
+     * Largest width in pixels; **End** snaps to this.
+     * @default enclosing `TableHeaderCell`'s `maxWidth` or `1000`
      */
     maxWidth?: number;
     /**
-     * Pixels one Arrow keypress moves the column edge by.
-     * @default the enclosing `TableHeaderCell`'s `resizeStep`, otherwise `8`.
+     * Pixels one Arrow keypress moves the edge by.
+     * @default enclosing `TableHeaderCell`'s `resizeStep` or `8`
      */
     step?: number;
     /**
-     * Accessible name for the handle — a focusable `role="separator"` is a widget
-     * and needs its own name. Prefer a column-specific one
-     * (`"Resize Name column"`): the handle sits inside the `<th>`, so its name
-     * joins the header's name-from-content.
-     * @default the enclosing `TableHeaderCell`'s `resizeLabel`, otherwise `'Resize column'`.
+     * Accessible name for the resize handle; a focusable separator widget needs its own name.
+     * @default enclosing `TableHeaderCell`'s `resizeLabel` or `'Resize column'`
      */
     label?: string;
 }
-/** Props for a single body cell (`<td>`) rendered inside a {@link Table} row. */
+/** Props for a single body cell. */
 export interface TableCellProps extends PrimitivePropsWithRef<'td'> {
 }
-/** Props for {@link TableCaption}, the table's `<caption>`. */
+/** Props for the table caption. */
 export interface TableCaptionProps extends PrimitivePropsWithRef<'caption'> {
 }
-/** Props for {@link TableExpandTrigger}, the disclosure button that opens a row's detail row. */
+/** Props for the disclosure button that opens a row's detail row. */
 export interface TableExpandTriggerProps extends PrimitivePropsWithRef<'button'> {
-    /** Id of the row this trigger expands. Must match the `rowId` of the paired `TableExpandedRow`. */
+    /** Id of the row this trigger expands. */
     rowId: string;
 }
-/** Props for {@link TableExpandedRow}, the full-width detail row revealed by a {@link TableExpandTrigger}. */
+/** Props for the full-width detail row revealed by an expand trigger. */
 export interface TableExpandedRowProps extends PrimitivePropsWithRef<'tr'> {
-    /** Id of the row this detail row belongs to. Must match the paired `TableExpandTrigger`'s `rowId`. */
+    /** Id of the row this detail row belongs to. */
     rowId: string;
     /**
-     * How many columns the detail cell spans — set it to the table's column
-     * count so the row doesn't tear the column grid.
+     * How many columns the detail cell spans.
      * @default 1
      */
     colSpan?: number;
 }
-/** Props for {@link TableEmpty}, the full-width row shown in place of body rows when there is no data. */
+/** Props for the full-width row shown when there is no data. */
 export interface TableEmptyProps extends PrimitivePropsWithRef<'tr'> {
     /**
-     * How many columns the empty cell spans — set it to the table's column count.
+     * How many columns the empty cell spans.
      * @default 1
      */
     colSpan?: number;