JavaScript Data Grid API Reference

Everything a column’s layout accepts, and the three locks as refusals

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

// Everything ColumnLayoutSpec accepts, on three columns.
const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [{ id: 1, ref: 'A-1', notes: 'long text', qty: 3 }],
  columns: [
    // An identifier: fixed width, pinned to the start edge, and locked against
    // every user gesture - resize, move, hide, and being pulled into a band.
    { field: 'ref', layout: { width: 130, min: 44, max: 300, pin: 'start',
        resizable: false, movable: false, lockVisible: true, lockPosition: true } },
    // A column that follows the grid's width, and one sized to its content.
    { field: 'notes', layout: { flex: 1, min: 200 } },
    { field: 'qty', layout: { fit: 'content', hidden: true } },
  ],
});

const ref = grid.columns.get('ref').layout;
const notes = grid.columns.get('notes').layout;
const qty = grid.columns.get('qty').layout;

// The locks are refusals, not decoration: each gesture is ignored and warns.
grid.columns.hide('ref');
grid.columns.resize('ref', 300);
grid.columns.move('ref', 2);
const stillThere = grid.columns.visible().map((c) => c.id).join(',');
const order = grid.columns.all().map((c) => c.id).join(',');
grid.destroy();

return `ref ${ref.width}/${ref.min}/${ref.max} ${ref.pin}; notes flex ${notes.flex} min ${notes.min};`
  + ` qty ${qty.fit} hidden ${qty.hidden}; after locks ${stillThere} | ${order}`;

A lookup column read by key, ordered, joined, and asked about an unknown value

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

// The dictionary is read by key, so an option list you already have needs no
// reshaping: `code` is the stored value, `name` the label, `team` the heading an
// editor groups under.
const dictionary = [
  { code: 'ops', name: 'Operations', team: 'Field' },
  { code: 'eng', name: 'Engineering', team: 'Field' },
  { code: 'fin', name: 'Finance', team: 'Back office' },
];
const base = { valueKey: 'code', labelKey: 'name', groupKey: 'team', options: dictionary };

const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [{ id: 1, owner: ['ops', 'fin'], next: 'ops', raw: 'nope', open: 'anything' }],
  columns: [
    // A cell that holds several values: the labels are joined by `separator`.
    { field: 'owner', type: 'lookup', lookup: { ...base, multiple: true, separator: ' + ' } },
    // Workflow order rather than alphabetical order, for the editor and the set filter.
    { field: 'next', type: 'lookup', lookup: { ...base, sortBy: 'optionOrder' } },
    // A value the dictionary does not hold still renders, never blanked.
    { field: 'raw', type: 'lookup', lookup: { ...base, unknownLabel: (v) => `unknown (${v})` } },
    // ...and is reported once per column, unless the column says it is open.
    { field: 'open', type: 'lookup', lookup: { ...base, allowCustom: true } },
  ],
});

// The text the reader sees, straight off the row.
const shown = (id) => grid.rows.text('1', id);
const order = (id) => grid.columns.get(id).lookup.sorted().map((o) => o.id).join(',');
// `sortBy` decides what the editor lists, and it is not the declaration order by
// default: 'label' collates, 'optionOrder' keeps the sequence as declared.
const byLabel = order('owner');
const byDeclared = order('next');
// `groupKey` names the heading an editor groups the options under.
const headings = grid.columns.get('owner').lookup.sorted().map((o) => o.group).join('|');
// Both are read before the snapshot below, because the unknown value is
// reported when the cell is formatted.
const multi = shown('owner');
const unknown = shown('raw');
const custom = shown('open');
const reported = grid.diagnostics.snapshot().warnings
  .filter((w) => w.id.startsWith('lookup:unknown:')).map((w) => w.id).join(',');
// Asked for matching options as the user types; the signal belongs to the
// request this keystroke supersedes.
const search = async (query, signal) => (signal.aborted ? [] : [{ code: 'new', name: query }]);
const extra = await search('Newco', { aborted: false });
// The unknown value is reported against the column that did not allow it, and
// not against the one that did.
grid.destroy();

return `${multi}; ${unknown}; ${custom}; ${byLabel} / ${byDeclared}; search ${extra[0].name}; reported ${reported}; groups ${headings}`;

Every declarative validation rule, refusing a commit

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

