Lattice Grid API

Version 1.65.0 Zero dependencies Developer guide →

Construction

Two files are all you need: a stylesheet and a script. Nothing is fetched at runtime (no CDN, no font, no icon sprite) however the two files themselves got there.

<!-- Script tag, from your own build. Everything is on one global. -->
<link rel="stylesheet" href="dist/lattice-grid.min.css">
<script src="dist/lattice-grid.min.js"></script>

<script>
  const grid = LatticeGrid.createGrid(document.getElementById('grid'), config);
</script>

Or straight from jsDelivr, no npm install, no bundler, no local copy at all:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1/lattice-grid.min.css">
<script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1/lattice-grid.min.js"></script>

<script>
  const grid = LatticeGrid.createGrid(document.getElementById('grid'), config);
</script>

Or as modules, importing the bundle by path: your own build, npm, or jsDelivr:

// With a renderer, in a browser. Any of:
import { createGrid } from './dist/lattice-grid.esm.js';
// import { createGrid } from '@toclocoinc/lattice-grid';
// import { createGrid } from 'https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1/lattice-grid.esm.min.js';
const grid = createGrid(document.getElementById('grid'), config);

// Headless: the same API without a renderer. Data, filters, sort,
// grouping, totals, formatting and export all work; grid.element is
// null and the DOM-only chrome is simply absent.
// Runs in Node, for tests and server-side export.
import { createHeadlessGrid } from './dist/lattice-core.esm.js';
const grid = createHeadlessGrid(config);

Framework adapters

The web component carries the grid inside it, so use it or createGrid in a page, not both: two copies keep separate registries, and a renderer registered through one is invisible to the other. One optional bundle per framework. The framework and createGrid are passed in rather than imported, so the adapters add no dependency and carry no second copy of the grid.

// React
import React from 'react';
import { createGrid } from './dist/lattice-grid.esm.js';
import { createLatticeGrid } from './dist/modules/react.esm.js';

const LatticeGrid = createLatticeGrid({ React, createGrid });
<LatticeGrid columns={columns} rows={rows} rowKey="id" onCellChanged={fn} />

// Vue 3
import * as vue from 'vue';
import { createLatticeGrid } from './dist/modules/vue.esm.js';

const LatticeGrid = createLatticeGrid({ vue, createGrid });
<LatticeGrid :columns="columns" :rows="rows" row-key="id" @cell-changed="fn" />

// Svelte, an action, so no framework runtime is needed
import { createLatticeAction } from './dist/modules/svelte.esm.js';

const lattice = createLatticeAction({ createGrid });
<div use:lattice={{ columns, rows, rowKey: 'id' }} on:cell-changed={fn}></div>

React: every viewer, not only the grid

Until 1.63 the React adapter wrapped createGrid and nothing else. Every other shipped viewer — the KPI panel, a chart, the board, the Gantt, the layout, the tab strip — and the data router had no React surface, so a React application wrote its own useEffect per viewer. It does not have to any more: there is one component per viewer, and each keeps the contract the grid component already kept.

import React from 'react';
import ReactDOM from 'react-dom';
import { createGrid } from '@toclocoinc/lattice-grid';
import { createKPI } from '@toclocoinc/lattice-grid/modules/kpi';
import { createChart } from '@toclocoinc/lattice-grid/modules/charts';
import { createDataRouter } from '@toclocoinc/lattice-grid/modules/data-router';
import { createLatticeReact } from '@toclocoinc/lattice-grid/modules/react';

// Built once, at module scope. Building components inside a component hands React a
// new type on every render, and a new type is a different element: the subtree would
// unmount and remount, destroying and rebuilding the grid on every keystroke.
const L = createLatticeReact({
  React, ReactDOM, createGrid, createKPI, createChart, createDataRouter,
});

function Dashboard({ rows }) {
  const router = L.useLatticeRouter(ROUTER_CONFIG);
  return (
    <L.LatticeRouterProvider router={router}>
      <L.LatticeGridProvider>
        <L.LatticeGrid name="quakes" route="all" {...GRID_CONFIG} rows={rows} />
        <L.LatticeKPI gridName="quakes" tiles={TILES} columns={5} />
        <L.LatticeChart gridName="quakes" type="bar" x="region" y="count" />
      </L.LatticeGridProvider>
    </L.LatticeRouterProvider>
  );
}

const A = await import('../packages/modules/react/index.js');

// A stand-in for React and react-dom. The adapter never imports either, so a
// factory only needs the handful of names it destructures — which is exactly
// why this example runs in Node with no framework installed.
const React = { createElement: () => ({}), createContext: () => ({}), forwardRef: (f) => f };
const ReactDOM = { createPortal: () => ({}) };
const stub = () => ({ on: () => () => {}, destroy() {} });

// One call builds whichever components the factories you pass support.
const L = A.createLatticeReact({
  React, ReactDOM, createGrid: stub, createKPI: stub, createChart: stub, createDataRouter: stub,
});

// …or one factory at a time.
const components = [
  A.createLatticeGrid({ React, createGrid: stub }),
  A.createLatticeKPI({ React, createKPI: stub }),
  A.createLatticeChart({ React, createChart: stub }),
  A.createLatticeKanban({ React, createKanban: stub }),
  A.createLatticeGantt({ React, createGantt: stub }),
  A.createLatticeLayout({ React, createLayout: stub }),
  A.createLatticeTabs({ React, ReactDOM, createTabs: stub }),
  A.createLatticeViewer({ React, viewer: 'kpi', mount: stub }),
].filter((c) => typeof c === 'function');

// The provider/hook pair and the router hook are built the same way.
const { LatticeGridProvider, useLatticeGrid } = A.createLatticeGridContext({ React });
const { useLatticeRouter } = A.createLatticeRouter({ React, createDataRouter: stub });

// And the lifecycle underneath, driven with no framework at all: mount once,
// push a changed live prop into the instance that already exists, destroy.
const seen = [];
const controller = A.createViewerController({
  viewer: 'kpi',
  element: {},
  props: { rows: [{ id: 1 }] },
  mount: () => ({ setRows: (r) => seen.push(r.length), on: () => () => {}, destroy() {} }),
});
controller.update({ rows: [{ id: 1 }, { id: 2 }] });
controller.destroy();

return `${components.length} components, ${A.viewerHandlerName('card:move')}, `
  + `${A.DEFAULT_GRID_NAME}, rows ${seen.join('/')}, `
  + `events ${A.VIEWER_EVENTS.kpi.length}/${Object.keys(A.VIEWER_APPLY).length}`;

Live props versus mount-time props. The grid takes any changed configuration key through one call (grid.setAll); no other viewer does. So each viewer declares which props it can take while it is running — the table above, and VIEWER_APPLY at runtime — and everything else is mount-time configuration. A mount-time prop that changes is not silently ignored and not silently remounted (that would throw away scroll position, selection and expansion): it is named once in a warning that tells you to give the component a key that changes when the rebuild is wanted, or to drive the instance through the ref.

Two props rebuild a viewer rather than update it: the grid it is bound to, and anything it cannot exist without. A chart holding a destroyed grid is not stale, it is invalid, so a new grid tears the old chart down and builds a new one against it — in that order, never the reverse.

A live feed: rowUpdates and predicates. rowUpdates is a keyed diff handed straight to grid.rows.apply(), applied when the object's identity changes — a feed produces a new change object per batch, so identity is the right trigger and re-applying the same object would re-land rows the grid already has. predicates is { name: fn } mapped to grid.filters.where(name, fn), diffed by name, with a name that has gone removed. Those compose with whatever filter the reader set in the tool panel; the filters prop cannot, because it maps to filters.set and replaces the whole condition tree.

StrictMode creates one instance. React 18's StrictMode deliberately mounts, unmounts and mounts again in development. Every component here builds its instance in an effect with an empty dependency list and destroys it in that effect's cleanup, so the first is destroyed before the second is built and exactly one survives. There is no module-level "already mounted" flag, because that would defeat a genuine remount.

Props are diffed with Object.is, and that is a promise about identity. An inline columns={[{ field: 'a' }]} is a new array on every render, so it counts as changed every render and reconfigures the grid every render. Hoist it to module scope or wrap it in useMemo. This is not a defect to work around: a deep compare of a million-row array on every render would cost more than the reload it prevents.

Sharing one rows array between grids is safe. Since 1.63 the grid copies the array it is handed on ingest, so two grids given the same rows={EMPTY} default no longer contaminate each other. The row objects are still shared, as they always were — mutate one and both grids see it.

React 18 and 19, no SSR. Nothing in the adapter uses an API added in 19 or removed in 19 (forwardRef is still supported there). Every component owns a real DOM element, so there is no server rendering and no React Server Component support: render them on the client.

One build warning is gone. The version resolver carried a Node-only fallback whose import('node:' + 'module') Vite could not analyse statically, so every Vite build of every application printed "The above dynamic import cannot be analyzed by Vite" about a line that could never run. The build now deletes that branch from every emitted artefact.

Angular: a compiled package, @toclocoinc/lattice-grid-angular

Angular's components are not objects a library can assemble at run time in a production build. modules/angular did assemble them that way, which needs Angular's JIT compiler in the page — present on a development server, absent from every AOT build. So Angular gets a package of its own: TypeScript components compiled by @angular/compiler-cli into a partial-Ivy library, which your build's Angular Linker turns into definitions exactly as it does for any other Angular library you install. No compiler in your bundle, and one standalone component per viewer.

npm install @toclocoinc/lattice-grid @toclocoinc/lattice-grid-angular

import { bootstrapApplication } from '@angular/platform-browser';
import { createGrid } from '@toclocoinc/lattice-grid';
import { createKPI } from '@toclocoinc/lattice-grid/modules/kpi';
import { createChart } from '@toclocoinc/lattice-grid/modules/charts';
import {
  LatticeGridComponent, LatticeKpiComponent, LatticeChartComponent, provideLattice,
} from '@toclocoinc/lattice-grid-angular';

@Component({
  selector: 'app-dashboard',
  imports: [LatticeGridComponent, LatticeKpiComponent, LatticeChartComponent],
  template: `
    <lattice-grid #grid name="quakes" [config]="config" [quickFilter]="search()"
                  (cell-changed)="save($event)" />
    <lattice-kpi  gridName="quakes" [config]="{ tiles }" />
    <lattice-chart gridName="quakes" [config]="{ type: 'bar', x: 'region', y: 'count' }" />
  `,
})
export class Dashboard {
  // The live grid, the same object createGrid returns.
  grid = viewChild<LatticeGridComponent>('grid');
}

// Each factory is injected, not imported by the library: an application that
// shows a grid downloads the grid, and never the board or the eighteen charts.
bootstrapApplication(Dashboard, {
  providers: [provideLattice({ createGrid, createKPI, createChart })],
});

Change detection: zone or zoneless, unconfigured. The grid is created inside NgZone.runOutsideAngular, because it installs its own scroll, wheel and pointer listeners and running change detection on every scroll frame of a million-row grid is the difference between smooth and unusable. An event that reaches an output you have bound re-enters the zone, so (cell-changed)="count = count + 1" repaints exactly as you expect; an output nobody bound costs nothing. Under zoneless change detection that machinery is Angular's own no-op and a signal you set in a handler repaints the view. The one thing to know when reading the grid's DOM from Angular: the grid paints on its own schedule, not Angular's, so measure a cell in a grid event, not in ngAfterViewInit.

OnPush is safe everywhere. None of these components asks its parent to re-render: each owns one element, builds one instance in afterNextRender and pushes changed inputs into it from ngOnChanges. A host on OnPush that never re-renders still gets a fully live grid, because the grid is not rendered by Angular.

Inputs are diffed by identity, and never rebuild the instance. A changed input reaches the viewer that is already on screen — scroll position, selection, expansion and any open editor intact. Two things rebuild rather than update: the grid a viewer is bound to, and an input it cannot exist without. An input a viewer has no live setter for is named once in a warning rather than silently dropped. And because the comparison is Object.is, an inline [config]="{ rows: rows }" is a new object on every pass: hold it in a field or a signal.

Cleanup is the component's. ngOnDestroy detaches from the router, withdraws the grid from the registry and destroys the instance — in that order. An @if that closes and opens again leaves exactly one instance alive, and destroying the application leaves no instance, interval or listener behind. That is asserted with counters in a real browser, against the linked package, in test/angular-package-browser.test.js.

Angular 17 and up, browser only. The library is compiled partially, so your own Angular version compiles it: its declarations need a linker no newer than 14, and its peer range is >=17. Nothing is created on the server — isPlatformBrowser guards every build and afterNextRender does not run there — so a server-rendered page emits the empty host element and the grid is built on hydration. Angular Universal is not otherwise supported.

modules/angular is deprecated. The old bundle still works where it always worked — a page with @angular/compiler loaded — and it now says so once, and fails with a [lattice] message naming this package when it finds a real Angular with no JIT compiler, instead of leaving you with Angular's own. In 1.65 it also gained the fix that <div [latticeGrid]="config"> binds the configuration through the directive's selector, as its documentation always said it did. It will be removed in a later release; move to @toclocoinc/lattice-grid-angular, which covers every viewer rather than the grid alone.

// your-lattice.js — the one place that knows your house defaults
import { createGrid as baseCreateGrid } from '@toclocoinc/lattice-grid';

export function createGrid(element, config) {
  return baseCreateGrid(element, { theme: 'house', density: 'compact', ...config });
}

// everywhere else
import { createGrid } from './your-lattice.js';

const { createHeadlessGrid, defaults } = await import('../packages/core/src/index.js');

// One place says what every grid in this application starts from.
defaults({ rowKey: 'id', selection: 'multiple' });

// This grid says nothing about rowKey, so the house value applies.
const a = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'name' }],
  rows: [{ id: 'a1', name: 'Ada' }],
});
const house = a.rows.byKey('a1').data.name;

// This one names its own rowKey. The grid's own config always wins.
const b = createHeadlessGrid({
  rowKey: 'sku',
  columns: [{ field: 'sku' }],
  rows: [{ sku: 's9', id: 'ignored' }],
});
const own = b.rows.byKey('s9') !== undefined && b.rows.byKey('ignored') === undefined;

a.destroy();
b.destroy();
defaults(null);                // clear: grids built after this are unaffected
return `${house}; own-key ${own}; cleared ${JSON.stringify(defaults())}`;

<lattice-grid> web component

A self-contained module bundle that registers a custom element on import. One script, one tag, no build step, for Rails, Django, Laravel or any page without a bundler. Load this or lattice-grid.esm.js, not both: the module carries the grid with it.

<link rel="stylesheet" href="dist/lattice-grid.min.css">
<script type="module" src="dist/modules/webcomponent.esm.min.js"></script>

<lattice-grid row-key="id"
  columns='[{"field":"id"},{"field":"city"}]'
  rows='[{"id":"A","city":"Leeds"}]'></lattice-grid>

Events are re-dispatched as CustomEvents named lattice- plus the grid name with colons hyphenated: cell:changed becomes lattice-cell-changed. The payload is on event.detail. The prefix avoids colliding with platform events, the grid emits one called scroll.

dhtmlx Grid compatibility wrapper

A Grid class shaped like dhtmlx's own dhx.Grid (Suite 5+), backed by a real Lattice grid. Covers column definitions, .data, .selection, .history, .export.csv/.xlsx, and a name-mapped subset of .events: see the guide for exactly what is and is not covered. Not the classic pre-Suite-5 dhtmlXGridObject.

import { Grid } from './dist/modules/dhtmlx-compat.esm.min.js';

const grid = new Grid(container, {
  columns: [{ id: 'name', header: [{ text: 'Name' }], sortable: true }],
  data: rows,
});
grid.data.serialize(); // every row's data, in source order

Which dhtmlx keys are translated

A key outside these lists is not silently dropped: the wrapper names it through warnOnce at construction, so a migration is told what did not come across rather than discovering it later.

Declarative init, hydration & state

Core-level primitives, usable with or without any framework adapter or the htmx module below. An element built by createGrid is discoverable from itself: element.__lattice holds the live instance, cleared on destroy().

htmx integration

One file. modules/htmx re-exports createGrid, autoInit, hydrateTable, readTable, serialiseState and restoreState alongside its own exports below, so a page using htmx integration never also loads the base bundle: that would mean two independent copies of the whole engine on one page. Registers on import: builds grids from [data-lattice-grid] elements or server-rendered <table>s, tears them down before htmx detaches a swapped-out subtree, and rebuilds them in newly-loaded content. driveServerMode/driveInfiniteScroll drive sort, filter and infinite scroll over plain htmx requests; driveOobUpdates applies out-of-band row updates in place. See the guide for the full request-lifecycle wiring and why infinite scroll uses two triggers.

import { autoInit, driveServerMode, driveInfiniteScroll } from './dist/modules/htmx.esm.min.js';

autoInit(document); // builds every [data-lattice-grid] under it

Configuration properties

Every key is settable at runtime through grid.set(key, value). Keys marked dom are read by createGrid and ignored by a headless grid.

Data and structure

Defaults and registries

Behaviour

Presentation

Performance

Chrome dom

Column definition

Everything is optional. A column with only field infers its type from sampled data and takes every default from there.

