@box-kite/react 1.0.0 → 2.0.1

package/components/dataGrid/models/gridModel.d.ts

@@ -1,18 +1,20 @@
 import { ComponentsAndVariants } from '../../../types';
-import { ColumnFilters, DataGridProps, FilterValue, Key, PaginationState, PinPositionInput, SortDirection } from '../contracts/dataGridContract';
+import { ColumnFilters, DataGridCsvOptions, DataGridProps, DataGridXlsxOptions, ExportConfig, FilterValue, Key, PaginationState, PinPositionInput, SortDirection } from '../contracts/dataGridContract';
+import { default as AggregationModel } from './aggregationModel';
 import { default as ColumnModel } from './columnModel';
 import { default as ColumnVisibilityModel } from './columnVisibilityModel';
+import { default as DataSourceModel } from './dataSourceModel';
 import { default as DetailRowModel } from './detailRowModel';
+import { default as EditModel } from './editModel';
+import { default as ExportModel } from './exportModel';
 import { default as FilterModel } from './filterModel';
 import { default as GroupRowModel } from './groupRowModel';
 import { default as PaginationModel } from './paginationModel';
 import { default as RowModel } from './rowModel';
+import { default as TreeModel } from './treeModel';
 import { default as ViewportModel } from './viewportModel';
-export declare const ROW_NUMBER_CELL_KEY: Key;
+export { GROUPING_CELL_KEY, ROW_DETAIL_CELL_KEY, ROW_NUMBER_CELL_KEY, ROW_SELECTION_CELL_KEY } from './cellKeys';
 export declare const DEFAULT_ROW_NUMBER_COLUMN_WIDTH = 70;
