@toclocoinc/lattice-grid 1.15.0 → 1.17.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.15.0, type declarations
+ * Lattice Grid 1.17.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -341,6 +341,22 @@ export interface LookupSpec {
 export type DecorationName = 'plain' | 'fill' | 'pill' | 'dot' | 'bar' | 'heat' | 'icon';
 export type VariantName = 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'accent' | 'none' | (string & {});
 
+/** A built-in threshold icon set, mapping value bands to built-in glyphs. */
+export type IconSetName = 'trafficLights' | 'arrows' | 'trafficArrows' | 'ratings' | (string & {});
+
+/**
+ * One band of a threshold icon set. A value clears a band when it is at least
+ * `min`; the highest band it clears wins. Omit `min` on the last band to make
+ * it the catch-all. `label` is what assistive technology announces for the
+ * glyph, so a screen-reader user hears the band's meaning, not only the value.
+ */
+export interface IconBand {
+  min?: number;
+  icon: string;
+  label?: string;
+  variant?: VariantName;
+}
+
 export interface DecorationSpec {
   type: DecorationName;
   size?: 'sm' | 'md' | 'lg';
@@ -349,6 +365,10 @@ export interface DecorationSpec {
   edge?: boolean;
   position?: 'start' | 'end';
   name?: string | Record<string, string>;
+  /** icon only: a built-in threshold icon set, expanded to `bands`. */
+  iconSet?: IconSetName;
+  /** icon only: value bands mapped to glyphs, first match by descending `min`. */
+  bands?: IconBand[];
   min?: number;
   max?: number;
   origin?: number;
@@ -738,6 +758,94 @@ export interface Source {
 
 export interface MemorySourceConfig { mode: 'memory'; columnarBelow?: number }
 
+/**
+ * How rows are ingested into the column store.
+ */
+export interface IngestConfig {
+  /**
+   * Retain the caller's row objects by reference so identity round-trips.
+   * Default `true`, the historical behaviour: `rows.data()` returns the exact
+   * objects you supplied, `row === sourceObject` holds, and a custom renderer
+   * reading `row.sourceObject` works.
+   *
+   * Set `false` to keep only the packed columns and reconstruct a plain row
+   * object from them on demand. This drops roughly half the resident footprint,
+   * but changes three behaviours: `rows.data()` returns freshly reconstructed
+   * objects (new object each call, so `row === sourceObject` no longer holds),
+   * a custom renderer that reaches for `row.sourceObject` gets a reconstruction
+   * rather than the original, and equality against a row becomes value-based.
+   * The stored values are unchanged, so `get()`, `byKey()`, `value()` and
+   * `values()` are unaffected.
+   */
+  retainSource?: boolean;
+
+  /**
+   * Release the caller's row objects from the *source layer* once the column
+   * store has been built, so the columns become the sole resident copy of the
+   * data. Default `false`, which keeps today's behaviour.
+   *
+   * `retainSource:false` stops the {@link https://en.wikipedia.org/wiki/Column-oriented_DBMS column store}
+   * from holding the caller's objects, but the memory source and the grid config
+   * still retain the supplied array by reference — so the objects stay alive and
+   * the resident footprint does not actually fall. This flag closes that gap: it
+   * clears `MemorySource`'s retained array and drops the array from the grid
+   * config, leaving nothing on the heap but the packed columns. That is where
+   * the large reduction comes from (roughly an order of magnitude at a million
+   * rows), not from `retainSource` on its own.
+   *
+   * Implies `retainSource:false`: dropping the caller's objects while the store
+   * still expects to read through them would leave the source with no data at
+   * all, so setting this on forces the store to reconstruct rows from columns.
+   * Every read is therefore served from the columns — `at()`, `byKey()`,
+   * `get()`, `value()`, `values()`, filtering, sorting, grouping, totals and
+   * export are all unaffected in their values. What changes is the same three
+   * identity behaviours `retainSource:false` documents: `rows.data()` returns
+   * freshly reconstructed objects (so `row === sourceObject` no longer holds), a
+   * custom renderer reaching for `row.sourceObject` gets a reconstruction, and
+   * equality against a row becomes value-based.
+   *
+   * One consumer cannot be served from the columns: an *impure computed column*
+   * (a shadow, or a rank/positional column) is deliberately never materialised
+   * into the store, so its handle is built by reading the source objects. Under
+   * `dropSourceRows` those objects are gone, so such a column reduces over
+   * nothing and warns once rather than returning a silently wrong figure. Do not
+   * enable `dropSourceRows` on a grid that sorts, filters, groups or totals on a
+   * shadow or a positional column.
+   */
+  dropSourceRows?: boolean;
+
+  /**
+   * Columnize `stream`-source ingest on a Worker so a large load does not block
+   * the main thread. Default `false`. When on, an arriving chunk that clears
+   * {@link IngestConfig.workerThreshold} is packed into typed column buffers on
+   * the Worker; the main thread merges the finished buffers into the store and
+   * renders, without running the per-field extraction pass that otherwise
+   * dominates ingest.
+   *
+   * This makes **stream** ingest non-blocking (remote sources already are).
+   * Memory and paged sources cannot be made non-blocking this way — the main
+   * thread must read the caller's own row objects — and are unaffected. The
+   * effect composes with `retainSource: false`: with it off the source keeps no
+   * caller-object array on the main thread at all, so the load is both
+   * non-blocking and lighter on memory.
+   *
+   * A column that reads through a closure — a `date` column's storage
+   * conversion, or a computed column — cannot cross the Worker boundary, so a
+   * grid with any such column columnizes on the main thread and says so once.
+   * Falls back silently to the main thread wherever a Worker cannot be created.
+   */
+  useWorker?: boolean;
+
+  /**
+   * Row count in a single stream chunk at or above which columnization is
+   * offloaded to the Worker when {@link IngestConfig.useWorker} is on. Default
+   * `10000`. A smaller first chunk is packed on the main thread, where the
+   * cost is trivial and the postMessage round trip would only add latency to
+   * time-to-first-row.
+   */
+  workerThreshold?: number;
+}
+
 export interface PagedSourceConfig {
   mode: 'paged';
   pageSize?: number;
@@ -968,6 +1076,15 @@ export interface EditConfig {
   commit?: (write: PendingWrite) => unknown;
   confirm?: 'auto' | 'manual';
   pendingTimeout?: number;
+  /**
+   * Show a preview of what a bulk paste will change before it commits (§12),
+   * with confirm/cancel. Off by default: a paste commits straight away, exactly
+   * as it always has. When on, a paste into more than one cell first opens a
+   * dialog listing every cell that changes (old → new) and every cell that would
+   * be rejected (permission, data-type, read-only); confirm commits precisely
+   * that set through the ordinary edit path, cancel commits nothing.
+   */
+  pastePreview?: boolean;
 }
 
 export interface PendingWrite {
@@ -1010,6 +1127,8 @@ export interface GridConfig {
   rowKey?: string | ((row: unknown) => string);
   /** Where rows come from: memory, paged, remote, stream or derived. */
   source?: SourceConfig;
+  /** How rows are ingested into the column store. */
+  ingest?: IngestConfig;
   /** Applied to every column before its own settings. */
   columnDefaults?: Column;
   /** Named bundles of column settings, referenced by a column's `preset`. */
@@ -1074,6 +1193,21 @@ export interface GridConfig {
    */
   cornerRadius?: boolean | number | string;
 
+  /**
+   * Shade alternate data rows (zebra striping).
+   *
+   * Off by default, and strictly opt-in: an existing grid must look exactly the
+   * same on upgrade. When `true`, every other data row takes the theme's
+   * `--lattice-surface-alt` background, which every palette already defines, so
+   * dark, high-contrast and terminal stripe correctly without extra work.
+   *
+   * Parity follows the row's *logical* index, not its position in the DOM, so a
+   * row keeps its stripe across a scroll even though the rows are recycled.
+   * Structural rows — group headings, group footers and the grand total — are
+   * never striped, and both selection and hover still win over the stripe.
+   */
+  stripedRows?: boolean;
+
   /**
    * Show a bar above the column headings for filtering columns by tag.
    *
@@ -1228,7 +1362,12 @@ export interface GridConfig {
    * only the sort, filter and menu controls inside them.
    */
   showHeader?: boolean;
-  /** Header height in pixels. */
+  /**
+   * Header height in pixels. Omitted, the header takes its height from the
+   * density-scaled `--lattice-header-height` token, so `density` sizes the
+   * header as it sizes the rows. A number names one explicitly and outranks the
+   * token.
+   */
   headerHeight?: number;
   /** How many rows to render beyond the viewport. More costs memory and
    * smooths fast scrolling; fewer is lighter and can show a gap. */
@@ -1374,6 +1513,14 @@ export interface GridConfig {
   totalOnlyChangedColumns?: boolean;
   /** Put the total in the header rather than a footer row. */
   showTotalInHeader?: boolean;
+  /**
+   * Let the user pick a column's reduction from the column menu. On, the
+   * totalling entry becomes an "Aggregate" submenu offering the aggregates the
+   * column's type says are meaningful (§9.4); off, the menu keeps its plain
+   * "Total this column" toggle. Off by default, so an existing grid is
+   * unchanged.
+   */
+  aggregateChooser?: boolean;
   /** Render only the visible columns once there are more than this many. */
   columnVirtualisationAbove?: number;
   /** The bar beneath the grid, and which panels it carries. */
@@ -1391,6 +1538,23 @@ export interface GridConfig {
    */
   columnMenu?: boolean | ((p: ColumnMenuParams, defaults: MenuItem[]) => MenuItem[] | void);
 
+  /**
+   * Chart a selected cell range — the spreadsheet "chart this selection"
+   * gesture. Off by default, so a grid opts in.
+   *
+   * The DOM layer draws no charts itself — the charts module is optional and
+   * loaded by the host — so this is where the host wires the two together: a
+   * function, or an object carrying `onChart`, is called with the grid and the
+   * selected range when the reader chooses "Chart selection" from the cell
+   * menu. The handler typically calls `chartRange` from
+   * `lattice-grid/modules/charts`. `true` offers the item and emits nothing
+   * extra; supply a handler to have it actually draw.
+   */
+  rangeChart?:
+    | boolean
+    | ((grid: Grid, range: CellRange) => void)
+    | { onChart?: (grid: Grid, range: CellRange) => void };
+
   /**
    * The `?` keyboard shortcut overlay. `false` suppresses it, for a host
    * that wants `?` for itself. Default true.
@@ -1453,9 +1617,11 @@ export interface GridConfig {
    * Keep the enclosing group headings pinned above the viewport while
    * scrolling inside a group.
    *
-   * On by default, stacking at most two. `false` turns it off; a number, or
-   * `{ depth }`, sets how many may stack: each costs a row of viewport, so a
-   * deep grouping would otherwise spend the screen describing itself.
+   * Off by default — a deliberate product default; sticky group headers are
+   * opt-in. `true` turns it on, stacking at most two; a number, or `{ depth }`,
+   * sets how many may stack: each costs a row of viewport, so a deep grouping
+   * would otherwise spend the screen describing itself. `false` is off, the
+   * same as leaving it unset.
    */
   stickyGroupHeaders?: boolean | number | { depth?: number };
   /**
@@ -1503,6 +1669,22 @@ export interface GridConfig {
     /** File name for the export action, without the extension. */
     exportName?: string;
   };
+  /**
+   * A drag-and-drop group-by strip above the column header — the pattern AG
+   * Grid calls the row-group panel. Drag a column heading into it to group by
+   * that column; the active groups show as removable, reorderable chips, and
+   * reordering the chips changes the nesting order. It is keyboard-operable
+   * (arrows navigate, Shift+arrow reorders, Delete ungroups, and an add control
+   * groups any column), and every change is announced through the live region,
+   * which is why it also addresses the drag-only complaint of BACKLOG-0000429.
+   *
+   * Off by default and non-breaking, matching `toolPanel`. It drives the same
+   * grouping model as `grid.columns.group()`; it reimplements nothing.
+   */
+  groupPanel?: boolean | {
+    /** Placeholder shown while nothing is grouped. */
+    hint?: string;
+  };
   /** The quick filter's initial text. */
   quickFilterText?: string;
   /**
@@ -1767,6 +1949,103 @@ export interface PushdownPlan {
   needsAll: boolean;
   /** Which parts could not be pushed: `filter`, `sort`, `quick`. */
   unpushed: string[];
+  /**
+   * Whether the whole result was fetched because `fullDataset` is on, rather
+   * than only because residual work forced it. When true, totals and statistics
+   * reduce over the whole matching set and the windowed-stat warning is silent.
+   */
+  full: boolean;
+  /**
+   * Per-aggregate provenance, present only when the last request computed
+   * aggregates (BACKLOG-0000730 Part B): which statistics the engine computed
+   * and which the client did, with the class the pushdown map assigned each.
+   * Under grouping it also carries the `groupBy` the subtotals were computed
+   * over. Build-time inspection, not a runtime per-figure marker.
+   */
+  aggregates?: {
+    engine: AggregateProvenance[];
+    client: AggregateProvenance[];
+    groupBy?: string[];
+  };
+}
+
+/**
+ * Opt-in, sticky full-dataset pull for a pushdown/remote source
+ * (BACKLOG-0000730). Off by default. When enabled, the source materialises the
+ * entire matching set client-side once per query signature and serves every
+ * window, total and statistic from it, so those figures are computed over the
+ * whole set rather than the loaded window. A set past either limit is refused
+ * with a visible `source:error` — never silently truncated.
+ */
+export interface PushdownFullDatasetConfig {
+  /** Sticky: hold the whole matching set client-side. Default `false`. */
+  enabled?: boolean;
+  /** Refuse (visible error) past this many rows. Default `1_000_000`. */
+  maxRows?: number;
+  /** Refuse past this estimated heap cost, in bytes. Default `512 * 1024 * 1024`. */
+  maxBytesEstimate?: number;
+}
+
+/** How one requested aggregate should be computed. */
+export type AggregateMode = 'engine' | 'client' | 'engine-if-identical';
+
+/**
+ * Design-time aggregate-pushdown policy for a pushdown source
+ * (BACKLOG-0000730 Part B, ungrouped). The developer chooses, at grid setup
+ * before render, whether each statistic is computed by the engine (fast, over
+ * the matching set) or client-side (the grid's exact definition, needs a
+ * full-dataset pull). It is fixed for the life of the grid, never a runtime
+ * toggle, and never surfaced to an end user.
+ *
+ * Absent, every aggregate is computed client-side — today's behaviour, so no
+ * existing caller regresses. `engine-if-identical` is the recommended setting
+ * for a windowed DuckDB source: it pushes only the statistics whose engine
+ * result is verified identical to the grid kernel, keeping the documented
+ * MAY-DIFFER stats (e.g. `mode`) client-side. The engine is used only when the
+ * filter is fully pushed; a residual filter forces every aggregate client-side,
+ * so an engine figure and a client figure never mix in one result set.
+ */
+export interface PushdownAggregatesConfig {
+  /**
+   * The default policy for stats the engine can express. `'engine'` pushes
+   * everything expressible (using the engine's method for MAY-DIFFER stats);
+   * `'engine-if-identical'` pushes only the verified-identical ones; `'client'`
+   * computes everything client-side. Default `'client'`.
+   */
+  default?: AggregateMode;
+  /** Per-stat overrides, winning over `default`. A stat the engine cannot
+   *  express (`weightedQuantile`) is always client-side regardless. */
+  overrides?: Record<string, 'engine' | 'client'>;
+}
+
+/**
+ * One aggregate the grid asks the source to compute over the matching set.
+ * `params` carries e.g. `{ share: 0.1 }` so an adapter emits the matching SQL;
+ * `weight` names the second column for a two-column stat like `correlation`.
+ */
+export interface AggregateRequest {
+  /** Keys the result back to the request. */
+  id: string;
+  /** The column to reduce. */
+  col: string;
+  /** The statistic name, as used in `total: '<name>'`. */
+  fn: string;
+  /** The second column, for a two-column statistic. */
+  weight?: string;
+  /** Parameters the statistic takes, e.g. a trim share. */
+  params?: Record<string, unknown>;
+}
+
+/** How one aggregate was routed, for `lastPlan()` provenance. */
+export interface AggregateProvenance {
+  id: string;
+  col: string;
+  fn: string;
+  /** How the engine result relates to the grid kernel. */
+  class: 'identical' | 'may-differ' | 'fallback';
+  /** Why it is client-side, when it is (config, fallback, or the guard). */
+  reason?: string;
+  weight?: string;
 }
 
 export interface PushdownSourceConfig {
@@ -1774,6 +2053,16 @@ export interface PushdownSourceConfig {
   /** The compute barrel, for applying whatever the engine could not. */
   compute?: object;
   pageSize?: number;
+  /**
+   * Opt-in full-dataset pull. Off unless `fullDataset.enabled` is set. See
+   * {@link PushdownFullDatasetConfig}.
+   */
+  fullDataset?: PushdownFullDatasetConfig;
+  /**
+   * Design-time aggregate-pushdown policy. Absent = client-side (today's
+   * behaviour). See {@link PushdownAggregatesConfig}.
+   */
+  aggregates?: PushdownAggregatesConfig;
 }
 
 export interface StatisticsApi {
@@ -2164,6 +2453,11 @@ export interface RowsApi {
 export interface ColumnsApi {
   /** Set or clear a column's totals-row reduction. */
   setTotal(id: string, fn: TotalName | TotalFn | null): void;
+  /**
+   * The aggregate names meaningful for a column, honouring its type's
+   * `totals.supported` declaration (§9.4). What the aggregate chooser offers.
+   */
+  aggregates(id: string): TotalName[];
   /** Every distinct value in a column, from the dictionary where there is one. */
   distinct(id: string): unknown[];
   get(id: string): ResolvedColumn | undefined;
@@ -2186,6 +2480,13 @@ export interface ColumnsApi {
   move(id: string, to: number): void;
   pin(id: string, side: 'start' | 'end' | null): void;
   resize(id: string, px: number): void;
+  /**
+   * Set, change or clear a column's decoration at runtime (§8.7). Pass `null` to
+   * clear it back to plain text. Presentation config: it is not on the undo
+   * timeline and is not carried in a saved view — use `grid.formatting` for
+   * durable, view-persisted conditional styling.
+   */
+  decorate(id: string, decoration: DecorationName | DecorationSpec | null, opts?: { variant?: VariantSpec }): void;
   autoSize(ids?: string | string[]): void;
   fit(): void;
   group(ids: string | string[]): void;
@@ -2269,6 +2570,18 @@ export interface EditApi {
   redo(): void;
   setCells(writes: { key: string; colId: string; value: unknown }[], type?: 'cell' | 'fill' | 'paste'): number;
   pasteInto(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): number;
+  /** Whether a bulk paste is previewed before it commits (`edit.pastePreview`, §12). */
+  readonly pastePreview: boolean;
+  /**
+   * Compute what a paste would change, without committing (§12). The engine
+   * behind `edit.pastePreview`: `changes` are the accepted writes with their old
+   * and new values (and whether each actually differs), `rejected` are the cells
+   * a commit would refuse, each with a reason.
+   */
+  previewPaste(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): {
+    changes: { key: string; colId: string; oldValue: unknown; newValue: unknown; changed: boolean }[];
+    rejected: { key: string; colId: string; value: unknown; reason: 'permission' | 'readOnly' | 'validation' | 'locked' | 'missing' }[];
+  };
   settle(id: string, ok: boolean, reason?: string): boolean;
   pending(): OpenWrite[];
   status(key: string, colId: string): 'pending' | null;
@@ -3265,7 +3578,51 @@ export function toneOf(direction: string, goodWhen: string): 'good' | 'bad' | 'f
  */
 export function createPushdownSource(
   config: PushdownSourceConfig,
-): SourceConfig & { lastPlan(): PushdownPlan | null };
+): SourceConfig & {
+  lastPlan(): PushdownPlan | null;
+  /**
+   * Compute a set of aggregates over the matching set, splitting them between
+   * the engine and the client by the design-time `aggregates` config
+   * (BACKLOG-0000730 Part B). Ungrouped, returns the engine-computed `values`
+   * keyed by id. When the request carries a `groupBy`, returns `groups` instead:
+   * one entry per subtotal level and the grand total (`level: 0`, produced by a
+   * single `GROUP BY ROLLUP`), each with its key values and its aggregate values
+   * keyed by id. The client list is what the caller computes itself over the
+   * full set. Aggregates are pushed only when the filter is fully pushed and —
+   * under grouping — every grouping key is a plain column the engine can group
+   * by; a residual filter or an unpushable group key forces every aggregate
+   * client-side (no mixed provenance).
+   */
+  aggregate(
+    request: RemoteRequest,
+    requested: AggregateRequest[],
+  ): Promise<{
+    values: Record<string, unknown>;
+    groups?: Array<{
+      keys: unknown[];
+      grouping?: number[];
+      level: number;
+      values: Record<string, unknown>;
+    }>;
+    engine: AggregateProvenance[];
+    client: AggregateProvenance[];
+  }>;
+};
+
+/**
+ * The pushdown map (BACKLOG-0000730 Part B): one published record per statistic
+ * giving whether the engine can express it, the DuckDB aggregate SQL it emits,
+ * and whether that result is IDENTICAL to the grid's own kernel or MAY-DIFFER.
+ * The single source of truth the push router, the docs and `lastPlan()` all read.
+ */
+export const STAT_PUSHDOWN: Readonly<Record<string, {
+  pushable: boolean;
+  class: 'identical' | 'may-differ' | 'fallback';
+  sql?: string;
+  note?: string;
+  twoColumn?: boolean;
+  blankAware?: boolean;
+}>>;
 
 /**
  * The capability set an adapter that declares nothing is treated as having:
@@ -3623,6 +3980,12 @@ export interface ChartSpec {
   y?: string;
   /** Splits the measure into one series per distinct value. */
   series?: string;
+  /**
+   * The exact rows to chart, overriding the grid's own walk — an array, or a
+   * function returning one at draw time. `chartRange` uses it to bind a chart
+   * to the band of rows a selected range covers rather than the whole grid.
+   */
+  rows?: object[] | ((grid: Grid) => object[]);
   /** Several measures at once, for combo and candlestick. */
   measures?: ChartMeasure[];
   /** Endpoints, for sankey, chord and network. */
@@ -3753,6 +4116,39 @@ declare module 'lattice-grid/modules/charts' {
   export const SCHEMES: Readonly<Record<string, readonly string[]>>;
   export const PALETTE: readonly string[];
   export function createChart(spec: ChartSpec): Chart;
+  /**
+   * Chart a selected cell range. Derives the chart from the range's shape — a
+   * leading text column becomes the categories, the numeric columns become the
+   * measures — and returns the live chart, or null when the range has nothing
+   * to measure. Respects hidden and unreadable columns. The type is a sensible
+   * default the caller can change with `chart.update({ type })`.
+   */
+  export function chartRange(
+    grid: Grid,
+    opts: {
+      container: Element | string;
+      range?: CellRange;
+      type?: ChartType;
+    } & Partial<ChartSpec>,
+  ): Chart | null;
+  /** Would {@link chartRange} draw something for the grid's current selection? */
+  export function canChartRange(grid: Grid, opts?: { range?: CellRange }): boolean;
+  /**
+   * Decide what a chart of a range should be, without drawing it: the type, the
+   * category column, the measure columns, and a `spec` ready for `createChart`
+   * — or a `reason` naming why the range cannot be charted.
+   */
+  export function deriveRangeSpec(
+    grid: Grid,
+    opts?: { range?: CellRange; type?: ChartType },
+  ): {
+    spec: ChartSpec | null;
+    type: ChartType | null;
+    x: string | null;
+    measures: string[];
+    columns: string[];
+    reason: string | null;
+  };
   export function registerScheme(name: string, colours: readonly string[]): void;
   export function resolveScheme(spec?: object): object;
   export function schemeNames(): string[];