Inferring a Date, or an ISO string. Inference walks boolean, number, date, dateString, datetime, text, object and takes the first type that matches every sampled value. A Date whose local wall clock reads exactly 00:00:00.000 infers as date and stores YYYY-MM-DD; a Date carrying any time of day infers as datetime and stores YYYY-MM-DDTHH:mm (with seconds when they are non-zero), because a date column would discard the clock on ingest and nothing downstream could recover it. An ISO string follows the same rule: a date-only string (YYYY-MM-DD) infers as date; a string with a time part (T plus a time, with or without a zone offset — '2026-09-12T14:30:00Z') infers as datetime and keeps the time, and a column mixing both forms infers datetime rather than falling back to text. A timestamp such as '2026-09-12T14:30:00Z' therefore keeps its 14:30 on ingest, rather than being read as the calendar day '2026-09-12' with nothing to say that a time had been dropped. This is a heuristic with one stated blind spot: a genuine timestamp that lands on exactly local midnight — a nightly batch stamped 00:00:00.000, or a bare '2026-09-12' string that really meant an instant — is indistinguishable from a date-only value and is still inferred as date, so its time of day is still discarded. Sub-second resolution is never retained by datetime. If you group by such a column, declare it: an undeclared Date column groups by the instant, which is one group per row, where a type: 'date' column groups into day buckets. Date filters are unaffected either way — they compare on the day and return the same rows. Declare type and none of this applies: 'date' truncates on purpose, 'datetime' keeps a wall clock, and 'timestamp' keeps the instant to the millisecond. rows.value() returns that stored form — and the same one on every path: the rows you passed at construction, rows.load(), rows.apply({ add }) and rows.apply({ update }), edit.setCells and a typed cell edit, a stream chunk and a stream re-send, a store-backed or columnar store, off-thread ingest, a bound KPI tile and a chart binding all answer the same shape for the same instant, so a host can do arithmetic on it without testing what it got. rows.text() is the formatted form, and row.data is always the raw value you supplied, unconverted. For millisecond arithmetic use type: 'timestamp', which answers the epoch number on every one of those paths. A column of ISO timestamps that must stay a calendar day opts out with an explicit type: 'date' — no warning is logged for that column, because the value is preserved (declared, not narrowed) and there is nothing to disclose.

Column sub-specs

value

cell

edit, sort, filter, layout, header

Rich cell tooltips

cell.tooltip as a string or a function gives you the browser's own title: one line of plain text, on the browser's schedule, unstyled, and invisible to a keyboard user. The object form declares a tooltip the grid draws instead, so a cell can show a related record, a small chart, a list of validation errors or an edit history (BACKLOG-0001204). The plain-text form is untouched and still becomes a title, so an existing grid behaves exactly as it did.

render(params) returns one of four things, and the difference between the last two is a security property rather than a matter of taste:

That last rule is the load-bearing one. The most natural tooltip anyone writes is render: (p) => p.value, and a value comes from row data — data the developer did not write and usually cannot audit. If a bare string were treated as markup, a name field holding <img src=x onerror=…> would execute and nothing in the code would have looked dangerous. Markup therefore has to be asked for in the source, where a reviewer can see it, and no value arriving from data can promote itself.

mount(el, params) and unmount(el) carry live content. Inside mount you call createChart or createKPI from a module bundle your application loaded — the grid core never imports a module — and unmount is called every time the tooltip closes, so nothing keeps running behind a hidden box. One tooltip element is built and re-used for every cell.

Accessibility. Nothing is built until the pointer or the keyboard cursor has rested on the cell for delay (400ms by default), so sweeping across the grid mounts nothing. Focusing a cell shows the same tooltip after the same delay and the cell points at it with aria-describedby; the tooltip can be hovered without closing, and Escape dismisses it (WCAG 2.2 AA, 1.4.13). Escape is only consumed while a tooltip is open, so it still reaches the editor, the menu and the maximised view.

It closes on scroll. Rows and cells are pooled and re-used, so a tooltip left open across a scroll would be anchored to a node that is now showing a different row. Closing is the honest answer and costs nothing: the browser re-hit-tests after a scroll, so a pointer parked over the grid simply gets a fresh tooltip for the row that is actually there. Content is resolved when the tooltip opens rather than when the pointer arrived, so it always names the row that node is showing at the moment it opens.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  tooltip: { delay: 250, maxWidth: 360 }, // the defaults for every tooltip
  columns: [
    { field: 'name' },
    {
      field: 'owner',
      cell: {
        tooltip: {
          // Returned as a spec: the grid writes every field as text.
          render: (p) => ({ title: p.value, rows: [{ label: 'Row', value: p.key }] }),
        },
      },
    },
  ],
  rows: [{ name: 'a', owner: 'Ada' }],
  rowKey: 'name',
});

const defaults = grid.get('tooltip');
const spec = grid.columns.get('owner').cell.tooltip;
const content = spec.render({ value: 'Ada', key: 'a' });
grid.destroy();
return `${defaults.delay}, ${defaults.maxWidth}, ${content.title}, ${content.rows[0].value}`;

Grid methods

Top-level members. Everything else hangs off a namespace.

grid.rows

Data usually arrives after the grid does. Build it with rows: [], then load when your fetch resolves, the sort, filters, grouping and column layout you set up in the meantime all survive, and apply to the new data.

const grid = createGrid(el, { columns, rowKey: 'id', rows: [] });
grid.overlay.show('loading');

const data = await fetch('/api/circuits').then(r => r.json());
grid.rows.load(data);          // replaces whatever was there
grid.overlay.hide();

grid.columns

grid.selection

grid.filters

grid.sort

grid.edit

Appending and deleting rows. Over a remote source whose adapter declares mutate.append/mutate.delete, grid.edit.addRow and grid.edit.deleteRow are the structural counterparts of the cell edit path. An appended row shows at once under a client temp key; when the server hands back the real key the row is rekeyed everywhere the grid tracks it — the source row, selection, expansion, focus and any in-flight cell edits all follow — and row:confirmed fires. A delete tombstones the row immediately and either purges it on confirmation or restores it on refusal. The example drives both against a mock adapter, and shows the rekey moving a selection:

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createPushdownSource } = await import('../packages/core/src/source/pushdown.js');

// A mock adapter that persists append and delete. append returns the server key.
let nextId = 1;
const adapter = {
  name: 'mock',
  capabilities: { sort: true, mutate: { append: true, delete: true, returning: 'key' } },
  async execute() { return { rows: [], total: 0 }; },
  async mutate(op) {
    if (op.kind === 'append') return { ok: true, keys: [`srv-${nextId++}`] };
    return { ok: true };   // delete confirmed
  },
};

const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'name' }],
  source: createPushdownSource({ adapter, edit: true }),
  selection: 'multiple',
  edit: true,
});

// The structural lifecycle events, bridged onto the grid's own bus.
const fired = [];
grid.on('row:pending', (e) => fired.push(`pending:${e.kind}`));
grid.on('row:confirmed', (e) => fired.push(`confirmed:${e.kind}`));
grid.on('row:reverted', (e) => fired.push(`reverted:${e.kind}`));
grid.on('row:conflict', () => fired.push('conflict'));

// Append: shows immediately under a temp key, then rekeys to the server key.
const temp = grid.edit.addRow({ name: 'Ada' });
grid.selection.set([temp]);                  // select the optimistic row
await new Promise((r) => setTimeout(r, 0));   // let mutate resolve; row:confirmed fires
const movedTo = grid.selection.keys()[0];    // selection followed the rekey

// Delete: tombstones then confirms.
grid.edit.deleteRow(movedTo);
await new Promise((r) => setTimeout(r, 0));
const gone = grid.rows.byKey(movedTo) === undefined;

grid.destroy();
// fired: pending:append, confirmed:append, pending:delete, confirmed:delete
return `${movedTo} selected; ${gone ? 'deleted' : 'still-there'}`;

The built-in delete gesture. deleteRow above only fires beforeDelete on a remote source. For the common case — letting a user delete rows of a memory grid with the Delete key or a "Delete row" menu item, confirmed through the same beforeDelete hook — set config.rowDelete: true. It is off by default because deleting data on a keystroke is destructive; every deletion still flows through beforeDelete, so a handler can confirm or veto it with preventDefault(reason). grid.edit.deleteRows is the programmatic entry.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'id' }],
  rows: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
  rowKey: 'id',
  selection: 'multiple',
  rowDelete: true,   // opt in to the Delete-key / menu gesture and the API
});

// A confirm hook that vetoes deleting row 'b' but allows the rest.
grid.on('beforeDelete', (e) => { if (e.rows.includes('b')) e.preventDefault('kept'); });

grid.edit.deleteRows(['a']);   // allowed — 'a' is removed
grid.edit.deleteRows(['b']);   // vetoed — 'b' stays, delete:cancelled fires

const count = grid.rows.count();
grid.destroy();
return `${count} rows`;   // 2 rows: 'b' and 'c'

Previewing a bulk paste. A paste can rewrite dozens of cells at once, and one that lands somewhere unexpected looks exactly like one that worked. Set edit.pastePreview: true and a paste into more than one cell opens a confirm/cancel dialog first, listing every cell that changes (old → new) and every cell a commit would reject. It is off by default, so existing paste behaviour is unchanged. previewPaste computes that same diff without any UI:

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  // A per-row rule: the middle row is locked, so a paste over it is refused.
  columns: [{ field: 'a', edit: { enabled: (p) => p.row.data.locked !== true } }],
  rows: [
    { id: '0', a: 'A0', locked: false },
    { id: '1', a: 'A1', locked: true },
    { id: '2', a: 'A2', locked: false },
  ],
  rowKey: 'id',
  // Opt in: off by default, so a plain paste is unaffected.
  edit: { enabled: true, pastePreview: true },
});

// What *would* happen — nothing is committed yet.
const preview = grid.edit.previewPaste({ key: '0', colId: 'a' }, 'X\nY\nZ');

// Confirming is setCells of the changes — the ordinary paste path.
grid.edit.setCells(preview.changes.map((c) => ({ key: c.key, colId: c.colId, value: c.newValue })), 'paste');

const changed = preview.changes.filter((c) => c.changed).length;
return `${changed} change, ${preview.rejected.length} rejected`;   // rows 0 and 2 change; row 1 refused

grid.form

The row edit form, a drawer or dialog holding one control per field. Present whether or not rowForm is configured; without it every method declines rather than throwing, so a caller need not guard. See Editing a row on a form.

grid.pagination

A window over the rows the query already produced, not another query. A page change re-slices; it does not re-filter, re-sort or re-group, so paging a million rows costs nothing beyond the repaint.

grid.scroll

grid.export

grid.import

The mirror of grid.export: rows coming in from delimited text — a CSV or TSV file, or the tab-separated block a spreadsheet puts on the clipboard. The pipeline is parse, infer each column's type, map the columns onto the grid's own fields, then preview and confirm. The API is always present; set config.import to add the DOM affordances (a "Import rows from CSV…" cell-menu item, a file drop target, and paste).

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'age', type: 'integer' }],
  rows: [{ id: 'seed', age: 1 }],
  rowKey: 'id',
  // Opt in to the DOM affordances; the grid.import API is present either way.
  import: true,
});

// Preview changes nothing — it is what a confirm dialog shows.
const preview = grid.import.preview('id,age\nx,20\ny,30');

// Confirming appends the previewed rows; `age` arrives coerced to a number.
grid.import.apply(preview);

return `${preview.rowCount} previewed, ${grid.rows.count()} rows`;   // 2 previewed, 3 rows

grid.state

grid.history

Undo across the whole grid, not only edits. Sorts, filters, column moves, grouping, an applied view and a restore all record an entry, and each carries a label written for a button: "sort by Region", not "sort".

grid.diagnostics

What the grid is doing, as data: render counts and their causes, memory layout, operation and provider timing, event listener counts, effective configuration, and a list of things that look like mistakes.

This is the API; the devtools panel is a consumer of it. Built in that order deliberately: instrumentation shaped by a UI tends to report what is convenient to display rather than what is true, and an API that only exists behind a panel cannot be asserted against in a test.

// the assertion this exists to make possible
const before = grid.diagnostics.renders().dom.cellWrites;
grid.filters.set({ col: 'status', op: 'eq', value: 'active' });
await nextFrame();
const written = grid.diagnostics.renders().dom.cellWrites - before;
expect(written).toBeLessThan(200);

The support bundle

bundle() returns configuration, query state, timing history, warnings, provider statistics, version and environment. It never contains row data, cell values or column values, and says so in its own contains field. The guarantee is the point: a bundle that had to be read for confidential content before sending is a bundle nobody sends.

Warnings

Each carries a stable id a support conversation can name, a plain description, and the specific values involved. Two sources are merged: checks run against the grid, and everything the grid has reported through its own one-per-cause warnings.

The devtools panel

An optional module. It imports nothing (the grid is handed to it) so deployments that never load it pay nothing.

import { createGrid } from '@toclocoinc/lattice-grid';
import { createDevtools } from '@toclocoinc/lattice-grid/modules/devtools';

const grid = createGrid(el, config);
createDevtools({ grid });          // Ctrl+Shift+D collapses it

Nine tabs over the API above, a compact vitals strip to leave open while working, and a render heat overlay that tints cells as they are written: blue for a new value, red for a cell rewritten with the value it already held. The second colour is the one worth chasing: it is work the grid did not need to do, and no counter alone will tell you where it is.

grid.presence

Who else is on this grid and what they are doing: cursor, selection, active edit, and an optional advisory lock. It prevents the two failure modes of multi-user data work: two people editing the same cell unaware of each other, and one person unable to tell whether anyone else is there at all.

The grid never opens a connection. You supply the transport and the identity; the grid renders what arrives and publishes what changes. A WebSocket, MQTT, a CRDT library or a polling endpoint all satisfy the interface. Without a provider the feature is inert.

presence: {
  provider,                              // subscribe + publish
  me: { id: 'u_17', name: 'Tony' },
  throttleMs: 60,
  lock: true                             // advisory; see below
}

The provider

{
  subscribe(onMessage) { /* call onMessage(peer) or onMessage(peer[]) */ return unsubscribe; },
  publish(state)       { /* send it however you like */ }
}

A message is one peer state or an array of them, so a transport that sends a full roster on connect and deltas afterwards needs no unwrapping. { id, left: true } removes a peer.

Positions travel as row keys

Peers sort and filter independently, so a row index addresses a different record on every screen. Presence is positional in data terms: a peer's cursor renders wherever that row currently sits in your view, and is held but not drawn when the row is filtered out, on another page, or evicted from a bounded window. Those peers are counted by hiddenCount() and shown in the roster as “not in view”, so their absence does not read as a disconnection.

Idle and removal

Derived from local receipt time, never the timestamp in the payload. Clocks between clients disagree by seconds routinely, so a peer with a fast clock would look permanently fresh and one with a slow clock permanently idle. Silence past idleMs desaturates them; past removeMs they go. An explicit left signal is used when your transport provides one.

Locking is advisory

With lock: true, starting an edit on a cell a peer holds returns false from edit.start, emits presence:lockRefused, and announces the holder through a live region, a cell that silently refuses to enter edit mode is indistinguishable from a broken grid.

What is drawn

A peer's cursor is a dashed border in their colour; your own focus ring is solid, and the difference is in the kind of line rather than only the hue so the two can never be confused. Their name shows for a moment after their cursor moves and on hover, then fades to the bare border. A selection is a low-opacity tint, with the most recent peer winning a contested cell outright rather than blending. An active edit is solid and tinted, the loudest treatment, because it is the state that matters most.

Nothing is inserted into the grid: every treatment is written onto cells that already exist, so presence cannot shift layout, cover an in-cell chart, or intercept a click. The roster is the exception, because it is a control.

Colours are assigned by hashing the peer id against --lattice-peer-1 … --lattice-peer-8, so one person is the same colour on every screen and across reloads.

grid.comments

Threaded comments attached to individual cells, for collaborative data review: flagging an anomaly, asking why a figure changed, recording the reason behind a manual correction. A commented cell carries a small triangle in its upper-right corner; clicking the corner opens the thread.

The grid owns presentation and interaction only. Storage, identity and permissions are yours. Comment data lives wherever you put it and is reached through a provider.

comments: {
  provider,                        // required; without it the feature is inert
  mode: 'anchored',                // or 'docked' for a side panel
  markdown: false,                 // restricted: emphasis, code, links
  rowLabel: (row) => row.data.name  // so the panel says what is being discussed
}

The provider

Every method returns a promise. A rejection surfaces in the panel without disturbing grid state, and an optimistic write is rolled back.

Author information is rendered exactly as the provider supplies it: author: { name, avatarUrl, initials }. The grid does not know who the user is and does not guess.

Bodies are text. The default path never produces markup. With markdown: true the panel handles emphasis, code and links only, builds elements rather than assigning HTML, and refuses any link scheme other than http, https and mailto.

Comments follow their row through sorting and grouping. When a commented row is filtered out its comments are not lost and not shown; hiddenUnresolved() reports what is outstanding on hidden rows so their absence does not mislead, and the status bar’s comments panel puts that count on screen whenever it is not zero. Comments remain available while streaming, and a thread whose row is evicted by a bounded window closes with an explanation. Comments do not appear in exports and do not serialise into saved views, a view captures display configuration, not data.