-export declare const ROW_SELECTION_CELL_KEY: Key;
-export declare const GROUPING_CELL_KEY: Key;
-export declare const ROW_DETAIL_CELL_KEY: Key;
 export default class GridModel<TRow> {
     props: DataGridProps<TRow>;
     constructor(props: DataGridProps<TRow>, onChange?: () => void);
@@ -30,6 +32,17 @@ export default class GridModel<TRow> {
      * lazily on next access).
      */
     setProps(props: DataGridProps<TRow>): void;
+    /**
+     * The rows the grid was handed. `data` is optional because `def.dataSource` replaces it, and every
+     * reader goes through here so that "no rows yet" is one empty array rather than a check at each site.
+     */
+    get data(): TRow[];
+    /**
+     * Every row the grid can act on right now. With a datasource that is the blocks it holds rather than
+     * the table behind them — a select-all cannot reach rows nobody has fetched, and saying otherwise is
+     * the one thing a server-backed grid must not do.
+     */
+    get loadedRows(): TRow[];
     get componentName(): keyof ComponentsAndVariants;
     private _identifier;
     /**
@@ -59,27 +72,34 @@ export default class GridModel<TRow> {
     get globalFilterValue(): string;
     private _columnFilters;
     get columnFilters(): ColumnFilters<TRow>;
+    /** Which columns the global filter searches: the ones named, or every column of the caller's own. */
+    private readonly globalFilterColumns;
     /**
-     * Apply global filter (fuzzy search across all or specified columns)
-     */
-    private applyGlobalFilter;
-    /**
-     * Apply column-level filters
+     * Whether one row survives the filters — all three of them, in the order they cost: the caller's own
+     * predicates, the global search box, then the column filters. A row rather than an array, because a
+     * tree is filtered a node at a time (a match keeps its ancestors) rather than in one pass.
      */
-    private applyColumnFilters;
+    rowMatchesFilters(row: TRow): boolean;
+    /** Whether anything is filtering at all — what says a filtering pass can be skipped outright. */
+    get hasRowFilters(): boolean;
+    private matchesGlobalFilter;
+    private matchesColumnFilters;
     /**
      * Check if a cell value matches a filter
      */
     private matchesFilter;
-    /**
-     * Apply external predicate filters from the filters prop
-     */
-    private applyExternalFilters;
     /**
      * Get filtered data (applies external, global, then column filters)
      */
     get filteredData(): TRow[];
     private fireServerStateChange;
+    /** Both pager callbacks: the one carrying a reason, and the `(page, pageSize)` pair it replaces. */
+    private firePaginationChange;
+    /**
+     * A query that changed underneath the pager sends it back to the first page. Returns where the page now
+     * is, which is what the server-state snapshot asks the server for.
+     */
+    private resetToFirstPage;
     /**
      * Set global filter value
      */
@@ -111,8 +131,17 @@ export default class GridModel<TRow> {
         filtered: number;
         total: number;
     };
-    readonly rows: import('../../../utils/memo').Memo<GroupRowModel<TRow>[] | RowModel<TRow>[]>;
-    readonly flatRows: import('../../../utils/memo').Memo<(GroupRowModel<TRow> | RowModel<TRow> | DetailRowModel<TRow>)[]>;
+    /** How many rows the query holds altogether: the server's count where there is one, else what is here. */
+    get totalRowCount(): number;
+    readonly rows: import('../../../utils/memo').Memo<(RowModel<TRow> | GroupRowModel<TRow>)[]>;
+    /**
+     * The columns the group row's label cell covers: the grouping cell itself and the data columns beside it in
+     * its own pin, stopping at the first one carrying an aggregate — past that each column draws a value of its
+     * own, and a number under the wrong heading is worse than a label with less room. With nothing aggregating
+     * the span is every one of them, which is what it was before aggregates existed.
+     */
+    readonly groupingSpan: import('../../../utils/memo').Memo<ColumnModel<TRow>[]>;
+    readonly flatRows: import('../../../utils/memo').Memo<(RowModel<TRow> | GroupRowModel<TRow> | DetailRowModel<TRow>)[]>;
     get rowHeight(): number;
     readonly sizes: import('../../../utils/memo').Memo<Record<string, string>>;
     private _containerWidth;
@@ -139,6 +168,13 @@ export default class GridModel<TRow> {
     expandedGroupRow: Set<Key>;
     private _expandedDetailRows;
     get expandedDetailRows(): Set<Key>;
+    /** The row whose panel a user action just opened, for the row itself to bring into view once. */
+    private _revealDetailKey;
+    /**
+     * Taken by the detail row on the render that puts it in the DOM, and only then: an `auto` panel's
+     * real height exists nowhere else, and the virtualization offsets carry an estimate for it.
+     */
+    takeDetailReveal(rowKey: Key): boolean;
     toggleDetailRow: (rowKey: Key) => void;
     private _page;
     private _pageSize?;
@@ -161,6 +197,34 @@ export default class GridModel<TRow> {
     readonly filter: FilterModel<TRow>;
     /** Pagination concern (navigation + row-range derivations). */
     readonly pagination: PaginationModel<TRow>;
+    /** Aggregation concern (which columns aggregate, and the footer's grand totals). */
+    readonly aggregation: AggregationModel<TRow>;
+    /** Export concern (the columns, rows and levels both file formats are written from). */
+    readonly exporter: ExportModel<TRow>;
+    /** Server row model: the blocks ~def.dataSource~ has answered, and the ones still in flight. */
+    readonly source: DataSourceModel<TRow>;
+    /** Tree data: the shape `def.treeData` describes, and which of its rows are open. */
+    readonly tree: TreeModel<TRow>;
+    /** Cell editing: which cell is open, what a commit is judged by, and the values the grid has accepted. */
+    readonly edits: EditModel<TRow>;
+    /**
+     * Throw the fetched blocks away and ask for them again. The grid invalidates on its own whenever it
+     * changes the query; this is for the half it cannot see — a filter of the page's own, a row somebody
+     * saved, a tenant that changed underneath the closure ~getRows~ was written in.
+     */
+    refresh: () => void;
+    /**
+     * Which export buttons the top bar shows, and the options they press with. `export: true` resolves to
+     * one shared record rather than a fresh one, so the buttons' handlers keep their identity.
+     */
+    get exportConfig(): ExportConfig | undefined;
+    /**
+     * Download the grid as a CSV. Both writers are behind an `import()`, so the format is fetched on the
+     * first press and a grid nobody exports from carries neither.
+     */
+    exportCsv: (options?: DataGridCsvOptions) => Promise<void>;
+    /** Download the grid as an `.xlsx`, with its groups as Excel's own outline levels. */
+    exportXlsx: (options?: DataGridXlsxOptions) => Promise<void>;
     /** Whether any user-facing column is currently visible (else the empty-columns state shows). */
     get hasVisibleColumns(): boolean;
     get isEmpty(): boolean;
@@ -190,14 +254,37 @@ export default class GridModel<TRow> {
     pinColumn: (uniqueKey: string, pin?: PinPositionInput) => void;
     toggleGrouping: (columnKey: Key) => void;
     unGroupAll: () => void;
-    toggleGroupRow: (groupRowKey: Key) => void;
+    /** Grouping changed, so every open path names a group that is not there and every block is stale. */
+    private collapseGroups;
+    /** Bumped by every expand and collapse, so the adapter's fetch effect asks for the level just opened. */
+    private _expansion;
+    get expansionVersion(): number;
+    /**
+     * Whether a group row is open. Explicit state wins: a group somebody has opened or shut is where they
+     * left it, and `def.groupDefaultExpanded` answers for every group nobody has touched. Client-side
+     * grouping only — with a datasource, a level that has never been fetched has no rows to open.
+     */
+    isGroupExpanded(groupRowKey: Key, depth: number): boolean;
+    /** Group rows shut by hand, which is what a `groupDefaultExpanded` grid needs to remember. */
+    private _collapsedGroupRow;
+    toggleGroupRow: (groupRowKey: Key, expanded?: boolean) => void;
+    /**
+     * A tree row opened or shut. The walk over the rows is a different walk — and where the tree is lazy the
+     * level just opened has not been asked for yet, which is what the bumped version tells the fetch effect.
+     */
+    treeExpansionChanged(): void;
     toggleRowSelection: (rowKey: Key) => void;
-    toggleRowsSelection: (rowKeys: Key[]) => void;
+    /** `all` is the header checkbox rather than a count: a group covering every row is still not select-all. */
+    toggleRowsSelection: (rowKeys: Key[], all?: boolean) => void;
     toggleSelectAllRows: () => void;
     toggleColumnVisibility: (columnKey: Key) => void;
     setWidth: (columnKey: Key, width: number) => void;
-    groupColumns: Set<Key>;
-    hiddenColumns: Set<Key>;
+    private _groupColumns?;
+    get groupColumns(): Set<Key>;
+    set groupColumns(value: Set<Key>);
+    private _hiddenColumns?;
+    get hiddenColumns(): Set<Key>;
+    set hiddenColumns(value: Set<Key>);
     columnWidths: Map<Key, number>;
     private _sortColumn?;
     get sortColumn(): Key | undefined;

package/components/dataGrid/models/groupRowCellModel.d.ts

@@ -1,12 +1,14 @@
+import { default as AggregateCellModel } from './aggregateCellModel';
 import { default as ColumnModel } from './columnModel';
 import { default as GridModel } from './gridModel';
 import { default as GroupRowModel } from './groupRowModel';
 /**
  * How a cell participates in a group row's layout: `grouping` is the expand/label cell spanning the
- * grouped columns, `selection` the select-all cell, `spacer` a pinned or leading cell with its own value,
- * and `hidden` a data column absorbed into the grouping cell's span.
+ * grouped columns, `selection` the select-all cell, `aggregate` a column totalling the rows under the group,
+ * `spacer` a pinned or leading cell with its own value, and `hidden` a data column absorbed into the
+ * grouping cell's span.
  */
-export type GroupRowCellKind = 'grouping' | 'selection' | 'spacer' | 'hidden';
+export type GroupRowCellKind = 'grouping' | 'selection' | 'aggregate' | 'spacer' | 'hidden';
 export default class GroupRowCellModel<TRow> {
     readonly grid: GridModel<TRow>;
     readonly row: GroupRowModel<TRow>;
@@ -17,6 +19,12 @@ export default class GroupRowCellModel<TRow> {
     get isFirst(): boolean;
     get isLast(): boolean;
     get cellKind(): GroupRowCellKind;
+    /**
+     * The aggregate over the rows under this group, on the columns that have one. A server group brings its
+     * own total down with it, since the rows it is over were never in the browser to add up.
+     */
+    private readonly _aggregate;
+    get aggregate(): AggregateCellModel<TRow> | null;
     get depthPadding(): number;
     get gridColumnSpan(): number;
     get widthVar(): string;

package/components/dataGrid/models/groupRowModel.d.ts

@@ -1,4 +1,4 @@
-import { Key } from '../contracts/dataGridContract';
+import { AggregateValue, Key } from '../contracts/dataGridContract';
 import { default as ColumnModel } from './columnModel';
 import { default as DetailRowModel } from './detailRowModel';
 import { default as GridModel } from './gridModel';
@@ -9,8 +9,26 @@ export default class GroupRowModel<TRow> {
     readonly groupColumn: ColumnModel<TRow>;
     readonly rows: RowModel<TRow>[] | GroupRowModel<TRow>[];
     readonly rowIndex: number;
-    readonly groupValue: Key;
     constructor(grid: GridModel<TRow>, groupColumn: ColumnModel<TRow>, rows: RowModel<TRow>[] | GroupRowModel<TRow>[], rowIndex: number, groupValue: Key);
+    protected _groupValue: Key;
+    /**
+     * The value this group collects. A getter rather than a parameter property so a subclass can read it
+     * from somewhere else — a field would shadow the override outright, which is what `useDefineForClassFields`
+     * does to a base class's own properties.
+     */
+    get groupValue(): Key;
+    /** What the expand cell reads: the value, and how many rows are under it. */
+    get label(): string;
+    /** Whether the group's rows have arrived at all. Always, until a server answers a level — see `SourceGroupRowModel`. */
+    get placeholder(): boolean;
+    /** Whether the select-all checkbox is offered: a group can only select the rows the grid holds. */
+    get selectable(): boolean;
+    /**
+     * An aggregate the grid was handed rather than one it works out. Nothing server-side can be totalled in
+     * the browser — the rows are not here — so a server group row carries its own totals and this is where
+     * they come from; `undefined` means "compute it", which is every client-side group.
+     */
+    aggregateValue(_column: ColumnModel<TRow>): AggregateValue | undefined;
     get key(): Key;
     parentRow?: GroupRowModel<TRow>;
     private readonly _cells;
@@ -41,6 +59,8 @@ export default class GroupRowModel<TRow> {
     get allRows(): RowModel<TRow>[];
     get groupingColumn(): ColumnModel<TRow>;
     get groupingColumnGridColumn(): number;
+    /** Whether the label cell has swallowed this column, which is what leaves it with no cell of its own. */
+    spans(column: ColumnModel<TRow>): boolean;
     readonly kind: "group";
     toggleRow(): void;
     /** Select/deselect every leaf row under this group. */

package/components/dataGrid/models/rowModel.d.ts

@@ -5,9 +5,15 @@ import { default as GridModel } from './gridModel';
 import { default as GroupRowModel } from './groupRowModel';
 export default class RowModel<TRow> {
     readonly grid: GridModel<TRow>;
-    readonly data: TRow;
     readonly rowIndex: number;
     constructor(grid: GridModel<TRow>, data: TRow, rowIndex: number);
+    protected _data: TRow;
+    /**
+     * The row's values. A getter rather than a parameter property so a subclass can read them from
+     * somewhere else — `SourceRowModel` reads them out of the block cache, which is what lets a block
+     * arriving change what a row shows without a single model being rebuilt.
+     */
+    get data(): TRow;
     private _key?;
     /**
      * Resolved lazily: getRowKey() can call crypto.randomUUID(), so building a model for every
@@ -18,6 +24,8 @@ export default class RowModel<TRow> {
     parentRow?: GroupRowModel<TRow>;
     readonly count = 1;
     readonly kind: "row";
+    /** Whether this is a row the server has not sent yet — see `SourceRowModel`, which answers it live. */
+    get placeholder(): boolean;
     /** Whether clicking the row toggles its detail panel. */
     get expandOnRowClick(): boolean;
     toggleDetail: () => void;
@@ -28,6 +36,10 @@ export default class RowModel<TRow> {
     /** Where a cell starts in column-index space: one cell per column, so its own ordinal. */
     columnOf(cell: number): number;
     get selected(): boolean;
+    /** Half-selected, which only a tree row with the cascade on can be. */
+    get indeterminate(): boolean;
+    /** Select or deselect this row. A tree row under `selection: 'cascade'` takes its subtree with it. */
+    toggleSelection: () => void;
     get expanded(): boolean;
     get flatRows(): (RowModel<TRow> | DetailRowModel<TRow>)[];
     get allRows(): this;

package/components/dataGrid/models/sourceGroupRowModel.d.ts

@@ -0,0 +1,45 @@
+import { AggregateValue, Key } from '../contracts/dataGridContract';
+import { default as ColumnModel } from './columnModel';
+import { default as GridModel } from './gridModel';
+import { default as GroupRowModel } from './groupRowModel';
+import { default as SourceLevel } from './sourceLevel';
+/**
+ * One group row of a `def.dataSource` grid: a row of a level the server answered with groups rather than
+ * data. It reads its value, its count and its totals *through* the block cache, the way `SourceRowModel`
+ * reads a leaf row's — so a block arriving fills in fifty group rows with no model rebuilt.
+ *
+ * Its children are not here and never were: a group holds a level of its own, fetched when somebody opens
+ * it. That is what `count` (the server's number) and `allRows` (empty) are both saying, and it is why the
+ * select-all checkbox is not offered — a group cannot select rows the browser has never seen.
+ */
+export default class SourceGroupRowModel<TRow> extends GroupRowModel<TRow> {
+    private readonly level;
+    constructor(grid: GridModel<TRow>, level: SourceLevel<TRow>, groupColumn: ColumnModel<TRow>, rowIndex: number);
+    private get row();
+    /** The row the server sent for this group: its value, and whatever totals came with it. */
+    get data(): TRow | undefined;
+    get placeholder(): boolean;
+    get groupValue(): Key;
+    /** The path that names this group's own level, and the identity the expansion set holds it by. */
+    get groupKeys(): Key[];
+    /**
+     * Keyed by the path rather than by position, so a group stays open while the block under it is dropped
+     * and fetched again. A group nobody has yet is keyed by where it sits — `getRowKey` has nothing to read.
+     */
+    get key(): Key;
+    get depth(): number;
+    /** The server's count, or nothing at all — a level it could not count cheaply shows the value alone. */
+    get count(): number;
+    get label(): string;
+    /** The totals came down with the group row, because the rows they are over are not in the browser. */
+    aggregateValue(column: ColumnModel<TRow>): AggregateValue | undefined;
+    get selectable(): boolean;
+    get selected(): boolean;
+    get indeterminate(): boolean;
+    get expanded(): boolean;
+    /** Nothing under it is in the browser, so nothing under it can be selected or exported. */
+    get allRows(): never[];
+    toggleRow(): void;
+}
+/** The key a group path is held by, in `expandedGroupRow` and in this model. */
+export declare function groupPathKey(groupKeys: Key[]): Key;

package/components/dataGrid/models/sourceLevel.d.ts

@@ -0,0 +1,71 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as DataSourceModel } from './dataSourceModel';
+/** Where one block of rows has got to. A block is the unit of a request, of a wait and of a failure. */
+export type BlockStatus = 'loading' | 'loaded' | 'error';
+/**
+ * One level of a `def.dataSource` grid: the blocks answering a single path, and the count and end-of-data
+ * they arrived with. With nothing opened there is exactly one of these; a group or a tree row being opened
+ * adds another, and which of the two the path *is* is the only thing that differs between them.
+ *
+ * A level knows the row that opened it (`parent`, `parentRowIndex`), because a group's children are worth
+ * nothing without it: eviction has to keep the chain above a level in play or the rows on screen would
+ * lose the group row they hang off.
+ */
+export default class SourceLevel<TRow> {
+    private readonly source;
+    /** What names this level, outermost first: group values, or a tree row's keys. `[]` is the top. */
+    readonly path: Key[];
+    readonly parent?: SourceLevel<TRow> | undefined;
+    /** Where in `parent` the group row that opened this one sits. A sort can move it. */
+    parentRowIndex: number;
+    constructor(source: DataSourceModel<TRow>, 
+    /** What names this level, outermost first: group values, or a tree row's keys. `[]` is the top. */
+    path: Key[], parent?: SourceLevel<TRow> | undefined, 
+    /** Where in `parent` the group row that opened this one sits. A sort can move it. */
+    parentRowIndex?: number, 
+    /** A count carried over an invalidation, so a filter keystroke does not collapse the scrollbar. */
+    keepCount?: number);
+    private blocks;
+    private _totalCount?;
+    /** False once disposed of: a request still in flight must not write into a level nobody can reach. */
+    private alive;
+    /** True once a block came back shorter than it was asked for: there is nothing past it. */
+    private _reachedEnd;
+    /** Its own identity, and the key it is held under. JSON, so no path value can spell another path. */
+    static keyOf(path: Key[]): string;
+    get key(): string;
+    /** The group this level sits inside — its path, unless the path is a tree's. */
+    get groupKeys(): Key[];
+    /** The row this level holds the children of — its path, when the path is a tree's. */
+    get treeKeys(): Key[];
+    /** What a row of this level that has not arrived is keyed by — unique per level, stable per position. */
+    get placeholderKey(): string;
+    /** How deep this level sits — for a grouped source, which column it groups by. */
+    get depth(): number;
+    /** Whether its rows are groups rather than data — true until the last grouped column has been named. */
+    get isGroupLevel(): boolean;
+    /**
+     * How many rows this level lays out. The server's count when there is one; otherwise what has been
+     * loaded, plus one block to scroll into — which is what keeps an uncounted source reachable.
+     */
+    get rowCount(): number;
+    get totalCount(): number | undefined;
+    rowAt(index: number): TRow | undefined;
+    /** How many leaf rows a group row holds, when the server said. */
+    groupCountAt(index: number): number | undefined;
+    statusAt(index: number): BlockStatus | 'missing';
+    get isLoading(): boolean;
+    failedBlocks(): number[];
+    errorAt(index: number): unknown;
+    has(index: number): boolean;
+    /** Which blocks are in hand, loaded or not — what eviction and the row walks read. */
+    loadedBlocks(): {
+        index: number;
+        rows: TRow[];
+    }[];
+    drop(index: number): void;
+    /** Abort everything in flight and forget the lot — a level whose query or whose group has gone. */
+    dispose(): void;
+    retry(): void;
+    load(index: number): void;
+}

package/components/dataGrid/models/sourceRowModel.d.ts

@@ -0,0 +1,29 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+import { default as RowModel } from './rowModel';
+import { default as SourceLevel } from './sourceLevel';
+/**
+ * One row of a `def.dataSource` grid, whether or not the server has answered for it yet. It reads its
+ * values *through* the block cache rather than holding them, which is the whole point: a block arriving
+ * changes what fifty rows show with no model rebuilt, and the million rows below the viewport cost one
+ * proxy each — that is, nothing, until somebody scrolls to one.
+ *
+ * Its key follows the same rule. A loaded row is keyed by its data, so a selection or an open detail
+ * panel survives the block being dropped and fetched again; a row that is still a skeleton is keyed by
+ * its position, since `getRowKey` would mint a fresh id on every render and React would remount it.
+ */
+export default class SourceRowModel<TRow> extends RowModel<TRow> {
+    /** The level it belongs to: the top one, or the group or tree row somebody opened. */
+    protected readonly sourceLevel: SourceLevel<TRow>;
+    constructor(grid: GridModel<TRow>, 
+    /** The level it belongs to: the top one, or the group or tree row somebody opened. */
+    sourceLevel: SourceLevel<TRow>, rowIndex: number);
+    private get row();
+    get data(): TRow;
+    get placeholder(): boolean;
+    get key(): Key;
+    /** Nothing to open and nothing to select: a row nobody has yet is not a row anybody can act on. */
+    get expandOnRowClick(): boolean;
+    get expanded(): boolean;
+    get selected(): boolean;
+}

package/components/dataGrid/models/sourceTreeRowModel.d.ts

@@ -0,0 +1,23 @@
+import { default as SourceRowModel } from './sourceRowModel';
+import { TreeRow } from './treeRow';
+/**
+ * One row of a lazy tree: a `def.dataSource` row that may hold rows of its own, fetched when somebody
+ * opens it. Everything it knows about the tree it reads off its level — how deep it sits, how many
+ * siblings it has — so a block landing fills in fifty rows of a tree with no model rebuilt.
+ *
+ * What is under it is not here and never was, which is the difference from the eager `TreeRowModel`: it
+ * cannot walk its own subtree, so a cascading selection is not offered and a row the server has not
+ * answered for grows no chevron.
+ */
+export default class SourceTreeRowModel<TRow> extends SourceRowModel<TRow> implements TreeRow {
+    readonly isTreeRow = true;
+    /** How deep the level is, which is how deep every row of it is. */
+    get level(): number;
+    get position(): number;
+    /** The server's count, or `-1` — ARIA's "nobody knows", which is the honest answer to an uncounted level. */
+    get siblings(): number;
+    /** A row the server has not answered for holds nothing anybody can ask about yet. */
+    get hasChildren(): boolean;
+    get treeExpanded(): boolean;
+    toggleTree: () => void;
+}

package/components/dataGrid/models/treeModel.d.ts

@@ -0,0 +1,94 @@
+import { Key, TreeDataConfig } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+import { default as TreeRowModel } from './treeRowModel';
+/** One row of the tree and everything under it, before any of it is a model. */
+export interface TreeNode<TRow> {
+    data: TRow;
+    children: TreeNode<TRow>[];
+}
+/**
+ * Rows that hold rows. The shape of the tree comes out of the data — nested in it, or named by a path on
+ * every row — and everything else here is what the grid does with it: filtering that keeps a match's
+ * ancestors, a sort that happens inside each parent, and which rows are open.
+ */
+export default class TreeModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    constructor(grid: GridModel<TRow>);
+    get config(): TreeDataConfig<TRow> | undefined;
+    /** Whether the grid is a tree at all — the chevrons, the indent, `role="treegrid"` and the arrow keys. */
+    get enabled(): boolean;
+    /**
+     * Whether the tree is in the browser. The two halves are the same feature from opposite ends: eager
+     * reads the shape off `data` and holds the lot, lazy asks the datasource for one level at a time — so
+     * everything here that walks the data is the eager half's, and the source owns the other.
+     */
+    get isEager(): boolean;
+    get isLazy(): boolean;
+    /**
+     * Whether a lazy tree's row holds anything — the one thing a row's own values cannot say, since what
+     * is under it has never been in the browser. Eager rows answer it from their node instead.
+     */
+    rowHasChildren(row: TRow): boolean;
+    /** Which column carries the chevrons: the one named, or the first of the caller's own. */
+    get columnKey(): Key | undefined;
+    /** How far one level indents, on the ÷4 spacing scale. */
+    get indent(): number;
+    /** Whether ticking a row ticks everything under it. Never on a lazy tree: it cannot reach what it has not got. */
+    get cascades(): boolean;
+    /** Whether the tree is read off a path per row rather than nested in the rows. */
+    private get isFlat();
+    private childrenOf;
+    private pathOf;
+    private buildNested;
+    /**
+     * The flat shape: every row carries its own path, and the tree is what those paths describe. Shallower
+     * rows are taken first (a stable sort, so siblings keep the order they were handed in) — a child cannot
+     * find a parent that has not been seen yet, and the data is under no obligation to be in order.
+     */
+    private buildFlat;
+    /**
+     * What the filters leave: a row that matches, and every ancestor of one — a match nobody can see the
+     * path to is a match the grid has hidden. A parent that matches on its own stays as a leaf, since the
+     * rows under it did not.
+     */
+    private prune;
+    /** A sort happens inside each parent: a tree sorted across its levels would not be a tree any more. */
+    private sortNodes;
+    /**
+     * The tree the data describes, filtered and sorted. Its own memo rather than part of `grid.rows`:
+     * opening a row rebuilds the models and must not rebuild the tree underneath them.
+     */
+    readonly nodes: import('../../../utils/memo').Memo<TreeNode<TRow>[]>;
+    /**
+     * Every row of the tree the filters left, in display order and whatever is open — what a select-all
+     * reaches, what the footer totals and what an export writes. `data` is only the top of a nested tree,
+     * so nothing that means "every row" can read it.
+     */
+    readonly allRows: import('../../../utils/memo').Memo<TRow[]>;
+    /** Every row in the data, filters ignored: the filter's own options, and what the row count is out of. */
+    everyRow(): TRow[];
+    /**
+     * One model per row that is showing, in display order. A shut row's children are not built at all,
+     * which is what keeps a tree nobody has opened the cost of its top level.
+     */
+    rowList(): TreeRowModel<TRow>[];
+    /** Rows opened and rows shut since the grid mounted. Explicit state wins over `defaultExpanded`. */
+    private _opened;
+    private _closed;
+    private _cachedKeys?;
+    /** A key list as a set, rebuilt only when the list itself changes — this is read once per row. */
+    private keySet;
+    private defaultExpanded;
+    /**
+     * Whether anything could be open at all. A lazy tree's walk reads a key off every row in hand to find
+     * the open ones, and a tree nobody has touched is the common case — so it is worth one check first.
+     */
+    get mayExpand(): boolean;
+    isExpanded(key: Key, level: number): boolean;
+    /**
+     * Every open row, walked down the tree as it is displayed — a row under a shut one is not open however
+     * it is marked. Only walked when somebody is listening, since it costs a key for every row it reaches.
+     */
+    private expandedKeys;
+    toggle: (key: Key, level: number) => void;
+}

package/components/dataGrid/models/treeRow.d.ts

@@ -0,0 +1,22 @@
+import { default as RowModel } from './rowModel';
+/**
+ * What the grid needs of a row that holds rows. Two models answer it and neither can extend the other:
+ * the eager `TreeRowModel` holds its node, and the lazy `SourceTreeRowModel` reads its level out of the
+ * block cache — so the chevron, the indent and the sideways keys work off this rather than off a class.
+ */
+export interface TreeRow {
+    /** Duck tag, so the guard below needs neither class in scope and no import cycle with them. */
+    readonly isTreeRow: true;
+    /** 0 at the top of the tree. `aria-level` is this plus one. */
+    readonly level: number;
+    /** Where it sits among its siblings, and how many of them there are — `aria-posinset`/`aria-setsize`. */
+    readonly position: number;
+    readonly siblings: number;
+    /** Whether there is anything under it: a row with nothing under it never grows a chevron. */
+    readonly hasChildren: boolean;
+    /** Whether the rows under it are showing. */
+    readonly treeExpanded: boolean;
+    readonly toggleTree: () => void;
+}
+/** Whether a row of the grid is one of the tree's. Narrows to a row, since every tree row is one. */
+export declare function isTreeRow<TRow>(row: unknown): row is RowModel<TRow> & TreeRow;

package/components/dataGrid/models/treeRowModel.d.ts

@@ -0,0 +1,50 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as DetailRowModel } from './detailRowModel';
+import { default as GridModel } from './gridModel';
+import { default as RowModel } from './rowModel';
+import { TreeNode } from './treeModel';
+import { TreeRow } from './treeRow';
+/**
+ * One row of a `def.treeData` tree: a row of the grid in every sense — its own values, its own cells,
+ * its own detail panel — that happens to hold rows of its own. The rows under it are its siblings in the
+ * same rowgroup rather than its children in the DOM, which is what `aria-level` is for.
+ */
+export default class TreeRowModel<TRow> extends RowModel<TRow> implements TreeRow {
+    private readonly node;
+    /** 0 at the top of the tree. `aria-level` is this plus one. */
+    readonly level: number;
+    /** Where it sits among its siblings, and how many of them there are — `aria-posinset`/`aria-setsize`. */
+    readonly position: number;
+    readonly siblings: number;
+    readonly treeParent?: TreeRowModel<TRow> | undefined;
+    readonly isTreeRow = true;
+    constructor(grid: GridModel<TRow>, node: TreeNode<TRow>, rowIndex: number, 
+    /** 0 at the top of the tree. `aria-level` is this plus one. */
+    level: number, 
+    /** Where it sits among its siblings, and how many of them there are — `aria-posinset`/`aria-setsize`. */
+    position: number, siblings: number, treeParent?: TreeRowModel<TRow> | undefined);
+    /** Built by `TreeModel` right after this row, and only where it is open: a shut row renders nothing. */
+    children: TreeRowModel<TRow>[];
+    /** Whether there is anything under it at all — read off the data, so a shut row still knows. */
+    get hasChildren(): boolean;
+    /** Whether the rows under it are showing. A row with nothing under it is never open. */
+    get treeExpanded(): boolean;
+    toggleTree: () => void;
+    /**
+     * Every key in this row's subtree, its own first. Walked over the *data* rather than the models, so a
+     * shut row can still select what is under it; cached per model, and the models are rebuilt whenever
+     * the tree is.
+     */
+    private readonly _subtreeKeys;
+    get subtreeKeys(): Key[];
+    /**
+     * With `selection: 'cascade'` a row is selected when everything under it is — a parent whose children
+     * are not all ticked is not itself ticked, which is what makes the indeterminate state mean something.
+     */
+    get selected(): boolean;
+    /** Some of the subtree is selected and some is not. Always false without the cascade. */
+    get indeterminate(): boolean;
+    toggleSelection: () => void;
+    /** This row, its detail panel if one is open, and then everything under it — in display order. */
+    get flatRows(): (RowModel<TRow> | DetailRowModel<TRow>)[];
+}