@skdx/react 0.26.0

package/dist/table/types.d.cts

@@ -0,0 +1,355 @@
+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. */
+export type SortDirection = 'asc' | 'desc';
+/** The currently sorted column and its direction, as tracked by {@link Table}. */
+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.
+ */
+export type TableSelectAllScope = 'page' | 'all';
+/** How many rows a {@link Table} allows selected at once: one, many, or no selection. */
+export type TableSelectionMode = 'single' | 'multiple' | 'none';
+/** Per-column pixel widths, keyed by a header cell's `columnKey` (falling back to its `sortKey`). */
+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. */
+export interface TableContextValue {
+    /** Unique per-table id, used to derive stable `id`/`aria-controls` pairs for detail rows. */
+    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. */
+    sortList: TableSortState[];
+    /** Whether activating a second column adds to the sort rather than replacing it. */
+    multiSort: boolean;
+    selected: Set<string>;
+    selectionMode: TableSelectionMode;
+    /** Row ids whose detail row is currently 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. */
+    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.
+     */
+    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.
+     */
+    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. */
+    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.
+ */
+export interface TableHeaderCellContextValue {
+    sortKey?: string;
+    columnKey?: string;
+    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'> {
+    /**
+     * 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.
+     */
+    sort?: TableSort;
+    /**
+     * Initial sort state, for uncontrolled usage.
+     * @default null — nothing sorted, so every header reports `aria-sort="none"`.
+     */
+    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.
+     */
+    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.
+     */
+    multiSort?: boolean;
+    /**
+     * Selected row ids, for controlled usage. Pair with `onSelectedChange`. Accepts a `Set` or an array.
+     * @default undefined
+     */
+    selected?: Set<string> | string[];
+    /**
+     * Initially selected row ids, for uncontrolled usage. Accepts a `Set` or an array.
+     * @default undefined
+     */
+    defaultSelected?: Set<string> | string[];
+    /**
+     * Fires with the new selected ids (as an array) whenever selection changes, controlled or not.
+     * @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.
+     * @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"`
+     */
+    getSortLabel?: (column: string, direction: SortDirection | null) => string;
+    /**
+     * Row ids whose `TableExpandedRow` detail row is open, for controlled usage.
+     * Pair with `onExpandedRowIdsChange`.
+     * @default undefined
+     */
+    expandedRowIds?: string[];
+    /**
+     * 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.
+     * @default undefined
+     */
+    onExpandedRowIdsChange?: (rowIds: string[]) => void;
+    /**
+     * Per-column pixel widths keyed by `columnKey`, for controlled usage. Pair
+     * with `onColumnWidthsChange`.
+     * @default undefined
+     */
+    columnWidths?: TableColumnWidths;
+    /**
+     * Initial per-column pixel widths, for uncontrolled usage. Columns left out
+     * size themselves until the user resizes them.
+     * @default {}
+     */
+    defaultColumnWidths?: TableColumnWidths;
+    /**
+     * Fires with the full width map whenever a resizable column is dragged or
+     * keyboard-resized, controlled or not.
+     * @default undefined
+     */
+    onColumnWidthsChange?: (widths: TableColumnWidths) => void;
+}
+/** Props for {@link TableHeader}, the `<thead>` section. */
+export interface TableHeaderProps extends PrimitivePropsWithRef<'thead'> {
+}
+/** Props for {@link TableBody}, the `<tbody>` section. */
+export interface TableBodyProps extends PrimitivePropsWithRef<'tbody'> {
+}
+/** Props for {@link TableFooter}, the `<tfoot>` section. */
+export interface TableFooterProps extends PrimitivePropsWithRef<'tfoot'> {
+}
+/** Props for a single selectable, sortable-aware row inside a {@link Table}. */
+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.
+     * @default undefined
+     */
+    rowId?: string;
+}
+/** Props for a single column header cell inside a {@link Table}, 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.
+     * @default undefined
+     */
+    sortKey?: string;
+    /**
+     * Column identifier used for resizing, when it differs from `sortKey`.
+     * Defaults to `sortKey`; a resizable column needs one of the two.
+     * @default sortKey
+     */
+    columnKey?: string;
+    /**
+     * 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.
+     * @default false
+     */
+    resizable?: boolean;
+    /**
+     * Smallest width in pixels the column can be resized to.
+     * @default 40
+     */
+    minWidth?: number;
+    /**
+     * Largest width in pixels the column can be resized to.
+     * @default 1000
+     */
+    maxWidth?: number;
+    /**
+     * Accessible name for the resize handle — a `role="separator"` widget needs
+     * its own name, distinct from the column header's.
+     * @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.
+     */
+    resizeStep?: number;
+}
+/**
+ * Props for {@link TableColumnHeaderSortTrigger}, the button inside a `<th>`
+ * that cycles that column's 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.
+     */
+    sortKey?: string;
+}
+/**
+ * Props for {@link TableSortIndicator}, the decorative arrow reflecting a
+ * column's sort direction.
+ */
+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`.
+     */
+    sortKey?: string;
+}
+/** Props for {@link TableSelectAllCheckbox}, the tri-state header 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.
+     */
+    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.
+     */
+    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"`
+     */
+    getSelectAllLabel?: (scope: TableSelectAllScope, count: number) => string;
+}
+/** Props for {@link TableRowSelectCheckbox}, one 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`. */
+    rowId: string;
+}
+/** Props for {@link TableColumnResizeTrigger}, the draggable/keyboard-operable column edge. */
+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`.
+     */
+    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`.
+     */
+    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`.
+     */
+    maxWidth?: number;
+    /**
+     * Pixels one Arrow keypress moves the column edge by.
+     * @default the enclosing `TableHeaderCell`'s `resizeStep`, otherwise `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'`.
+     */
+    label?: string;
+}
+/** Props for a single body cell (`<td>`) rendered inside a {@link Table} row. */
+export interface TableCellProps extends PrimitivePropsWithRef<'td'> {
+}
+/** Props for {@link TableCaption}, the table's `<caption>`. */
+export interface TableCaptionProps extends PrimitivePropsWithRef<'caption'> {
+}
+/** Props for {@link TableExpandTrigger}, 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`. */
+    rowId: string;
+}
+/** Props for {@link TableExpandedRow}, the full-width detail row revealed by a {@link TableExpandTrigger}. */
+export interface TableExpandedRowProps extends PrimitivePropsWithRef<'tr'> {
+    /** Id of the row this detail row belongs to. Must match the paired `TableExpandTrigger`'s `rowId`. */
+    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.
+     * @default 1
+     */
+    colSpan?: number;
+}
+/** Props for {@link TableEmpty}, the full-width row shown in place of body rows 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.
+     * @default 1
+     */
+    colSpan?: number;
+}