Keyboard: Alt+M opens the thread on the focused cell. The panel traps focus while open and returns it to the originating cell on close. Cells carrying comments announce the fact, and the unresolved count, through their accessible description.

grid.facets

A distribution chart in each column heading, which is also a filter control. Clicking a bar filters to that bucket; dragging across bars on an ordered column filters to the range. As filters are applied, the other columns' charts recount, so a dataset can be explored by clicking through headings rather than opening a dialog.

Off by default. The band roughly doubles the header's height, which is a cost no grid should pay without being asked.

facets: { enabled: true }                // grid-wide

// per column, layered over the grid's settings
{ field: 'price', type: 'number', facet: { strategy: 'quantile', buckets: 16 } }
{ field: 'notes', facet: false }         // opt one column out

A column is never counted against its own filter. Every other active filter applies; that column's own conditions are pruned out. Without this, clicking a bucket would collapse the chart to that single bar, leaving no way to see what was excluded or to widen the selection.

The filters are ordinary filters. They go through filters.set, so they undo, ride in saved views, and appear in whatever filter UI you already have. A drag emits a between range rather than a set of bucket indices, so it still means something after the data is replaced and the edges move.

Live streams suppress charts. Buckets that move under the pointer are worse than no chart, the control lies about what clicking it will do. Filters already made stay applied, because they are ordinary filters. Pausing the stream brings the charts back; set whilePaused: false if you would rather it did not.

Server-side sources need a provider. It receives the column, the current filter state with that column's own conditions removed, and the bucketing settings, and returns counts. Results are cached against the filter state, but this is still one query per column per filter change, a grid with eight faceted columns will ask eight questions every time a filter moves, and the backend has to be able to absorb that.

Charts are keyboard operable: focus enters from the header, arrows move between buckets, Enter toggles, Shift with arrows extends a range on ordered columns, Escape clears. Each bucket carries its range and count as an accessible name, and the chart as a whole carries a one-sentence description of the distribution's shape, which is the part bar-by-bar labels cannot convey.

grid.updates

Control over an incoming feed: hold it, let it through, and see what the batching is actually saving you. Pausing does not drop anything: held changes keep merging, so a long pause costs one entry per changed row rather than one per update.

grid.updates.pause();                // hold the feed; it keeps arriving and merging
grid.updates.stats();                // { pending, queued, coalesced, flushes, ... }
grid.updates.flush();                // apply what is waiting, stay paused
grid.updates.resume();               // apply everything and go live again

coalesced is the number a batching strategy is actually bought with: rows that arrived more than once in a window and were written once. A feed where it stays at zero is not being coalesced, whatever the interval says.

The log is bounded two ways, because an entry is not a fixed size, one carrying a single changed cell and one carrying a fifty-thousand-row batch both count as one.

Applying changes

rows.apply(change) applies immediately and returns what happened; rows.queue(change) batches into the next flush and returns a promise. Both take the same shape: add, update, remove, and an optional at insert position.

An update is a patch, not a replacement. Fields absent from the update are untouched, so a delta from a websocket or a save response can be applied as it arrives without reading the row back first. Coalescing merges fields too: {price} and {volume} arriving as separate messages inside one window both survive.

grid.rows.apply({ update: [{ id: 'R1', price: 42 }] });
// every other field on R1 is left alone

Rows that cannot be applied are reported, not thrown. A batch of a thousand containing three bad rows applies the other 997 and lists the three.

const result = grid.rows.apply({ update: [ ... ] });
result.rejected;  // [{ operation, id, reason }]

stats() reports held against heldLimit: what the log is carrying now, against what it will carry. rows is a lifetime total of everything that ever arrived and says nothing about memory; these two do. Raise logRows for a deeper scrubber on a grid you have measured, and lower it on a feed of very wide rows.

grid.timeline

Moves the grid back through recent data changes: what a row held a minute ago, before the number moved. It reads the change log rather than the undo history: history records what you did, and on a live grid the question is what the data did.

Nothing is scrubbable until attach(). What a value used to be is not recoverable after the fact, and reading a row per key on every change is real cost on a busy feed, so recording is off until you ask for it and the window fills from that moment.

grid.timeline.attach();              // start recording; a scrubber appears
grid.timeline.seek(5);               // stand five changes back
grid.timeline.step(-1);              // one further back
grid.timeline.at();                  // the moment being shown
grid.timeline.toLive();              // return, applying everything stepped over
grid.timeline.detach();              // stop recording; the scrubber goes

Cells whose value moved during a seek are marked and stay marked until the next seek, in --lattice-timeline-changed. On a wide row the change you are hunting for is easy to scroll past, and a flash you can miss helps nobody. Marking compares rendered column values rather than raw fields, so a computed column that moved because its inputs moved is marked too. Chart columns redraw as you scrub, like any other cell.

grid.presentation

Enlarges the grid, drops the chrome and steps through saved views, for a screen share or a room. State only at this level: full screen and the pixels are the DOM layer's, so a headless grid can still be put into presentation state and asked about it.

grid.presentation.start({ scale: 1.5, views: ['q3', 'q4'] });
grid.presentation.step(1);                       // next view
grid.presentation.setSpotlight({ colIds: ['revenue'] });
grid.presentation.nudge(1);                      // a little larger
grid.presentation.stop();                        // or Esc

Enlargement is a CSS scale factor multiplied into the same tokens density uses, so text, rows, padding and controls grow together rather than the grid being zoomed as an image. Font size is damped against it: type that scaled linearly with a 2× row height reads as shouting.

grid.annotate

The drawing layer over the grid: pixels on a transparent canvas, never data. A presenter picks a tool (pen, arrow, rect, highlight) and draws; the layer is inert until one is chosen, so scrolling and selection pass straight through otherwise. Marks are stored in content coordinates, so a circle drawn round a cell stays on that cell as the grid scrolls and resizes rather than hanging over the viewport.

Marks can also be seeded and added without drawing (BACKLOG-0000813), which is what lets a host ship a pre-drawn callout or restore one from storage. A mark descriptor is { type, points, colour? } — type is freehand, arrow, rect, highlight or text (pen is accepted as an alias for freehand); points are {x, y} in content coordinates (a trail for freehand, the two endpoints for an arrow or rectangle, a single anchor for text). Seeded and added marks are durable: they survive a presentation ending, unlike a live-drawn mark, and they round-trip through getState and a saved view.

A text mark (BACKLOG-0000875) is a label anchored at one content point, carrying its text string and a basic style: colour, an optional fontSize in content pixels (default 14, scaled with a presentation), and an optional background colour drawn behind it. Like every mark it is held in content coordinates, so the label tracks the cell it annotates through scroll and resize.

// Seed a mark at construction — rendered on first paint, the way redaction seeds.
createGrid(el, {
  columns, rows,
  annotate: true,
  state: { annotations: [
    { type: 'arrow', points: [{ x: 40, y: 120 }, { x: 220, y: 80 }], colour: '#e0245e' },
    { type: 'text', text: 'Q3 spike', points: [{ x: 232, y: 72 }], colour: '#1a6bc7', background: '#fffbe6' },
  ] },
});

// Or add one durably at runtime — no synthesised pointer input.
grid.annotate.add({ type: 'rect', points: [{ x: 40, y: 100 }, { x: 260, y: 160 }] });
grid.annotate.add({ type: 'text', text: 'review', points: [{ x: 48, y: 108 }], fontSize: 16 });

// Persist and restore: seeded and added marks come back out of the state.
const marks = grid.getState().annotations;   // [{ type, points, colour }, …]
grid.state.apply({ annotations: marks });     // re-seed a fresh grid

grid.redaction

Obscures a column's values on screen while leaving the shape of the data (row count, sort, filters, layout) perfectly readable. Built for presenting and screen sharing. Right-click a column heading for Redact column.

This is not a security control. The values stay in the model, the DOM, the clipboard and every export; anyone with the page can read them from devtools or by turning off one CSS rule. It defeats a camera, which is the whole claim. For a value that must not reach the browser at all, use permissions with writeOnly.

grid.redaction.toggle('salary');     // returns the state it is now in
grid.redaction.add('salary');
grid.redaction.set(['salary', 'bonus']);
grid.redaction.list();               // ['salary', 'bonus']
grid.redaction.clear();              // back to normal when the call ends

The treatment is a CSS token, so a host can swap it: --lattice-redaction-filter defaults to blur(5px) contrast(0.85) and accepts anything the filter property does, including url(#your-svg-filter) for a mosaic.

grid.formatting

Conditional formatting rules the grid holds as runtime state, so an end user can change them. Rules travel in a saved view and undo like any other change. A scope is a column id, or '*' for every column; grid-wide rules are evaluated first, then the column's own, as one ordered list in which the first match wins.

This is distinct from compileRules() feeding cell.style, which compiles at configuration time and is what you want for rules a user should not be able to change. Both work at once: a runtime rule layers over whatever cell.style produced, winning only for the properties it names.

createGrid(el, {
  formatting: {                                   // optional seed
    margin: [{ when: { op: 'lt', value: 0 }, style: { background: '#fbeceb' } }],
  },
});

grid.formatting.add('margin', { when: { op: 'lt', value: 0 }, style: { background: 'red' } });
grid.formatting.add('*', { when: { op: 'blank' }, style: { background: '#f1f3f5' } });
grid.formatting.move('margin', ruleId, 0);        // order is meaning
grid.formatting.update('margin', ruleId, { enabled: false });
grid.formatting.remove('margin', ruleId);
grid.formatting.clear('margin');                  // or clear() for everything

Rules that describe the data, not a threshold

gt: 100 needs somebody to know that 100 is the interesting number. Often nobody does, the interesting cells are the top decile, or the outliers, and where those fall is a property of the data rather than of the rule. These operators say that directly, and the grid works out the threshold from the column itself, over the filtered rows.

grid.formatting.add('margin', { when: { op: 'outlier' }, style: { background: '#fbeceb' } });
grid.formatting.add('qty',    { when: { op: 'topPercent', value: 10 }, style: { bold: true } });
grid.formatting.add('score',  { scale: { from: 'quantile', colours: ['#f8f9fa', '#1a6bc7'] } });

grid.formatting.distribution('margin');   // { n, min, max, mean, stddev, median, q1, q3, iqr }
grid.formatting.restat();                 // re-derive every threshold from the data as it stands

A colour scale can take its bounds the same way, with from in place of min and max: 'minmax' spans the data, 'quantile' spans low to high (5th to 95th percentile by default), 'stddev' spans deviations either side of the mean. The quantile form is the better default on real data, one mistyped order of magnitude otherwise compresses every real value into the first swatch.

Data bars and icon sets as rules (BACKLOG-0000955)

A rule can carry a data bar or an icon set instead of a style or a scale, so the same declarative, view-persisted, headless rule list that already paints colour scales also paints proportional bars and per-band glyphs. Both compile to a plain style object — a data bar is a CSS gradient on the background, an icon set a background-image — so they need no extra element, compose with the cell's text, and resolve the same way for a server-side export as for a browser paint. This is the rule-engine sibling of the cell decoration below; reach for a rule when you want the visual to travel in a saved view and to derive its bounds from the column's distribution.

// A data bar spanning the data, and a three-arrow icon set split at the tertiles.
grid.formatting.add('revenue', { dataBar: { from: 'minmax', colour: '#5b9bd5' } });
grid.formatting.add('score',   { iconSet: { set: 'trafficLights' } });

// Bounds and bands can be pinned instead of derived; bars that straddle zero
// grow both ways from a shared axis, in their own colours.
grid.formatting.add('delta', { dataBar: { min: -100, max: 100, colour: '#2e7d32', negativeColour: '#c0392b' } });
grid.formatting.add('rank',  { iconSet: { set: 'arrows', thresholds: [10, 20], reverse: true } });

A data bar takes min/max to pin its scale, or from: 'minmax' | 'quantile' | 'stddev' to derive it from the column; colour and negativeColour fill the two sides of a zero axis, and direction: 'rtl' reverses it. An icon set names a built-in — the keys of ICON_SETS (arrows, trafficLights, ratings) — or supplies its own icons; thresholds place the band edges, or, given none, the column is cut into equal-count bands; reverse flips the order so a high value can read as red.

const { createHeadlessGrid, ICON_SETS } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'revenue', type: 'number' }, { field: 'score', type: 'number' }],
  rowKey: 'id',
  rows: [1, 2, 3, 4, 5].map((n) => ({ id: 'r' + n, revenue: n * 20, score: n })),
  formatting: {
    revenue: [{ dataBar: { from: 'minmax', colour: '#5b9bd5' } }],
    score: [{ iconSet: { set: 'trafficLights' } }],
  },
});

// A data bar compiles to a gradient the cell layer paints as a background.
const bar = grid.formatting.styleFor('revenue', 100).backgroundImage.includes('linear-gradient') ? 'bar' : 'none';

// An icon set resolves different bands to different glyphs.
const low = grid.formatting.styleFor('score', 1).backgroundImage;
const high = grid.formatting.styleFor('score', 5).backgroundImage;
const icon = low !== high ? 'icon' : 'flat';

const sets = Object.keys(ICON_SETS).length;   // the three built-in sets
grid.destroy();
return [bar, icon, sets].join('|');

Runtime decorations: data bars and icon sets on demand

Where a colour rule paints the cell's background, a decoration changes the shape the cell renders as, a data bar sized by value, or a threshold icon set. grid.columns.decorate(id, spec) turns one on, changes it, or clears it with null, after the grid is built. It is presentation config rather than query state: unlike a formatting rule it is not on the undo timeline and does not travel in a saved view. Icon sets carry an aria-label per band and keep the value beside the glyph, so the meaning is announced, never only shown.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'score' }, { field: 'trend' }],
  rows: [{ id: '1', score: 72, trend: 8 }],
  rowKey: 'id',
});

// A data bar, sized 0..100, set at runtime.
grid.columns.decorate('score', { type: 'bar', min: 0, max: 100 });
const bar = grid.columns.get('score').cell.decoration.type;

// A built-in three-arrow icon set on the trend column, with its own bands.
grid.columns.decorate('trend', { type: 'icon', bands: [
  { min: 0, icon: 'chevronUp', label: 'increasing', variant: 'success' },
  {         icon: 'chevronDown', label: 'decreasing', variant: 'danger' },
] });
const set = grid.columns.get('trend').cell.decoration.type === 'icon' ? 'arrows' : 'none';
const band = grid.columns.get('trend').cell.decoration.bands[0].label;

// Clearing a decoration returns the column to plain text.
grid.columns.decorate('score', null);
const cleared = grid.columns.get('score').cell.decoration === undefined ? 'cleared' : 'still-set';

// A runtime colour rule is the durable, view-persisted sibling.
grid.formatting.add('score', { when: { op: 'lt', value: 50 }, style: { background: '#fdecea' } });
const painted = grid.formatting.styleFor('score', 20) ? 'painted' : 'plain';

return [bar, set, band, cleared, painted].join('|');

grid.validation

Declarative column validation (BACKLOG-0000956). Where edit.validate is an imperative function you write, this is the same job said as data: required, min/max, minLength/maxLength, pattern, oneOf, and a crossField predicate, declared per column in validation. Each rule is checked against a new value before it is written, riding the cancellable beforeEdit before-event: a failing value cancels the commit so no cell is written, marks the cell with the grid's ordinary invalid state (an accessible error, not only a red border), and fires validation:failed. A corrected value clears the mark and, where you are watching, fires validation:cleared. The cancellation carries reason: 'validation:<code>', so a host logging cancellations can tell a validation veto from any other.

// Declared per column, config-time.
createGrid(el, {
  columns: [
    { field: 'name', edit: true, validation: { required: true, minLength: 2 } },
    { field: 'age',  type: 'number', edit: true, validation: { min: 0, max: 120 } },
    { field: 'code', edit: true, validation: { pattern: '^[A-Z]{3}$', messages: { pattern: 'Three capitals.' } } },
  ],
});

grid.validation.check('age', 200);          // { code: 'max', message: 'Must be at most 120.' } — records nothing
grid.validation.errorFor('r1', 'age');       // the recorded error for a cell, or null
grid.validation.errors();                    // every cell that currently holds an error
grid.validation.define('age', { min: 18 }); // set or replace a column's rules at runtime
grid.validation.clear('r1', 'age');          // drop a mark by hand

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const grid = createHeadlessGrid({
  columns: [{ field: 'id' }, { field: 'age', type: 'number', edit: true, validation: { min: 0, max: 120 } }],
  rowKey: 'id',
  rows: [{ id: 'r1', age: 30 }],
});

let failed = 0;
grid.on('validation:failed', () => { failed++; });
grid.on('validation:cleared', () => {});

// A user edit that breaks the rule is refused: the cell is not written.
grid.edit.start('r1', 'age'); grid.edit.stop(false, { value: 999 });
const blocked = grid.rows.byKey('r1').data.age;              // still 30
const why = grid.validation.errorFor('r1', 'age').code;      // 'max'

// A valid value writes through and clears the mark.
grid.edit.start('r1', 'age'); grid.edit.stop(false, { value: 40 });
const now = grid.rows.byKey('r1').data.age;                  // 40

grid.destroy();
return [blocked, why, now, failed].join('|');

grid.statistics

What the grid knows about its own numbers, and about how they have changed since the page loaded. Every figure is computed over the filtered rows, through the same column handles the totals row uses, so a median here and a median in the footer are the same number, by the same definition (R type 7).