// Declarative edit rules. Each is checked before the value is written, so a
// failing commit is refused rather than corrected afterwards.
const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [{ id: 'r1', name: 'Alice', age: 30, ref: 'ABC', state: 'open', from: 5, to: 9, span: 1 }],
  columns: [
    { field: 'id' },
    { field: 'name', edit: true, validation: { required: true, minLength: 2, maxLength: 20 } },
    { field: 'age', type: 'number', edit: true, validation: { min: 0, max: 120 } },
    { field: 'ref', edit: true, validation: { pattern: '^[A-Z]{3}$', messages: { pattern: 'Three capitals.' } } },
    { field: 'state', edit: true, validation: { oneOf: ['open', 'closed'], message: 'Not a state.' } },
    // A cross-field rule sees the whole row, so it can compare siblings.
    { field: 'to', type: 'number', edit: true, validation: {
      crossField: (value, row) => (Number(value) >= Number(row.from) ? true : 'Ends before it starts.'),
    } },
    // A free-form check, the same contract as `crossField`.
    { field: 'span', type: 'number', edit: true, validation: {
      validate: (value) => (Number(value) < 100 ? true : 'Too far out.'),
    } },
  ],
});

// Commit a value the way a user does, through the editor.
const commit = (colId, value) => { grid.edit.start('r1', colId); grid.edit.stop(false, { value }); };
const refused = [];
for (const [colId, value] of [['name', ''], ['age', 999], ['ref', 'abc'], ['state', 'paused'], ['to', 1], ['span', 500]]) {
  commit(colId, value);
  const error = grid.validation.errorFor('r1', colId);
  if (error) refused.push(`${colId}:${error.code}`);
}
// The cells still hold what they held: a failing value is not written.
const kept = `${grid.rows.byKey('r1').data.age}/${grid.rows.byKey('r1').data.ref}`;
// A valid value writes through and clears the mark.
commit('age', 40);
const after = `${grid.rows.byKey('r1').data.age} ${grid.validation.errorFor('r1', 'age')}`;
const wording = grid.validation.errorFor('r1', 'ref');
grid.destroy();

return `refused ${refused.join(',')}; kept ${kept}; then ${after}; message ${wording && wording.message}`;

Rolling, positional and anomaly shadows over a stated order

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

// A shadow is a value the grid maintains about a column, not a field in the
// data. The rolling kinds read an explicit `orderBy` - never the screen sort, or
// a trailing average would change on every header click.
const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [
    { id: 'r1', t: 1, v: 2, g: 'a' }, { id: 'r2', t: 2, v: 4, g: 'a' },
    { id: 'r3', t: 3, v: 5, g: 'a' }, { id: 'r4', t: 4, v: 4, g: 'b' },
    { id: 'r5', t: 5, v: 99, g: 'b' },
  ],
  columns: [
    { field: 't', type: 'number' },
    { field: 'v', type: 'number' },
    { field: 'g' },
    // The last three rows of the series, across the whole dataset rather than
    // per group.
    { id: 'sum3', shadow: { kind: 'rollingSum', of: 'v', orderBy: 't', within: 'all',
        window: { kind: 'count', span: 3 } } },
    // How full that window is: the first rows carry a partial one, and are
    // stamped as such rather than dressed as full.
    { id: 'cov', shadow: { kind: 'windowCoverage', of: 'v', orderBy: 't', within: 'all',
        window: { kind: 'count', span: 3 } } },
    // The median of the window; `q` moves it anywhere in [0, 1].
    { id: 'p90', shadow: { kind: 'rollingQuantile', of: 'v', orderBy: 't', within: 'all', q: 0.9,
        window: { kind: 'session' } } },
    // Everything so far, and the change on the row before.
    { id: 'cum', shadow: { kind: 'cumulativeToDate', of: 'v', orderBy: 't', within: 'all' } },
    { id: 'pop', shadow: { kind: 'periodOverPeriod', of: 'v', orderBy: 't', within: 'group' } },
    // A rank is positional: `scope` decides whether the filters move it.
    { id: 'rankAll', shadow: { kind: 'rank', of: 'v', scope: 'all' } },
    { id: 'rankLeft', shadow: { kind: 'rank', of: 'v', scope: 'filtered' } },
    // An outlier by modified z-score; `threshold` is the score a row must clear.
    { id: 'odd', shadow: { kind: 'anomalyFlag', of: 'v', threshold: 3.5 } },
    // A running total is the one derived value that depends on the display
    // order, which is why it is not a shadow kind.
    { field: 'v', id: 'sofar', running: 'total' },
  ],
});

