@toclocoinc/lattice-grid 1.50.0 → 1.52.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.50.0, type declarations
+ * Lattice Grid 1.52.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -863,6 +863,24 @@ export interface Column {
   layout?: ColumnLayoutSpec | number;
   /** The header cell: its text, tooltip, menu and any header chart. */
   header?: ColumnHeaderSpec | string;
+  /**
+   * The cell right-click menu for this column alone (BACKLOG-0001068), in the
+   * same shapes the grid-level `contextMenu` takes plus a bare array for the
+   * common "just these items here" case.
+   *
+   * Declared where the column is declared rather than as another branch inside
+   * one grid-level callback: the menu logic for a column belongs beside the
+   * column it belongs to. It does not replace the grid-level menu — the three
+   * levels compose as a chain, built-in defaults then grid-level then this one,
+   * each handed the previous result as its `defaults`, so a column adding one
+   * item does not have to restate Paste, Clear and Fill down.
+   *
+   * `false` suppresses the menu on this column and leaves every other column
+   * alone: what a sensitive or read-only column wants. The more specific level
+   * wins, so a column may also declare a menu on a grid whose `contextMenu` is
+   * `false`.
+   */
+  contextMenu?: boolean | MenuItem[] | ((p: CellMenuParams, defaults: MenuItem[]) => MenuItem[] | void);
   /**
    * When this column's header controls — its sort arrow, filter funnel and menu
    * button — are shown, overriding the grid-level `headerControls` default for
@@ -939,6 +957,12 @@ export interface ResolvedColumn {
   grandTotal: TotalName | TotalFn | null;
   layout: ColumnLayoutSpec;
   header: ColumnHeaderSpec;
+  /**
+   * This column's own cell-menu declaration (BACKLOG-0001068), or null when it
+   * makes none and the grid-level menu stands alone. Carried onto the resolved
+   * column so a column preset or `columnDefaults` can supply one.
+   */
+  contextMenu: boolean | MenuItem[] | ((p: CellMenuParams, defaults: MenuItem[]) => MenuItem[] | void) | null;
   export: ColumnExportSpec;
   lookup: LookupSpec | null;
   allowGroup: boolean;
@@ -1220,9 +1244,57 @@ export interface DerivedSourceConfig {
    * key when nothing is grouped. `config.rowKey` defaults to it, so it need not
    * be set; an explicit `rowKey` still wins.
    */
-  /** The grid to read. */
-  from: Grid;
-  /** Which of its rows to read. `filtered` by default. */
+  /**
+   * The grid to read, or several to combine into one row set before the rest
+   * of the pipeline runs (BACKLOG-0001045). A bare `Grid` is shorthand for a
+   * `UnionSourceOptions` with no `label`/`follow`/`map` override, so an
+   * existing `from: <grid>` keeps meaning exactly what it always has.
+   *
+   * Given an array, every source is read (each narrowed by its own `follow`,
+   * defaulting to `'filtered'` as a lone `from` does today), concatenated in
+   * **declaration order** — deterministic, not interleaved — and only then
+   * does `unnest`/`join`/`where`/`bucket`/`groupBy`/`select`/`sort`/`limit`/
+   * `limitPer`/`cumulative` run, over the combined set, so "the worst
+   * performers across both" is one derivation rather than a hand-merge.
+   *
+   * The output carries the **union of the sources' fields**: a field present
+   * on only one source is `undefined` on rows from the others. Sources are
+   * **not** type-reconciled — if two disagree on what a field means or holds,
+   * that is not resolved for you; give each source a `map` to project it into
+   * a common shape first. Every row also carries `__source` (the entry's
+   * `label`, or its declaration index when unlabelled), which is required —
+   * not optional — because without it a combined list cannot be read, filtered
+   * or grouped by where it came from; it is an ordinary field to `where`,
+   * `groupBy` and `select`. And because the derived key (`__key`) would
+   * otherwise collide across sources sharing the same identifiers, it is
+   * namespaced by the same source tag when nothing is grouped (a grouped
+   * union's `__key` is the group value, exactly as today, and rows from
+   * different sources correctly land in the *same* group when their group
+   * values agree — that merging is the point of grouping a union, not a
+   * collision to guard against).
+   *
+   * This is **not** a join: there is no dedup or merge-on-key, and it draws no
+   * UNION/UNION ALL distinction — overlapping rows from two sources simply
+   * both appear. Reach for `join` when two sides share a key and you want them
+   * matched rather than stacked.
+   *
+   * An empty source contributes nothing and the rest still combine; a source
+   * that fails to read is named in a `warnOnce` and skipped for that pass
+   * rather than silently dropped, because a silently missing source would
+   * make "worst across both" quietly wrong. A source list that includes the
+   * grid being derived, directly or through a chain, is refused when the
+   * source is built (naming the offender) rather than recursed into.
+   *
+   * `crossFilter` has no single target once there is more than one parent, so
+   * it is not supported alongside a union `from` (ignored, with a `warnOnce`,
+   * rather than guessing which parent to push onto).
+   */
+  from: Grid | UnionSourceOptions[];
+  /**
+   * Which of its rows to read. `filtered` by default. Ignored — with a
+   * `warnOnce` — when `from` is a union array: each entry there carries its
+   * own `follow` instead (BACKLOG-0001045).
+   */
   follow?: 'filtered' | 'all' | 'selected' | 'grouped';
 
   /** An array property to expand, one row per element, before anything else. */
@@ -1255,6 +1327,52 @@ export interface DerivedSourceConfig {
   /** With `profile`, emit one row per statistic instead of one per column. */
   orient?: 'columns' | 'metrics';
 
+  /**
+   * Project a **relational** statistic into rows (BACKLOG-0001046): the figures
+   * that need two or more columns, or a second grid, and so cannot be reached
+   * through `select`.
+   *
+   * Every *single-column* statistic already has a route and this is not it —
+   * the derived `select` reduces a group by any kernel the totals row uses, and
+   * that table is a superset of the statistics one, so
+   * `select: { p95: { of: 'amount', fn: 'p95' } }` (or `gini`, `stddev`,
+   * `median`, `trimmedMean`, …) works today. Reach for `statistics` only when
+   * the answer is a correlation, a series summary or a comparison against
+   * another dataset.
+   *
+   * **A terminal producer, like `profile`, not a pipeline stage.** A
+   * correlation is one row per column *pair*, a series summary one row per
+   * *metric*, a comparison one row per compared *column* — none of which is one
+   * row per group, so there is no position in
+   * `unnest → where → bucket → groupBy → select → sort → limit` for it to
+   * occupy. It replaces the pipeline, and those keys are ignored with a warning
+   * naming them (BACKLOG-0001092) rather than silently discarded. Sort, filter
+   * or limit the derived grid itself instead, or chain a second derived grid
+   * whose `from` is this one.
+   *
+   * **`profile` and `statistics` are mutually exclusive** and declaring both is
+   * refused, by name, when the source is built. **Not supported alongside a
+   * union `from`** — a relational statistic reduces one grid's own columns and a
+   * union has no single set of them; also refused by name.
+   *
+   * **Cost.** Like every terminal producer this never patches incrementally: a
+   * change on the parent re-derives the whole thing. `correlation` additionally
+   * scans the rows once *per pair*, so N columns cost N·(N−1)/2 passes. Use
+   * `refresh` (`'idle'` is the default; `'manual'` or a debounce in ms for an
+   * expensive analysis over a live feed) — see `docs/api-detail.html` for the
+   * measured figures.
+   *
+   * Every row carries `n`, the rows the figure covered, because a derived
+   * statistic travels into an export or a chart without its grid and "r = 0.98
+   * over eleven rows" is a different claim from the same number over eleven
+   * thousand. It does NOT carry a windowed/approximate flag: whether a source
+   * held fewer rows than matched its filters is decided from the source's own
+   * counters, which a derived source cannot reach, so that signal stays where
+   * it already works - the `stat.windowed:*` console warning the parent grid
+   * emits.
+   */
+  statistics?: DerivedStatistics;
+
   /** When to re-derive. `idle` by default: coalesced to a frame. */
   refresh?: 'live' | 'idle' | 'manual' | number;
 
@@ -1265,6 +1383,118 @@ export interface DerivedSourceConfig {
   crossFilter?: boolean | string | { col?: string };
 }
 
+/**
+ * Which relational statistic a derived source projects into rows, and how
+ * (BACKLOG-0001046). See `DerivedSourceConfig.statistics`.
+ *
+ * A discriminated union on `fn`, so the relational statistics still deferred —
+ * `regression`, `regressionModel`, `forecast`, `anomalies`, `adf`, `acf`,
+ * `spearman`, `kendall`, `covariance`, `subsetVsPopulation`, `compareGroups`,
+ * `capability`, `interval`, `windowed`, `weightedQuantile`, `weightedAverage` —
+ * arrive as further arms of this one key rather than as a second mechanism.
+ */
+export type DerivedStatistics =
+  | DerivedCorrelation
+  | DerivedSeries
+  | DerivedDatasetComparison;
+
+/**
+ * Pearson's correlation across N columns, pairwise.
+ *
+ * Rows, `orient: 'pairs'` (the default): one per unordered pair,
+ * `{ a, b, coefficient, n }` — the long form, because that is what
+ * a grid sorts, filters and charts well, and "the three most correlated pairs"
+ * is then a sort and a `limit` on the derived grid. Only the upper triangle is
+ * emitted: r is symmetric, so `(a,b)` and `(b,a)` are one finding, and a column
+ * against itself is 1 by definition.
+ *
+ * Rows, `orient: 'matrix'`: one per column, carrying a field per other column
+ * plus `column` and `n` — the classic square, for a heat map.
+ * The diagonal is 1 and both triangles are filled.
+ */
+export interface DerivedCorrelation {
+  fn: 'correlation';
+  /** The columns to correlate pairwise. At least two, or the source is refused. */
+  columns: string[];
+  /** `pairs` (default) for one row per pair; `matrix` for the square. */
+  orient?: 'pairs' | 'matrix';
+}
+
+/**
+ * A `grid.statistics.series` summary, as one row per metric:
+ * `{ metric, value, n }`.
+ *
+ * One row per *metric*, not per point: `series` returns a `SeriesStats` summary
+ * object — `n`, `first`, `last`, `change`, `changePercent`, `volatility`,
+ * `annualisedVolatility`, `growth`, `maxDrawdown`, `maxDrawdownFrom`,
+ * `maxDrawdownTo`, `autocorrelation`, `upDays`, `downDays` — and not a value
+ * per row. The shape is deliberately the one `profile`'s `orient: 'metrics'`
+ * already emits rather than a third convention for the same idea.
+ */
+export interface DerivedSeries {
+  fn: 'series';
+  /** The column to summarise. */
+  of: string;
+  /** The column that orders it. Required and never guessed. */
+  by: string;
+  /** Annualise volatility and growth against this many periods per year. */
+  periodsPerYear?: number;
+}
+
+/**
+ * How this grid differs from another, ranked by effect size, as rows:
+ * `{ column, measure, magnitude, distance, direction, nA, nB, reliable,
+ * unmatched }`, largest difference first.
+ *
+ * The two-grid shape: one grid is the data, a second *is* the analysis of it.
+ * Both sides are read over their filtered rows, and the peer is watched — an
+ * edit or a filter on it re-derives the comparison, because a comparison whose
+ * other side has moved is wrong rather than merely late.
+ *
+ * A column present on only one side cannot be compared. It is still reported,
+ * as a row with a null `magnitude` and `unmatched` set to `'A'` or `'B'`, so a
+ * reader sees that it was skipped and why rather than finding it absent.
+ */
+export interface DerivedDatasetComparison {
+  fn: 'datasetVsDataset';
+  /** The second grid to compare this one against. */
+  with: Grid;
+  /** Restrict the comparison to these columns. All shared columns by default. */
+  columns?: string[];
+}
+
+/**
+ * One member of a union `from` (BACKLOG-0001045): a grid to combine with the
+ * others, plus how to read it and reshape it before it joins the rest. A bare
+ * `Grid` in the `from` array is shorthand for `{ grid }` with every other
+ * field defaulted.
+ */
+export interface UnionSourceOptions {
+  /** The grid this source reads. */
+  grid: Grid;
+  /**
+   * Identifies this source: it is what `__source` carries on every row this
+   * source contributes, and what namespaces that row's `__key` so two sources
+   * sharing the same identifiers do not collide. Defaults to the source's
+   * position in the `from` array (`'0'`, `'1'`, …), as a string.
+   */
+  label?: string;
+  /**
+   * Which of this source's rows to read. `filtered` by default, exactly as a
+   * lone `from` follows its grid today — set independently per source, so
+   * filtering one narrows only its own contribution.
+   */
+  follow?: 'filtered' | 'all' | 'selected' | 'grouped';
+  /**
+   * Reshape this source's rows into the common shape before they join the
+   * rest — typically a rename or a projection, for a field this source calls
+   * something else. Not a type coercion: if a field means something different
+   * on two sources, `map` is where you make them agree, because the union
+   * itself does not guess.
+   */
+  map?: (row: unknown) => unknown;
+}
+
 export interface DerivedJoin {
   /** The grid holding the other side. */
   with: Grid;
@@ -5952,6 +6182,18 @@ export function duckdbAdapter(options: {
   from: string;
   /** Columns to select. Everything by default. */
   fields?: string[];
+  /**
+   * Whether to count the matching set at all. `true` by default: the total is a
+   * separate `count(*)` statement carrying the same `WHERE`, dispatched in the
+   * same tick as the page query rather than serialised behind it
+   * (BACKLOG-0001065). `false` issues no count statement, declares
+   * `capabilities.total: false`, and leaves the result's `total` **absent** — so
+   * the grid scrolls open-ended instead of being told the page length is the
+   * whole set. Turn it off for a grid that never shows a count: an unfiltered
+   * count is answered from Parquet metadata and a filtered one still has to
+   * evaluate the predicate, so it is cheap rather than free.
+   */
+  count?: boolean;
   /**
    * The key column an update and a delete target in their `WHERE`, and that an
    * add-row is rekeyed by. Write-back is refused unless this names a real column,
@@ -5974,7 +6216,15 @@ export function duckdbAdapter(options: {
    * key to rekey the temp row.
    */
   returning?: 'row' | 'none';
-}): PushdownAdapter & { sqlFor(query: RemoteRequest): { sql: string; params: unknown[] } };
+}): PushdownAdapter & {
+  sqlFor(query: RemoteRequest): { sql: string; params: unknown[] };
+  /**
+   * The separate `count(*)` statement that reports the matching set's size, with
+   * the same `WHERE` as {@link sqlFor} and no `ORDER BY` or `LIMIT`
+   * (BACKLOG-0001065). `null` when the adapter was built with `count: false`.
+   */
+  countSqlFor(query: RemoteRequest): { sql: string; params: unknown[] } | null;
+};
 
 /**
  * An adapter for a DemandFlow entity, speaking `POST /v1/query`.
@@ -6054,6 +6304,15 @@ export function graphqlAdapter(options: {
   pagination?: 'offset' | 'cursor';
   /** The page size for the whole-result and forward-cursor walks. */
   pageSize?: number;
+  /**
+   * Whether the default query asks for `totalCount`. `true` by default.
+   * `false` drops it from the selection set and declares
+   * `capabilities.total: false`, so a grid that never shows a count does not
+   * make the server compute one (BACKLOG-0001065). Unlike the DuckDB adapter the
+   * count is not split into a second operation — that would cost an extra HTTP
+   * round trip rather than saving one — so suppression is the only lever here.
+   */
+  count?: boolean;
   /** Rename the pagination variables the adapter drives per page. */
   vars?: Partial<Record<'offset' | 'limit' | 'first' | 'after', string>>;
   capabilities?: PushdownCapabilities; operators?: string[];
@@ -7220,11 +7479,17 @@ declare module 'lattice-grid/modules/gantt' {
   /**
    * A typed dependency between two tasks (by id), with optional lag/lead. `type`
    * defaults to `'FS'`; either endpoint may be a leaf or a summary.
+   *
+   * `type` also accepts the MS Project string shorthand — `'FS+2'`, `'SS-1'`
+   * (BACKLOG-0001072). It is normalised to the structured form on the way in, so
+   * `gantt.dependencies` always reads back `{ type, lag }` and there is no second
+   * internal representation. Giving both a shorthand lag and a conflicting `lag`
+   * field warns; the explicit field wins.
    */
   export interface GanttDependency {
     from: string | number;
     to: string | number;
-    type?: GanttLinkType;
+    type?: GanttLinkType | `${GanttLinkType}${'+' | '-'}${number}`;
     lag?: number;
   }
 
@@ -7467,7 +7732,15 @@ declare module 'lattice-grid/modules/gantt' {
      * milestones, progress). The view redraws when the schedule recomputes.
      */
     mount(container: unknown, options?: {
-      width?: number;
+      /**
+       * The plot width. `'container'` (the default) measures the element it was
+       * mounted into and keeps following it, so a plan in a tab, drawer,
+       * accordion or split pane fits without the host writing a
+       * `ResizeObserver` (BACKLOG-0001079); a container with no box yet holds a
+       * 720px fallback rather than drawing at zero. A number is honoured
+       * exactly and installs no observer. Ignored under `zoom`, which warns.
+       */
+      width?: number | 'container';
       rowHeight?: number;
       labelWidth?: number;
       rowLabels?: boolean;
@@ -7475,7 +7748,23 @@ declare module 'lattice-grid/modules/gantt' {
       showCritical?: boolean;
       showProgress?: boolean;
       dateAxis?: boolean;
-      today?: number;
+      /**
+       * The today line, as a plan day-number or a calendar date. A date is
+       * converted into plan space through `projectEpoch` (BACKLOG-0001079), so
+       * "put the line on the real today" is expressible for a relative plan.
+       */
+      today?: number | string | Date;
+      /**
+       * The calendar date plan day 0 stands for (BACKLOG-0001079).
+       *
+       * Display-only: axis ticks, bar labels, tooltips, screen-reader text and
+       * the built-in `'weekends'` shading move with it; the schedule, `getState`
+       * and the CSV/MSPDI exports do not. Without it, the engine's contract makes
+       * day 0 the Unix epoch, which is why a plan written as day offsets renders
+       * as January 1970. A host-supplied `nonWorking` function still receives raw
+       * plan days.
+       */
+      projectEpoch?: number | string | Date | null;
       nonWorking?: 'weekends' | ((day: number) => boolean);
       label?: 'name' | 'percent' | 'dates' | 'none' | ((task: GanttScheduledTask) => string);
       /** Whether bars can be dragged to move/resize (default true). */
@@ -8348,6 +8637,75 @@ declare module 'lattice-grid/modules/kpi' {
     sparkline?: KPISparkline | string;
   }
 
+  /**
+   * The hierarchy a KPI panel arranges its tiles into (BACKLOG-0001059): a rail
+   * of top-level items that expand to the indicators beneath them, each parent
+   * highlighted with the worst status below it.
+   *
+   * The shape is declared with `path` or `parentKey` — the same two shapes the
+   * grid's tree data and the tree-select editor take — over the **tile specs**,
+   * not the rows. With neither declared, one is derived by splitting the tile
+   * ids on `separator`, so `system.compute.cpu` files itself under Compute
+   * under System. A panel whose ids carry no separator stays flat, and `false`
+   * keeps it flat whatever they look like.
+   *
+   * A tile's `field` is never a source: a dot there already means a nested
+   * object property.
+   */
+  interface KPITreeConfig {
+    /** The tile's own place in the hierarchy, its own segment last. */
+    path?: (tile: KPITile) => (string | number)[];
+    /** The id of the tile this one sits under, or a reader for it. */
+    parentKey?: string | ((tile: KPITile) => unknown);
+    /** The heading tiles whose parent is not in the panel are gathered under. */
+    orphans?: 'root' | string;
+    /** The separator a derived hierarchy splits a tile id on. Defaults to `.`. */
+    separator?: string;
+    /** Which branches start open: every one (`true`), or these node keys. */
+    expanded?: true | string[];
+  }
+
+  /**
+   * One node of the rail.
+   *
+   * **No value rolls up.** `value` and `formatted` are the node's own tile's
+   * reading, and are `null` on a level the hierarchy synthesised, because the
+   * running accumulators cannot be composed without a rescan.
+   *
+   * **Severity does.** `rollup` is the worst status at or below the node, which
+   * is what a collapsed branch reports. `unknown` is excluded from it on
+   * purpose — ranking "nothing was measured" as the worst would hide a real
+   * warning underneath it — and is surfaced as `unknown`, a count of the
+   * descendants that measured nothing, so neither can pass unnoticed.
+   */
+  interface KPINodeModel {
+    /** The node's stable identity: the tile id, or the path of a synthesised level. */
+    key: string;
+    /** The tile id, or null on a synthesised level. */
+    id: string | null;
+    label: string;
+    /** Depth, 0 at the top level. */
+    level: number;
+    /** Its place among its siblings, from 1, and how many there are. */
+    posinset: number;
+    setsize: number;
+    hasChildren: boolean;
+    expanded: boolean;
+    children: KPINodeModel[];
+    /** The node's own tile, or null on a synthesised level. */
+    tile: KPITileModel | null;
+    value: unknown;
+    formatted: string | null;
+    /** The node's own status. */
+    status: 'good' | 'warn' | 'critical' | 'unknown' | null;
+    /** The worst status at or below the node. Never `unknown`. */
+    rollup: 'good' | 'warn' | 'critical' | null;
+    /** How many tiles at or below the node measured nothing. */
+    unknown: number;
+    /** How many tiles are at or below the node. */
+    items: number;
+  }
+
   /** A computed tile, as it appears in the model. */
   interface KPITileModel {
     id: string;
@@ -8356,7 +8714,17 @@ declare module 'lattice-grid/modules/kpi' {
     field?: string;
     value: unknown;
     formatted: string;
-    status: 'good' | 'warn' | 'critical' | null;
+    /**
+     * The tile's semantic band, or `unknown` when the panel holds no rows at
+     * all. `unknown` is decided from data presence before any threshold is
+     * consulted: an aggregation over nothing returns the identity of its
+     * operation (`sum` and `count` return 0), and 0 is a number a threshold
+     * grades, so without it an empty panel would report as a healthy one. A
+     * tile whose `filter` matches none of the rows the panel *does* hold has
+     * measured a real zero and is banded normally. `null` means the tile has no
+     * thresholds or bands configured.
+     */
+    status: 'good' | 'warn' | 'critical' | 'unknown' | null;
     target?: number;
     baseline?: number;
     delta: number | null;
@@ -8382,10 +8750,20 @@ declare module 'lattice-grid/modules/kpi' {
     columns?: number;
     ariaLabel?: string;
     nullText?: string;
+    /** Arrange the tiles as a hierarchy; `false` keeps the panel flat. */
+    tree?: KPITreeConfig | false;
+    /**
+     * The catalogue the panel's own text is read from. A panel routinely has no
+     * grid to borrow one off — two of its three input modes have none — so this
+     * is the first-class way to translate it. A grid's own `messages` satisfies
+     * the shape; a key it does not carry falls back to English.
+     */
+    messages?: { t(key: string, params?: Record<string, unknown>): string };
     onTileClick?: (event: KPIEvent) => void;
     onTileDblClick?: (event: KPIEvent) => void;
     onTileContextMenu?: (event: KPIEvent) => void;
-    onChange?: (event: { model: { tiles: KPITileModel[] } }) => void;
+    onNodeToggle?: (event: { key: string; expanded: boolean; node?: KPINodeModel }) => void;
+    onChange?: (event: { model: { tiles: KPITileModel[]; nodes?: KPINodeModel[] } }) => void;
   }
 
   /** The keyed-diff consumer surface a KPI panel shares with a grid, so a Data Router routes to it directly. */
@@ -8404,10 +8782,21 @@ declare module 'lattice-grid/modules/kpi' {
   interface KPI {
     readonly el: unknown | null;
     readonly rowKey: string | ((row: KPIRow) => unknown);
+    /** Whether the panel renders as a hierarchy rather than a flat tile grid. */
+    readonly tree: boolean;
     rows: KPIRows;
     tiles(): KPITileModel[];
     tile(id: string): KPITileModel | undefined;
     value(id: string): unknown;
+    /** The top-level nodes of the hierarchy. Empty on a flat panel. */
+    nodes(): KPINodeModel[];
+    /** One node by its key, at any depth. */
+    node(key: string): KPINodeModel | undefined;
+    /** The nodes on screen: the roots, plus the children of every open branch. */
+    visibleNodes(): KPINodeModel[];
+    expand(key: string): KPI;
+    collapse(key: string): KPI;
+    toggle(key: string): KPI;
     setRows(rows: KPIRow[]): KPI;
     refresh(): KPI;
     getState(): object;