grid.statistics.profile('margin');
// { column, rows, present, missing, distinct, min, max, mean, median,
//   q1, q3, iqr, stddev, outliers, histogram: [{ from, to, count }, …] }

grid.statistics.profile('region');   // a categorical column (BACKLOG-0000959)
// { column, rows, present, missing, distinct, …numeric figures null…,
//   histogram: [], topValues: [{ value, count, share }, …] }

grid.statistics.reduce('margin', 'p95');          // any registered kernel
grid.statistics.correlation('spend', 'revenue');  // Pearson's r, clamped to [-1, 1]
grid.statistics.weightedAverage('price', 'qty');

grid.statistics.covariance('spend', 'revenue');
grid.statistics.regression('spend', 'revenue');   // { slope, intercept, r2, stdError, n }
grid.statistics.spearman('spend', 'revenue');     // rank; one outlier cannot drag it
grid.statistics.kendall('spend', 'revenue');      // tau-b, null past 5,000 rows
grid.statistics.weightedQuantile('price', 'qty'); // the median by default

grid.statistics.series('price', { by: 'date', periodsPerYear: 252 });
// { volatility, annualisedVolatility, growth, maxDrawdown, maxDrawdownFrom,
//   maxDrawdownTo, autocorrelation, upDays, downDays, … }

grid.statistics.capability('mm', { baseline: 20 });
// { cp, cpk, pp, ppk, sigmaWithin, sigmaOverall, outOfSpec, defectRate,
//   limits: { centre, upper, lower, sigma }, violations: [{ index, rule }] }

grid.statistics.shadow('price', 'delta', 'R42');  // one row's shadow value
grid.statistics.rebase('price');                  // "mark all": today's values become the baseline
grid.statistics.tracking();                       // { columns, rows, forgotten }

The statistics tool panel is the end-user half of profile(): a column picker, the twelve figures and a histogram of the column's shape, all following the filters. Add it with toolPanel: { panels: ['columns', 'statistics'] }. It profiles categorical columns too (BACKLOG-0000959): a text column shows its count, distinct count and Top values (each value with its count and share) instead of the numeric figures and the histogram it has none of.

The column header menu carries a Column statistics item that opens this panel seeded on the column it belongs to. It emits column:profile:open with { colId } rather than reaching into the dock, exactly as the header filter affordance emits column:filter:open; a mounted tool panel turns that into the open, seeded statistics panel.

The regression tool panel is its multi-column sibling (BACKLOG-0000812): it fits the model you name and shows the coefficient table — each term's estimate ± standard error with its t and p — alongside R² and adjusted R², the variance-inflation factor per predictor, and the Breusch–Pagan heteroscedasticity flag, all over the filtered rows and computed by the one core engine (grid.statistics.regressionModel). Name the model on the panel: toolPanel: { panels: ['columns', { name: 'regression', props: { predictors: ['x1', 'x2'], response: 'y' } }] }. p-values are reported as numbers with a documented method, never a significance verdict.

The same fitted model can live in the data as shadow columns (BACKLOG-0000812): shadow: { kind: 'fitPredicted', model: { predictors: ['x'], response: 'y' } }, and likewise fitResidual and fitInfluence — plus fitStdResidual, fitLeverage and fitCooksD (BACKLOG-0000872), which surface the internally studentised residual, the hat-matrix leverage and Cook's distance the engine already computes. They are ordinary numeric/boolean cells — sortable, filterable, groupable, exportable — that read the fit by row key and follow the grid's filters (the model refits over the filtered rows); a row outside the fit reads null. fitInfluence flags Cook's D > 4/n by default (overridable with threshold), keeping "not influential" (false) and "cannot tell" (null) distinct.

It shows the twelve one-pass figures, then Shape (skewness, kurtosis, Jarque–Bera), Robust (trimmed and winsorized means, MAD, robust outliers), Concentration (Gini, HHI, entropy, evenness, top-3 share) and Capability where the column declares a spec. A section whose reductions all return null is left out rather than shown as a column of dashes.

Or put it in your own page. mountPanel takes no dock and does not create one: toolPanel may be off entirely, so a statistics readout can sit beside a chart, in your own sidebar, or in a settings dialog, at whatever size you give it. It repaints on the same events the rail does, so it stays in step with filters, edits and saved views without you subscribing to anything.

import { mountPanel } from '@toclocoinc/lattice-grid';

const stats = mountPanel({ grid, panel: 'statistics', container: sidebar });
stats.refresh();   // for a change the grid does not announce
stats.destroy();   // yours to call: the element belongs to your page

Any built-in panel works: columns, filters, views, quick, formatting, statistics, regression, compare, insights, as does a constructor of your own.

The insights panel

The insights tool panel is the on-screen half of the comparison analytics (§9.9): the API-only subsetVsPopulation(), datasetVsDataset(), capability() and compareGroups() rendered without you building any UI. It is opt-in — off unless you name it. Add it with toolPanel: { panels: ['columns', 'insights'] }.

It shows four things, all over the filtered rows: the columns of the current filtered subset ranked by effect size against the whole; the same ranking against a second grid when you pass one as toolPanel: { panels: ['insights'], /* config */ } with insights: { compareWith: otherGrid }; process capability for the chosen column where it declares a spec; and a two-group comparison — pick a column and a column to group by, and the panel shows the named test, its confidence interval and its effect size together.

The stance is enforced on screen. The effect size is never shown without its interval beside it; the test or method that produced a figure is always named, from the API's own method string; and nothing renders a significant flag, a verdict, a badge or a star — the p-value is shown as the plain datum it is, when it is shown at all. The panel adds no statistic of its own: every number it shows is the one grid.statistics returns.

createGrid(el, { toolPanel: { panels: ['columns', 'insights'] } });

// with a second dataset to rank this grid against:
createGrid(el, {
  toolPanel: { panels: ['insights'] },
  insights: { compareWith: otherGrid },
});

The reductions

Forty-one, all available to a totals row, to reduce() and to the profiling panel. Names are the same everywhere and the labels come from the message catalogue, so a grid in Polish reads in Polish.

Process capability

Declare the customer's tolerance on the column, and the capability figures, a control chart and any rule marking an out-of-tolerance cell all read the same limits.

columns: [{ field: 'mm', type: 'number', spec: { lower: 9.5, upper: 10.8, target: 10 } }]

Cp and Cpk use short-term variation, estimated from the moving range; Pp and Ppk use the overall standard deviation. The gap between them is the point: Cpk well above Ppk means the process drifted. Cp above Cpk means it is precise and aimed wrong, which needs a different fix from being too variable.

Seeing it

The statistics have chart types to match, in modules/charts. Each takes its numbers from this namespace rather than recomputing, so a coefficient in a matrix and the same one from the API cannot drift apart.

Values the grid maintains for you

Three of the ideas in this section are not standard grid vocabulary, so it is worth saying what they have in common before the detail. Each of them is a value the grid keeps up to date from data you already have, declared once rather than maintained by hand.

The alternative, in every application that needs one of these, is a parallel structure in the host: a copy of what each row looked like a moment ago, a rank recomputed on every tick, a cumulative total that has to be redone whenever the sort changes, and a dashboard panel running its own query beside the table. That code works for a while and then produces a number nobody can account for, usually because one part of it noticed a filter and another did not.

The line between a shadow and a running column is the sort order. A shadow is a function of the column: a row’s own history, or where its value sits among the others. Sort the grid differently and a rank is still the same rank. A running total is the opposite : it answers “how much by the time we reach this row”, and by the time is the order the rows are in, so re-sorting changes every value in the column. That is why they are declared separately rather than as two kinds of one thing.

A derived grid is a different scale of the same idea. A shadow adds a column to the rows you have; a derivation produces different rows altogether: one per sales person rather than one per sale. Because it is a source rather than a special kind of grid, the result sorts, filters, totals, themes and exports like any other, and can itself be the source of another.

All three read the rows the grid is currently showing, so a filter applied to the table moves the ranks, the running totals and every derived panel together. That is the property worth having: not that any one of them is clever, but that they cannot disagree.

Shadow columns

A shadow column is declared against another column and maintained by the grid. It has no field in the data and it is not a pure computed column either, because its value depends on what happened before. It is a real column throughout: sortable, filterable, totalled, grouped, exported, saved into a view, which is what makes "show me every circuit repriced more than twice this session, most-changed first" one gesture rather than a report.

columns: [
  { field: 'price', type: 'number' },
  { id: 'moved',  title: 'Change',  shadow: { of: 'price', kind: 'delta' } },
  { id: 'churn',  title: 'Updates', shadow: { of: 'price', kind: 'updates' } },
  { id: 'run',    title: 'Streak',  shadow: 'streak' },   // shorthand: shadows the column beside it
]

A second family answers where the row sits among the others rather than what it did before. They share the same declaration and the same state, the tracker already holds every row's current value and its baseline, which is exactly what a rank and a rank change need.

Running totals

A running column answers “how much by the time we reach this row”: a balance that accumulates down the page, or the share of the total accounted for so far. It is the column a Pareto chart is made of, and the one a finance report opens with.

It is declared separately from a shadow column, and the sort order is the reason. Every shadow is a function of the column (of a row's own history, or of where its value sits among the others) so it reads the same however the rows are arranged. A running total does not: sort the grid differently and every value changes, because the question is "how much by the time we reach this row", and by the time is the sort order.

columns: [
  { field: 'amount', type: 'number' },
  { id: 'cum',   title: 'Running',      running: { of: 'amount', kind: 'total' } },
  { id: 'share', title: 'Cumulative %', running: { of: 'amount', kind: 'percent' } },
]

Computed in one pass over the display rows and cached against that ordering, so a hundred thousand rows are walked once per sort rather than once per cell. A running column is not sortable. Sorting on one asks the sort to depend on its own output (the value is defined by the display order) so the column does not offer a sort unless its definition asks for one, and the query layer refuses such a sort with a warning rather than computing it. Sort by the column it runs over instead. Group headings and totals rows are skipped, a running total that counted a subtotal would double everything below it, and a row with no value carries the figure forward unchanged rather than resetting it.

History has two clocks: a count of changes, or a span of time (BACKLOG-0001043)

Plain history (above) is an event series: it records a reading only when the value changes, so a row that sits still never advances it. Bound to a cell.render sparkline ('line', 'area', 'column', 'winloss') that means a static row's sparkline freezes, then jumps when a change finally lands — while a title like "last 60s" keeps claiming a span the column never measured. Add a time window to make it a real time series instead:

{ id: 'spark', title: 'Last 60s', shadow: { of: 'price', kind: 'history', window: { kind: 'time', span: 60_000 }, depth: 20 } }

This is the same window: { kind, span } shape the rolling kinds below already accept — not a second spelling of it — and it changes what history means rather than adding a new kind: depth (20 here) is now how many buckets the span divides into, so this is sixty seconds as twenty three-second buckets. Each bucket is sampled once, at its close, as the row's last known value at that moment — carried forward from the previous bucket when nothing changed in between. A static row therefore draws a flat line that keeps advancing, one sample per bucket, and a change lands in the bucket it actually happened in rather than being appended at the end. The bucket clock runs on its own low-frequency timer (never a render loop), so the series keeps moving even while no data event ever reaches the column. window: { kind: 'count' } and { kind: 'session' } are refused for history — a plain count is already what depth means without a window, and a session has no fixed span to divide into buckets — and a caller who never sets window gets the original count-based behaviour, unchanged.

Rolling time-series columns

A total answers "how much"; a rolling total answers "how much lately, as the series ran" — the seven-day average that smooths a daily figure, the trailing sum, the change on the period before. These are rolling shadow kinds (BACKLOG-0000748): real columns, sortable and filterable and exportable like any other, computed in one ordered pass and cached by row key. They compose the windowed-aggregate model the grid already uses for "the average lately" over a live stream, asked instead over a column arranged in a stated order.

The order is explicit and required — an orderBy column, never the screen sort, because a rolling figure defined by the current sort would change on every header click and a column sorted on its own rolling value would define itself. The window is the last span rows (count), the last span of the order axis (time), or the whole series so far (session). The first rows carry a partial window; that figure is still emitted, but a windowCoverage companion stamps how much of the window it actually covers, so a two-day average is never shown as a seven-day one. within chooses per-group (the default, partitioned by the grid's grouping) or across the whole dataset.

A rollingQuantile (a trailing median, a p95, set by q) is exact while the window is small and comes from a KLL sketch past an internal span cap and for a session window — where a windowApproximate companion reports which rows are approximate, so a sketched quantile is never presented as exact. At a million rows the single ordered pass stays well within the suite's budget (≈380ms for the window aggregates, ≈490ms for the exact rolling median, ≈420ms for the session sketch on the reference bench).

columns: [
  { field: 'day',  type: 'date' },
  { field: 'sales', type: 'number' },
  { id: 'ma7',   title: '7-day avg', shadow: { kind: 'rollingAvg', of: 'sales', orderBy: 'day', window: { kind: 'count', span: 7 } } },
  { id: 'cover', title: 'Coverage',  shadow: { kind: 'windowCoverage', of: 'sales', orderBy: 'day', window: { kind: 'count', span: 7 } } },
  { id: 'p50',   title: '30-day median', shadow: { kind: 'rollingQuantile', of: 'sales', orderBy: 'day', window: { kind: 'count', span: 30 }, q: 0.5 } },
  { id: 'ytd',   title: 'Cumulative', shadow: { kind: 'cumulativeToDate', of: 'sales', orderBy: 'day' } },
  { id: 'delta', title: 'vs prev',   shadow: { kind: 'periodOverPeriod', of: 'sales', orderBy: 'day' } },
]

A rolling window is a property of the series, so it is computed over every row before any filter: hiding rows with a filter narrows what you see, never what "the last seven" means. A missing reading is a gap, skipped rather than treated as a zero that would report a plunge and a rebound the series never made.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
// A short series, ordered by t: values 2,4,5,4,5.
const base = { of: 'v', orderBy: 't', within: 'all' };
const win = { kind: 'count', span: 3 };
const grid = createHeadlessGrid({
  columns: [
    { field: 't', type: 'number' },
    { field: 'v', type: 'number' },
    { id: 'sum', shadow: { kind: 'rollingSum', window: win, ...base } },
    { id: 'avg', shadow: { kind: 'rollingAvg', window: win, ...base } },
    { id: 'cov', shadow: { kind: 'windowCoverage', window: win, ...base } },
    { id: 'med', shadow: { kind: 'rollingQuantile', window: win, q: 0.5, ...base } },
    { id: 'cum', shadow: { kind: 'cumulativeToDate', ...base } },
    { id: 'pop', shadow: { kind: 'periodOverPeriod', ...base } },
  ],
  rows: [
    { id: 'r1', t: 1, v: 2 }, { id: 'r2', t: 2, v: 4 }, { id: 'r3', t: 3, v: 5 },
    { id: 'r4', t: 4, v: 4 }, { id: 'r5', t: 5, v: 5 },
  ],
  rowKey: 'id',
});
const round4 = (x) => Math.round(x * 10000) / 10000;
const round2 = (x) => Math.round(x * 100) / 100;
return [
  grid.rows.value('r3', 'sum'),          // 2+4+5 = 11
  round4(grid.rows.value('r3', 'avg')),  // 11/3
  round4(grid.rows.value('r5', 'avg')),  // (5+4+5)/3
  round2(grid.rows.value('r1', 'cov')),  // 1/3 of the window filled
  grid.rows.value('r5', 'cum'),          // running total to the end
  grid.rows.value('r2', 'pop'),          // 4 - 2
  grid.rows.value('r3', 'med'),          // median of 2,4,5 = 4
].join('|');

Seasonal decomposition

Splitting a series into trend + seasonal + residual (BACKLOG-0000873) answers "what's the underlying trend with the weekly pattern removed?". It is classical decomposition — the same algorithm statsmodels.seasonal_decompose uses, verified against it in the reference suite — delivered as four shadow columns over the same ordered pass: tsTrend (a centred moving average), tsSeasonal (the repeating index), tsResidual (what the two leave behind), and tsCoverage.

The period is caller-declared and required — 7 for a weekly cycle in daily data, 12 for a monthly cycle in monthly data; there is no auto-detection in v1. The model is additive by default; decomposition: 'multiplicative' is a declared option that is undefined on a non-positive series (those rows report null, with a warning). The centred window runs off the ends, so the leading and trailing rows have no trend — they are partial edges, reported as null and stamped tsCoverage: 0 rather than emitted as if full.

columns: [
  { field: 'day',  type: 'date' },
  { field: 'sales', type: 'number' },
  { id: 'trend',  title: 'Trend',    shadow: { kind: 'tsTrend',    of: 'sales', orderBy: 'day', period: 7 } },
  { id: 'season', title: 'Weekly',   shadow: { kind: 'tsSeasonal', of: 'sales', orderBy: 'day', period: 7 } },
  { id: 'resid',  title: 'Residual', shadow: { kind: 'tsResidual', of: 'sales', orderBy: 'day', period: 7 } },
  { id: 'cover',  title: 'Coverage', shadow: { kind: 'tsCoverage', of: 'sales', orderBy: 'day', period: 7 } },
]

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
// A period-4 series: trend 10+i plus a season [2,-1,0,-1], so value = trend + season.
const season = [2, -1, 0, -1];
const base = { of: 'v', orderBy: 't', within: 'all', period: 4 };
const grid = createHeadlessGrid({
  columns: [
    { field: 't', type: 'number' },
    { field: 'v', type: 'number' },
    { id: 'trend',  shadow: { kind: 'tsTrend', ...base } },
    { id: 'season', shadow: { kind: 'tsSeasonal', ...base } },
    { id: 'resid',  shadow: { kind: 'tsResidual', ...base } },
    { id: 'cover',  shadow: { kind: 'tsCoverage', ...base } },
  ],
  rows: Array.from({ length: 8 }, (unused, i) => ({ id: String(i), t: i, v: (10 + i) + season[i % 4] })),
  rowKey: 'id',
});
return [
  grid.rows.value('4', 'trend'),   // centred MA recovers the trend: 14
  grid.rows.value('4', 'season'),  // the phase-0 seasonal index: 2
  grid.rows.value('4', 'resid'),   // nothing left over: 0
  grid.rows.value('4', 'cover'),   // interior row: full, 1
  grid.rows.value('0', 'trend') === null ? 'null' : 'x',  // partial edge: null, not invented
  grid.rows.value('0', 'cover'),   // edge stamped partial: 0
].join('|');

Exponential smoothing

Smoothing pulls the signal out of a noisy series (BACKLOG-0000873). tsSmoothed is the fitted level — not a forecast of the future — from single exponential smoothing (smoothing: 'ses', the default) or Holt's level+trend (smoothing: 'holt'). The recursion matches statsmodels and is verified against it in the reference suite. Holt-Winters (seasonal) smoothing is deferred; seasonality is covered by decomposition above.

The smoothing factor is either caller-set (alpha, and beta for Holt) or fit by minimising the in-sample SSE when omitted — and the chosen value is reported, not hidden, by the tsSmoothingAlpha / tsSmoothingBeta companion columns.

columns: [
  { field: 'day',   type: 'date' },
  { field: 'sales', type: 'number' },
  { id: 'level', title: 'Smoothed', shadow: { kind: 'tsSmoothed',       of: 'sales', orderBy: 'day', smoothing: 'holt' } },
  { id: 'a',     title: 'α',        shadow: { kind: 'tsSmoothingAlpha', of: 'sales', orderBy: 'day', smoothing: 'holt' } },
  { id: 'b',     title: 'β',        shadow: { kind: 'tsSmoothingBeta',  of: 'sales', orderBy: 'day', smoothing: 'holt' } },
]

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
// SES at alpha 0.5 over 4,8,6,10: level runs 4, 6, 6, 8.
const base = { of: 'v', orderBy: 't', within: 'all', smoothing: 'ses', alpha: 0.5 };
const grid = createHeadlessGrid({
  columns: [
    { field: 't', type: 'number' },
    { field: 'v', type: 'number' },
    { id: 'sm', shadow: { kind: 'tsSmoothed', ...base } },
    { id: 'a',  shadow: { kind: 'tsSmoothingAlpha', ...base } },
  ],
  rows: [4, 8, 6, 10].map((v, i) => ({ id: String(i), t: i, v })),
  rowKey: 'id',
});
return [
  grid.rows.value('1', 'sm'),   // 0.5*8 + 0.5*4 = 6
  grid.rows.value('3', 'sm'),   // 0.5*10 + 0.5*6 = 8
  grid.rows.value('0', 'a'),    // the factor used, reported: 0.5
].join('|');

Stationarity (ADF)

Before you compare two series or detrend one, it helps to know whether it is stationary — reverting to a level or trend — or wandering with a unit root. grid.statistics.adf runs the Augmented Dickey-Fuller test (BACKLOG-0000873) and returns a scalar readout, not a per-row column: the statistic, the augmenting lag chosen by AIC, MacKinnon's critical values, an interpolated p-value (stamped approximate), and a plain-language verdict at the 5% level. The constant+trend regression and the AIC lag choice match statsmodels' adfuller, against which the statistic and lag are verified.

The lag search and what it costs. maxlag caps the number of augmenting lags the AIC search considers; left out, it is the Schwert rule ⌈12·(n/100)^0.25⌉ — 34 candidates on 7,000 rows — itself capped so the fixed sample keeps degrees of freedom. The candidates are nested, so the search builds one design matrix at the cap and reads every smaller candidate off it — one pass to accumulate the normal equations, then a small solve and a single residual pass per candidate, rather than a fresh fit each time (BACKLOG-0001347). The default search over 7,000 rows is a matter of milliseconds. Setting maxlag narrows the search, never the arithmetic: the lag chosen, the statistic and the p-value are whatever the data says, and a cap that still contains the AIC-preferred lag returns exactly the same readout.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
// A random walk (a unit root): it wanders rather than reverting.
const walk = [0.138, -0.725, -1.26, -0.536, -0.267, 0.167, -0.765, -0.146, -0.311, -0.586,
  0.376, -0.41, 0.282, 0.865, -0.024, 0.149, -0.2, -0.654, -1.338, -1.917, -1.832, -1.333,
  -0.492, -1.259, -1.89, -2.145, -2.146, -1.297, -1.26, -0.716, -0.846, -1.206, -2.126,
  -1.724, -0.945, -1.599, -1.316, -0.413, 0.304, 0.732, -0.257, 0.086, -0.572, -0.501,
  -1.153, -1.186, -1.455, -1.607];
const grid = createHeadlessGrid({
  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }],
  rows: walk.map((v, i) => ({ id: String(i), t: i, v })),
  rowKey: 'id',
});
const adf = grid.statistics.adf({ of: 'v', orderBy: 't' });
return [adf.verdict, adf.usedLag].join('|');   // non-stationary, 0 lags