const at = (col, key) => grid.rows.value(key, col);
const series = ['r1', 'r2', 'r3', 'r4', 'r5'].map((k) => at('sum3', k)).join(',');
const coverage = `${at('cov', 'r1').toFixed(2)}/${at('cov', 'r5')}`;
const quantile = at('p90', 'r5');
const cumulative = at('cum', 'r5');
const perGroup = at('pop', 'r5');
const running = at('sofar', 'r5');
const flagged = ['r1', 'r5'].map((k) => at('odd', k)).join(',');
// With `scope: 'filtered'` the rank is taken over what the filters left; with
// `'all'` it does not move.
grid.filters.set({ col: 'g', op: 'eq', value: 'b' });
const ranks = `${at('rankAll', 'r4')}/${at('rankLeft', 'r4')}`;
grid.destroy();

return `sum ${series}; cov ${coverage}; q ${quantile}; cum ${cumulative}; pop ${perGroup};`
  + ` running ${running}; anomaly ${flagged}; rank ${ranks}`;

The options a decomposition, a smoothing model, a regression and a tolerance need

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

// A seasonal series: level 10 plus a four-step cycle, so the decomposition has
// something to find. `period` is required - there is no auto-detection.
const values = [12, 8, 11, 9, 12, 8, 11, 9, 12, 8, 11, 9];
const series = { of: 'v', orderBy: 't', within: 'all' };

const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: values.map((v, i) => ({ id: String(i), t: i, v, x: i, y: 2 * i + 1 })),
  columns: [
    { field: 't', type: 'number' },
    { field: 'v', type: 'number' },
    { field: 'x', type: 'number' },
    { field: 'y', type: 'number' },
    // The classical decomposition. `decomposition: 'multiplicative'` is the
    // other model, and is undefined on a non-positive series.
    { id: 'trend', shadow: { kind: 'tsTrend', ...series, period: 4 } },
    { id: 'seasonal', shadow: { kind: 'tsSeasonal', ...series, period: 4, decomposition: 'additive' } },
    // Single smoothing at a fixed level factor, and Holt's level+trend, whose
    // `beta` is the trend factor.
    { id: 'ses', shadow: { kind: 'tsSmoothed', ...series, smoothing: 'ses', alpha: 0.5 } },
    { id: 'holt', shadow: { kind: 'tsSmoothed', ...series, smoothing: 'holt', alpha: 0.5, beta: 0.1 } },
    // A regression: the predictors and the response may be given on the shadow
    // itself, or as a whole `model`. `method` picks the fit.
    { id: 'fit', shadow: { kind: 'fitPredicted', predictors: ['x'], response: 'y', method: 'ols' } },
    { id: 'fit2', shadow: { kind: 'fitPredicted', model: { predictors: ['x'], response: 'y', method: 'robust' } } },
    // The customer's tolerance, judged per row: outside lower/upper fails, and
    // inside the inner warnLower/warnUpper band is a still-in-spec warning.
    { id: 'judged', shadow: { kind: 'specStatus', of: 'v', lower: 8, upper: 12, warnLower: 9, warnUpper: 11 } },
    // Declared on the column, so the capability figures, a control chart and a
    // rule marking an out-of-tolerance cell cannot disagree about the tolerance.
    { field: 'v', id: 'graded', spec: { lower: 8, upper: 12, target: 10 } },
  ],
});

const at = (col, key) => grid.rows.value(key, col);
const decomposed = `${at('trend', '4')}/${at('seasonal', '4')}`;
const smoothed = `${at('ses', '11').toFixed(2)}/${at('holt', '11').toFixed(2)}`;
const fitted = `${at('fit', '5')}/${at('fit2', '5')}`;
const judged = ['0', '2', '1'].map((k) => at('judged', k)).join(',');
const tolerance = grid.columns.get('graded').spec;
grid.destroy();

return `trend/seasonal ${decomposed}; ses/holt ${smoothed}; fit ${fitted}; spec ${judged};`
  + ` tolerance ${tolerance.lower}-${tolerance.upper}`;

Grouping and pivot order, three reductions, and what the interface is allowed to offer

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

