@box-kite/react 0.0.1 → 2.0.0

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>)[];
+}

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

@@ -0,0 +1,44 @@
+import { default as GridModel } from './gridModel';
+/** Windowing parameters for the virtualized body. Rows are sliced by the adapter from these. */
+export interface ViewportWindow {
+    /** Index of the first row to render. */
+    startIndex: number;
+    /** Number of rows to render starting at `startIndex`. */
+    take: number;
+    /** Pixel offset to translate the rendered slice down to its scroll position. */
+    translateY: number;
+    /** Total scrollable height of all rows. */
+    totalHeight: number;
+    /** Fixed viewport height, or undefined when rendering all rows. */
+    viewHeight: number | undefined;
+}
+/**
+ * Headless virtualization: given a scrollTop, computes which rows are visible and how
+ * to position them. Pure math — `scrollTop` is owned by the adapter (so scrolling does
+ * not notify the store / re-render the whole grid).
+ */
+export default class ViewportModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    static readonly DEFAULT_VISIBLE_ROWS_COUNT = 10;
+    static readonly ROWS_TO_PRELOAD = 20;
+    constructor(grid: GridModel<TRow>);
+    get showAll(): boolean;
+    get hasDetailRows(): boolean;
+    get isEmpty(): boolean;
+    /** Number of rows the viewport shows at once (all rows when `visibleRowsCount === 'all'`). */
+    get visibleRowsCount(): number;
+    /**
+     * Rows a PageUp/PageDown moves. Deliberately not `visibleRowsCount`, which is every row when
+     * `visibleRowsCount === 'all'` — a Page key that jumps to the end of the grid is the End key.
+     */
+    get pageRows(): number;
+    get viewHeight(): number | undefined;
+    get totalHeight(): number;
+    /** Height to reserve for the empty/no-data state. */
+    get emptyHeight(): number;
+    /** Where a row sits inside the scrolled body — what a keyboard jump scrolls to. */
+    rowTop(index: number): number;
+    /** Binary search for the first row whose offset is <= scrollTop (variable-height rows). */
+    private findStartIndex;
+    window(scrollTop: number): ViewportWindow;
+}

package/components/dataGrid/useGrid.d.ts

@@ -0,0 +1,8 @@
+import { DataGridProps } from './contracts/dataGridContract';
+import { default as GridModel } from './models/gridModel';
+/**
+ * React binding for the headless GridModel store: the model owns all state and behaviour, React only
+ * subscribes. `setProps` syncs incoming props during render, and `useSyncExternalStore` re-renders
+ * whenever the model notifies.
+ */
+export default function useGrid<TRow>(props: DataGridProps<TRow>): GridModel<TRow>;

package/components/dataGrid/useGridNavigation.d.ts

@@ -0,0 +1,21 @@
+import { GridNavigation } from './gridNavigationContext';
+import { default as GridModel } from './models/gridModel';
+export interface GridNavigationOptions<TRow> {
+    grid: GridModel<TRow>;
+    /** The scrolling element — a jump to a row outside the rendered window has to scroll first. */
+    scrollerRef: React.RefObject<HTMLElement | null>;
+    scrollTop: number;
+    onScrollTo: (top: number) => void;
+}
+export interface GridNavigator extends GridNavigation {
+    /** Put this on the `role="grid"` element: cell keystrokes bubble to it. */
+    onKeyDown: (event: React.KeyboardEvent) => void;
+}
+/**
+ * APG's grid pattern over a virtualized body. Focus lives on the cells, one in the tab order at a time,
+ * and `useRovingFocus` owns which; what belongs here is what virtualization adds — a jump to a row nobody
+ * has scrolled to has no element to focus, so the move scrolls, waits for the render it caused, and
+ * focuses from a layout effect. Inside a cell the grid steps back: the widget keeps every key, and Enter
+ * or F2 got focus there while Escape takes it out.
+ */
+export default function useGridNavigation<TRow>(options: GridNavigationOptions<TRow>): GridNavigator;