Autocorrelation (ACF / PACF)

grid.statistics.acf shows how far back a series depends on itself (BACKLOG-0000873): the autocorrelation (ACF) and partial autocorrelation (PACF) arrays out to a maximum lag, each with the approximate ±1.96/√n white-noise band (stamped approximate) — a lag whose bar clears the band is evidence of real dependence. The estimators are the biased ACF and the Yule-Walker (Levinson-Durbin) PACF, matching statsmodels, verified in the reference suite. Lag 1 is the single source of truth: acf[1] is the same number statistics.series(...).autocorrelation reports, and pacf[1] === acf[1].

The correlogram is the arrays fed to a bar chart over explicit points, with the band as reference lines — reusing the existing chart primitives:

const { acf, bounds } = grid.statistics.acf({ of: 'sales', orderBy: 'day', maxlag: 20 });
createChart({
  grid, container: '#acf', type: 'bar',
  points: acf.map((v, lag) => ({ x: lag, y: v })),
  reference: [{ value: bounds.upper }, { value: bounds.lower }, { value: 0 }],
});

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
// A deterministic AR(1): each reading leans 0.6 on the one before.
let s = 5; const rand = () => { s = (Math.imul(s, 1664525) + 1013904223) >>> 0; return s / 4294967296 - 0.5; };
const y = []; let prev = 0;
for (let i = 0; i < 200; i++) { const v = 0.6 * prev + rand(); y.push(v); prev = v; }
const grid = createHeadlessGrid({
  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }],
  rows: y.map((v, i) => ({ id: String(i), t: i, v })),
  rowKey: 'id',
});
const res = grid.statistics.acf({ of: 'v', orderBy: 't', maxlag: 6 });
const series = grid.statistics.series('v', { by: 't' });
return [
  res.acf[0],                                    // lag 0 is always 1
  res.pacf[1] === res.acf[1],                    // the first partial equals the first acf
  Math.abs(res.acf[1] - series.autocorrelation) < 1e-9,  // lag 1 is the single source of truth
].join('|');

grid.highlight

One mechanism for two jobs: the flash a changed cell makes, and a marker you paint deliberately. A target is a cell ({key, colId}), a row ({key}, or a bare row key) or a column ({colId}). Cell beats row beats column, so a specific highlight is never hidden by a broad one laid over it.

createGrid(el, {
  highlightOnChange: { colour: '#ffe08a', duration: 1200 },   // or just true
});

grid.highlight({ key: 'r1', colId: 'cap' }, { colour: 'green', duration: 800 });
grid.highlight({ key: 'r3' }, { colour: '#fdeaea', duration: 0 });   // 0 = until cleared
grid.highlight({ colId: 'margin' }, { colour: '#e7f1fd', duration: 0 });
grid.highlight.clear({ key: 'r3' });
grid.highlight.clear();                                             // everything

grid.views

Named states the user can return to. Views supplied in config.views.saved are defined views: listed apart in the picker, and neither renamable nor deletable, refused by the model as well as hidden in the interface. Views the user saves are their own and carry rename, share, default and delete.

createGrid(el, {
  views: {
    saved: [{ id: 'escalations', name: 'Escalations', description: 'Worst SLA first',
              state: { filters: { col: 'statusId', op: 'eq', value: 4 },
                       sort: [{ col: 'utilisation', dir: 'desc' }] } }],
    allowSave: true,   // false removes the save form entirely
    local: true,       // saved views live in this browser's localStorage, no backend
    // storage: { read, write }, // or bring your own backend; see the note below
  },
});

grid.diff

Audit mode. Give it a prior snapshot and every row reports whether it was added, removed or changed, and which cells moved.

Built-in renderers and editors

Both are addressable by name. Anything you register through components is addressable the same way, and a name you register wins over a built-in one.

Cell renderers, for cell.render:

Editors, for edit.editor. Each column type already selects a sensible one, so naming an editor is for overriding that choice:

grid.permissions

Four levels per column, resolved from configuration or a callback. They are the four corners of read × write rather than a ladder:

permissions: 'read'                                  // blanket
permissions: { salary: 'read', ssn: 'hidden' }       // map; '*' sets the default
permissions: (column, ctx) => ctx.context.role === 'admin' ? 'write' : 'read'
permissions: { default: 'read', columns: { name: 'write' }, resolve }

grid.permissions.setContext({ role: 'clerk' });      // re-resolves everything

grid.ai

The grid composes a prompt describing its own columns and operators, you send it to whichever model you like, and it validates the reply before anything is applied. It makes no network call and has no default model.

Ask-your-data (modules/ai)

The opt-in AI module (createAI, UMD LatticeGridAI) turns a question into a validated read-only query spec, runs it in the grid's own engine over the grid.ai skill layer, and — on apply — fans the answer to any router-attached viewers (a chart, a KPI tile) through the Data Router's load(). It uses the same BYO ask() seam as the rest of the module: the grid makes no model call and holds no key. Ask-your-data is read-only; a write/mutation the model asks for is refused and never executed (writes are a separate, human-gated feature).

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');
const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'region' }, { field: 'amount', type: 'number' }],
  rows: [{ id: 1, region: 'EMEA', amount: 100 }, { id: 2, region: 'AMER', amount: 300 }, { id: 3, region: 'EMEA', amount: 200 }],
});
// Your model returns a schema-constrained SPEC, never rows. WE run it, read-only.
const reads = createAI(grid, { ask: async () => ({ actions: [{ type: 'setFilters', filters: { col: 'region', op: 'eq', value: 'EMEA' } }] }) });
const result = await reads.query('EMEA only');
result.apply();
const rows = grid.rows.data().length;
// A write verb is refused by the read-only gate and never executed.
const writes = createAI(grid, { ask: async () => ({ actions: [{ type: 'setCells', edits: [] }] }) });
const write = await writes.query('change the data');
return `${rows} rows; write ${write.ok ? 'allowed' : 'refused'}`;

AI as a governed actor (modules/ai, writes)

The governed actor lets the model propose edits — a single NL-targeted change (“set the Network Upgrade project to In Progress”) or a bulk cleanup — that a human previews as a before/after diff and approves. The model NEVER writes. On approval the edit applies through the grid's own gate, exactly like a person's edit: a grid cell edit via grid.edit.setCells(writes, 'cell', { origin: 'ai' }) (the beforeEdit veto), a Kanban card move via board.move(…, { origin: 'ai' }) (the beforeMove veto). The AI can never bypass the gate: a host beforeEdit/beforeMove handler that calls preventDefault() (or vetoes async) stops the write, and nothing persists. Writes carry origin: 'ai' on the before-event payload, so a host can allow a person's edit while vetoing the AI's — policing AI writes distinctly. Approved edits are optimistic and revert on a source reject through the shipped write-back (there is no separate beforeCommit event; the edit gate is beforeEdit, and the optimistic/revert half is grid.edit.settle).

NL targeting and any bulk edit bind to the current filtered view (grid.rows.data()), never the whole table implicitly; a target not in the view is surfaced for an explicit opt-in widen, not edited silently. A human label is resolved to the column's stored option value; an unknown label is rejected, not coerced. An ambiguous match (more than one row) surfaces its candidates for the user to pick.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');
const status = { options: [{ id: 'todo', label: 'To do' }, { id: 'doing', label: 'In Progress' }] };
const seed = () => createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'name' }, { field: 'status', lookup: status, edit: { enabled: true } }],
  rows: [{ id: 'r1', name: 'Network Upgrade', status: 'todo' }, { id: 'r2', name: 'Payroll', status: 'todo' }],
});
// A MOCK ask() returns a structured PROPOSAL — never a write, never rows.
const ask = async () => ({ structured: { edits: [{ match: 'Network Upgrade', column: 'status', value: 'In Progress' }] } });

// Propose: a before/after diff, nothing written yet.
let grid = seed();
let ai = createAI(grid, { ask });
const proposal = await ai.propose('set the Network Upgrade project to In Progress');
const d = proposal.diff[0];
const before = `${d.oldDisplay} then ${d.newDisplay}`;

// A vetoing beforeEdit handler on the AI write => NOTHING persists.
grid.on('beforeEdit', (e) => { if (e.origin === 'ai') e.preventDefault('reviewed elsewhere'); });
await ai.applyProposal(proposal);
const vetoed = grid.rows.byKey('r1').data.status;

// Approve on a grid with no veto => the edit lands through the gate.
grid = seed();
ai = createAI(grid, { ask });
await ai.applyProposal(await ai.propose('set the Network Upgrade project to In Progress'));
const approved = grid.rows.byKey('r1').data.status;

return `diff ${before}; vetoed kept ${vetoed}; approved wrote ${approved}`;

grid.overlay

grid.maximise

Fills the browser window with the grid, and puts it back. The rail's last button is this; grid.maximise is the same thing, so an application can bind its own control or keyboard shortcut. Esc restores.

grid.maximise.toggle();     // what the rail button calls
grid.maximise.enter();
grid.maximise.active();     // true while it fills the window
grid.maximise.exit();

grid.licence

There is one Lattice Grid and every copy is feature-identical. No community edition, no pro tier, no feature held back behind a key. A licence removes the trial watermark; that is the whole of what it does.

Free to develop against, licensed to deploy. A grid on localhost, or any loopback host: needs no key at all. On any other domain an unlicensed grid still renders everything and carries a small trial watermark linking to latticegrid.dev. Nothing ever refuses to render: the failure worth avoiding is a broken production screen, and no licensing state is worth causing one.

// Before creating a grid.
LatticeGrid.setLicence('LG1.…');           // your key; setLicense also works

const grid = LatticeGrid.createGrid(el, config);
grid.licence.state();      // 'licensed' | 'localhost' | 'trial'

Domains

A key names the hosts it covers. *.acme.com matches app.acme.com, a.b.acme.com and acme.com itself, a wildcard that refused the apex would be a puzzle rather than a licence. A bare acme.com matches only itself, and a key naming no domains is valid anywhere. Matching ignores case and a trailing dot.

Getting a key

Keys are issued from latticegrid.dev. A key is issued per deployment rather than per developer or per seat: name the domains the grid will run on and one key covers every developer, every build and every user on them.

Keys are perpetual by default. A key carries no expiry unless one was deliberately issued (a trial, a time-boxed pilot) so the ordinary key is valid until the domains it names change, not one that quietly lapses on a date nobody is tracking.

Checking a key needs no network. There is no licence server, no call home, and nothing that can fail at three in the morning, a key carries its own answer and the grid reads it locally, fresh on every load. A key for the wrong domain, or a key that will not read at all, does the same thing a genuinely expired trial key does: log one console warning and show the watermark.

Sources

Where rows come from. memory is the default and needs no configuration.

A memory grid's rows may be declared either way. The top-level rows option is the usual one and what every example here uses; the same array inside the block works identically — createGrid(el, { columns, source: { mode: 'memory', rows } }) opens with exactly those rows, with the same count(), value(), text(), type inference and bound KPI and chart readings as createGrid(el, { columns, rows }), and rows.load() and rows.apply() behave the same afterwards. Either array is copied on ingest, so the one you passed is never written to (see rows under Configuration). Declare them once: a grid given both uses the top-level rows, ignores the block's, and warns once naming both places. Only memory reads a rows key from the block — the fetching modes take theirs from the server.

Load from a URL: a JSON or NDJSON file

createUrlSource(url, opts) points the grid straight at a file. A JSON file (a top-level array, or a nested array picked out with rowsPath or map) is read whole and handed over as rows. An NDJSON / JSONL file — one JSON value per line — is streamed in incrementally: the first rows render while the rest is still arriving, and a large file never sits in memory as one string. It is built on the stream source, so it inherits the frame-coalesced render, the stream:chunk / stream:end progress events and promotion to memory once a small file has fully landed.

