@toclocoinc/lattice-grid 1.49.0 → 1.51.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.49.0, type declarations
+ * Lattice Grid 1.51.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -729,6 +729,12 @@ export interface Column {
   shadow?: ShadowKind | {
     of?: string;
     kind: ShadowKind;
+    /**
+     * For `kind: 'history'`, how many past readings to keep (20 by default). With
+     * a time `window` (BACKLOG-0001043) this is instead how many buckets the span
+     * divides into — `window: {kind: 'time', span: 60_000}, depth: 20` is sixty
+     * one-second buckets. Ignored by every other kind.
+     */
     depth?: number;
     /**
      * For a positional kind, what to rank against. `'all'` (the default) uses
@@ -768,6 +774,16 @@ export interface Column {
      * (`time`), or everything so far (`session`). The first rows of a series
      * carry a partial window, stamped by a `windowCoverage` companion rather than
      * dressed as full.
+     *
+     * For `kind: 'history'` (BACKLOG-0001043), only `{kind: 'time', span}` (or
+     * `minutes`) applies, and it changes what `history` means rather than what it
+     * aggregates: the `depth` buckets that span divides into are read once each,
+     * carrying the row's last known value forward into any bucket in which it did
+     * not change, so a static row still draws a flat, advancing line instead of
+     * freezing — the plain count-based history (no `window`) is a count of
+     * *changes* and stays exactly as it was. `count` and `session` are refused
+     * here: a plain count is already what `depth` means, and a session has no
+     * fixed span to divide into buckets.
      */
     window?: {
       kind: 'count' | 'time' | 'session';
@@ -847,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
@@ -923,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;
@@ -1204,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. */
@@ -1249,6 +1337,38 @@ export interface DerivedSourceConfig {
   crossFilter?: boolean | string | { col?: 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;
@@ -5936,6 +6056,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,
@@ -5958,7 +6090,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`.
@@ -6038,6 +6178,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[];
@@ -8340,7 +8489,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;
@@ -8808,3 +8967,108 @@ declare module 'lattice-grid/modules/ai' {
 
   export default createAI;
 }
+
+declare module 'lattice-grid/modules/tabs' {
+  /**
+   * One tab: an id, a display label, a grid config, and — for a derived tab —
+   * the parent tab id plus the narrowing forwarded onto the derived source
+   * built for it (`source: { mode: 'derived', from: <parent's grid>, ... }`).
+   * The derivation keys are the ones `packages/core/src/source/derive.js`
+   * already understands; this module invents none of its own.
+   */
+  interface TabDescriptor {
+    /** A stable, unique id. Required. */
+    id: string;
+    /** The tab button's text. Defaults to `id`. */
+    label?: string;
+    /** The grid config passed to `createGrid` for this tab (merged with the derived `source`, when `from` is set). */
+    config?: object;
+    /** The parent tab id to derive from. When set, `config.source` is built for you and any of your own is replaced (with a warning). */
+    from?: string;
+    /** Row predicate forwarded to the derived source. */
+    where?: (row: unknown) => boolean;
+    /** Group-by forwarded to the derived source. */
+    group?: unknown;
+    groupBy?: unknown;
+    /** Time-bucketing forwarded to the derived source. */
+    bucket?: unknown;
+    /** Join spec forwarded to the derived source. */
+    join?: unknown;
+    /** Array-field unnesting forwarded to the derived source. */
+    unnest?: unknown;
+    /** `'live' | 'idle' | 'manual' | number` forwarded to the derived source. */
+    refresh?: 'live' | 'idle' | 'manual' | number;
+    /** Cross-filter wiring forwarded to the derived source. */
+    crossFilter?: unknown;
+    /** Which slice of the parent's rows to derive from: `'filtered' | 'all' | 'selected' | 'grouped'`. */
+    follow?: 'filtered' | 'all' | 'selected' | 'grouped';
+    /** Row limit forwarded to the derived source. */
+    limit?: number;
+    /** Sort forwarded to the derived source. */
+    sort?: unknown;
+    /** Statistical-profile derivation, forwarded to the derived source. */
+    profile?: unknown;
+    /** This tab's panel's own `aria-label`, when the label alone is not enough context. */
+    ariaLabel?: string;
+  }
+
+  /** The payload every tab-change event carries. */
+  interface TabChangeEvent {
+    id: string;
+    previousId: string | null;
+    origin?: 'api' | 'user' | 'init';
+    reason?: string | null;
+    /** Cancel the switch (only meaningful on `beforeTabChange`). */
+    preventDefault?: (reason?: string) => void;
+    defaultPrevented?: boolean;
+  }
+
+  /** Tabbed-grid configuration. */
+  interface TabsConfig {
+    /** The grid factory to mount each tab with, e.g. `import { createGrid } from 'lattice-grid'`. Required. */
+    createGrid: (el: HTMLElement, config: object) => unknown;
+    /** The tabs, in display order. Required, at least one. */
+    tabs: TabDescriptor[];
+    /** The initially active tab id. Defaults to the first tab. */
+    active?: string;
+    /** The tablist landmark's accessible name. */
+    ariaLabel?: string;
+    /** An explicit message-catalogue override; otherwise a mounted tab's own `grid.messages` is used. */
+    messages?: { t(key: string, params?: Record<string, unknown>): string };
+    onTabChange?: (event: TabChangeEvent) => void;
+    onBeforeTabChange?: (event: TabChangeEvent) => boolean | void | Promise<boolean>;
+    onTabChangeCancelled?: (event: TabChangeEvent) => void;
+  }
+
+  /**
+   * A tabbed grid: a `role="tablist"` strip above a stack of `role="tabpanel"`
+   * regions, each hosting its own, independently-configured grid instance
+   * (BACKLOG-0001039). A tab's grid mounts on first activation and is kept
+   * alive, hidden, until `destroy()`.
+   */
+  interface Tabs {
+    readonly el: HTMLElement;
+    /** The currently active tab id. */
+    readonly activeId: string;
+    /** The configured tab ids, in order. */
+    tabs(): string[];
+    /** The live grid instance for a tab, or `null` before it has been materialised. */
+    tab(id: string): unknown | null;
+    /** Whether a tab's grid has been created yet. */
+    isMounted(id: string): boolean;
+    /** Switch the active tab, gated by `beforeTabChange`. */
+    activate(id: string, opts?: { origin?: 'api' | 'user' }): boolean | Promise<boolean>;
+    on(name: 'beforeTabChange' | 'tab:changed' | 'tabChange:cancelled' | string, fn: (event: TabChangeEvent) => void): () => void;
+    off(name: string, fn: (event: TabChangeEvent) => void): void;
+    /** Tear the whole strip down; destroys every mounted tab's grid. */
+    destroy(): void;
+  }
+
+  /**
+   * Create a tabbed grid over a host element. Each tab is a full,
+   * independently-configured grid instance; a tab may derive from another via
+   * `from`, reusing the shipped `source: { mode: 'derived' }` mechanism.
+   */
+  export function createTabs(el: HTMLElement, config: TabsConfig): Tabs;
+  export default createTabs;
+}