const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [
    { id: 1, region: 'EMEA', team: 'Ops', tags: ['red', 'blue'], at: '2026-03-02T09:00:00Z', qty: 4, price: 10 },
    { id: 2, region: 'EMEA', team: 'Eng', tags: ['red'], at: '2026-03-03T09:00:00Z', qty: 6, price: 20 },
    { id: 3, region: 'APAC', team: 'Ops', tags: ['blue'], at: '2026-03-09T09:00:00Z', qty: 2, price: 30 },
  ],
  columns: [
    // Two grouping columns, in a stated order rather than the column order.
    { field: 'team', group: { enabled: true, index: 1 } },
    { field: 'region', group: { enabled: true, index: 0 } },
    // A multi-value cell: one group per value rather than one for the combination.
    { field: 'tags', group: { explode: true } },
    // A timestamp buckets by civil week, starting on Sunday.
    { field: 'at', type: 'timestamp', group: { granularity: 'week', weekStart: 7 } },
    // Two pivot dimensions, also ordered by a stated index.
    { field: 'region', id: 'pivotRegion', pivot: { enabled: true, index: 1 } },
    { field: 'team', id: 'pivotTeam', pivot: { enabled: true, index: 0 } },
    // A column that averages within each group while the grand total sums, and
    // one nobody may group, pivot or total from the interface.
    { field: 'qty', type: 'number', total: 'sum', groupTotal: 'avg', grandTotal: 'sum' },
    { field: 'price', type: 'number', allowGroup: false, allowPivot: false, allowTotal: false, nullable: true },
  ],
});

// The grouping order is the declared `index`, not the column order.
const grouped = grid.columns.state().filter((c) => c.groupIndex !== null)
  .sort((a, b) => a.groupIndex - b.groupIndex).map((c) => c.id).join('+');
// `explode` gives the row one group per value.
const exploded = grid.columns.get('tags').group.explode;
const buckets = grid.columns.get('at').group;
const reductions = ['total', 'groupTotal', 'grandTotal'].map((k) => grid.columns.get('qty')[k]).join('/');
// The pivot order is the declared `index` too.
const pivoted = grid.columns.state().filter((c) => c.pivotIndex !== null)
  .sort((a, b) => a.pivotIndex - b.pivotIndex).map((c) => c.id).join('+');
// The three permissions are what the column menu, the tool panel and the AI
// layer's schema read to decide what to offer; they are carried on the resolved
// column, and they do not veto your own calls.
const price = grid.columns.get('price');
const offered = `${price.allowGroup}/${price.allowPivot}/${price.allowTotal}`;
const blanks = price.nullable;
grid.destroy();

return `groups ${grouped}; pivots ${pivoted}; explode ${exploded}; ${buckets.granularity}/${buckets.weekStart};`
  + ` reductions ${reductions}; offered ${offered}; nullable ${blanks}`;

A preset, a type turned off, column tags, and a computed value’s own hooks

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

let computes = 0;
const grid = createHeadlessGrid({
  rowKey: 'id',
  locale: 'en-US',
  // A house style declared once, merged in before anything the column says.
  columnPresets: { money: { type: 'number', format: { decimals: 2, prefix: '$' } } },
  rows: [
    { id: 1, code: 'b', paid: 1000.5, qty: 2, note: 'x' },
    { id: 2, code: 'a', paid: 20, qty: 3, note: null },
  ],
  columns: [
    // `type` decides parsing, formatting, sorting, the default editor and the
    // default filter together; `false` turns inference off.
    { field: 'qty', type: 'number' },
    { field: 'note', type: false },
    // The preset is merged first, so the column may still override it.
    { field: 'paid', preset: 'money' },
    // Free-form labels, so the column tag bar can show and hide sets of columns.
    { field: 'code', tags: ['identity', 'audited'] },
    // A computed value: `deps` are the columns it reads, `pure` says the result
    // depends on nothing else, so it is computed once per dependency change.
    { id: 'net', value: {
      deps: ['paid', 'qty'],
      compute: (deps) => { computes++; return deps.paid * deps.qty; },
      pure: true,
    } },
    // A comparator of the column's own, and the parse an edit goes through.
    { id: 'byLength', field: 'code', value: {
      compare: (a, b) => String(a).localeCompare(String(b)),
      parse: (p) => String(p.value).trim().toLowerCase(),
    } },
  ],
});

const shown = grid.rows.text('1', 'paid');
const opaque = grid.columns.get('note').type;
const tags = grid.columns.tags().join(',');
const net = `${grid.rows.value('1', 'net')}/${grid.rows.value('2', 'net')}`;
// A pure compute is memoised: reading the same cell again does not re-run it.
const before = computes;
grid.rows.value('1', 'net');
const memoised = computes === before;
const compare = grid.columns.get('byLength').compare('a', 'b') < 0;
const parsed = grid.columns.get('byLength').def.value.parse({ value: '  AB  ' });
grid.destroy();

return `preset ${shown}; type ${opaque}; tags ${tags}; net ${net}; memoised ${memoised};`
  + ` compare ${compare}; parse ${parsed}`;

Null ordering, an unexported column, the filter and editor a column asks for, and a history depth

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