Format is resolved in order: an explicit format: 'json' | 'ndjson' wins; else the URL extension (.ndjson/.jsonl vs .json); else the Content-Type (application/x-ndjson vs application/json); else a sniff of the first bytes, or a clear error asking for an explicit format. Pass fetch to supply auth or a proxy (default is the global fetch), headers to merge request headers, batchSize to tune NDJSON chunking (default 500), lenient: true to skip a malformed NDJSON line with a warning rather than failing, and poll (ms) to re-fetch on an interval, replacing the rows each pass. Every failure — a non-2xx status, a network error, a bad body, a malformed line — surfaces as source:error and leaves the grid usable, never an uncaught throw. The fetch is aborted when the grid is destroyed. Zero new dependencies: fetch, response.body.getReader() and TextDecoder.

A JSON file loaded through a mock transport so the example runs headless with no network; in an app, omit fetch and the global one is used. Run on every build.

const { createHeadlessGrid, createUrlSource } = await import('../packages/core/src/index.js');

// A mock transport, so this runs with no network. In your app, drop `fetch`.
const file = JSON.stringify([{ id: 1, city: 'Oslo' }, { id: 2, city: 'Lima' }, { id: 3, city: 'Cairo' }]);
const fetchImpl = async () => new Response(file, { headers: { 'content-type': 'application/json' } });

const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'city' }],
  source: createUrlSource('https://example.test/cities.json', { fetch: fetchImpl }),
});

await new Promise((r) => setTimeout(r, 50)); // let the file load
const count = grid.rows.count();
grid.destroy();
return count; // 3

For NDJSON, point it at a .ndjson or .jsonl URL — createUrlSource('/events.ndjson') — and the rows stream in as they parse.

Derived sources: a grid built from another grid

Most dashboards put a summary panel beside a table, the top five sales people, the breakdown by region, the exceptions list. Built by hand, that panel runs its own query, and sooner or later somebody filters the table and the panel does not follow. Everyone who has shipped a dashboard has been in the meeting where two numbers on one screen disagree.

A derived grid removes the possibility. It is a second grid whose rows are built from the first (grouped, unnested, filtered, ranked or profiled) so the panel is the table, one derivation later, and one filter moves both. It answers the questions a summary panel exists for: the top five sales people, the most-sold SKUs, a statistical profile of whatever the user has filtered to.

It is a source rather than a new kind of grid, so everything downstream: its own sorting and filters, totals, shadow columns, formatting, export, themes: works on the result and knows nothing about where the rows came from. Charts bind to one as readily as to any grid.

source: {
  mode: 'derived',
  from: salesGrid,
  follow: 'filtered',

  groupBy: 'rep',
  select: { revenue: { of: 'amount', fn: 'sum' }, deals: { fn: 'count' } },
  sort: [{ col: 'revenue', dir: 'desc' }],
  limit: 5,
}

The pipeline runs in one order, and the order is the contract: unnest → where → bucket → group → reduce → sort → limit. where sits before grouping deliberately: filtering afterwards is a different question, which groups, not which rows, and one key cannot mean both.

// refresh: 'manual' — the summary re-derives only when the host asks.
refreshButton.addEventListener('click', () => summary.rows.load());

The relational statistics, as rows

A single-column statistic already has a route: select reduces a group with any kernel the totals row uses, and that table is a superset of the statistics one, so select: { p95: { of: 'amount', fn: 'p95' } } works, along with median, stddev, gini and the rest. statistics is for what select structurally cannot reach: the figures needing two or more columns, or a second grid. Like profile it is a terminal producer — it replaces the pipeline rather than joining it, and the two cannot be used together. Every row carries n, the rows the figure covered. Full detail, including the measured re-derive cost of each producer, is in the detail reference.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const readings = Array.from({ length: 20 }, (_, i) => ({ id: i, t: i, v: 100 + i * 3, w: 50 - i }));
const plant = createHeadlessGrid({ rowKey: 'id',
  columns: [{ field: 't', type: 'number' }, { field: 'v', type: 'number' }, { field: 'w', type: 'number' }],
  rows: readings });
plant.rows.count();

// One row per column PAIR: { a, b, coefficient, n }. `w` runs exactly against `t`.
const pairs = createHeadlessGrid({ rowKey: '__key',
  columns: [{ field: 'a' }, { field: 'b' }, { field: 'coefficient', type: 'number' }, { field: 'n', type: 'number' }],
  source: { mode: 'derived', from: plant, refresh: 'live',
    statistics: { fn: 'correlation', columns: ['t', 'v', 'w'] } } });
let tw = null;
pairs.rows.forEach((row) => {
  if (pairs.rows.value(row.key, 'a') === 't' && pairs.rows.value(row.key, 'b') === 'w') {
    tw = pairs.rows.value(row.key, 'coefficient');
  }
});

// One row per METRIC of the series summary, not one per point.
const series = createHeadlessGrid({ rowKey: '__key',
  columns: [{ field: 'metric' }, { field: 'value', type: 'number' }],
  source: { mode: 'derived', from: plant, refresh: 'live',
    statistics: { fn: 'series', of: 'v', by: 't' } } });

// One row per compared column, against a second grid. The peer is watched.
// `t` is on this grid only, so it is reported as unmatched rather than dropped.
const peer = createHeadlessGrid({ rowKey: 'id',
  columns: [{ field: 'v', type: 'number' }, { field: 'w', type: 'number' }],
  rows: readings.map((r) => ({ id: r.id, v: r.v * 2, w: r.w })) });
peer.rows.count();
const compared = createHeadlessGrid({ rowKey: '__key',
  columns: [{ field: 'column' }, { field: 'magnitude', type: 'number' }],
  source: { mode: 'derived', from: plant, refresh: 'live',
    statistics: { fn: 'datasetVsDataset', with: peer, columns: ['v', 'w'] } } });

let shared = 0, unmatched = 0;
compared.rows.forEach((row) => {
  if (compared.rows.value(row.key, 'magnitude') === null) unmatched += 1; else shared += 1;
});

return `t/w ${tw}; pairs ${pairs.rows.count()}; metrics ${series.rows.count()}; compared ${shared} + ${unmatched} unmatched`;

Union sources: combining several grids into one

"Worst performers across two datasets" is easy when the two datasets share a key: a join brings the second grid's fields onto the first. It is not expressible at all when they do not: incidents from two regions with no shared identifier, orders from two systems, this quarter and last as one ranked list. from takes an array of sources for exactly this: stack several row sets into one, then rank, group or filter the combined set with the same pipeline a single from already runs.

source: {
  mode: 'derived',
  from: [
    { grid: eastIncidents, label: 'east' },
    { grid: westIncidents, label: 'west' },
  ],
  sort: [{ col: 'severity', dir: 'desc' }],
  limit: 10,
}

Every source is read (each narrowed by its own follow, filtered by default) and concatenated in declaration order, deterministic rather than interleaved, before unnest/join/where/bucket/ groupBy/select/sort/limit/limitPer/ cumulative run once over the result — so "the worst across both" is one derivation, not a hand-merged array.

__source is required, not optional. Every row carries it — the entry's label, or its declaration index when unlabelled — because without it a combined list cannot be read, filtered or grouped by where it came from, which is most of the point of stacking several sources. It is an ordinary field to where, groupBy and select, exactly like a column the data itself carries.

The union of fields, not the intersection. A field present on only one source is undefined on rows from the others — not fabricated, not coerced. Sources are not type-reconciled: if two disagree on what a field means, map is where you make them agree, before they combine, not something the union guesses at for you.

The key is namespaced. A derived grid's __key is the source row's own key when nothing is grouped, and two sources sharing the same identifiers would otherwise collide. So it is qualified by the source tag when there is no groupBy. Grouped, the key is the group value exactly as it always has been — rows from different sources landing in the same group when their group values agree is the point of grouping a union, not a collision to guard against.

Not a join. There is no dedup and no merge-on-key: two sources reporting the same fact both appear as separate rows, and there is no UNION-vs-UNION-ALL distinction to draw. Reach for join when two sides share a key and you want them matched rather than stacked; use groupBy on the combined set when you want them summed together.

Empty and failing sources. A source with no matching rows contributes nothing; the rest of the union still derives. A source that throws while being read (or mapped) is named in a warnOnce and skipped for that pass — reported, never silently dropped, because a silently missing source would make "worst across both" quietly wrong.

A cycle is refused, not recursed. A source list that includes the grid being derived, directly or through a chain of other derived grids, is refused when the source is built, naming the offending source.

Not supported alongside a union. crossFilter has no single target once there is more than one parent, and profile reduces one grid's own columns, so both are refused with a warning rather than guessed at.

const { createHeadlessGrid } = await import('../packages/core/src/index.js');

const east = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'title' }, { field: 'severity', type: 'number' }],
  rows: [{ id: 'e1', title: 'disk-full', severity: 9 }, { id: 'e2', title: 'slow-query', severity: 3 }],
});
// A second, unrelated incident log — its own "rating" field, no shared id with `east` at all.
const west = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'name' }, { field: 'rating', type: 'number' }],
  rows: [{ id: 'w1', name: 'oom-kill', rating: 10 }, { id: 'w2', name: 'stale-cache', rating: 2 }],
});

const worst = createHeadlessGrid({
  columns: [{ field: 'title' }, { field: 'severity', type: 'number' }, { field: '__source' }],
  source: {
    mode: 'derived',
    from: [
      { grid: east, label: 'east' },
      // `map` brings west's differently-named fields into the common shape.
      { grid: west, label: 'west', map: (row) => ({ title: row.name, severity: row.rating }) },
    ],
    sort: [{ col: 'severity', dir: 'desc' }],
    limit: 2,
  },
});

const titles = [];
worst.rows.forEach((r) => titles.push(worst.rows.value(r.key, 'title')));

// A per-source breakdown reads `__source` like any other field.
const bySource = createHeadlessGrid({
  columns: [{ field: '__source' }],
  source: { mode: 'derived', from: [{ grid: east, label: 'east' }, { grid: west, label: 'west' }] },
});
const sources = [];
bySource.rows.forEach((r) => sources.push(bySource.rows.value(r.key, '__source')));

worst.destroy(); bySource.destroy(); east.destroy(); west.destroy();
return `worst=${titles.join(',')}; sources=${sources.join(',')}`;

Read-only. A derived row is an answer, not a record: there is no write-back for the sum of four hundred rows, so writes are refused with a reason rather than accepted and discarded on the next refresh.

They chain. A derived grid can be the source of another to any depth: a profile of the top five, and a change at the root travels the whole chain. A cycle is refused rather than recursed.

The key. rowKey defaults to the derived key and need not be set. It is the group value, which is what makes a live ranking readable: the row moves rather than the values under it changing.

Cost. The first derivation is linear in the rows read and largely independent of what is reduced: roughly 900 ms per 200,000 rows grouped into forty, whether the selection is one sum or four statistics. After that, a change that names the rows it touched is patched rather than re-derived: only the groups those rows entered or left are reduced again, so a live feed costs time proportional to what changed rather than to the table. Five hundred updates against that same source take under 300 ms in total, not 300 ms each. A joined derivation is maintained the same way from both sides: the lookup is held between derivations rather than rebuilt, a change to the fact table rejoins only the rows that moved, and a change to the lookup rejoins only the rows behind the keys whose match actually changed, about 2 ms per fact update and 1.5 ms per lookup edit against a 200,000-row source joined to 2,000 customers. A change that cannot be reasoned about that way, a new filter, a regrouping, a derivation using unnest or where, or a lookup row arriving for rows an inner join had dropped, falls back to a full derivation, which is correct but costs the full linear pass. Narrow with follow: 'filtered' so the derivation reads what the user is looking at rather than the whole table.

What a change firing promises

Anything maintaining state from rows:changed (a derived grid, a chart, your own cache) needs to know whether a firing names the rows that moved or merely says that something did. One rows.apply announces itself more than once: the source reports how many rows moved, the row model reports which ones, and the grid reports that a change happened. Acting on all three does the work three times over.

The default is the safe one. A firing that carries neither flag is treated as a change of unknown extent, so a listener re-reads rather than assuming nothing moved. Read the flags rather than the shape of the payload: a firing that reports a row move carries counts, because no row changed value, and only the flags distinguish that case from a duplicate announcement.

Confidence intervals: how much to trust the figure

Every other statistic here describes the data you have. An interval describes how well that data pins down the figure you actually care about, and it is the one thing a descriptive tool can honestly say about the world beyond its rows.

The line this draws. Lattice quantifies uncertainty; it does not adjudicate hypotheses. There are no p-values, no significance tests and no verdicts, and reading two non-overlapping intervals as a significance test is a mistake often enough to be worth not encouraging. An interval says "the mean is 42, and the sample pins that down to between 39 and 45". It does not say 42 differs from 40.

Every interval carries its level. The result's confidence field says what it was computed at, so a figure copied out of one cannot lose the thing that makes it readable. An interval without its level is not a smaller claim, it is an unreadable one.

A proportion is Wilson, not Wald. The textbook p ± z√(p(1−p)/n) fails exactly where a rate is most interesting: near zero it reaches below zero, and at no observed successes it collapses to the single point zero: claiming perfect certainty from the least informative sample there is. The Wilson interval stays inside 0 to 1 and stays sensible at the extremes, so "none of forty failed" correctly reads as "the failure rate is under 9%" rather than "the failure rate is zero".

Report the capability interval. Its absence is the commonest way a capability study overstates itself. A Cpk of 1.35 measured on thirty parts has a lower bound below 1.0, so a process that has "passed" a 1.33 requirement on thirty parts has demonstrated very little. The point estimate alone does not say that; the interval does.

It follows the filters. Like every statistic here, an interval reads the rows the filters left, so it narrows as the user narrows the grid. That is the correct behaviour and worth knowing: it describes the filtered population, not the whole table.

Reading an SPC chart

The figures are only half of it. A capability claim is made in a picture, and these are the two the discipline expects.

The lines are named, on opposite edges. CL, UCL and LCL at the right; LSL, USL and Target at the left. Control limits are what the process does; specification limits are what the customer asked for, and reading one as the other is the classic misreading of a control chart. A capable process puts its control limits just inside its tolerance, so the two families sit close together, which is exactly when they need telling apart, and why they are named at opposite ends rather than left to collide.

Rule breaks carry their number. With Western Electric's four rules a marked point was readable on its own; with Nelson's eight it is not. A spike (rule 1) is a bad part; a six-point trend (rule 3) is tool wear or a drifting sensor. They call for different responses, and a chart that marks both the same way has told you the less useful half of what it knows. Set the rule set with rules: 'nelson' on the chart, as on statistics.capability.

The capability report draws two curves, not one. Cp and Cpk are computed from short-term variation, Pp and Ppk from overall. When a process has drifted the two differ, and the four indices say so only as numbers a reader has to know how to compare. Drawn, the gap is the finding: a narrow solid curve inside a wide dashed one is a capable process that has been allowed to wander, a scheduling problem, not a machine problem.

What this covers, and what it does not. These are individuals charts: one reading per point, with short-term variation estimated from the moving range. That is the right instrument when readings arrive one at a time, a sensor, a test rig, a single-piece flow.

It is not the right instrument for subgrouped data, and the difference is not cosmetic. If you measure five parts an hour, the correct chart is X̄-R: its limits come from within-subgroup variation and are roughly √n tighter, which is what makes a shift in the process centre visible. Run an individuals chart over the same readings and the limits are computed from differences that mix within- and between-subgroup variation; they come out around twice as wide, and a two-sigma shift that X̄-R flags a dozen times over reads as scattered noise. Lattice does not ship X̄-R, X̄-S, or the attribute charts (p, np, c, u), and an individuals chart should not be substituted for them.

Pair the two control charts. An individuals chart asks whether the process has moved; a movingRange chart asks whether it has become less repeatable. A process can fail either without failing the other: it can drift while its point-to-point variation holds steady, and it can hold its average while shaking itself apart. The second is close to invisible on the individuals chart alone, because a wider spread pulls that chart's own limits wider with it: it rescales to accommodate the very thing that has gone wrong. Drawn one above the other, they are the standard I-MR pair.

Bind it to the readings, not to a summary of them. A whisker is computed from the values the chart can see behind each mark. Bound to a grid whose rows are already one per mark, a summary or a derived panel, the chart sees a single value per category and there is no spread to draw: the readings that produced each average are upstream and no longer reachable. Bind the chart to the rows the summary was computed from, or carry a margin yourself and use error: { of: 'margin' }. A chart asked for whiskers it cannot compute says so once rather than drawing nothing in silence.

Uncertainty on a chart. error: true draws a whisker on each mark, computed from the readings behind it. Four bars side by side invite a comparison the numbers alone cannot support, a five per cent gap between two categories of eight readings is noise, and between two of eight hundred it is the finding. The whisker is what tells them apart, and its absence is why bar charts are so often over-read. A mark with a single reading gets none, because one reading has no spread and a zero-height whisker would claim certainty rather than admit ignorance.

Fitted lines. fit: true draws a least-squares line through a scatter with its R² beside it; fit: 'line' draws the line alone. A cloud of points invites a reader to draw the line themselves, and people are consistently poor at it, the eye is pulled by the extremes, which is exactly what least squares is not.

