@jayalfredprufrock/mobx-toolbox 0.7.1 → 0.8.1

package/dist/table.d.mts

@@ -0,0 +1,619 @@
+import { CSSProperties, FC, HTMLAttributes, ReactNode } from "react";
+
+//#region src/table/table.types.d.ts
+type RowData = Record<string, any>;
+type TableData = RowData[];
+type DotPath<T> = T extends object ? T extends Date | readonly unknown[] | ((...args: any) => any) ? never : { [K in keyof T & string]: K | `${K}.${DotPath<T[K]>}` }[keyof T & string] : never;
+type ColumnDef<T> = DotPath<T> | FieldColumnDef<T> | ComputedColumnDef<T> | SelectionColumnDef;
+type ColumnsDef<T> = (ColumnDef<T> | ((firstRow: T) => ColumnDef<T> | ColumnDef<T>[]))[];
+type RowId = string | number;
+interface TableConfig<T> {
+  rows?: T[];
+  /** Fixed pixel height of every row (the virtualization contract). Default 40. */
+  rowHeight?: number;
+  columns?: ColumnsDef<T>;
+  /**
+   * Height (px) of the detail panel below an expanded row. The binary-height contract: a row is
+   * `rowHeight` or `rowHeight + expansionHeight`, never measured — panel content taller than
+   * this scrolls internally (`<Table.Expansion>` owns that). Default 320.
+   */
+  expansionHeight?: number;
+  /** Whether expanding a row collapses all others. Default "multiple". */
+  expandMode?: "single" | "multiple";
+  /**
+   * How the sort list is applied. `"auto"` (default) sorts rows client-side through each
+   * column's value accessor / `compare`. `"manual"` treats `sorts` as pure reactive state and
+   * leaves row order untouched — react to `sorts`, refetch server-sorted rows, `setRows`. The
+   * sort state APIs (`setSort`, `clearSort`, `sortDirection`, `sortIndex`) behave identically
+   * in both modes, so header sort UIs need no changes.
+   */
+  sortMode?: "auto" | "manual";
+  /** Extra rows rendered above/below the visible window. Default 3. */
+  rowOverscan?: number;
+  /** Extra columns rendered on either side of the visible window. Default 1. */
+  columnOverscan?: number;
+  /**
+   * Stable row identity, used to key all row-scoped state (selection) and React row keys. Must be
+   * unique per row. Defaults to the row's index in the source array — stable across `appendRows`,
+   * reset (with the rest of row-keyed state) by `setRows`. Provide a business key when row objects
+   * may be replaced by fresh instances that mean the same row.
+   */
+  getRowId?: (row: T, index: number) => RowId;
+  /**
+   * Client-side row filtering. Pass anything exposing a reactive `predicate`; an array is
+   * AND-composed (a global search + a filter panel compose without knowing about each other).
+   * Filtering runs over `rows` without replacing them, so selection persists. Omit for
+   * server-side filtering — react to the source's serialized query and refetch instead.
+   */
+  filter?: FilterSource<T> | FilterSource<T>[];
+  /**
+   * Fires whenever persisted table state changes (see `getState`) — including as a result of
+   * `applyState`. The snapshot is JSON-serializable; debouncing/storage is the consumer's job.
+   */
+  onStateChange?: (state: TableState) => void;
+}
+/** Persisted per-column state (see TableState). `width` is the manual resize override; absent = automatic. */
+interface ColumnState {
+  hidden: boolean;
+  pinned: false | "left" | "right";
+  width?: number;
+}
+/**
+ * JSON-serializable snapshot of the user-curated table arrangement: column order, per-column
+ * visibility/pinning/manual widths, and the sort list. Ephemeral state (selection, scroll) and
+ * anything owned elsewhere (filters) is deliberately excluded. Produced by `getState`, restored
+ * by `applyState`, observed by `onStateChange`.
+ */
+interface TableState {
+  columnOrder: string[];
+  columns: Record<string, ColumnState>;
+  sorts: ColumnSort[];
+}
+/**
+ * The table's contract with any filter implementation: a reactive predicate over rows. Deliberately
+ * structural so the table takes on no dependency — a hand-rolled observable object satisfies it.
+ * `undefined` predicate = pass-through (no filtering).
+ */
+interface FilterSource<T = RowData> {
+  readonly predicate?: (row: T) => boolean;
+}
+interface ColumnConfig {
+  key: string;
+  /** Raw cell value — feeds sorting and the default render. Resolved dot-path for field columns, the `value` fn for computed ones. */
+  value: (row: RowData) => unknown;
+  render: (row: RowData) => any;
+  /** Sort comparator over extracted values. Omitted = default (numeric / chronological / locale string). */
+  compare?: (a: any, b: any) => number;
+  title?: string;
+  pinned?: false | "left" | "right";
+  width?: ColumnWidth;
+  minWidth?: number;
+  maxWidth?: number;
+  resizable?: boolean;
+  /** See BaseColumnDef.sortable — advisory flag for header sort UIs. Defaults to true. */
+  sortable?: boolean;
+  /** Marks the built-in row-selection column (rendered via `<Table.SelectionCell>`). */
+  selection?: boolean;
+}
+type ColumnWidth = number | `${number}fr`;
+type SortDirection = "asc" | "desc";
+/** One entry in the table's sort priority list. */
+interface ColumnSort {
+  key: string;
+  direction: SortDirection;
+}
+interface BaseColumnDef<T> {
+  title?: string;
+  render?: (row: T) => any;
+  /**
+   * Custom sort comparator. Receives the two rows' *extracted* values (the dot-path lookup for
+   * field columns, the `value` fn's result for computed ones), not the rows. Return negative /
+   * zero / positive as usual; the table handles direction. Defaults to numbers numerically,
+   * Dates chronologically, everything else by locale string, nullish first.
+   */
+  compare?: (a: any, b: any) => number;
+  /** Initial pin side; can also be changed at runtime via ColumnModel.setPinned. */
+  pinned?: false | "left" | "right";
+  /** Fixed pixel width (`number`) or a flex weight (`"Nfr"`). Defaults to `"1fr"`. */
+  width?: ColumnWidth;
+  /** Minimum width for flex columns (px). Defaults to 120. Ignored for fixed-px columns. */
+  minWidth?: number;
+  /** Maximum width for flex columns (px). Ignored for fixed-px columns. */
+  maxWidth?: number;
+  /** Whether the column can be resized by dragging its header edge. Defaults to true. */
+  resizable?: boolean;
+  /**
+   * Whether the column participates in sorting. Defaults to true. Advisory for header UIs
+   * (hide the sort controls); the model's sort APIs are not gated, so programmatic
+   * `setSort`/`applyState` still work.
+   */
+  sortable?: boolean;
+}
+interface FieldColumnDef<T> extends BaseColumnDef<T> {
+  key: DotPath<T>;
+  value?: never;
+}
+interface ComputedColumnDef<T> extends BaseColumnDef<T> {
+  key: string & Record<never, never>;
+  value: (row: T) => any;
+}
+/**
+ * The built-in row-selection column. Rendered by `<Table.SelectionCell>` (body) and
+ * `<Table.SelectionHeaderCell>` (header), so it needs no `render`/`value`. `key` is optional —
+ * the table assigns one when omitted.
+ */
+interface SelectionColumnDef {
+  selection: true;
+  key?: string;
+  pinned?: false | "left" | "right";
+  width?: ColumnWidth;
+  minWidth?: number;
+  maxWidth?: number;
+  resizable?: boolean;
+}
+//#endregion
+//#region src/table/table.model.d.ts
+declare class TableModel {
+  readonly config?: TableConfig<any>;
+  rows: RowData[];
+  columns: Map<string, ColumnModel>;
+  columnOrder: string[];
+  filterSources: FilterSource[];
+  scrollX: number;
+  scrollY: number;
+  height: number;
+  width: number;
+  sorts: ColumnSort[];
+  selectedIds: Set<RowId>;
+  expandedIds: Set<RowId>;
+  scrollRequest: {
+    y: number | "end";
+  } | undefined;
+  private appliedState;
+  private stateReactionDisposer;
+  get rowHeight(): number;
+  get rowOverscan(): number;
+  get expansionHeight(): number;
+  get columnOverscan(): number;
+  get rowIds(): Map<RowData, RowId>;
+  get allColumns(): ColumnModel[];
+  get orderedColumns(): ColumnModel[];
+  /**
+   * Resolved pixel width for every column, distributed across the viewport (`width`).
+   * Fixed columns (explicit px or a manual override) claim their width; the rest are flex
+   * (`"Nfr"`, default `1fr`) and share the remaining space by weight, clamped to
+   * [minWidth, maxWidth] via a freeze-redistribute pass (a column that hits a clamp is frozen
+   * and its share is re-split among the others). Any leftover slack — every flex column capped
+   * at its max — is absorbed by the last column so the columns always fill the viewport (this
+   * also soaks up sub-pixel rounding). When the minimums don't fit, the total exceeds the
+   * viewport and the table scrolls horizontally.
+   */
+  get columnWidths(): Map<ColumnModel, number>;
+  get virtualWidth(): number;
+  get virtualHeight(): number;
+  get expandedDisplayIndices(): number[];
+  get unpinnedColumns(): ColumnModel[];
+  get firstUnpinnedRenderedIndex(): number;
+  get lastUnpinnedRenderedIndex(): number;
+  get unpinnedRenderedColumns(): ColumnModel[];
+  get leftPinnedRenderedColumns(): ColumnModel[];
+  get rightPinnedRenderedColumns(): ColumnModel[];
+  get filteredRows(): RowData[];
+  get displayRows(): RowData[];
+  get firstRenderedIndex(): number;
+  get lastRenderedIndex(): number;
+  get renderedRows(): RowData[];
+  get virtualOffsetX(): number;
+  get virtualOffsetY(): number;
+  get renderedColumns(): ColumnModel[];
+  get visualColumns(): ColumnModel[];
+  get displayRowIndexMap(): Map<RowData, number>;
+  /** Whether the table has a selection column (drives aria-multiselectable / aria-selected). */
+  get selectable(): boolean;
+  get gridTemplateColumns(): string;
+  /** Whether the viewport is scrolled to (within one row of) the end of the content. */
+  get atEnd(): boolean;
+  /** The selected row objects, in source order. Derived from `selectedIds`, so ids without a
+   * matching row (possible only if a consumer mutates `selectedIds` directly) drop out. */
+  get selectedRows(): RowData[];
+  get allRowsSelected(): boolean;
+  get someRowsSelected(): boolean;
+  constructor(config?: TableConfig<any>);
+  /**
+   * (Re)start the `onStateChange` reaction. Pairs with `dispose` — `useTable` calls both across
+   * effect cycles, so a StrictMode dev remount (mount → cleanup → mount against the same model)
+   * re-arms the reaction instead of leaving the surviving model deaf. No-op when already active
+   * or when the config has no `onStateChange`.
+   */
+  activate(): void;
+  /** Drop the `onStateChange` reaction. Pairs with `activate`. */
+  dispose(): void;
+  rowId(row: RowData): RowId | undefined;
+  /** Snapshot of the user-curated arrangement (see `TableState`). JSON-serializable. */
+  getState(): TableState;
+  /**
+   * Restore a (possibly partial) snapshot. Keys with no matching column are kept aside and land
+   * when a matching column appears (see `appliedState`); columns the snapshot doesn't mention are
+   * left as they are, ordered after the snapshot's columns.
+   */
+  applyState(state: Partial<TableState>): void;
+  /** Replace the client-side filter source(s). Pass `undefined` to clear. */
+  setFilter(filter: FilterSource | FilterSource[] | undefined): void;
+  /** Move a column to a new index in the display order. */
+  moveColumn(key: string, toIndex: number): void;
+  /** Replace the dataset. Row-keyed state (selection, expansion) is reset — ids from the old world
+   * (indices by default) must not silently attach to new rows. Use `appendRows` to add without resetting. */
+  setRows(rows: RowData[]): void;
+  /** Append rows without resetting row-keyed state — the "load more" path. Existing rows keep
+   * their positions, so default (index) ids stay stable and selection survives. */
+  appendRows(rows: RowData[]): void;
+  setScroll(x: number, y: number): void;
+  /** Content offset of a display index's block top (row plus any expansion panels above it). */
+  blockOffset(index: number): number;
+  /** Scroll so the row's block top lands at the viewport top, or its block end at the bottom. */
+  scrollToRow(row: RowData, align?: "top" | "bottom"): void;
+  /** Scroll to the very end of the content. */
+  scrollToEnd(): void;
+  clearScrollRequest(): void;
+  setWidth(width: number): void;
+  setHeight(height: number): void;
+  /**
+   * Set a column's sort. By default the whole sort list is replaced (single-sort behavior).
+   * With `preserve: true` existing sorts are kept: a column already in the list changes
+   * direction in place (keeping its priority), a new column is appended at the lowest priority.
+   */
+  setSort(key: string, direction: SortDirection, opts?: {
+    preserve?: boolean;
+  }): void;
+  /** Replace the whole sort list at once (restoring a saved view); `setSort` covers per-column interactions. */
+  setSorts(sorts: ColumnSort[]): void;
+  /** Remove one column from the sort (later entries move up in priority), or all sorts when no key is given. */
+  clearSort(key?: string): void;
+  isRowSelected(row: RowData): boolean;
+  toggleRow(row: RowData): void;
+  selectAllRows(): void;
+  clearSelection(): void;
+  toggleAllRows(): void;
+  isRowExpanded(row: RowData): boolean;
+  toggleRowExpanded(row: RowData): void;
+  collapseAllRows(): void;
+  private syncColumns;
+  private applyColumnState;
+  private mergedOrder;
+  private expandedAbove;
+  /**
+   * The display index of the row whose block (row + its expansion panel, if any) contains the
+   * vertical content offset `y`. Walks the expanded indices accumulating their extra height —
+   * a row scrolled past its own top stays "at" `y` while its panel is in view, so expanded rows
+   * render as long as any part of their block does.
+   */
+  private indexAtOffset;
+}
+//#endregion
+//#region src/table/column.model.d.ts
+/** Key assigned to a selection column when its def doesn't supply one. */
+declare const SELECTION_COLUMN_KEY = "__selection__";
+declare class ColumnModel {
+  readonly table: TableModel;
+  readonly config: ColumnConfig;
+  pinned: ColumnConfig["pinned"];
+  hidden: boolean;
+  manualWidth: number | undefined;
+  /** Resolved pixel width — distributed across the viewport by the table (see `columnWidths`). */
+  get width(): number;
+  /** Fixed pixel width when the column isn't flexible (manual override or an explicit number). */
+  get fixedWidth(): number | undefined;
+  /** Flex weight (the `N` in `"Nfr"`); `0` when fixed. An unspecified width means `1fr`. */
+  get grow(): number;
+  get minWidth(): number;
+  get maxWidth(): number;
+  get resizable(): boolean;
+  /** Whether header UIs should offer sorting on this column (selection columns never do). */
+  get sortable(): boolean;
+  /** Whether this is the built-in row-selection column. */
+  get selection(): boolean;
+  /**
+   * True for the innermost pinned column on its side (the one bordering the scrollable area).
+   * Consumers hang the pinned boundary shadow off `[data-pinned-edge]` so a group of pinned
+   * columns shows a single shadow at the seam.
+   */
+  get isPinnedEdge(): boolean;
+  /**
+   * True for the outermost pinned column on its side (the one at the viewport edge). Used by the
+   * header to round its outer corners so a pinned column doesn't paint a square over the rounded
+   * header background. Both rendered pinned arrays are ordered outer-edge-first.
+   */
+  get isPinnedOuterEdge(): boolean;
+  get offset(): number;
+  get title(): string;
+  /** 1-based visual column position (pinned blocks at the edges) — the aria-colindex value. */
+  get ariaColIndex(): number;
+  get key(): string;
+  /** Active sort direction for this column, or undefined when it doesn't participate in the sort. */
+  get sortDirection(): SortDirection | undefined;
+  /** 1-based position in the sort priority (the "1"/"2" badge in multi-sort UIs); undefined when unsorted. */
+  get sortIndex(): number | undefined;
+  private get pinnedSiblings();
+  constructor(table: TableModel, config: ColumnConfig);
+  setPinned(pinned: ColumnConfig["pinned"]): void;
+  setManualWidth(width: number | undefined): void;
+  setHidden(hidden: boolean): void;
+  /** Sort by this column — replaces the sort list unless `preserve: true` (see TableModel.setSort). */
+  sortBy(direction: SortDirection, opts?: {
+    preserve?: boolean;
+  }): void;
+  /** Remove this column from the sort; other columns' sorts are untouched. */
+  clearSort(): void;
+  /** Raw cell value for a row — what sorting compares and the default render displays. */
+  getValue(row: RowData): unknown;
+  /** Ascending comparison of two rows by this column's extracted values (`compare` def or the default). */
+  compareRows(a: RowData, b: RowData): number;
+  static fromDef(table: TableModel, def: ColumnDef<any>): ColumnModel;
+}
+//#endregion
+//#region src/table/components/cell-slot.d.ts
+type RenderColumn = (column: ColumnModel) => ReactNode;
+/**
+ * Per-cell reactive boundary. `Table.Header`/`Table.Row` iterate the rendered columns and hand each
+ * off to a `CellSlot` rather than calling the consumer's render function inline — so the render runs
+ * inside *this* component's MobX reaction. The upshot: a cell re-renders only when the observables
+ * *it* reads change (e.g. one field of one row), never because a sibling cell or the row did.
+ *
+ * It renders a transparent fragment, so whatever the consumer returns (a `<Table.Cell>`) lands
+ * directly in the parent grid with no wrapper element.
+ */
+declare const CellSlot: import("react").FunctionComponent<{
+  column: ColumnModel;
+  render: RenderColumn;
+}>;
+//#endregion
+//#region src/table/components/cell-style.d.ts
+/**
+ * Structural style shared by header and body cells: pinned cells stick to their edge at the
+ * column's offset and must be opaque (they overlap scrolling cells). The opaque fill is a CSS var
+ * so the consumer owns the color — set `--table-pinned-bg` once (and override it inside the header
+ * to match a header background). `Canvas` is a theme-aware system default for zero-config use.
+ *
+ * These are the *only* styles the library forces on a cell; everything cosmetic (padding, font,
+ * borders, hover) is left to the consumer's `className`/`style`.
+ */
+declare const pinnedCellStyle: (column: ColumnModel) => CSSProperties;
+//#endregion
+//#region src/table/components/checkbox.d.ts
+/**
+ * Props a selection-control component receives. Kept intentionally minimal so any checkbox — the
+ * native input below, a Chakra `Checkbox`, a Tailwind one — can satisfy it.
+ */
+interface TableCheckboxProps {
+  checked: boolean;
+  indeterminate?: boolean;
+  onChange: () => void;
+  "aria-label"?: string;
+}
+/**
+ * Zero-config fallback used by `<Table.SelectionCell>` / `<Table.SelectAll>` when the consumer
+ * neither registers a `checkbox` on `<Table.Root>` nor passes a render-prop. `indeterminate` is a
+ * DOM-only property, so it's applied via ref rather than an attribute.
+ */
+declare const NativeCheckbox: FC<TableCheckboxProps>;
+//#endregion
+//#region src/table/components/column-resizer.d.ts
+interface TableResizerProps {
+  column: ColumnModel;
+}
+/**
+ * Drag handle on a header cell's edge that resizes its column. Dragging sets the column's
+ * `manualWidth` (treated as a fixed width in the distribution, so the remaining flex columns reflow
+ * to fill); double-click resets it to auto. Right-pinned columns are anchored to the right, so their
+ * handle sits on the left edge and the drag delta is inverted.
+ *
+ * Move/up listeners live on the window for the duration of the drag, so the resize tracks and ends
+ * wherever the pointer is released — not only over the handle.
+ */
+declare const TableResizer: FC<TableResizerProps>;
+//#endregion
+//#region src/table/components/table-root.d.ts
+interface TableRootProps {
+  table: TableModel;
+  children?: React.ReactNode;
+  style?: React.CSSProperties;
+  className?: string;
+  /**
+   * Selection control used by `<Table.SelectionCell>` / `<Table.SelectAll>` when no render-prop is
+   * given. Register it once here to capture your app's checkbox everywhere. Defaults to a native
+   * `<input type="checkbox">`.
+   */
+  checkbox?: FC<TableCheckboxProps>;
+}
+/**
+ * The table skeleton: a non-scrolling viewport wrapper (owns measured size + the shared
+ * `--table-row-height` var) around the scroll container that everything else renders into. This is
+ * the only structural piece consumers mount directly; header/body compose inside it.
+ */
+declare const TableRoot: FC<TableRootProps>;
+//#endregion
+//#region src/table/components/table-header.d.ts
+interface TableHeaderProps {
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Renders one header cell. Called once per *rendered* column (the library owns which columns are
+   * live, their order, and the virtualization spacer); return a `<Table.ColumnHeader>` /
+   * `<Table.SelectionHeaderCell>`.
+   */
+  children: RenderColumn;
+}
+/**
+ * The sticky header row group. Owns layout — the grid track template, the left-pinned / spacer /
+ * unpinned / right-pinned ordering — and defers each cell's content to the `children` render-prop
+ * via a per-cell `CellSlot`.
+ */
+declare const TableHeader: FC<TableHeaderProps>;
+interface TableColumnHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  column: ColumnModel;
+}
+/**
+ * A single header cell. Owns the structural bits (sticky pinning, offset, `data-pinned*`) and stays
+ * cosmetically open — the consumer's `className`/`style` add padding, font, borders, etc.; other
+ * DOM props pass through.
+ */
+declare const TableColumnHeader: FC<TableColumnHeaderProps>;
+//#endregion
+//#region src/table/components/table-body.d.ts
+interface TableBodyProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Renders one row. Called once per *rendered* row; return a `<Table.Row>`. */
+  children: (row: RowData) => ReactNode;
+}
+/**
+ * The virtualized body. Owns the scroll-sized spacer and the `translate3d` window offset, then maps
+ * the rendered slice of rows through the `children` render-prop. Rows are keyed by their row id
+ * (see `rowIds`): by default the original index in the source array — stable under sort/filter/
+ * scroll and across `appendRows` — or the consumer's `getRowId`, which stays stable even when a
+ * refetch replaces the row objects.
+ */
+declare const TableBody: FC<TableBodyProps>;
+interface TableRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  row: RowData;
+  /** Renders one body cell. Called once per rendered column; return a `<Table.Cell>` / `<Table.SelectionCell>`. */
+  children: RenderColumn;
+}
+/**
+ * Memoized on identity so scrolling (and filtering) only renders rows that actually entered/changed.
+ * `children` (the per-column render-prop) gets a fresh closure on every `TableBody` render, so it is
+ * *deliberately excluded* from the comparison — for a row still in the window that closure is
+ * equivalent (it closes over the same `row` and reads row/column state live). Every other prop —
+ * including pass-through DOM props like `onClick` — is compared shallowly. Layout changes still
+ * flow through because the inner `observer` re-renders on the column/width observables it reads, and
+ * per-cell data changes flow through each `CellSlot`'s own observer — neither is gated by this memo.
+ * (Pass stable `className`/`style`/handlers, not fresh inline values, or the row re-renders every frame.)
+ */
+declare const TableRow: import("react").NamedExoticComponent<TableRowProps>;
+interface TableCellProps extends HTMLAttributes<HTMLDivElement> {
+  column: ColumnModel;
+}
+/**
+ * A single body cell. Owns pinning/offset/`data-pinned*`; cosmetics are the consumer's via
+ * `className`/`style`, other DOM props pass through.
+ */
+declare const TableCell: FC<TableCellProps>;
+//#endregion
+//#region src/table/components/table-empty.d.ts
+type TableEmptyProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * The empty-state surface. Render it after `<Table.Body>`, gated by the consumer — e.g.
+ * `table.displayRows.length === 0 && <Table.Empty>…</Table.Empty>` — the library never decides
+ * what "empty" means or what to say about it (no rows vs. filtered-out are different stories,
+ * and only the consumer knows the words and recovery actions).
+ *
+ * Owns placement only: fills the viewport below the sticky header (subtracting the theme-owned
+ * header vars, falling back to the row height) and pins horizontally like the header pill, so
+ * children center in the visible area at any horizontal scroll offset. Cosmetics are the
+ * consumer's; `data-empty` is the styling hook.
+ */
+declare const TableEmpty: FC<TableEmptyProps>;
+//#endregion
+//#region src/table/components/table-expansion.d.ts
+interface TableExpansionProps {
+  row: RowData;
+  className?: string;
+  style?: CSSProperties;
+  children?: ReactNode;
+}
+/**
+ * Memoized on row identity like `TableRow`, with `children` deliberately excluded: the panel's
+ * element tree is rebuilt by the body render-prop every window shift, but for the same row it is
+ * equivalent. Panel content must derive from `row` (or be an observer reading live state) — not
+ * from other values captured in the render-prop closure.
+ */
+declare const TableExpansion: import("react").NamedExoticComponent<TableExpansionProps>;
+//#endregion
+//#region src/table/components/selection.d.ts
+type RowSelectState = Pick<TableCheckboxProps, "checked" | "onChange">;
+type SelectAllState = Pick<TableCheckboxProps, "checked" | "indeterminate" | "onChange">;
+interface SelectionCellProps {
+  column: ColumnModel;
+  row: RowData;
+  /** Custom control. Omit to use the checkbox registered on `<Table.Root>` (native by default). */
+  children?: (state: RowSelectState) => ReactNode;
+}
+/** A body cell wired to per-row selection. Renders the registered checkbox unless given a render-prop. */
+declare const SelectionCell: FC<SelectionCellProps>;
+interface SelectAllProps {
+  /** Custom control. Omit to use the checkbox registered on `<Table.Root>` (native by default). */
+  children?: (state: SelectAllState) => ReactNode;
+}
+/** The select-all control (checked / indeterminate / none). Place inside a header cell, or use `<Table.SelectionHeaderCell>`. */
+declare const SelectAll: FC<SelectAllProps>;
+interface SelectionHeaderCellProps {
+  column: ColumnModel;
+  children?: (state: SelectAllState) => ReactNode;
+}
+/** A header cell holding the centered select-all control — the header twin of `<Table.SelectionCell>`. */
+declare const SelectionHeaderCell: FC<SelectionHeaderCellProps>;
+//#endregion
+//#region src/table/components/namespace.d.ts
+/**
+ * Compound namespace for the table skeleton. Consumers compose these into their own closed
+ * component (styles + defaults captured once), e.g. `<Table.Root><Table.Header>…`.
+ */
+declare const Table: {
+  Root: import("react").FC<TableRootProps>;
+  Header: import("react").FC<TableHeaderProps>;
+  ColumnHeader: import("react").FC<TableColumnHeaderProps>;
+  Body: import("react").FC<TableBodyProps>;
+  Row: import("react").NamedExoticComponent<TableRowProps>;
+  Cell: import("react").FC<TableCellProps>;
+  Empty: import("react").FC<TableEmptyProps>;
+  Expansion: import("react").NamedExoticComponent<TableExpansionProps>;
+  Resizer: import("react").FC<TableResizerProps>;
+  SelectionCell: import("react").FC<SelectionCellProps>;
+  SelectionHeaderCell: import("react").FC<SelectionHeaderCellProps>;
+  SelectAll: import("react").FC<SelectAllProps>;
+};
+//#endregion
+//#region src/table/table.context.d.ts
+declare const tableContext: import("react").Context<TableModel | undefined>;
+declare const useTableContext: () => TableModel;
+declare const TableProvider: import("react").Provider<TableModel | undefined>;
+/**
+ * Slots let a consumer register defaults once on `<Table.Root>` (currently just the selection
+ * `checkbox`) that the built-in parts fall back to. Defaults to a native checkbox so selection
+ * works with zero wiring.
+ */
+interface TableSlots {
+  checkbox: FC<TableCheckboxProps>;
+}
+declare const slotsContext: import("react").Context<TableSlots>;
+declare const TableSlotsProvider: import("react").Provider<TableSlots>;
+declare const useTableSlots: () => TableSlots;
+//#endregion
+//#region src/table/use-scroll.d.ts
+/**
+ * Reports a scroll container's offsets on every scroll event.
+ *
+ * `onScroll` is read through a ref so an inline arrow doesn't re-subscribe on every render — the
+ * table's root re-renders as the window shifts, and re-attaching the listener each time would be
+ * pure waste.
+ */
+declare const useScroll: (ref: React.RefObject<HTMLElement | null>, onScroll: (x: number, y: number) => void) => void;
+//#endregion
+//#region src/table/use-table.d.ts
+declare const useTable: <T>(config?: TableConfig<T>) => TableModel;
+//#endregion
+//#region src/table/util.d.ts
+declare const titleCase: (str: string) => string;
+/**
+ * Resolve a column key against a row: a direct property hit wins (so a literal "a.b" property
+ * still works), otherwise the key is walked as a dot-path ("owner.name").
+ */
+declare const getPath: (obj: unknown, path: string) => unknown;
+/**
+ * Default sort comparator over extracted cell values — nullish first, numbers numerically, Dates
+ * chronologically, everything else by locale string.
+ */
+declare const compareValues: (a: unknown, b: unknown) => number;
+//#endregion
+export { BaseColumnDef, CellSlot, ColumnConfig, ColumnDef, ColumnModel, ColumnSort, ColumnState, ColumnWidth, ColumnsDef, ComputedColumnDef, DotPath, FieldColumnDef, FilterSource, NativeCheckbox, RenderColumn, RowData, RowId, SELECTION_COLUMN_KEY, SelectAll, SelectAllProps, SelectionCell, SelectionCellProps, SelectionColumnDef, SelectionHeaderCell, SelectionHeaderCellProps, SortDirection, Table, TableBody, TableBodyProps, TableCell, TableCellProps, TableCheckboxProps, TableColumnHeader, TableColumnHeaderProps, TableConfig, TableData, TableEmpty, TableEmptyProps, TableExpansion, TableExpansionProps, TableHeader, TableHeaderProps, TableModel, TableProvider, TableResizer, TableResizerProps, TableRoot, TableRootProps, TableRow, TableRowProps, TableSlots, TableSlotsProvider, TableState, compareValues, getPath, pinnedCellStyle, slotsContext, tableContext, titleCase, useScroll, useTable, useTableContext, useTableSlots };
+//# sourceMappingURL=table.d.mts.map

package/dist/table.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.mts","names":[],"sources":["../src/table/table.types.ts","../src/table/table.model.ts","../src/table/column.model.ts","../src/table/components/cell-slot.tsx","../src/table/components/cell-style.ts","../src/table/components/checkbox.tsx","../src/table/components/column-resizer.tsx","../src/table/components/table-root.tsx","../src/table/components/table-header.tsx","../src/table/components/table-body.tsx","../src/table/components/table-empty.tsx","../src/table/components/table-expansion.tsx","../src/table/components/selection.tsx","../src/table/components/namespace.tsx","../src/table/table.context.ts","../src/table/use-scroll.ts","../src/table/use-table.ts","../src/table/util.ts"],"mappings":"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"}