@box-kite/react 2.0.1 → 2.1.0

package/components/dataGrid/components/dataGridGroupRow.d.ts

@@ -3,6 +3,17 @@ interface Props<TRow> {
     row: GroupRowModel<TRow>;
     /** Position in the whole row list, not in the rendered window. */
     index: number;
+    /**
+     * The grid's store version. Not read: it is what tells the memo below that something the row draws
+     * from the model has moved, since every other prop it takes holds still while the window slides.
+     */
+    version: number;
 }
-export default function DataGridGroupRow<TRow>(props: Props<TRow>): import("react").JSX.Element;
-export {};
+declare function DataGridGroupRowImpl<TRow>(props: Props<TRow>): import("react").JSX.Element;
+/**
+ * Memoized on its props, which is what makes a scroll cost one row rather than a window of them: the
+ * rows either side of the new one are handed the same model and the same index, so they bail out.
+ * `memo` loses the type parameter, and the cast is what hands it back.
+ */
+declare const DataGridGroupRow: typeof DataGridGroupRowImpl;
+export default DataGridGroupRow;

package/components/dataGrid/components/dataGridRow.d.ts

@@ -3,6 +3,17 @@ interface Props<TRow> {
     row: RowModel<TRow>;
     /** Position in the whole row list, not in the rendered window. */
     index: number;
+    /**
+     * The grid's store version. Not read: it is what tells the memo below that something the row draws
+     * from the model has moved, since every other prop it takes holds still while the window slides.
+     */
+    version: number;
 }
-export default function DataGridRow<TRow>(props: Props<TRow>): import("react").JSX.Element;
-export {};
+declare function DataGridRowImpl<TRow>(props: Props<TRow>): import("react").JSX.Element;
+/**
+ * Memoized on its props, which is what makes a scroll cost one row rather than a window of them: the
+ * rows either side of the new one are handed the same model and the same index, so they bail out.
+ * `memo` loses the type parameter, and the cast is what hands it back.
+ */
+declare const DataGridRow: typeof DataGridRowImpl;
+export default DataGridRow;

package/components/dataGrid/contracts/dataGridContract.d.ts