const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [
    { id: 1, ref: 'A', closed: null, secret: 'hide me', note: 'first', price: 100 },
    { id: 2, ref: 'B', closed: '2026-03-02', secret: 'hide me too', note: 'second', price: 100 },
  ],
  columns: [
    { field: 'ref' },
    // Empty values before the rest, in both directions: the sort never moves them.
    { field: 'closed', type: 'date', sort: { direction: 'asc', nullsFirst: true } },
    // Shown, but never exported.
    { field: 'secret', export: { csv: false, excel: false } },
    // Which filter the column offers, and what that filter is handed.
    { field: 'note', filter: { type: 'set', props: { limit: 50 } } },
    // The editor by name, in a popup, with props of its own. `edit.validate` is
    // the imperative check, distinct from the declarative `validation` rules.
    { field: 'price', type: 'number', edit: {
      enabled: true, editor: 'textarea', popup: true, props: { rows: 3 },
      validate: (value) => (Number(value) > 0 ? true : 'Must be positive.'),
    } },
    // `history` keeps the last `depth` readings of the column it shadows.
    { id: 'trail', shadow: { of: 'price', kind: 'history', depth: 3 } },
  ],
});

// The excluded column is not in the file, and the nulls sorted to the head.
const header = grid.export.csv({ lineEnding: '|' }).split('|')[0];
const order = [0, 1].map((i) => grid.rows.get(i).data.ref).join(',');
const filter = grid.columns.get('note').filter;
const editor = grid.columns.get('price').edit;
// The imperative check is a veto: the cell keeps the value it had.
grid.edit.start('1', 'price');
grid.edit.stop(false, { value: -5 });
const kept = grid.rows.byKey('1').data.price;
// Four readings, a depth of three: the oldest falls off the end.
for (const value of [110, 120, 130, 140]) grid.rows.apply({ update: [{ id: 1, price: value }] });
const trail = grid.rows.value('1', 'trail').join('+');
grid.destroy();

return `csv ${header}; nulls ${order}; filter ${filter.type}/${filter.props.limit};`
  + ` editor ${editor.editor}/${editor.popup}/${editor.props.rows}; kept ${kept}; trail ${trail}`;

A band whose columns are married: both moves are refused

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

const grid = createHeadlessGrid({
  rowKey: 'id',
  rows: [{ id: 1, ref: 'A', jul: 10, aug: 10, sep: 10, other: 1 }],
  columns: [
    { field: 'ref' },
    // A band whose columns are kept together: a move that would take one of them
    // out of the band's run, or drop an outsider into it, is refused.
    { id: 'q3', title: 'Q3', marryChildren: true, columns: [
      { field: 'jul' }, { field: 'aug' }, { field: 'sep' },
    ] },
    { field: 'other' },
  ],
});

const order = () => grid.columns.all().map((c) => c.id).join(',');
const before = order();
// Moving a married child out of its band, and an outsider into it, are both
// refused: the column order does not change.
grid.columns.move('aug', 4);
const afterChild = order();
grid.columns.move('other', 2);
const afterOutsider = order();
grid.destroy();

return `${before}; child ${afterChild}; outsider ${afterOutsider}`;

A cell drawn every way a column can ask: renderer and props, classes, inline styles, a decoration and variant, a template, alignment, wrapping, a title tooltip and both spans

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { root } = createTestDom({ width: 1200, height: 300 });

const grid = createGrid(root, {
  rowKey: 'id',
  locale: 'en-US',
  rows: [
    { id: 1, account: 'Acme', amount: 1200, status: 'late', note: 'Call before noon', region: 'North' },
    { id: 2, account: 'Bolt', amount: -40, status: 'ok', note: 'Paid', region: 'North' },
  ],
  columns: [
    // A renderer of your own, handed the column's `props`, and a plain-text
    // tooltip, which becomes the browser's own `title`.
    { field: 'account', title: 'Customer', cell: {
      render: (p) => `${p.props.prefix}${p.value}`,
      props: { prefix: '#' },
      tooltip: (p) => `Account ${p.value}`,
    } },
    // Classes, static and per value, and an inline style computed per cell.
    { field: 'amount', type: 'number', format: { decimals: 1 }, cell: {
      class: 'money',
      classWhen: { 'is-negative': (p) => p.value < 0 },
      css: (p) => (p.value < 0 ? { background: 'mistyrose' } : {}),
    } },
    // A decoration whose colour comes from a variant mapped from the value.
    { field: 'status', cell: { decoration: 'pill', variant: { map: { late: 'danger', ok: 'success' } } } },
    // A template (escaped), aligned, top-aligned and wrapping.
    { field: 'note', cell: { template: '<b>{{value}}</b>', align: 'center', verticalAlign: 'top', wrap: true } },
    // A fixed inline style, and a region cell that covers the row below it.
    { field: 'region', cell: {
      style: { color: 'navy' },
      spanRows: (p) => (p.index === 0 ? 2 : 1),
    } },
    // A cell that covers the column to its right when the amount is negative.
    { field: 'id', title: 'Ref', cell: { spanColumns: (p) => (p.data.amount < 0 ? 2 : 1) } },
    { field: 'spare' },
  ],
});
flushFrames();