The interval travels with the index. The statistics panel shows the bounds under Cpk and Ppk, and createStat takes an interval function that puts them under the value. A tile is where a figure is read fastest and questioned least, which makes it the place an interval earns its keep rather than the place it is least needed.

Pushdown adapters: one query, many engines

A remote source already receives a structured request: range, sort, filters, quick text, grouping, pivoting and totals. A pushdown adapter turns that request into whatever an engine speaks, so connecting a new back end is a translation layer rather than a new source.

import { createPushdownSource, odataAdapter } from 'lattice-grid';

const source = createPushdownSource({
  adapter: odataAdapter({ url: 'https://api.example.com/Orders' }),
  compute,
});

createGrid(host, { source, columns: [...] });

An adapter never carries an engine. Each one takes what it needs as a parameter: restAdapter takes a fetch and bundles no HTTP library, dfqlAdapter takes a token, and duckdbAdapter takes a connection you have already made. So a grid can drive a full analytical engine without this package carrying one, and installing Lattice never installs anything else.

An adapter declares what it can answer. No engine speaks the whole query. OData takes a condition tree but only some operators; a single-term API takes one field and one value; a hand-written endpoint may take nothing but a page number. The adapter states its capabilities, the SDK divides the request accordingly, and the grid finishes whatever is left.

Anything left over means the whole result is fetched. Filtering a window of rows in the browser is not a slower way to get the right answer, it is a fast way to get a wrong one: the rows that belong on the first page may be on the ninth, and the count is whatever the engine happened to return. So when the grid has work left to do it asks the engine for the complete result, applies the remainder, and pages from what it holds. It says so once, naming the part that could not be pushed, because the fix is usually a wider adapter rather than a bigger machine. source.lastPlan() reports the division for any request.

A conjunction splits; a disjunction does not. An and group narrows with each condition, so the engine can apply the conditions it understands and the grid narrows what comes back. An or group widens with each branch, so pushing only the supported branches returns fewer rows than the filter allows, and the grid cannot recover rows that were never fetched. A disjunction the engine cannot fully answer therefore stays with the grid whole. The same asymmetry governs faceting.

A sort is pushed whole or not at all. Ordering by the first column and fixing the rest in the browser needs every row anyway, so a partial sort buys nothing and returns rows in an order that is wrong until the grid corrects it.

What each adapter takes

Every adapter is a function of one options object. The tables below list what each accepts, the type, the default where it is not obvious, and what it means. The defaults are the load-bearing part: an adapter is designed to work when handed almost nothing, so most of what you can set is about telling it what your endpoint cannot do rather than switching features on.

odataAdapter

restAdapter

The parameter names are yours, and the defaults are not zero. Paging and sorting are assumed present; filtering is assumed absent until you declare operators, because an adapter that claims to filter when the endpoint ignores it returns the wrong rows silently. The query-string names default to offset, limit, sort, order, filter and q (search); params overrides any of them.

Persisting a cell edit. With edit: true the adapter advertises mutate, so a committed cell edit is sent as an HTTP request. REST has no universal write convention, so the request is yours to shape: writeUrlFor names the per-row endpoint, encodeMutation takes full control of method and body, and writeRow reads the authoritative row back when returning: 'row'.

const { restAdapter } = await import('../packages/core/src/index.js');

// The per-row endpoint a mutation targets.
const writeUrlFor = (op) => `/api/orders/${op.key}`;

let sentMethod;
const adapter = restAdapter({
  url: '/api/orders',
  edit: true,          // opt into write-back (advertises mutate.update / delete)
  returning: 'row',    // reconcile to the server's authoritative row
  writeUrlFor,
  // Full control of the request; supersedes the default envelope.
  encodeMutation: (op) => ({
    method: 'PATCH',
    url: writeUrlFor(op),
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(op.patch),
  }),
  // Pull the authoritative row out of this service's envelope.
  writeRow: (body) => body.record,
  fetch: async (url, init) => {
    sentMethod = init.method;
    return { ok: true, status: 200, json: async () => ({ record: { id: '42', status: 'shipped' } }) };
  },
});

const result = await adapter.mutate({ kind: 'update', key: '42', patch: { status: 'shipped' } });
return result.rows[0].status;   // 'shipped', read back from the server

duckdbAdapter

How the total is counted, and what it costs. The grid needs the size of the matching set to size its scrollbar. Until 1.51 every page query carried count(*) OVER () AS "__lattice_total", which looks free: the window is evaluated before LIMIT, so one round trip returns both the window and the size of the set it was cut from. Against a local table it is free. Against a remote Parquet it is the most expensive thing the adapter does — a window function has to see every matching row of the projected columns, so whatever row-group pruning or range reads DuckDB and the file host might otherwise manage between them (see whether a Parquet file streams or downloads whole) cannot help, and the whole file crosses the wire to produce one page. Measured in Chrome on duckdb-eh.wasm against a 10,000,000-row Parquet of 162,386,227 bytes — 162.4 MB decimal, 154.9 MiB binary, and every transfer figure on this page is decimal MB so that it can be compared with it directly — on an origin counting bytes actually served, first paint pulled 162.5 MB. Slightly more than the file, because the reads overlap.

The total is now its own statement — SELECT count(*) FROM <from> WHERE …, the same predicate through the same builder with the same typed casts and the same bound values, and no ORDER BY or LIMIT. Read it with adapter.countSqlFor(query), the counting counterpart of adapter.sqlFor(query); it returns null when count is false. The two statements are dispatched in the same tick — both started before either is awaited — so there is no browser round trip between them.

That does not make the count free on the clock, and on DuckDB-Wasm it often is not. One DuckDB-Wasm connection funnels its statements through a single worker, so the engine still runs the two in sequence; what dispatching together buys there is that the second is already queued the instant the first finishes. Measured on the file below: an unfiltered first paint takes 566 ms with the count and 558 ms without, so the count costs about 8 ms — genuinely hidden. A filtered query takes 2122 ms with the count and 573 ms without, so there the count costs about 1550 ms and is not hidden at all. (It is still faster than the 3064 ms the old window function took for the same query.) A server-side DuckDB with a thread pool runs the two at once and the distinction goes away.

Cheap, not free — and on a filtered query, not even cheap. An unfiltered count(*) over Parquet is answered from the file's footer metadata and reads no data at all: measured against the 162.4 MB file above, first paint costs the same 5.71 MB with the count on as with count: false — the count's own share is 0.00 MB. A filtered count still has to evaluate the predicate. It reads the predicate columns rather than the whole projection, and row-group statistics can prune entire groups (a predicate no row group can satisfy is answered from metadata alone — country = 'ZZ' against this file costs 0.12 MB, count and all). But a predicate whose columns are spread across every row group has to read them all: country = 'GB' AND risk_score > 70 costs 45.2 MB with the count and 3.2 MB without, so 41.9 MB of it is the count. Against the 191.2 MB the old window function cost, that is still a 4× saving — and if your grid never shows a count, count: false makes the same query a 59× one.

One case where 1.51 transfers more, not less: a session that eventually reads the whole table anyway. Every individual query above is cheaper than or equal to its 1.50.0 counterpart, but a whole session need not be. 1.50.0 dragged the entire file down on first paint in a handful of large sequential reads, after which everything was cache-warm and every later query cost nothing. 1.51 reads lazily, and lazy range reads over a big Parquet overlap where one eager read did not — so bytes already paid for can be paid for again. Measured over one browser session doing first paint, a selective filter, a full-table ORDER BY, a deep page and two more filters, with the counter reset between each: 1.50.0 transferred 162.5 MB in total and 1.51 transferred 209.8 MB. The user who never sorts the whole table pays 46.7 MB instead of 162.5 MB and sees a first paint in 566 ms instead of 5808 ms; the user who does sort the whole table has to read the whole file either way, and now pays some of it twice. A full ORDER BY over an unindexed column with SELECT * is unchanged at 162.5 MB before and after — this card neither helps nor hurts it.

Turning the count off changes what the grid knows, on purpose. With count: false the adapter reports no total, and the grid does what it already does for any source of unknown length: it scrolls open-ended and discovers the end when a short page arrives. It does not substitute the page length for the total — a page presented as the whole is a wrong number where a right one goes, and every “showing X of Y”, scrollbar and row count would be wrong with nothing said.

So count: false is a trade, not a free win, and here is the part you will notice first: the grid can only scroll as far as it has discovered. The scrollbar is open-ended rather than proportional, a “showing X of Y” readout has no Y, and grid.scroll.toRow(n) cannot jump to a row beyond the discovered end — asking for row 900 of a not-yet-discovered million lands at the furthest row known so far, and reaching the real row 900 means paging to it. Turn the count off for a grid whose users scroll; leave it on for one whose users jump.