@@ -309,8 +309,48 @@ export interface CellEdit<TRow> {
  * message the cell shows and a screen reader is told; `false` rejects it with the grid's own wording.
  */
 export type CellEditResult = void | boolean | string;
-/** Why the edit stream changed: a cell was accepted, or the host took the edits off the grid's hands. */
-export type DataGridEditReason = 'edit' | 'clear';
+/** Why the edit stream changed: a cell was accepted, a block was pasted, or the host took the edits. */
+export type DataGridEditReason = 'edit' | 'paste' | 'clear';
+/** One cell a paste could not write, and the message `def.onCellEdit` refused it with. */
+export interface RejectedCellEdit<TRow> extends CellEdit<TRow> {
+    error: string;
+}
+/**
+ * What one Ctrl+V did, reported once for the whole block however many cells it covered. A refusal skips
+ * its own cell and nothing else — a paste is many independent judgements, and one bad value must not lose
+ * the ninety-nine good ones — so `applied` and `rejected` together are every cell that was asked about.
+ */
+export interface DataGridPaste<TRow> {
+    /** The block it landed in. It reads the values the grid now shows, so `values()` is the result. */
+    range: CellRange;
+    /** The cells that were written, in the order they were judged. */
+    applied: CellEdit<TRow>[];
+    /** The cells that were refused, each with what it was refused with. */
+    rejected: RejectedCellEdit<TRow>[];
+    /** How many cells the block covered that cannot be edited at all — a read-only column, a group row, a row nobody has fetched. */
+    skipped: number;
+}
+/**
+ * The block of cells that is marked, in display order. `startRow`/`endRow` are indices into the rows on
+ * screen rather than keys, because a range may reach rows a datasource has not fetched — and building a
+ * key for each of them is exactly what a lazily-listed grid must not do.
+ */
+export interface CellRange {
+    /** The first row the rectangle covers. */
+    startRow: number;
+    /** The last row it covers, inclusive. */
+    endRow: number;
+    /** The columns it covers, by key, in display order. */
+    columns: Key[];
+    /**
+     * What is in it, row by row in display order — through the same pipeline an export uses, so a figure
+     * read here is the one a `.csv` would carry. A call rather than a field: a range can cover more rows
+     * than anybody has fetched, so the values are gathered when they are asked for.
+     */
+    values: () => unknown[][];
+}
+/** Why the range changed: a cell became the current one, the block grew, or the grid gave it up. */
+export type DataGridRangeReason = 'select' | 'extend' | 'clear';
 /** Controls which sections appear in the column header context menu */
 export interface ContextMenuConfig {
     /** Show sort actions (Sort Ascending, Sort Descending, Clear Sort). Default: true */
@@ -500,6 +540,17 @@ export interface GridDefinition<TRow> {
      * not, since it costs the keyboard its way out of the grid.
      */
     tabNavigation?: 'none' | 'cells';
+    /**
+     * Rectangular cell selection: a drag or Shift with the arrow keys marks a block of cells, and Ctrl+C
+     * copies it as the tab-separated text a spreadsheet pastes. Off by default, because a drag that marks
+     * cells is a drag that no longer selects text — which is a decision about the page, not about the grid.
+     *
+     * The *current* cell needs no opt-in and never did: every grid marks the cell its arrows carry on from,
+     * whether the pointer or the keyboard put it there, and Ctrl+C on it copies that one cell. Ctrl+V is
+     * the same — it fills from the current cell wherever a column is editable, and a block only gives it a
+     * bigger target.
+     */
+    rangeSelection?: boolean;
     rowHeight?: number;
     /** Number of visible rows. Set to 'all' to render all rows without virtualization or vertical scrollbar. */
     visibleRowsCount?: number | 'all';
@@ -653,6 +704,19 @@ export interface DataGridProps<TRow> extends Omit<BoxProps<'div', 'datagrid'>, '
      * when `clearEdits()` says the host has saved them.
      */
     onCellEditsChange?: ChangeHandler<CellEdit<TRow>[], DataGridEditReason>;
+    /**
+     * Fires with the block of cells that is marked, or `undefined` once the grid has given it up. It
+     * reports the single current cell too, which is the degenerate range and what Ctrl+C acts on — so a
+     * status bar summing the selection is `range?.values()`, and a `reason` of `'select'` is the press or
+     * the arrow key that collapsed it back to one.
+     */
+    onRangeChange?: ChangeHandler<CellRange | undefined, DataGridRangeReason>;
+    /**
+     * Fires once with everything a Ctrl+V did: the cells that were written, the cells `def.onCellEdit`
+     * refused and the message each was refused with, and how many the block covered that nothing could be
+     * written to. It fires after the values have landed, so `range.values()` reads what the grid now shows.
+     */
+    onPaste?: (paste: DataGridPaste<TRow>) => void;
     /** Fires with the column and direction the grid is sorted by, or `undefined` once the sort is cleared. */
     onSortingChange?: ChangeHandler<DataGridSort | undefined, DataGridSortReason>;
     /**

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

@@ -28,6 +28,9 @@ export default class CellModel<TRow> {
     get draft(): unknown;
     /** What the last commit was rejected with. The editor stays open until it is fixed or abandoned. */
     get error(): string | undefined;
+    /** Whether the last paste was refused on this cell. A batch shows its refusals on the cells, not in
+     *  an editor: there is no editor open on any of them, and the messages go to `onPaste`. */
+    get rejected(): boolean;
     /** Whether an async `def.onCellEdit` has been asked about this cell and has not answered. */
     get pending(): boolean;
     /**

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

@@ -1,9 +1,12 @@
 import { CellEdit, CellEditorConfig, Key } from '../contracts/dataGridContract';
 import { default as ColumnModel } from './columnModel';
 import { default as GridModel } from './gridModel';
+import { RangeBounds } from './rangeModel';
 import { default as RowModel } from './rowModel';
 /** What a rejection with no message of its own says. A silent refusal is one nobody can act on. */
 export declare const DEFAULT_EDIT_ERROR = "Invalid value";
+/** What a pasted value is refused with when it is not the kind of value the cell holds at all. */
+export declare const WRONG_KIND_ERROR = "Wrong kind of value";
 /** A key that starts an edit by replacing the value: one printable character, unmodified. */
 export declare function isTypingKey(event: React.KeyboardEvent): boolean;
 /**
@@ -21,6 +24,8 @@ export default class EditModel<TRow> {
     constructor(grid: GridModel<TRow>);
     /** The accepted values, keyed by cell. Cleared by `clearEdits()` and by a datasource refresh. */
     private readonly values;
+    /** The cells the last paste was refused on. They keep the invalid ring, which is all a batch can show. */
+    private rejected;
     private _edits;
     private _active?;
     private _token;
@@ -31,6 +36,10 @@ export default class EditModel<TRow> {
     /** The editor a cell opens, worked out from the value in it when the column names none. */
     editorFor(column: ColumnModel<TRow>, value: unknown): CellEditorConfig<TRow>;
     isEditing(rowKey: Key, columnKey: Key): boolean;
+    /** Whether an editor is open anywhere. A Ctrl+V while one is belongs to the editor, not to the grid. */
+    get isOpen(): boolean;
+    /** Whether the last paste was refused on this cell, which is the only mark a batch of them can carry. */
+    isRejected(rowKey: Key, columnKey: Key): boolean;
     /** What is in the open editor. `undefined` when none is open, which a cell checks with `isEditing`. */
     get draft(): unknown;
     /** What the last commit was rejected with. The editor stays open on it. */
@@ -65,6 +74,24 @@ export default class EditModel<TRow> {
      * the server says next is the newer answer.
      */
     clearEdits: () => void;
+    /**
+     * Fill a block from the clipboard, one `def.onCellEdit` judgement per cell. `textAt` is read by offsets
+     * into the block rather than by grid coordinates, because a short clipboard wraps to fill a long block
+     * and only the caller knows what it was carrying.
+     *
+     * A refusal skips its own cell and nothing else: a paste is many independent judgements, and stopping
+     * at the first bad value would leave the block half written with no way back. Everything the block
+     * covered that cannot be edited at all — a read-only column, a group row, a row nobody has fetched — is
+     * skipped before anything is asked, so a validator hears about cells that could actually take a value.
+     */
+    paste(bounds: RangeBounds, textAt: (row: number, column: number) => string): void;
+    /** A `select`'s options, which may be a function of the row being pasted into. */
+    private optionsFor;
+    /**
+     * What the block's answers do, once they are all in. One notification for the whole paste however many
+     * cells it held — the edit stream is a list, and a hundred appends to it is a hundred renders.
+     */
+    private settlePaste;
     /**
      * The next editable cell, as a pair of grid coordinates — along the row first and on into the rows
      * after it, which is the order Tab walks a spreadsheet in. Nothing when there is none: Tab then does

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

@@ -25,8 +25,9 @@ export default class ExportModel<TRow> {
     /**
      * One row's value for one column: the column's own `exportValue` when it has one, else the raw field —
      * either way through the edits, so a file carries what the grid is showing rather than what it was given.
+     * Public because the clipboard is an export too: a copied figure is the one a `.csv` would hold.
      */
-    private value;
+    value(column: ColumnModel<TRow>, row: TRow): unknown;
     /** A column's aggregate over a set of rows, or null where it has no aggregation. */
     private aggregateOf;
     /**

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

@@ -10,6 +10,7 @@ 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 RangeModel } from './rangeModel';
 import { default as RowModel } from './rowModel';
 import { default as TreeModel } from './treeModel';
 import { default as ViewportModel } from './viewportModel';
@@ -207,6 +208,8 @@ export default class GridModel<TRow> {
     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>;
+    /** The current cell, the block of cells marked around it, and what the clipboard is written from. */
+    readonly range: RangeModel<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

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

@@ -0,0 +1,119 @@
+import { CellRange } from '../contracts/dataGridContract';
+import { default as ColumnModel } from './columnModel';
+import { default as GridModel } from './gridModel';
+/** A body cell, as the grid counts them: a row of the display list and a visible leaf column. */
+export interface CellPosition {
+    row: number;
+    column: number;
+}
+/** The rectangle two corners describe, in display order and inclusive at both ends. */
+export interface RangeBounds {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+}
+/**
+ * A rectangle of values as the text a spreadsheet pastes: tabs between the cells, CRLF between the rows.
+ * Excel, Sheets and Numbers all split on the tab natively, which is why the clipboard carries no file.
+ */
+export declare function toTsv(rows: unknown[][]): string;
+/**
+ * The same text back, as a rectangle. Scanned character by character rather than split on the separators,
+ * because inside a quoted field a tab is a character and a newline is not the end of a row — which is the
+ * whole reason the quoting exists. A trailing newline ends the last row rather than opening an empty one.
+ */
+export declare function fromTsv(text: string): string[][];
+/**
+ * The current cell and the rectangle it reaches: which cell the arrows carry on from, which block a drag
+ * or a Shift+arrow has marked, and what Ctrl+C writes.
+ *
+ * The current cell lives here rather than in a `:focus-visible` rule (bug #64) for two reasons a CSS
+ * pseudo-class cannot answer: a *clicked* cell never matches one, and the mark has to survive the grid
+ * losing focus — otherwise a copy has nothing to act on and a range has nowhere to extend from. The
+ * roving focus still owns the tab stop and moves the DOM focus; every move it makes is mirrored here,
+ * which is what keeps the two from disagreeing about where the user is.
+ */
+export default class RangeModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    constructor(grid: GridModel<TRow>);
+    private _anchor?;
+    private _focus?;
+    private _dragging;
+    /**
+     * Whether a block of cells can be marked at all. Copy needs no opt-in — it acts on the current cell,
+     * which every grid has — but extending does: a drag that selects cells is a drag that no longer
+     * selects text, and that is a decision about the page rather than about the grid.
+     */
+    get enabled(): boolean;
+    /** The cell the arrows carry on from, and the corner a Shift+arrow moves. */
+    get current(): CellPosition | undefined;
+    /** Whether a pointer is marking cells right now, which is what makes a cell answer to being entered. */
+    get isDragging(): boolean;
+    /** The rectangle, normalized, or nothing at all when no cell is current. */
+    get bounds(): RangeBounds | undefined;
+    /** Whether the rectangle covers more than the current cell — the only case anything is *selected*. */
+    get hasSelection(): boolean;
+    isCurrent(row: number, column: number): boolean;
+    /** Whether the cell is part of a marked block. A single current cell is the cursor, not a selection. */
+    isSelected(row: number, column: number): boolean;
+    /**
+     * Put the current cell here. `extend` keeps the anchor where it is, which is what makes Shift+arrow and
+     * a drag grow a rectangle instead of moving a cursor.
+     */
+    setCurrent(row: number, column: number, extend?: boolean): void;
+    /**
+     * Follow a focus the grid did not ask for — a press, a Tab out of an editor, a cell focused by name.
+     * It collapses the rectangle only when it lands somewhere the model was not already: a Shift+press has
+     * already extended by the time the browser focuses the cell it landed on, and must not be undone.
+     */
+    syncCurrent(row: number, column: number): void;
+    /** Give up the current cell — what a move into the header or the footer leaves behind. */
+    clear(): void;
+    /**
+     * A press on a cell. Shift extends from wherever the anchor is; anything else collapses onto this cell
+     * and starts marking, so a drag out of it is one gesture. The browser focuses the cell straight after,
+     * which `syncCurrent` then sees as the position it already holds.
+     */
+    press(row: number, column: number, extend: boolean): void;
+    /** A cell entered while the pointer is down. */
+    dragTo(row: number, column: number): void;
+    endDrag: () => void;
+    /** The columns a rectangle covers, in display order. The marked one when none is named. */
+    columnsOf(bounds?: RangeBounds | undefined): ColumnModel<TRow>[];
+    /**
+     * One cell's value for the clipboard: the export pipeline, so a copied figure is the one a `.csv` of
+     * the same grid would carry — the column's `exportValue` when it has one, and the accepted edit over
+     * either. The grid's own columns hold no data, bar the row number, which is a value worth copying.
+     */
+    private valueOf;
+    /**
+     * The rectangle, row by row. Rows that hold no cells of their own keep their place rather than closing
+     * the gap — a group row carries its own value in the column it groups by, and a detail panel or a block
+     * nobody has fetched copies as blanks, so what is pasted is the shape that was on screen.
+     */
+    values(bounds?: RangeBounds | undefined): unknown[][];
+    /** A rectangle as a consumer hears about it. `values` is a call because a range can be very large. */
+    rangeOf(bounds: RangeBounds): CellRange;
+    private get range();
+    private emit;
+    /**
+     * Ctrl+C, through the browser's own copy event rather than through a keystroke: `clipboardData` is
+     * writable there with no permission and no promise, and the same press on a page with text selected in
+     * it still belongs to the browser — which is why a live selection is left alone rather than overridden.
+     */
+    onCopy: (event: React.ClipboardEvent) => void;
+    /**
+     * Where a paste lands. Each axis takes whichever is longer — the block that is marked, or the clipboard
+     * — so a block bigger than the clipboard is tiled with it and a clipboard bigger than the block spills
+     * past it, both clipped at the edge of the grid. That one rule covers the two cases a spreadsheet keeps
+     * apart, and the degenerate one with it: a paste onto the current cell alone starts from a 1×1 block.
+     */
+    private pasteBounds;
+    /**
+     * Ctrl+V, through the browser's own paste event for the reason the copy rides its own: the text is on
+     * the event, with no permission to ask for and no promise to wait on. A paste that reaches an open
+     * editor belongs to the editor — that is a value being typed, not a block being filled.
+     */
+    onPaste: (event: React.ClipboardEvent) => void;
+}

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

@@ -1,4 +1,11 @@
 import { default as GridModel } from './gridModel';
+/** Which way the reader is going. The rendered buffer is only worth its cost in the direction of travel. */
+export type ScrollDirection = 'down' | 'up';
+/** Everything the window needs of a scroll: where the rows are, and which way they are moving. */
+export interface ScrollPosition {
+    top: number;
+    direction: ScrollDirection;
+}
 /** Windowing parameters for the virtualized body. Rows are sliced by the adapter from these. */
 export interface ViewportWindow {
     /** Index of the first row to render. */
@@ -20,7 +27,21 @@ export interface ViewportWindow {
 export default class ViewportModel<TRow> {
     readonly grid: GridModel<TRow>;
     static readonly DEFAULT_VISIBLE_ROWS_COUNT = 10;
-    static readonly ROWS_TO_PRELOAD = 20;
+    /**
+     * Rows rendered outside the viewport, and the reason the two numbers differ: the buffer is cover for
+     * the frame between a scroll and the render that answers it, so it is only ever needed ahead. Twenty
+     * each way rendered fifty-eight rows around an eighteen-row viewport, and cost seven times the fling
+     * of a grid rendering twenty-eight (bug #178).
+     */
+    static readonly ROWS_AHEAD = 12;
+    static readonly ROWS_BEHIND = 4;
+    /** The row a scroll cuts through at the top, and the fifth of one `viewHeight` adds at the bottom. */
+    private static readonly PARTIAL_ROWS;
+    /**
+     * Which way the reader is going, given where they were. A scroll that stops keeps the direction it
+     * arrived in: the cover belongs ahead of the fling that is about to carry on, not behind it.
+     */
+    static directionOf(from: number, to: number, last: ScrollDirection): ScrollDirection;
     constructor(grid: GridModel<TRow>);
     get showAll(): boolean;
     get hasDetailRows(): boolean;
@@ -40,5 +61,5 @@ export default class ViewportModel<TRow> {
     rowTop(index: number): number;
     /** Binary search for the first row whose offset is <= scrollTop (variable-height rows). */
     private findStartIndex;
-    window(scrollTop: number): ViewportWindow;
+    window(scrollTop: number, direction?: ScrollDirection): ViewportWindow;
 }

package/components/dataGrid/useGridNavigation.d.ts

@@ -1,13 +1,21 @@
 import { GridNavigation } from './gridNavigationContext';
 import { default as GridModel } from './models/gridModel';
+import { ScrollPosition } from './models/viewportModel';
 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;
+    /** Read rather than written: a jump has to know which rows are rendered, which the direction decides. */
+    scroll: ScrollPosition;
     onScrollTo: (top: number) => void;
 }
-export interface GridNavigator extends GridNavigation {
+export interface GridNavigator {
+    /**
+     * What every cell reads, through the context. Held apart from `onKeyDown` because it has to be the
+     * same object between two renders that changed nothing a cell can see: a scroll re-renders the content,
+     * and a fresh context value there re-renders every cell in the window whatever their elements memoize.
+     */
+    navigation: GridNavigation;
     /** Put this on the `role="grid"` element: cell keystrokes bubble to it. */
     onKeyDown: (event: React.KeyboardEvent) => void;
 }