const cells = [...root.querySelectorAll('.lat-cell')];
const cell = (key, col) => cells.find((c) => c.getAttribute('data-col') === col
  && c.closest('[data-key]')?.getAttribute('data-key') === String(key));
const has = (el, name) => String(el?.className || '').split(/\s+/).includes(name);

const account = cell(1, 'account');
const drawn = `${account.textContent} '${account.getAttribute('title')}'`;
const money = cell(2, 'amount');
const classes = `${has(money, 'money')}/${has(money, 'is-negative')}/${has(cell(1, 'amount'), 'is-negative')}`;
const shaded = money.style.getPropertyValue('background');
const pill = has(cell(1, 'status'), 'lat-dec--pill') && String(cell(1, 'status').className).includes('danger');
const note = cell(1, 'note');
const bold = note.childNodes.some((n) => n.tagName === 'B');
const laid = ['lat-cell--center', 'lat-cell--valign-top', 'lat-cell--wrap'].every((c) => has(note, c));
const navy = cell(1, 'region').style.getPropertyValue('color');
const tall = cell(1, 'region').style.height;
const wide = `${cell(1, 'id').style.width}/${cell(2, 'id').style.width}`;
const heading = [...root.querySelectorAll('.lat-header-cell')]
  .find((h) => h.getAttribute('data-col') === 'account').textContent.trim();
grid.destroy();

return `${heading}: ${drawn}; classes ${classes}; css ${shaded}; pill ${pill}; template ${bold};`
  + ` laid ${laid}; style ${navy}; rows ${tall}; cols ${wide}; amount ${money.textContent}`;

A rich tooltip: content from render, live content from mount, and the unmount that tears it down

