@toclocoinc/lattice-grid 1.50.0 → 1.51.0

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.50.0</p>
+    <p class="rail__sub">Developer guide · v1.51.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -473,6 +473,7 @@
         <span class="rail__label">Connected grids</span>
         <a href="#pushdown">Querying an engine</a>
         <a href="#derived">Derived grids</a>
+        <a href="#derived-union">Combining several grids</a>
         <a href="#cross-filter">Cross-filtering</a>
         <a href="#joins">Joining two grids</a>
         <a href="#aggregate-safety">Aggregate safety</a>
@@ -3325,6 +3326,81 @@ createGrid(right, {
       </table>
     </div>
 
+    <h2 id="derived-union">Combining several grids into one</h2>
+    <p class="lead-in">
+      A <code>join</code> matches two grids on a shared key. Some questions have no key to share at
+      all &mdash; "the worst performers across two regional datasets" when the two regions use
+      unrelated ids &mdash; and for those, <code>from</code> takes an array of sources instead of one
+      grid: every source is read, concatenated in the order you declared them, and only then does the
+      rest of the pipeline run, once, over the combined set.
+    </p>
+    <div class="example">
+      <p class="example__label">Worst performers, two unrelated datasets</p>
+      <pre><code>createGrid(right, {
+  columns: [{ id: 'title' }, { id: 'severity', type: 'number' }, { id: '__source' }],
+  source: {
+    mode: 'derived',
+    from: [
+      { grid: eastIncidents, label: 'east' },
+      { grid: westIncidents, label: 'west', map: (row) =&gt; ({ title: row.name, severity: row.rating }) },
+    ],
+    sort: [{ col: 'severity', dir: 'desc' }],
+    limit: 10,
+  },
+});</code></pre>
+    </div>
+    <p>
+      <code>label</code> defaults to the source's position in the array (<code>'0'</code>,
+      <code>'1'</code>, &hellip;), and <code>follow</code> is independent per source &mdash; filtering
+      one narrows only its own contribution, exactly as a lone <code>from</code> follows its grid
+      today. A source with differently-named fields uses <code>map</code> to project them into a
+      common shape before it joins the rest.
+    </p>
+    <div class="why">
+      <p><strong><code>__source</code> is not optional.</strong> Every combined row carries it &mdash;
+      the entry's <code>label</code>, or its index when unlabelled &mdash; and it is an ordinary field
+      to <code>where</code>, <code>groupBy</code> and <code>select</code>. Leaving it out would mean a
+      combined list that cannot say where any row came from, which defeats most of the reason to
+      combine several sources in the first place.</p>
+      <p><strong>The union of fields, never a merge.</strong> A field only one source has is
+      <code>undefined</code> on the others' rows, not fabricated and not type-coerced &mdash; two
+      sources disagreeing about what a field means is yours to resolve with <code>map</code>, not
+      something the union guesses at. And there is no dedup: two sources reporting the same fact both
+      appear as separate rows. There is no UNION-vs-UNION-ALL distinction to draw; reach for
+      <code>join</code> when rows should be matched on a key rather than stacked.</p>
+      <p><strong>The key is namespaced, only where it needs to be.</strong> Two sources can easily
+      share row identifiers, so the derived <code>__key</code> is qualified by the source tag when
+      nothing is grouped. Grouped, <code>__key</code> is the group value exactly as it always has
+      been, and rows from different sources landing in the same group is what grouping a union is
+      <em>for</em>, not a collision.</p>
+      <p><strong>An empty source is fine; a broken one is loud.</strong> A source with no rows
+      contributes nothing. A source that throws while being read is named in a console warning and
+      skipped for that pass &mdash; a silently missing source would make "worst across both" quietly
+      wrong, so it is reported rather than swallowed.</p>
+      <p><strong>A cycle is refused when the source is built.</strong> If a union's sources include
+      the grid being derived, directly or through a chain of other derived grids, it is refused up
+      front, naming the offending source, rather than being recursed into.</p>
+      <p><strong>A union never patches &mdash; know the cost before you reach for one at scale.</strong>
+      A lone <code>from</code> maintains its grouping incrementally: an edit that names the rows it
+      touched re-reduces only the groups those rows belong to. A union does not do this for any of its
+      sources &mdash; every change on <em>any</em> parent re-reads and re-derives the <em>whole</em>
+      combined set from scratch. On a synthetic 200,000-row union across four sources, one row changed
+      on one parent cost on the order of <strong>800&nbsp;ms&ndash;3&nbsp;s</strong> (machine-dependent;
+      run <code>node bench/union-parents.mjs</code> against your own shape), against a few
+      milliseconds for the equivalent patched change on a lone <code>from</code> over the same row
+      count. And because a union is watched by as many independent change streams as it has sources,
+      that full-rescan cost is paid once <em>per source that moves</em>, not once per union &mdash;
+      four active parents each firing their own updates pay it four times over. Below a few tens of
+      thousands of combined rows this is unlikely to matter; above that, or with several sources each
+      updating on their own live feed, budget for it, keep <code>refresh</code> away from every tick
+      (<code>idle</code>, or a debounce), and prefer fewer, larger sources over many small ones where
+      the shape of your data allows it.</p>
+      <p><strong>Not supported alongside a union.</strong> <code>crossFilter</code> has no single
+      target once there is more than one parent; <code>profile</code> reduces one grid's own columns.
+      Both are refused with a warning rather than guessed at, and the top-level <code>follow</code> is
+      ignored in favour of each source's own.</p>
+    </div>
+
     <h2 id="cross-filter">Cross-filtering</h2>
     <p class="lead-in">
       A derived panel can filter the grid it summarises. Click a region in the summary and the
@@ -5982,6 +6058,162 @@ r.ok ? r.value : r.error;   <span class="cmt">// 42</span></code></pre>
       a missing <code>return</code> is a typo and deleting the whole menu is a harsh reading of
       one.</p>
     </div>
+    <h3 id="per-column-menu">Declaring a menu on the column itself</h3>
+    <p class="lead-in">
+      A cell menu can also be declared <strong>on the column</strong>, with
+      <code>contextMenu</code> on the column definition. It takes the same shapes the grid-level
+      option takes, plus a bare array for the common &ldquo;just these items here&rdquo; case:
+      <code>boolean | MenuItem[] | (params, defaults) =&gt; items</code>.
+    </p>
+    <div class="example">
+      <p class="example__label">Each column's menu logic beside the column it is about</p>
+      <pre><code>createGrid(el, {
+  columns: [
+    { field: 'account' },
+    <span class="cmt">// Just these items, here.</span>
+    { field: 'owner', contextMenu: [{ name: 'Reassign', action: reassign }] },
+    <span class="cmt">// Or the built-ins plus one, the same form the grid-level option takes.</span>
+    {
+      field: 'amount',
+      contextMenu: (params, defaults) =&gt; [
+        ...defaults,
+        { separator: <span class="kw">true</span> },
+        { name: `Reprice ${params.value}`, action: (ctx) =&gt; reprice(ctx.data) },
+      ],
+    },
+    <span class="cmt">// And nothing at all on a column nobody should act on from here.</span>
+    { field: 'nationalId', contextMenu: <span class="kw">false</span> },
+  ],
+});</code></pre>
+    </div>
+    <p class="lead-in">
+      This adds no power the grid-level option did not have &mdash; <code>params.colId</code> and
+      <code>params.column</code> always let one callback branch by column. What it adds is
+      <strong>locality</strong>: the menu for a column is declared where the column is, instead of
+      collecting into one growing <code>switch</code> a long way from the thing it is about.
+    </p>
+
+    <h4 id="per-column-menu-chain">The three levels compose as a chain</h4>
+    <p class="lead-in">
+      The built-in items go in first, then the grid-level <code>contextMenu</code>, then the
+      column's own &mdash; <strong>each handed the previous level's result as its
+      <code>defaults</code></strong>. A column that wants one extra item writes one extra item; it
+      never has to restate Paste, Clear and Fill&nbsp;down, nor whatever the grid-level builder just
+      added.
+    </p>
+    <div class="example">
+      <p class="example__label">Built-ins &rarr; grid &rarr; column, executed</p>
+      <pre data-run="js" data-expect="grid|column" data-covers="config:contextMenu"><code><span class="kw">const</span> { createTestDom, flushFrames } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
+<span class="kw">const</span> { createGrid } = <span class="kw">await</span> import('../packages/dom/src/index.js');
+<span class="kw">const</span> { root } = createTestDom({ width: 600, height: 300 });
+
+<span class="kw">let</span> handedToTheColumn = [];
+<span class="kw">const</span> grid = createGrid(root, {
+  rowKey: 'id',
+  rows: [{ id: 1, account: 'Acme', amount: 120 }],
+  columns: [
+    { field: 'account' },
+    {
+      field: 'amount',
+      contextMenu: (params, defaults) =&gt; {
+        handedToTheColumn = defaults.map((d) =&gt; d.name);
+        <span class="kw">return</span> [...defaults, { name: 'from the column', action() {} }];
+      },
+    },
+  ],
+  contextMenu: (params, defaults) =&gt; [...defaults, { name: 'from the grid', action() {} }],
+});
+flushFrames();
+
+<span class="kw">const</span> row = grid.rows.get(0);
+grid.emit('cell:contextmenu', {
+  row, key: row.key, index: 0, colId: 'amount',
+  column: grid.columns.get('amount'), value: 120,
+  event: { clientX: 10, clientY: 10, preventDefault() {} },
+});
+flushFrames();
+
+<span class="cmt">// The column builder was handed the grid builder's output, not the raw</span>
+<span class="cmt">// built-ins: 'from the grid' is already in its `defaults`.</span>
+<span class="kw">const</span> chained = handedToTheColumn.includes('from the grid');
+<span class="kw">const</span> shown = [...root.querySelectorAll('.lat-menu__item')]
+  .map((i) =&gt; String(i.textContent).trim());
+grid.destroy();
+<span class="kw">return</span> chained &amp;&amp; shown.includes('from the column') ? 'grid|column' : 'broken';</code></pre>
+    </div>
+    <p class="lead-in">
+      <strong>Suppression follows the same order, and the more specific level wins.</strong>
+      <code>contextMenu: false</code> on a column is a statement about <em>that column</em> and no
+      other. Equally, a column may declare a menu on a grid whose <code>contextMenu</code> is
+      <code>false</code> &mdash; which is how you say &ldquo;no menu anywhere except here&rdquo;.
+      <code>contextMenu: true</code> on a column means &ldquo;whatever came before&rdquo;, so it
+      restores the built-in menu on a grid that turned it off.
+    </p>
+    <table class="ref">
+      <thead><tr><th>Grid level</th><th>Column level</th><th>What opens on that column</th></tr></thead>
+      <tbody>
+        <tr><td><em>not set</em></td><td><em>not set</em></td><td>the built-in menu</td></tr>
+        <tr><td>a builder</td><td><em>not set</em></td><td>the builder's result</td></tr>
+        <tr><td>a builder</td><td>a builder</td><td>the column's builder, handed the grid builder's result</td></tr>
+        <tr><td>a builder</td><td>an array</td><td>the array &mdash; the grid level still ran, and was replaced</td></tr>
+        <tr><td>a builder, or not set</td><td><code>false</code></td><td><strong>nothing</strong> &mdash; the column suppresses, and no other column is affected</td></tr>
+        <tr><td><code>false</code></td><td><em>not set</em></td><td><strong>nothing</strong> &mdash; the grid-level off stands, as it always has</td></tr>
+        <tr><td><code>false</code></td><td>an array</td><td><strong>the column's array.</strong> The column opts back in: grid-level <code>false</code> is a default, not a lock</td></tr>
+        <tr><td><code>false</code></td><td>a builder</td><td><strong>the builder's result</strong>, handed the built-in items as its <code>defaults</code>. The column opts back in</td></tr>
+        <tr><td><code>false</code></td><td><code>true</code></td><td><strong>the built-in menu.</strong> The column opts back in and asks for the defaults</td></tr>
+      </tbody>
+    </table>
+    <div class="note">
+      <p><strong><code>contextMenu: false</code> on the grid is a default, not a lock.</strong> If
+      you set it as a safety property &mdash; a read-only grid, a screen where nobody should be
+      able to copy or clear from a right-click &mdash; be aware that a column declaring its own
+      <code>contextMenu</code> will still open one, because the more specific level wins in
+      <em>both</em> directions. That is deliberate: a read-only grid with one actionable column is a
+      real shape, and it is the only way to say &ldquo;no menu anywhere except here&rdquo;. But it
+      does mean grid-level <code>false</code> does not guarantee that no cell menu can open
+      anywhere &mdash; only that none opens unless a column asks for one. If you need the absolute
+      guarantee, do not declare <code>contextMenu</code> on any column.</p>
+    </div>
+    <div class="why">
+      <p><strong>A chain, not a replacement.</strong> If the column level replaced the grid level,
+      every column that wanted one extra item would have to restate everything the grid-level
+      builder does &mdash; and would then stop tracking it the first time it changed. This is the
+      same rule <code>columnMenu</code> already follows for the header: you are handed what came
+      before so you can add to it rather than reproduce it.</p>
+    </div>
+
+    <h4 id="per-column-menu-edges">A range, and rows that belong to no column</h4>
+    <p class="lead-in">
+      <strong>On a multi-column selection, the column you right-clicked decides.</strong> Not the
+      intersection of the selected columns' menus, which silently drops items; not their union,
+      which offers actions that are wrong for most of the selection. The clicked column is the one
+      the user pointed at, and it is the one that answers &mdash; the built-in range actions
+      (Copy, Clear, Fill&nbsp;down) still act on the whole range as they always did.
+    </p>
+    <p class="lead-in">
+      <strong>A row with no owning column falls back to the grid-level menu.</strong> Group rows,
+      pivot group rows and full-width rows do not belong to one column, so there is no column-level
+      declaration to consult; the chain simply has one fewer link and the grid-level menu stands.
+      Nothing errors and nothing silently shows an empty menu.
+    </p>
+    <p class="lead-in">
+      Every route honours the column: a right-click, and the keyboard's
+      <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Context&nbsp;Menu</kbd> key on the focused cell.
+      The menu is a <code>role="menu"</code> of <code>role="menuitem"</code>s that takes focus and
+      closes on <kbd>Escape</kbd> wherever it was opened from.
+    </p>
+    <div class="why">
+      <p><strong>Trust is unchanged.</strong> A <code>MenuItem</code> is the same object it always
+      was, including <code>icon</code> markup being trusted at the same level as
+      <code>action</code>. Declaring one on a column changes <em>where</em> it is written, not who
+      is trusted to write it: a column definition is your code, exactly as a grid config is.</p>
+    </div>
+    <p class="lead-in">
+      A column preset or <code>columnDefaults</code> may supply <code>contextMenu</code> too, and
+      the column's own declaration outranks both &mdash; so a house rule like &ldquo;no cell menu on
+      anything tagged sensitive&rdquo; is written once.
+    </p>
+
     <p class="lead-in">
       <code>columnMenu</code> takes the same function form, for both routes into a column's menu:
       the header's 3-dot button and a right-click on the heading. Its <code>params</code> is

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.50.0, type declarations
+ * Lattice Grid 1.51.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. */
@@ -1265,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;
@@ -5952,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,
@@ -5974,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`.
@@ -6054,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[];
@@ -8356,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;