Whether a Parquet file streams or downloads whole is DuckDB's and the file host's doing, not the grid's. duckdbAdapter only writes SQL; it never opens a file, so it has no say in whether read_parquet(...) reads the whole thing or only the row groups a query needs. Measured against a 1.5 MB Parquet on GitHub Pages (BACKLOG-0001324): DuckDB-Wasm 1.32.0's default HTTP path issued 0 Range requests and read 100% of the file, for every query including a single-value chip filter. Running LOAD httpfs; on the connection before the first read_parquet(...) call changed that to 25 Range requests and 30% of the file for the same query. (DuckDB-Wasm 1.29.0 read 119% of the file on the same test — its ranges overlapped — so the exact figures are a version's, not a promise.) A file registered with db.registerFileBuffer(...) is always read whole, whatever version is loaded: a buffer has already been downloaded in full before DuckDB ever sees it. And the file host has to cooperate: it must answer HEAD, advertise Accept-Ranges: bytes and answer a range request with 206 Partial Content and a Content-Range header — GitHub Pages does all three — and, cross-origin, its CORS policy must expose Content-Range and Content-Length or the browser cannot read them back. Any of that missing and DuckDB falls back to reading the file whole, silently.

Typed binding for timestamp and date columns. A prepared statement binds a filter value with the value's own type, not the column's: the grid sends an instant as an ISO-8601 string, the client binds it as VARCHAR, and DuckDB refuses "ts" >= ? against a TIMESTAMP column (Binder Error: Cannot compare values of type TIMESTAMP and type VARCHAR). The adapter therefore types the placeholder: a comparison or IN member against a TIMESTAMP, TIMESTAMP WITH TIME ZONE, DATE, TIME or TIMESTAMP_S/_MS/_NS column is written CAST(? AS <that type>), and the value is still bound, never interpolated. The column's type comes from the engine — one DESCRIBE SELECT * FROM <from> on the first query, cached for the adapter's life and exposed as adapter.describe() — so an untyped grid column over a timestamp is covered. When the schema does not name the column (a DESCRIBE that failed, said once), the grid column's declared type on the condition is the fallback: timestamp/datetime cast to TIMESTAMP, date/dateString to DATE, time to TIME. The engine's type wins when both are known. A Date or an epoch-milliseconds number is bound as its ISO instant, because DuckDB has no cast from a number to a timestamp. The same schema fixes blank: = '' is a conversion error on any non-text column, so a typed column's blank test is IS NULL alone. Text and numeric comparisons (VARCHAR, BIGINT, DOUBLE, DECIMAL, HUGEINT) are written exactly as before, with no cast.

Time zones, honestly. The cast is the engine's, so its zone rules apply. Against a naive TIMESTAMP column the wall-clock digits of the bound string are compared; an instant ending in Z — which is what the grid's own date filter sends — therefore matches a column that stores UTC wall time, the usual convention for log and event data. A non-zero offset in the string is engine-version dependent (DuckDB 1.1 converts it to UTC, 1.5 keeps the digits as written), so send Z instants, not local offsets. Against a TIMESTAMP WITH TIME ZONE column an offset or Z is honoured exactly, and a string with no zone is interpreted in the engine's session TimeZone (UTC in DuckDB-Wasm unless the ICU extension is loaded and the setting changed). Against a DATE column an instant is truncated to its UTC day.

duckdbAdapter: grouping runs in the engine, one level at a time

Grouping a hundred million Parquet rows used to mean fetching a hundred million Parquet rows: the adapter declared no group capability, so the push router never sent it a grouped request and the grid grouped whatever it held. duckdbAdapter now declares group: true and answers the grouped view with GROUP BY — one statement per grid level, paged like any other window.

Nothing is configured. Group a grid over a DuckDB source and the grouping is pushed:

const grid = createGrid(el, {
  columns: [
    { id: 'region' },
    { id: 'tier' },
    { id: 'amount', type: 'number', total: 'sum' },
  ],
  groupBy: ['region', 'tier'],
  source: createPushdownSource({
    adapter: duckdbAdapter({ connection, from: "read_parquet('s3://bucket/sales/*.parquet')" }),
  }),
});

The root level is one statement — SELECT "region", count(*), sum("amount") … GROUP BY "region" ORDER BY "region" ASC NULLS LAST LIMIT ? OFFSET ? — so the group rows on screen cost a grouped scan and no leaf crosses the wire. Expanding a group narrows the next level by its parent's key; expanding the deepest one runs the ordinary row query with the same predicate ANDed on, so the leaves arrive paged and sorted exactly as they would without grouping. Every identifier goes through the same validation the row query uses and every value is bound, so the grouped path is no more exposed than the read path.

Subtotals come from the engine, and a statistic it cannot express shows nothing rather than something. Each totalled column contributes one aggregate expression, taken from the same verified pushdown map the statistics panel uses (see pushing statistics down) — sum, avg, min, max, count, the quantiles, and the rest. A column whose total is a host function, a two-column statistic such as weightedAvg (a grouped request carries no weight column), and the one genuine fallback weightedQuantile are not sent, are named in source.lastPlan().aggregates.client with the reason, and warn once. The group row then carries no value for that column. That is deliberate: the leaves of an unexpanded group are not in the browser, so the only alternative to the engine's figure is a figure computed over something that is not the group.

The counts a grouped grid shows are the engine's. Under grouping the display count is group headers plus whatever is expanded, which is how a grid showing three rows under one group once reported “4 of 3”. The root level's fetch therefore also asks for count(*) over the matching set and the grand total over it, in one extra statement, and an unfiltered count(*) once per adapter (on a Parquet file that is a footer read, not a scan). rows.matchCount() and rows.totalCount() read them, and grandTotalRow: 'bottom' draws its row from them.

Group order, and the collation decision. Group rows are ordered by their own key, ascending unless the sort names that column, which is exactly what the grid does to sibling group rows in memory — a sort naming some other column does not reorder groups in either. Absent keys sort last ascending and first descending, written as explicit NULLS LAST/NULLS FIRST rather than left to the connection's default_null_order. No COLLATE is written and the ICU extension is not loaded: the grid compares group keys with < on the JavaScript string (UTF-16 code-unit order) and DuckDB's default VARCHAR ordering is UTF-8 byte order, and the two agree for every character in the Basic Multilingual Plane. They part only for supplementary-plane characters (emoji, CJK extension B and above) compared against U+E000–U+FFFF. An ICU collation would disagree with the grid everywhere instead, so binary ordering is the pin. Practically: 'North' sorts before 'north' in both.

When grouping is not pushed, it says so. Grouping is all or nothing — group rows counted over the wrong set are wrong rows, not slow ones — so the whole level is refused if anything else in the query stayed behind: a filter that did not fully push, a sort the engine could not take, a quick search, a host where predicate, a grouping key that is not a plain column, or fullDataset (which holds the whole set and groups it client-side on purpose). source.lastPlan() then reports grouped: false, 'group' in unpushed and a groupReason sentence, and a one-time warning names it.

One known difference from a memory grid. A column holding both NULL and the empty string produces two groups in the engine and one in a memory grid, because the grid keys its group nodes on a display path where an absent value and an empty string are both ''. The engine's answer is the right one; the two are otherwise identical group for group, count for count and subtotal for subtotal, which the parity suite asserts at every level.

dfqlAdapter

graphqlAdapter

GraphQL has no fixed query semantics, so this adapter is configured. A filter, a sort and pagination are whatever the schema defines, so the two hooks are yours to write: buildQuery turns the pushed plan into the { query, variables } body the endpoint is POSTed, and parseResponse reads its data back into { rows, total }. The defaults cover an offset/limit list with a totalCount and a Relay cursor connection; either is replaced whole by passing the hook. The default query pushes only the window and asks for the total, which is why the default capabilities are range and total and nothing more — declare operators or capabilities for filter or sort only alongside a buildQuery that genuinely emits them, or the grid returns the wrong rows silently.

If your schema does not expose totalCount. The adapter reports no total, rather than the number of rows in the page, and the grid scrolls open-ended; the endpoint is named once in a warning so the silence is not mistaken for a working count. Before 1.51 the page length was reported as the total, and that was not only a wrong number on screen — it truncated results. When the grid has residual work to finish it asks for the whole result and the adapter walks offset/limit to get it, stopping when it has as many rows as the total says exist. With the total invented from page one, the walk stopped at page one: a 337-row connection came back as 100 rows, reported as complete, and any client-side filter or sort then ran over that fraction. The walk now stops on a short page or an exhausted cursor, so it returns everything and its count is exact. A schema that does report totalCount was never affected.

Authenticating a remote adapter

Two shapes cover almost every endpoint. A fixed credential — an API key or a long-lived token — goes in headers, which odataAdapter and restAdapter send on every request. A credential that expires — a short-lived bearer token you refresh — goes in a custom fetch, which is the one place that can mint a fresh value per request. dfqlAdapter takes its token directly, and headers for anything a gateway adds on top.

A fixed token in headers. The map is sent on every request, so an Authorization header authenticates the whole grid. Below, a custom fetch stands in for the network only so the example can prove the header arrived:

const { odataAdapter } = await import('../packages/core/src/index.js');

let seen;
const adapter = odataAdapter({
  url: 'https://api.example.com/Orders',
  // A fixed credential authenticates every request.
  headers: { Authorization: 'Bearer static-token-123' },
  // Only here to capture what the adapter sent; in a browser, omit it.
  fetch: async (url, init) => {
    seen = init.headers.Authorization;
    return { ok: true, json: async () => ({ value: [], '@odata.count': 0 }) };
  },
});

await adapter.execute({ range: { start: 0, end: 20 } }, {});
return seen;   // the header reached the request

An expiring token in a custom fetch. A token with a lifetime cannot sit in a fixed map, because the map is read once and the token outlives no request that matters. A custom fetch is called afresh for every request, so it is where you refresh the credential and set the header on the outgoing call:

const { restAdapter } = await import('../packages/core/src/index.js');

// Stands in for a token service that hands out a new value each time.
let issued = 0;
const freshToken = async () => `token-${++issued}`;

let lastAuth;
const adapter = restAdapter({
  url: '/api/orders',
  fetch: async (url, init) => {
    // Refreshed per request, then merged over whatever headers the adapter set.
    const headers = { ...init.headers, Authorization: `Bearer ${await freshToken()}` };
    lastAuth = headers.Authorization;
    return { ok: true, json: async () => ({ rows: [], total: 0 }) };
  },
});

await adapter.execute({ range: { start: 0, end: 20 } }, {});   // token-1
await adapter.execute({ range: { start: 20, end: 40 } }, {});  // token-2
return lastAuth;   // a fresh token on the second request

Wiring it to the API you already have

Most data sits behind a service someone on your team wrote. The adapter below sends four parameters and expects { rows, total } back. Start by declaring only what the endpoint genuinely does, and widen it as you teach the endpoint more.

const source = createPushdownSource({
  compute,
  adapter: restAdapter({
    url: '/api/orders',
    // Only the comparisons the endpoint really applies. Claiming more here
    // returns the wrong rows rather than merely running slowly.
    operators: ['eq', 'gt', 'lt', 'contains'],
    params: { offset: 'skip', limit: 'take' },
  }),
});

The request that reaches your service, and the answer it owes:

// Express. FastAPI and ASP.NET differ only in how the query string is read.
app.get('/api/orders', async (req, res) => {
  const { skip = 0, take = 100, sort, order, filter } = req.query;

  let q = db('orders');
  if (filter) q = applyConditions(q, JSON.parse(filter));   // your translation
  if (sort) {
    sort.split(',').forEach((col, i) => {
      q = q.orderBy(col, (order || '').split(',')[i] === 'desc' ? 'desc' : 'asc');
    });
  }

  // The count is of everything matching, not of the page. A grid scrollbar is
  // sized from it, so a page-sized total makes the grid look empty below.
  const [{ count }] = await q.clone().clearOrder().count({ count: '*' });
  const rows = await q.offset(Number(skip)).limit(Number(take));

  res.json({ rows, total: Number(count) });
});

The total is the commonest mistake. It is the number of rows matching the filter, not the number returned in this page. The grid sizes its scrollbar from it and requests windows against it, so returning the page length makes a large result look like one page.

A worked example, executed on every build so it cannot go stale (data-run, PRD §7 C3):

const { capabilitiesOf, splitFilters, resolveMutate } = await import('../packages/core/src/source/pushdown.js');

// An adapter that understands three comparisons and nothing else.
const caps = capabilitiesOf({ filter: 'tree', operators: ['eq', 'gt', 'lt'] });

// Read-only by declaration: an adapter that says nothing about writing
// cannot mutate, and one that opts in resolves to a complete capability.
if (resolveMutate() !== false) throw new Error('a silent adapter must stay read-only');
if (!resolveMutate({ update: true }).update) throw new Error('an opt-in must resolve');

// A conjunction splits: what the engine knows goes to it, the rest stays here.
const { pushed } = splitFilters({
  op: 'and',
  conditions: [
    { col: 'a', op: 'eq', value: 1 },
    { col: 'b', op: 'gt', value: 2 },
    { col: 'c', op: 'lt', value: 3 },
  ],
}, caps);

return pushed.conditions.length;   // all three are supported

Building an adapter from the parts

createPushdownSource is the whole story for most callers. When an engine needs a source of its own, the four pieces it is assembled from are exported separately, so a custom source can plan and finish work the same way rather than reimplementing the split.

Residual work needs the complete result. applyResidual expects every matching row, not a window. Filtering a window is not a slower route to the right answer, it is a fast route to a wrong one: the rows that belong on page one may sit on page nine. planQuery sets needsAll whenever that applies, and createPushdownSource switches to fetching everything and paging from what it holds.

Whole-dataset statistics: fullDataset

A windowed source computes a total, statistic or group over the loaded window — the rows on screen — not the whole matching set, unless residual work already forced a whole-result fetch. “Median revenue” in the footer becomes the median of ~200 rows, wrong and looking right. fullDataset.enabled makes the whole-result fetch sticky and explicit: the entire matching set is held client-side once per query and every window, total and statistic is served from it, so the figures are computed over everything. It reuses the same whole-result path residual work already takes — needsAll — rather than a parallel mechanism. It is off by default and strictly opt-in. For a restAdapter, which cannot compute, it is the only way to get a correct whole-dataset statistic at all.

Memory-guarded, refused loudly. A matching set past maxRows or maxBytesEstimate is refused — thrown, surfaced as a source:error with no rows shown — never silently truncated. Presenting a fraction as the whole is the exact failure whole-dataset pull exists to prevent, so it is never the failure mode of the fix itself. Narrow the filter or raise the limit.

// An adapter that can page but reports the whole matching count. Without
// fullDataset a stat would see only the window; with it, the whole set.
const { createPushdownSource } = await import('../packages/core/src/source/pushdown.js');
const all = Array.from({ length: 100 }, (_, i) => ({ id: i, amount: i }));
const adapter = {
  name: 'demo',
  capabilities: { range: true, total: true },
  execute: async (query) => {
    const start = query.range ? query.range.start : 0;
    const end = query.range ? query.range.end : all.length;
    return { rows: all.slice(start, end), total: all.length };
  },
};
const source = createPushdownSource({ adapter, fullDataset: { enabled: true, maxRows: 1000, maxBytesEstimate: 5_000_000 } });
// Ask for a 10-row window; fullDataset holds all 100, so the mean is the true one.
const block = await source.fetch({ range: { start: 0, end: 10 }, filters: null, sort: [], quick: '' });
const held = block.total; // 100: the whole set is held, not the 10-row window
return all.reduce((s, r) => s + r.amount, 0) / held; // 49.5, the true whole-dataset mean

Refusing a partial result: allowPartialResults

When a query has residual work — a filter, sort or quick search the engine could not push — the source asks the adapter for the whole matching set, applies the residual here, and pages from what it holds. If the adapter instead returns a page of that result (it paged when told not to), the client-side filter or sort runs over the wrong rows: the rows that belong on page one may be in the fraction that was never fetched, so a page is presented as the full filtered set. That is a wrong answer, not a slow one.

By default the source refuses such a shortfall — it throws, and the remote source surfaces a source:error with no rows shown, rather than filter a fraction and lie. The fix is to make the adapter follow the engine's own paging before returning, or hold the data in memory. allowPartialResults: true is the knowing escape hatch: a caller who accepts the permissive behaviour — an adapter that genuinely cannot page and a result small enough not to matter, or a diagnostic run — keeps the old warn-once-and-proceed path. It is off by default, because a silent wrong answer is the one thing the design refuses. It does not affect the fullDataset memory guard, nor the no-residual short-return warning.

// An eq-only engine: the `gt` filter is residual and runs in the browser. The
// adapter reports 40 matching but returns only 1 row — a page shown as the whole.
const { createPushdownSource } = await import('../packages/core/src/source/pushdown.js');
const adapter = {
  name: 'shortfall',
  capabilities: { filter: 'tree', operators: ['eq'] },
  execute: async () => ({ rows: [{ id: 1, a: 5 }], total: 40 }),
};
const req = { range: { start: 0, end: 10 }, filters: { col: 'a', op: 'gt', value: 1 }, sort: [], quick: '' };

// Default: refused. Filtering 1 of 40 rows would return the wrong rows.
const strict = createPushdownSource({ adapter });
let refused = false;
try { await strict.fetch(req); } catch (e) { refused = /returned 1 of 40|refused/.test(e.message); }

// Knowing opt-in: warns once and proceeds with the fraction.
const lax = createPushdownSource({ adapter, allowPartialResults: true });
const block = await lax.fetch(req);
return refused ? `refused; opted in: ${block.rows.length} rows` : 'not refused';

Running a host predicate: whereRowLimit

A where predicate is a host function — whether this user may see the row, whether you hold a rate for its currency. No engine can evaluate one, so the only way a pushdown source can honour it is to fetch every matching row and filter here. That is a real answer, and it is also a windowed grid quietly turning into a whole-dataset download — the one thing a pushdown source exists to avoid.

So it is gated rather than done on your behalf. Under whereRowLimit (default 50_000, the same anchor as the grid's workerThreshold) the predicate runs and the counts are whole-dataset counts. At or past it — or when the adapter reports no row total, since the only way to learn the size from such an adapter is to fetch the set — the source refuses: the predicate is not applied, the rows it would exclude stay on screen, and one warning names the adapter, the size, the limit and the way out. Raise the limit when you want the download.

// Three rows, two of them ana's. The predicate is a host function with no twin,
// so the engine cannot narrow the fetch and the source must hold the set to run it.
const { createPushdownSource } = await import('../packages/core/src/source/pushdown.js');
const all = [{ id: 1, owner: 'ana' }, { id: 2, owner: 'bo' }, { id: 3, owner: 'ana' }];
const adapter = {
  name: 'demo',
  capabilities: { range: true, total: true },
  execute: async (q) => ({ rows: q.range ? all.slice(q.range.start, q.range.end) : all, total: all.length }),
};
const where = { active: true, names: ['mine'], version: 1, passes: (row) => row.owner === 'ana' };
const req = { range: { start: 0, end: 10 }, filters: null, sort: [], quick: '', where };

// Under the limit: the whole matching set is fetched and the predicate runs.
const under = createPushdownSource({ adapter, whereRowLimit: 1000 });
const applied = await under.fetch(req);

// At or past it: refused and warned about, and every row stays on screen.
const over = createPushdownSource({ adapter, whereRowLimit: 2 });
const refused = await over.fetch(req);

return `applied: ${applied.rows.length}, refused: ${refused.rows.length}`;

Pushing statistics down: aggregates

A DuckDB-class engine can compute a median or a standard deviation over the whole matching set far faster than pulling every row to do it here. The aggregates config decides, at grid setup, which statistics are computed by the engine and which by the grid. It is a design-time developer choice — fixed for the life of the grid, never a runtime toggle, never shown to an end user. Absent, every aggregate is computed client-side, so no existing grid changes behaviour.

Each statistic is classified IDENTICAL (the engine's result equals the grid's own kernel, verified against it) or MAY-DIFFER (the engine computes it by a method that can differ from the grid's definition). The classification drives this documentation and build-time provenance, not whether a stat is pushed — that is your choice. Only weightedQuantile is a genuine fallback: the engine cannot express the grid's midpoint convention, so it is always computed client-side.

No mixed provenance. An engine number and a client number never appear in one result set. Aggregates are pushed only when the filter is fully pushed; a residual filter the engine could not apply forces every aggregate client-side, because an engine figure computed over a superset beside a client figure over the real set would be wrong-but-plausible. lastPlan().aggregates reports, per statistic, whether the engine or the client computed it and the class it was assigned — build-time inspection, not a per-figure runtime marker.

The classification table below is generated from the single pushdown map (STAT_PUSHDOWN), so it cannot drift from what the adapter actually emits:

// Push the verified-identical stats to the engine; keep the fallback here.
// STAT_PUSHDOWN is the published map every stat's class and SQL comes from.
const { createPushdownSource, STAT_PUSHDOWN } = await import('../packages/core/src/source/index.js');
void STAT_PUSHDOWN;   // the single source of truth for the classification table above
const adapter = {
  name: 'demo',
  capabilities: { filter: 'tree', operators: ['eq'] },
  execute: async () => ({ rows: [], total: 0 }),
  // A real duckdbAdapter runs SQL; here we just echo which stats arrived.
  executeAggregates: async (query, aggs) => Object.fromEntries(aggs.map((a) => [a.id, 1])),
};
const source = createPushdownSource({ adapter, aggregates: {
  default: 'engine-if-identical',   // push only the verified-identical stats
  overrides: { mode: 'client' },     // but always keep mode's exact definition
} });
const split = await source.aggregate(
  { filters: null, sort: [], range: null },
  [{ id: 'a', col: 'revenue', fn: 'median' }, { id: 'b', col: 'size', fn: 'weightedQuantile' }],
);
// median is IDENTICAL so it pushes; weightedQuantile is a fallback so it stays here.
return `engine=${split.engine[0].class} client=${split.client[0].class}`;

Joining two grids

Two grids each holding their own data, and a third showing where they meet. Orders against customers; shipments against carriers; enrolments against students. The third grid derives from one side and names the other as its join partner.

const joined = createGrid(host, {
  source: {
    mode: 'derived',
    from: orders,
    join: {
      with: customers,
      on: { left: 'customerId', right: 'id' },
      select: ['name', 'tier'],
    },
  },
  columns: [{ field: 'ref' }, { field: 'name' }, { field: 'tier' }, { field: 'amount' }],
});

The row count does not change. A key appearing twice on the right keeps the first match rather than emitting a row per pair. SQL would multiply them out; here that would change the row count of a grid the reader thinks of as “the orders” and quietly double every total taken from it.

Both sides are live. The partner is read at derivation time, not captured when the grid was built, and editing it re-derives, a corrected tier in the customer grid moves the order into a different band in the joined one.

Cross-filtering: the path back up

Derivation runs one way. A derived grid reads its source and never writes to it, which is what makes a chain of them safe to reason about. Cross-filtering is the single deliberate path back up: clicking a row in a summary panel filters the grid it summarises.

const byRep = createGrid(panel, {
  source: {
    mode: 'derived', from: main, groupBy: 'rep', refresh: 'live',
    crossFilter: true,
    select: { total: { of: 'amount', fn: 'sum' } },
  },
  columns: [{ field: 'rep' }, { field: 'total' }],
});

byRep.on('row:clicked', (e) => byRep.crossFilter.toggle(e.key));

The event is row:clicked, not row:click. A handler bound to the wrong name subscribes without error and never fires, so this example is executed on every build to keep the name honest: it wires the same handler to a stand-in grid, emits the event, and checks the click reached the cross-filter.

// A stand-in for the grid's event bus and cross-filter, so the wiring above can
// be executed here without a DOM. The names are the product's own.
const listeners = {};
const filtered = [];
const grid = {
  on: (name, fn) => { (listeners[name] = listeners[name] || []).push(fn); },
  emit: (name, e) => { for (const fn of listeners[name] || []) fn(e); },
  crossFilter: { toggle: (key) => { filtered.push(key); } },
};

// The line from the example, verbatim in its event name.
grid.on('row:clicked', (e) => { if (e.key) grid.crossFilter.toggle(e.key); });

// A click on a rep row. The wrong name — 'row:click' — would reach no handler,
// and this block would produce '' instead of the key.
grid.emit('row:clicked', { key: 'EMEA' });
grid.emit('row:click', { key: 'US' });

return filtered.join(',');

A panel does not filter itself. The grid pushing the filter leaves its own condition out when it reads the source back. Without that, clicking one rep would collapse the panel to that single row and strand the reader with nothing else to click. It is the same rule that keeps a header histogram showing every bar after you click one (facets), applied between grids instead of within one.

Several panels compose. Each leaves out only its own condition, so two panels over different columns narrow each other while both stay whole: pick a rep and the region panel shows that rep's regions, pick a region and the rep panel shows that region's reps.

It needs a memory source. Leaving a panel's own condition out means asking the source for every row that survives the other filters, which a source holding one page cannot answer. Over a remote, paged or stream source the read falls back to the ordinary filtered rows (narrowed by the very column the panel asked to be excluded from) and the panel collapses to the row that was clicked. It warns when it does. Exclude the originating panel on the server instead.

It is an ordinary filter. The condition goes through the source's filters.set, so it undoes, rides in a saved view, and appears in whatever filter UI the grid already has. There is no second filter model beside the real one.

The remote request

Your fetch receives one object and returns { rows, total }.

Events

One bus. There are no onX configuration properties. Every payload also carries type, origin and grid.

const off = grid.on('cell:changed', e => save(e.row.data));
grid.once('ready', init);
grid.on('*', e => console.log(e.type, e));   // wildcard, for debugging
off();                                       // on() returns its own unsubscribe