const { createTestDom, flushFrames, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { root, document } = createTestDom({ width: 800, height: 300 });

const log = [];
const grid = createGrid(root, {
  rowKey: 'id',
  // No delay, so focusing a cell opens its tooltip at once.
  tooltip: { delay: 0 },
  rows: [{ id: 'R1', account: 'Acme', qty: 3 }],
  columns: [
    // `render` returns the content: here a { title, rows } spec the grid lays out.
    { field: 'account', cell: { tooltip: {
      render: (p) => ({ title: `Account ${p.value}`, rows: [{ label: 'Qty', value: p.row.data.qty }] }),
    } } },
    // `mount` fills the element with live content; `unmount` is its teardown,
    // called exactly once when the tooltip closes.
    { field: 'qty', cell: { tooltip: {
      mount: (el, p) => { log.push(`mount ${p.key}`); el.textContent = `live ${p.value}`; },
      unmount: (el) => { log.push(`unmount ${el.textContent}`); },
    } } },
  ],
});
flushFrames();

const cell = (col) => [...root.querySelectorAll('.lat-cell')].find((c) => c.getAttribute('data-col') === col);
const tip = () => String(document.querySelector('[role="tooltip"]')?.textContent || '').trim();

// A keyboard user reaches the tooltip exactly as a pointer does: by focus.
cell('account').dispatchEvent(new TestEvent('focusin', { bubbles: true }));
const rendered = tip();
cell('qty').dispatchEvent(new TestEvent('focusin', { bubbles: true }));
const live = tip();
// Escape closes it without moving the pointer, and the host's teardown runs.
document.dispatchEvent(new TestEvent('keydown', { bubbles: true, key: 'Escape' }));
grid.destroy();

return `render ${rendered} | mount ${live} | ${log.join(', ')}`;

Headings and bands: a leaf and a band heading drawn by their own renderers, and a band that opens and closes with the columns that follow it

const { createTestDom, flushFrames, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { root } = createTestDom({ width: 1200, height: 300 });

const grid = createGrid(root, {
  rowKey: 'id',
  rows: [{ id: 1, ref: 'A-1', jan: 1, feb: 2, mar: 3, q1: 6, cat: 4, dog: 5, note: 'hi', code: 'R' }],
  columns: [
    // A leaf heading drawn by a renderer of your own, handed `header.props`,
    // with a class on the heading cell.
    { id: 'ref', field: 'ref', header: {
      render: (el, p) => `${p.props.mark} ${p.title}`, props: { mark: '' }, class: 'is-key',
    } },
    // A band that opens and closes, starting closed. Its months show only while
    // it is open and its total only while it is closed. The band heading takes
    // the same `render`, `props` and `class` a leaf heading does.
    { id: 'q1', title: 'Q1', collapsible: true, openByDefault: false,
      header: { render: (el, p) => `${p.title} (${p.props.unit})`, props: { unit: 'kg' }, class: 'quarter' },
      columns: [
        { field: 'jan', showWhen: 'open' }, { field: 'feb', showWhen: 'open' },
        { field: 'mar', showWhen: 'open' },
        { field: 'q1', id: 'q1total', title: 'Q1 total', showWhen: 'closed' },
      ] },
    // A plain band: its title over its columns, always shown.
    { id: 'pets', title: 'Pets', columns: [{ field: 'cat' }, { field: 'dog' }] },
    // A heading that wraps: the newline in the title is honoured and the cell
    // is stamped `data-wrap` so the theme folds it instead of clipping.
    { field: 'note', title: 'Long note\nwrapped', header: { wrap: true } },
    // A heading that turns: for a narrow RACI-style column the title reads
    // bottom-to-top, and the cell is stamped `data-vertical`.
    { field: 'code', title: 'RACI code', header: { orientation: 'vertical' }, layout: { width: 20 } },
  ],
});
flushFrames();

const leaves = () => [...new Set([...root.querySelectorAll('.lat-header-cell')]
  .map((c) => c.getAttribute('data-col')))].join(',');
const bands = [...root.querySelectorAll('.lat-header-group-cell')]
  .map((c) => `${String(c.textContent).trim()}${c.className.includes('quarter') ? '.quarter' : ''}`).join(' + ');
const ref = [...root.querySelectorAll('.lat-header-cell')].find((c) => c.getAttribute('data-col') === 'ref');
const heading = `${String(ref.textContent).trim()}${ref.className.includes('is-key') ? '.is-key' : ''}`;
const note = [...root.querySelectorAll('.lat-header-cell')].find((c) => c.getAttribute('data-col') === 'note');
const code = [...root.querySelectorAll('.lat-header-cell')].find((c) => c.getAttribute('data-col') === 'code');

const closed = leaves();
// Open the band with its own control.
root.querySelector('.lat-header-group-toggle').dispatchEvent(new TestEvent('click', { bubbles: true }));
flushFrames();
const opened = leaves();
const wrap = note && note.getAttribute('data-wrap') === '' ? 'on' : 'off';
const nl = note && String(note.textContent).includes('\n') ? 'nl' : 'no-nl';
const vertical = code && code.getAttribute('data-vertical') === '' ? 'on' : 'off';
grid.destroy();

return `${heading} | ${bands} | closed ${closed} | open ${opened} | wrap ${wrap} ${nl} | vertical ${vertical}`;

A column that flashes its own changed cells: the default, a colour of its own, a duration, and switched off

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

const grid = createHeadlessGrid({
  rowKey: 'id',
  edit: { enabled: true },
  rows: [{ id: 1, bid: 10, ask: 11, last: 10.5, volume: 100 }],
  columns: [
    // `true`: the default flash colour and duration.
    { field: 'bid', edit: { enabled: true }, cell: { flash: true } },
    // A colour of its own (either spelling) and a duration in milliseconds;
    // `0` leaves the highlight until it is cleared.
    { field: 'ask', edit: { enabled: true }, cell: { flash: { color: 'gold', duration: 0 } } },
    { field: 'last', edit: { enabled: true }, cell: { flash: { colour: 'tomato', duration: 5000 } } },
    // Declared but switched off, so a host can toggle it without deleting it.
    { field: 'volume', edit: { enabled: true }, cell: { flash: { colour: 'tomato', enabled: false } } },
  ],
});

grid.edit.setCells(['bid', 'ask', 'last', 'volume'].map((colId) => ({ key: '1', colId, value: 12 })));
const colours = ['bid', 'ask', 'last', 'volume']
  .map((id) => `${id} ${grid.highlight.colourFor('1', id) ?? 'none'}`).join(', ');
const held = grid.highlight.list().find((h) => h.colId === 'ask').duration;
const timed = grid.highlight.list().find((h) => h.colId === 'last').duration > 4000;
grid.destroy();

return `${colours}; ask held ${held}; last timed ${timed}`;

The starting sort, the controls a heading offers, and a column left out of quick search

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { root } = createTestDom({ width: 1000, height: 300 });

const grid = createGrid(root, {
  rowKey: 'id',
  headerControls: 'always',
  rows: [
    { id: 1, team: 'b', qty: 2, code: 'X-9', secret: 'kryptonite' },
    { id: 2, team: 'a', qty: 2, code: 'Y-1', secret: 'plain' },
    { id: 3, team: 'a', qty: 1, code: 'Z-5', secret: 'plain' },
  ],
  columns: [
    // The starting sort: qty descending first (`order: 0`), then team ascending.
    { field: 'team', sort: { direction: 'asc', order: 1 } },
    { field: 'qty', type: 'number', sort: { direction: 'desc', order: 0 } },
    // No sort control and no filter control in this heading.
    { field: 'code', sort: { enabled: false }, filter: { enabled: false } },
    // Left out of quick search, whatever it holds.
    { field: 'secret', quickFilter: false },
  ],
});
flushFrames();

const order = () => grid.rows.data().map((r) => r.id).join(',');
const sorted = order();
const heading = (id) => [...root.querySelectorAll('.lat-header-cell')].find((c) => c.getAttribute('data-col') === id);
const controls = (id) => ['.lat-header-sort', '.lat-header-filter']
  .map((sel) => (heading(id).querySelector(sel) ? 'y' : 'n')).join('');
const affordances = `team ${controls('team')}, code ${controls('code')}`;
grid.filters.quick('kryptonite');
const hidden = order() || 'none';
grid.filters.quick('X-9');
const found = order();
grid.destroy();

return `sorted ${sorted}; controls ${affordances}; search secret ${hidden}, code ${found}`;

A rolling window in minutes, the value hooks, a data type’s own options, a target, and a column kept out of a workbook

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

const t0 = Date.UTC(2026, 0, 1, 9, 0);
const grid = createHeadlessGrid({
  rowKey: 'id',
  edit: { enabled: true },
  rows: [0, 1, 2, 5, 6].map((minute, i) => ({
    id: `r${i}`, at: t0 + minute * 60_000, v: i + 1, size: i + 1, note: `batch ${i}`, tag: `lot-${i}`,
    sizes: [i, i + 1], secret: `s${i}`,
  })),
  columns: [
    { field: 'at', type: 'number' },
    { field: 'v', type: 'number' },
    // The same rolling sum over the last three minutes of `at`, and over the
    // last three rows: `kind` picks the statistic, `window.minutes` the span.
    { id: 'last3min', shadow: { kind: 'rollingSum', of: 'v', orderBy: 'at', within: 'all',
      window: { kind: 'time', minutes: 3 } } },
    { id: 'last3rows', shadow: { kind: 'rollingSum', of: 'v', orderBy: 'at', within: 'all',
      window: { kind: 'count', span: 3 } } },
    // What the reader sees, what a commit writes, and what quick search reads.
    { field: 'size', type: 'number', edit: true, value: {
      format: (p) => `${p.value} kg`,
      apply: (p) => { p.data.size = Number(p.value) * 10; return true; },
      quickFilterText: (p) => String(p.data.tag),
    } },
    // Options the data type reads: a list of numbers, joined with ' / '.
    { field: 'sizes', type: 'list', typeOptions: { of: 'number', joiner: ' / ' } },
    // A tolerance with a target, declared once on the column.
    { field: 'v', id: 'graded', spec: { lower: 1, upper: 5, target: 3 } },
    // Both shown; only `note` is written to a workbook.
    { field: 'note' },
    { field: 'secret', export: { excel: false } },
  ],
});

const byTime = grid.rows.data().map((r) => grid.rows.value(r.id, 'last3min')).join(',');
const byCount = grid.rows.data().map((r) => grid.rows.value(r.id, 'last3rows')).join(',');
const shown = grid.rows.text('r1', 'size');
grid.edit.start('r1', 'size');
grid.edit.stop(false, { value: 3 });
const written = grid.rows.byKey('r1').data.size;
grid.filters.quick('lot-4');
const searched = grid.rows.data().map((r) => r.id).join(',');
grid.filters.quick('');
const items = grid.columns.get('sizes').itemType.name;
const target = grid.columns.get('graded').spec.target;
// A stored (`level: 0`) workbook keeps its text readable in the bytes.
const workbook = new TextDecoder().decode(await (await grid.export.excel({ level: 0 })).arrayBuffer());
const excel = `${workbook.includes('batch 0')}/${workbook.includes('s0')}`;
grid.destroy();

return `3min ${byTime}; 3rows ${byCount}; shown ${shown}; written ${written}; searched ${searched};`
  + ` items ${items}; target ${target}; note/secret in xlsx ${excel}`;