Licensing and recipes: JavaScript Data Grid Guide

Installing a key

LatticeGrid.setLicence('LG1.…');   // your key; setLicense also works
grid.licence.state();   // 'licensed' | 'localhost' | 'trial'

The loop

ai: {
  async ask({ message }) {
    const res = await yourModelClient.complete({
      model: 'your-model-of-choice', messages: [{ role: 'user', content: message }],
    });
    return res.text;
  },
}

grid.on('state:changed', () => {
  const encoded = btoa(JSON.stringify(grid.state.get()));
  history.replaceState(null, '', `?view=${encoded}`);
});

const saved = new URLSearchParams(location.search).get('view');
if (saved) grid.state.apply(JSON.parse(atob(saved)));

grid.on('cell:changed', async (e) => {
  if (e.undo) return;                    // a rollback, not a new change
  grid.highlight({ key: e.key, colId: e.colId }, { colour: '#fff3cd', duration: 0 });
  try {
    await api.patch(`/rows/${e.key}`, { [e.colId]: e.value });
    grid.highlight({ key: e.key, colId: e.colId }, { colour: '#d4edda', duration: 900 });
  } catch {
    grid.highlight({ key: e.key, colId: e.colId }, { colour: '#f8d7da', duration: 0 });
    grid.history.undo();
  }
});

createGrid(el, {
  columns, rows, rowKey: 'id',
  edit: false,
  contextMenu: false,        // the default menu offers Paste, Clear and Fill down
  columnMenu: false,         // optional: the header's 3-dot menu
  selection: { ranges: false },
});

createGrid(el, {
  columns, rows, rowKey: 'id',
  edit: false, contextMenu: false, selection: 'none',
  rowHeight: 24, density: 'compact',
  grandTotalRow: 'bottom',
});

// lattice.js
import { createGrid as baseCreateGrid } from '@toclocoinc/lattice-grid';

export function createGrid(element, config) {
  return baseCreateGrid(element, { theme: 'house', locale: 'en-GB', ...config });
}

Five cities and two areas, filtered, sorted, shown and exported, executed

const { geometryModule } = await import('../packages/modules/geometry/index.js');  // registers the type
const { createHeadlessGrid } = await import('../packages/core/src/index.js');

// Five cities and two areas, in all three of the forms geometry arrives in.
const grid = createHeadlessGrid({
  rowKey: 'id',
  locale: 'en-US',
  columns: [{ field: 'id' }, { field: 'site', type: 'geometry' }],
  rows: [
    { id: 'London', site: { type: 'Point', coordinates: [-0.1278, 51.5074] } },
    { id: 'Paris', site: 'POINT (2.3522 48.8566)' },
    { id: 'Birmingham', site: 'POINT (-1.8904 52.4862)' },
    { id: 'Edinburgh', site: 'POINT (-3.1883 55.9533)' },
    { id: 'Madrid', site: '0101000000fe65f7e461a10dc0857cd0b359354440' }, // WKB, as hex
    { id: 'South East', site: 'POLYGON ((-1.5 50.7, 1.5 50.7, 1.5 52, -1.5 52, -1.5 50.7))' },
    { id: 'Iberia', site: { type: 'Feature', geometry: { type: 'Polygon',
      coordinates: [[[-9.5, 36], [3.3, 36], [3.3, 43.8], [-9.5, 43.8], [-9.5, 36]]] } } },
  ],
});
const ids = () => Array.from({ length: grid.rows.count() }, (_, i) => grid.rows.get(i).key).join(', ');

grid.filters.set({ col: 'site', op: 'withinDistance',
  value: { lon: -0.1278, lat: 51.5074, metres: 200000 } });
const near = ids();                       // by great-circle distance from each centroid

grid.filters.set({ col: 'site', op: 'withinBbox', value: [-10, 35, 4, 50] });
grid.sort.set([{ col: 'site', dir: 'asc' }]);   // centroid latitude, then longitude
const south = ids();

const text = grid.rows.text('South East', 'site');   // what the cell shows
const csv = grid.export.csv({ lineEnding: '\n' }).split('\n')[2];  // CSV writes WKT, whatever the input was
if (geometryModule.name !== 'geometry') throw new Error('not registered');
return `near London: ${near} | in the box, south first: ${south} | ${text} | ${csv}`;

Board structure: grouping, order and a done set, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [
  { id: 1, status: 'todo', epic: 'E1', points: 3, order: 20 },
  { id: 2, status: 'todo', epic: 'E1', points: 2, order: 10 },
  { id: 3, status: 'done', epic: 'E1', points: 5, order: 5 },
];
const b = createKanban(null, {
  rows, rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'done' }],
  columnOrder: ['done', 'todo'],
  pointsProperty: 'points', showPoints: true,
  orderProperty: 'order',
  doneColumns: ['done'],
});
const ids = b.columns().map((c) => c.id);
const todoOrder = b.column('todo').cards.map((c) => c.row.id);
const donePoints = b.rollup('epic')[0].donePoints;
return (`${ids.join(',')} | ${todoOrder.join(',')} | points ${b.points('todo')} | done ${donePoints}`);

columnOrder pins done before todo though it was configured second; orderProperty sorts card 2 (order 10) before card 1 (order 20) inside todo; pointsProperty is what makes b.points('todo') a real sum rather than 0 (showPoints only decides whether that sum is drawn into the DOM column header - see the accessible-name example below for that half); and doneColumns: ['done'] - set directly, with no column def carrying done: true - is what lets rollup('epic') count card 3's points as done.

Sprint, epic and swimlane selection, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [
  { id: 1, status: 'todo', sprint: 'S1', epic: 'E1', assignee: 'Ann' },
  { id: 2, status: 'todo', sprint: 'S2', epic: 'E1', assignee: 'Bob' },
  { id: 3, status: 'todo', sprint: 'S1', epic: 'E2', assignee: 'Cy' },
];
const b = createKanban(null, {
  rows, rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }],
  sprintProperty: 'sprint', sprint: 'S1',
  epicProperty: 'epic', epic: 'E1',
  swimlaneProperty: 'assignee', swimlanes: true,
  lanes: [{ id: 'Ann', title: 'Ann T' }, { id: 'Zed', title: 'Empty lane' }],
  laneOrder: ['Zed', 'Ann'],
  sprints: [{ id: 'S1', title: 'Sprint 1' }, { id: 'S2', title: 'Sprint 2' }],
});
const visible = [...b.model.cardsByKey.keys()];
const laneIds = b.model.lanes.map((l) => l.id);
const emptyLane = b.model.lanes.find((l) => l.id === 'Zed');
return (`${visible.join(',')} | lanes ${laneIds.join(',')} | empty ${emptyLane ? emptyLane.count : 'MISSING'} | sprints ${b.sprints().join(',')}`);

The board is constructed already narrowed to sprint S1 and epic E1 - no setSprint/ setEpic call - so only card 1 is visible. lanes configures an Ann lane and a Zed lane nobody's assignee matches, kept (count 0) because it is configured, exactly as an empty column is; laneOrder pins it first. sprints lists both configured sprints even though only S1 has a visible card.

Card mapping, quick filter and readonly, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [
  { id: 1, status: 'todo', title: 'Login form' },
  { id: 2, status: 'todo', title: 'OAuth flow' },
];
const b = createKanban(null, {
  rows, rowKey: 'id',
  columnProperty: 'status',
  columns: [{ id: 'todo' }],
  card: { title: 'title' },
  quickFilter: 'oauth',
  readonly: { columns: { todo: true } },
});
const visibleTitles = [...b.model.cardsByKey.values()].map((c) => c.fields.title);
const isReadonly = b.readonly({ column: 'todo' });
return (`${visibleTitles.join(',')} | readonly ${isReadonly}`);

card: { title: 'title' } is what makes c.fields.title readable at all; the initial quickFilter narrows the board to the one matching card before anything renders; and the per-column readonly map reports todo as locked.

Accessible name, localised labels and selection, executed

const { createTestDom, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
const { createKanban } = await import('../packages/modules/kanban/index.js');
const dom = createTestDom({});
const el = dom.document.createElement('div');
dom.root.appendChild(el);
const b = createKanban(el, {
  rows: [{ id: 1, status: 'todo', title: 'A', points: 5 }],
  rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'blocked' }],
  card: { title: 'title' },
  ariaLabel: 'Sprint board',
  emptyText: 'No cards',
  selectable: false,
  labels: { grabbed: 'Grabbed' },
  pointsProperty: 'points', showPoints: true,
});
const cardEl = el.querySelector('.lat-kanban__card');
cardEl.dispatchEvent(new TestEvent('click', {}));
const selectedAfterClick = b.selection().length;
cardEl.setAttribute('tabindex', '0');
cardEl.dispatchEvent(new TestEvent('keydown', { key: ' ' }));
const liveText = b.live.textContent;
const blockedEmpty = [...el.querySelectorAll('.lat-kanban__column')].find(c => c.dataset.column === 'blocked').querySelector('.lat-kanban__empty').textContent;
const ariaLabel = el.getAttribute('aria-label');
const todoContent = el.querySelector('.lat-kanban__headcontent');
const hasPoints = /lat-kanban__points/.test(todoContent.innerHTML);
return (`${ariaLabel} | selectable-click ${selectedAfterClick} | grab '${liveText}' | empty '${blockedEmpty}' | points ${hasPoints}`);

ariaLabel replaces the default "Board" name; selectable: false means a plain click leaves the selection empty (the keyboard grab is a separate mechanism, unaffected); labels.grabbed supplies the word the live region announces; emptyText is the placeholder shown in the empty blocked column; and showPoints (with pointsProperty) is what draws the points span into the column header - its real job, distinct from pointsProperty alone computing the sum (see the board structure example above, where showPoints is absent and b.points() still works).

Add-card, edit and move lifecycle, plus WIP enforcement, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const seen = [];
const b = createKanban(null, {
  rows: [{ id: 'a', status: 'todo' }, { id: 'b', status: 'doing' }],
  rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing', wipLimit: 1 }, { id: 'blocked' }, { id: 'review' }],
  card: { title: { field: 'title', edit: true } },
  addCard: true,
  onAddCard: (columnId) => ({ id: 'new', status: columnId, title: 'Created by onAddCard' }),
  onCardEdit: () => true,
  onBeforeMove: (card, from, to) => to !== 'blocked',
  onCardMove: (e) => e.keys[0] !== 'a' || e.to !== 'review',
  onCardClick: (e) => seen.push(`click:${e.card.key}`),
  onCardDblClick: (e) => seen.push(`dbl:${e.card.key}`),
  onCardContextMenu: (e) => seen.push(`ctx:${e.card.key}`),
  enforceWip: true,
});

const newKey = b.addCard('todo');
const createdTitle = b.card(newKey).row.title;
await b.applyEdit('a', 'title', 'Renamed');
const editedTitle = b.card('a').row.title;

const wipRefused = await b.move('a', 'doing');
const vetoRefused = await b.move('a', 'blocked');
const revertedMove = await b.move('a', 'review');

b.fire('card:click', { card: b.card('a') });
b.fire('card:dblclick', { card: b.card('a') });
b.fire('card:contextmenu', { card: b.card('a') });

return ([
  `created ${createdTitle}`,
  `edited ${editedTitle}`,
  `wip-moved ${wipRefused.moved.length}`,
  `veto-moved ${vetoRefused.moved.length}`,
  `reverted ${revertedMove.reverted}`,
  `events ${seen.join(',')}`,
].join(' | '));

addCard opts the column into add-card at all; onAddCard supplies the new row rather than an auto-generated one; onCardEdit confirms the inline edit. enforceWip refuses the move into doing (already at its limit of 1) before onBeforeMove is ever asked; a separate move into blocked is vetoed by onBeforeMove instead; and a move into review - allowed by both - is still reverted because onCardMove rejects it. onCardClick/ onCardDblClick/onCardContextMenu each fire from the matching card:* event.

Workflow rules: transitions and required fields, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const b = createKanban(null, {
  rows: [
    { id: 1, status: 'todo', title: 'A' },
    { id: 2, status: 'doing', title: 'B', deployed: '2026-01-01' },
  ],
  rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
  card: { title: 'title' },
  transitions: { todo: ['doing'], doing: ['done'] },
  require: { done: [{ field: 'deployed', label: 'Deployed' }] },
});
let transition = 'no';
try { await b.move(1, 'done'); } catch (err) { transition = /kanban\.transition/.test(err.message) ? 'transition' : err.message; }
let required = 'no';
await b.move(1, 'doing');
try { await b.move(1, 'done'); } catch (err) { required = /kanban\.require/.test(err.message) ? 'require' : err.message; }
const moved = (await b.move(2, 'done')).moved.length;
return ([transition, required, moved].join(' | '));

transitions maps a source column to the columns a card may enter - todo lists only doing, so a straight todo → done move is refused with a kanban.transition error, while a source column absent from the map may move anywhere. require maps a destination column to the fields a card must carry to enter it, so the doing → done move of card 1 - allowed by the transition, but lacking deployed - is refused with kanban.require, while card 2, which already carries it, moves through. A drag over a disallowed column is marked not droppable and the keyboard move skips it; a drop into a column with missing required fields opens a small form and the move commits only when they are filled. Both maps may also be set per lane in config.lanes.

Card aging / SLA: basis, thresholds, callbacks and the tick, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const E = 1_700_000_000_000;
const DAY = 24 * 60 * 60 * 1000;

// basis comparison: same row data, two boards differing only in `basis`.
const rowData = { id: 'x', status: 'doing', enteredAt: E - 1 * DAY, createdAt: E - 10 * DAY };
function makeBoard(basis) {
  return createKanban(null, {
    rows: [rowData],
    rowKey: 'id', columnProperty: 'status',
    columns: [{ id: 'doing' }],
    flow: false,
    sla: {
      basis, enteredProperty: 'enteredAt', createdProperty: 'createdAt',
      useTransitionLog: false, warn: { days: 2 }, breach: { days: 5 },
      now: () => E,
    },
  });
}
const byColumn = makeBoard('column').sla.stateFor('x').level; // uses enteredAt (1d) -> ok
const byBoard = makeBoard('board').sla.stateFor('x').level;   // uses createdAt (10d) -> breach

// ignoreDone
const doneRow = { id: 'd', status: 'done', enteredAt: E - 30 * DAY };
const withIgnore = createKanban(null, {
  rows: [doneRow], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'done', done: true }], flow: false,
  sla: { enteredProperty: 'enteredAt', useTransitionLog: false, warn: { days: 2 }, breach: { days: 5 }, now: () => E },
});
const ignoredByDefault = withIgnore.sla.stateFor('d').level;
const notIgnored = createKanban(null, {
  rows: [doneRow], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'done', done: true }], flow: false,
  sla: { enteredProperty: 'enteredAt', useTransitionLog: false, ignoreDone: false, warn: { days: 2 }, breach: { days: 5 }, now: () => E },
}).sla.stateFor('d').level;

// onWarn/onBreach + showAge
const hits = [];
const warnBoard = createKanban(null, {
  rows: [
    { id: 'w', status: 'doing', enteredAt: E - 3 * DAY },
    { id: 'br', status: 'doing', enteredAt: E - 6 * DAY },
  ],
  rowKey: 'id', columnProperty: 'status', columns: [{ id: 'doing' }], flow: false,
  sla: {
    enteredProperty: 'enteredAt', useTransitionLog: false,
    warn: { days: 2 }, breach: { days: 5 }, now: () => E, showAge: 'always',
    onWarn: (level, rows) => hits.push(`warn:${level}:${rows[0].id}`),
    onBreach: (level, rows) => hits.push(`breach:${level}:${rows[0].id}`),
  },
});
const showAgeState = warnBoard.sla.stateFor('w').ageText;

// tick: a real re-check interval that fires without a manual evaluate()/move.
const clock = { t: E };
const ticks = [];
const tickBoard = createKanban(null, {
  rows: [{ id: 't', status: 'doing', enteredAt: E }],
  rowKey: 'id', columnProperty: 'status', columns: [{ id: 'doing' }], flow: false,
  sla: {
    enteredProperty: 'enteredAt', useTransitionLog: false,
    breach: { days: 1 }, tick: 15, now: () => clock.t,
  },
});
tickBoard.on('card:sla', (e) => ticks.push(e.level));
clock.t = E + 2 * DAY; // now past breach, but nobody called evaluate()
await new Promise((resolve) => setTimeout(resolve, 60));
tickBoard.sla.destroy();

return ([
  `basis-column ${byColumn}`,
  `basis-board ${byBoard}`,
  `ignore-default ${ignoredByDefault}`,
  `ignore-false ${notIgnored}`,
  `hits ${hits.join(',')}`,
  `age ${showAgeState}`,
  `tick-fired ${ticks.length > 0}`,
].join(' | '));

The same card (an enteredAt of 1 day and a createdAt of 10 days) is ok under basis: 'column' (which prefers enteredProperty) and breach under basis: 'board' (which prefers createdProperty) - the same warn/breach thresholds, only the basis changed. ignoreDone defaults a done card to no ageing at all (null) and ignoreDone: false ages it anyway. onWarn and onBreach each fire, shaped (level, rows), for the card that reaches that level; showAge: 'always' gives an age chip on a card that is not yet warned. tick re-evaluates on its own timer - the card crosses into breach with no move or manual evaluate() call - and useTransitionLog: false throughout is what keeps every reading on the row timestamps rather than the flow log.

Custom card body, virtualization and a child pop-out, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createKanban } = await import('../packages/modules/kanban/index.js');

const dom = createTestDom({});
const el = dom.document.createElement('div');
dom.root.appendChild(el);

const many = [];
for (let i = 0; i < 200; i++) many.push({ id: i, status: 'todo', title: `C${i}`, parent: null });
many.push({ id: 'e1', status: 'todo', title: 'Epic', parent: null });
many.push({ id: 's1', status: 'todo', title: 'Story', parent: 'e1' });

const b = createKanban(el, {
  rows: many, rowKey: 'id', columnProperty: 'status', columns: [{ id: 'todo' }],
  card: { title: 'title' },
  cardRenderer: (card) => `<div class="custom">${card.fields.title}!</div>`,
  virtualize: { rowHeight: 100, viewport: 500, threshold: 50, overscan: 2 },
  children: { property: 'parent' },
});

const list = el.querySelector('.lat-kanban__cards');
const rendered = list.querySelectorAll('.lat-kanban__card').length;
const isVirtual = list.dataset.virtual;
const first = list.querySelector('.lat-kanban__card');
const customRendered = /class="custom"/.test(first.innerHTML);
const canExpandEpic = b.canExpand(b.card('e1'));
const canExpandLeaf = b.canExpand(b.card('s1'));

return ([
  `virtual ${isVirtual}`,
  `rendered ${rendered > 0 && rendered < 202}`,
  `custom ${customRendered}`,
  `expand-epic ${canExpandEpic}`,
  `expand-leaf ${canExpandLeaf}`,
].join(' | '));

202 cards in one column, but virtualize renders only a scroll window of them; cardRenderer owns the whole card body, replacing the default template; and children: { property: 'parent' } is what makes the epic card expandable (canExpand true) while a plain story is not.

Column and lane interaction: collapse, reorder and single-move, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [
  { id: 1, status: 'todo', assignee: 'Ann' },
  { id: 2, status: 'doing', assignee: 'Bob' },
  { id: 3, status: 'done', assignee: 'Cy' },
];
const b = createKanban(null, {
  rows, rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
  swimlaneProperty: 'assignee', swimlanes: true,
});
b.collapseColumn('doing');
const doingCollapsed = b.column('doing').collapsed;
b.collapseLane('Bob');
const bobCollapsed = b.model.lanes.find((l) => l.id === 'Bob').collapsed;
b.reorderColumns(['done', 'doing', 'todo']);
const afterReorder = b.columns().map((c) => c.id).join(',');
b.moveColumn('todo', 'done'); // sit todo just before done
const afterMoveColumn = b.columns().map((c) => c.id).join(',');
b.reorderLanes(['Cy', 'Bob', 'Ann']);
const afterLaneReorder = b.model.lanes.map((l) => l.id).join(',');
b.moveLane('Ann', 'Cy'); // sit Ann just before Cy
const afterMoveLane = b.model.lanes.map((l) => l.id).join(',');
return (`collapsed ${doingCollapsed},${bobCollapsed} | reorder ${afterReorder} | moveColumn ${afterMoveColumn} | laneReorder ${afterLaneReorder} | moveLane ${afterMoveLane}`);

collapseColumn/collapseLane toggle without an id argument and force a state with one; reorderColumns/reorderLanes take the whole desired order, while moveColumn/moveLane move a single id to sit before another (or the end, with null) - the primitive a header drag calls underneath a full reorder.

Selection and search: select, filter and facets, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [
  { id: 'a', status: 'todo', points: 3, title: 'Login form' },
  { id: 'b', status: 'todo', points: 5, title: 'OAuth flow' },
  { id: 'c', status: 'doing', points: 2, title: 'Reset flow' },
];
const b = createKanban(null, {
  rows, rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }], card: { title: 'title' },
});
b.select(['a', 'b'], 'set');
const aSelected = b.isSelected('a');
b.clearSelection();
const afterClear = b.selection().length;
b.setFilter((row) => row.points >= 3);
const afterFilter = [...b.model.cardsByKey.keys()].sort().join(',');
b.setQuickFilter('oauth');
const afterQuick = [...b.model.cardsByKey.keys()].join(',');
b.setFilter(null); b.setQuickFilter('');
const facetCounts = b.facets('status').map((f) => `${f.value}:${f.count}`).join(',');
return (`selected ${aSelected} | cleared ${afterClear} | filter ${afterFilter} | quick ${afterQuick} | facets ${facetCounts}`);

select replaces the set (mode 'set'); isSelected reads it back; clearSelection empties it. setFilter narrows to the points-3+ cards, and setQuickFilter narrows that further by text - the two compose, which is why only card b survives both. facets reads every row (not just the shown ones) for a distinct-value/count breakdown, over status here.

Sprint, epic and backlog navigation, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [
  { id: 1, status: 'todo', sprint: 'S1', epic: 'E1', points: 3 },
  { id: 2, status: 'doing', sprint: 'S1', epic: 'E1', points: 5 },
  { id: 3, status: 'done', sprint: 'S2', epic: 'E2', points: 8 },
  { id: 4, status: 'todo', sprint: null, epic: 'E1', points: 2 }, // backlog: no sprint
];
const b = createKanban(null, {
  rows, rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done', done: true }],
  sprintProperty: 'sprint', epicProperty: 'epic', pointsProperty: 'points',
  sprints: [{ id: 'S1', title: 'Sprint 1' }, { id: 'S2', title: 'Sprint 2' }],
});
b.setSprint('S1');
const inSprint = [...b.model.cardsByKey.keys()].sort().join(',');
b.showBacklog();
const inBacklog = [...b.model.cardsByKey.keys()].join(',');
b.setSprint(undefined);
b.setEpic('E1');
const inEpic = [...b.model.cardsByKey.keys()].sort().join(',');
const epicList = b.epics().join(',');
const rollup = b.epicRollup().find((r) => r.value === 'E1');
const defs = b.sprintDefs().map((d) => d.title).join(',');
return (`sprint ${inSprint} | backlog ${inBacklog} | epic ${inEpic} | epics ${epicList} | rollup ${rollup.count},${rollup.points} | defs ${defs}`);

setSprint narrows to one sprint; showBacklog (sugar for setSprint(board.BACKLOG)) shows only the card with no sprint; setEpic narrows by epic instead. epics lists the distinct epic values (facet sugar); epicRollup gives per-epic count/points; sprintDefs gives the configured sprint dataset as display titles, in order.

Board lifecycle: columns, rows, status and events, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const rows = [{ id: 1, status: 'todo' }, { id: 2, status: 'doing' }];
const b = createKanban(null, {
  rows, rowKey: 'id', columnProperty: 'status', columns: [{ id: 'todo' }, { id: 'doing' }],
});
const countTodo = b.count('todo');
const cardsCount = b.cards().length;
b.setColumns([{ id: 'todo' }, { id: 'doing' }, { id: 'done' }]);
const columnsAfter = b.columns().map((c) => c.id).join(',');
const arr = [{ id: 3, status: 'done' }];
b.setRows(arr); // back to a configured array (rather than a routed rows.apply feed)
arr.push({ id: 4, status: 'todo' }); // mutate the array in place
b.refresh(); // re-reads config.rows, so the pushed row shows up
const afterRefresh = b.cards().map((c) => c.key).sort().join(',');
b.setLoading(true);
const loadingState = b.status.loading;
b.setError('Oops');
const errorState = b.status.error;
b.collapseColumn('done');
const snap = b.getState();
const b2 = createKanban(null, {
  rows: [{ id: 3, status: 'done' }], rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done' }],
});
b2.setState(snap);
const restoredCollapsed = b2.column('done').collapsed;
let handlerCalls = 0;
const h = () => { handlerCalls += 1; };
b.on('card:add', h);
b.off('card:add', h); // unsubscribed before the next card:add
b.addCard('todo');
b.destroy();
const afterDestroy = b.model.columns.length;
return (`count ${countTodo} | cards ${cardsCount} | setColumns ${columnsAfter} | refresh ${afterRefresh} | loading ${loadingState} | error ${errorState} | state ${restoredCollapsed} | off ${handlerCalls} | destroy ${afterDestroy}`);

setColumns replaces the column set in place; setRows points a standalone board back at a plain array, and refresh re-reads it (the pushed row appears with no further call); setLoading/setError set the host-visible status; getState/setState round-trip the collapsed set onto a second board; off - called before the triggering addCard - is why the handler never runs; and destroy empties the model.

Blocked cards and dependencies, executed

const { createKanban } = await import('../packages/modules/kanban/index.js');
const board = createKanban(null, {
  rows: [
    { id: 'a', status: 'todo', title: 'A' },
    { id: 'b', status: 'todo', title: 'B', blockedBy: 'a' },
    { id: 'c', status: 'doing', title: 'C', blocked: 'Waiting on design' },
  ],
  rowKey: 'id', columnProperty: 'status',
  columns: [{ id: 'todo' }, { id: 'doing' }, { id: 'done', done: true }],
  blockedProperty: 'blocked', blockedByProperty: 'blockedBy', blockedFilter: true, card: { title: 'title' },
});
board.setBlockedFilter(false);
const c = board.card('c');
const badge = c.blocked + ' ' + c.blockedReason;
const b = board.card('b');
const deps = b.blockedBy.join(',') + ' ' + b.blocked;
board.setBlockedFilter(true);
const filter = board.model.cardsByKey.size;
board.setBlockedFilter(false);
await board.setBlocked('c', false);
const cleared = board.card('c').explicitBlocked;
await board.toggleBlocked('c', 'oops');
const toggled = board.card('c').blocked;
await board.move('a', 'done');
const ready = board.card('b').ready;
board.destroy();
return (`c ${badge} | b ${deps} | filter ${filter} | cleared ${cleared} | toggled ${toggled} | ready ${ready}`);

blockedProperty names the field that blocks a card (a boolean or a reason string); blockedByProperty names the keys of the cards blocking it. The blocked filter (setBlockedFilter) shows only blocked cards, and setBlocked/toggleBlocked write the property and raise card:edit; a blocker moving into a done column flips the dependant to ready.

Card pop-out and inline edit, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createKanban } = await import('../packages/modules/kanban/index.js');
const dom = createTestDom({});
const el = dom.document.createElement('div');
dom.root.appendChild(el);
const rows = [
  { id: 'e1', status: 'todo', title: 'Epic', parent: null },
  { id: 's1', status: 'todo', title: 'Story', parent: 'e1' },
];
const b = createKanban(el, {
  rows, rowKey: 'id', columnProperty: 'status', columns: [{ id: 'todo' }],
  card: { title: { field: 'title', edit: true } },
  children: { property: 'parent', render: () => {} },
});
const editable = b.isFieldEditable('title');
const detail = await b.expand('e1');
const opened = !!detail;
b.closeDetail();
const handle = b.editCard('e1', 'title');
const editing = !!handle;
return (`editable ${editable} | opened ${opened} | editing ${editing}`);

isFieldEditable is true only for a card field mapped with edit: true; expand opens the epic's child pop-out (here via a custom children.render, so no grid factory is needed) and closeDetail closes it; editCard then starts inline edit on the same field, independent of the pop-out.

Geometry: overflow axes, track size, gap and padding, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { document, root } = createTestDom({ width: 600, height: 400 });
const host = document.createElement('div');
root.appendChild(host);
const layout = createLayout(host, {
  columns: 6, rows: 4, overflowX: 'scroll', overflowY: 'static', columnWidth: '200px',
  gap: '20px', padding: '15px', compact: 'none',
  windows: [{ id: 'a', xPos: 1, yPos: 1, xSize: 2, ySize: 1 }],
});
const canvas = host.querySelector('.lat-layout__canvas');
const viewport = host.querySelector('.lat-layout__viewport');
return (`${viewport.style.overflowX} ${viewport.style.overflowY} | ${canvas.style.gridTemplateColumns} | gap ${canvas.style.gap} | padding ${layout.payload('a').style.padding}`);

overflowX: 'scroll' is the axis that scrolls; overflowY stays 'static' independently; columnWidth is the fixed track a scrolling axis repeats; and gap/padding reach the DOM as the real CSS lengths configured, not their 8px/5px built-in fallbacks. compact: 'none' is what a single-window layout cannot show on its own - see the before-events example below for compact's effect on a move.

Layout-level interactivity defaults, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { document, root } = createTestDom({ width: 600, height: 400 });
const host = document.createElement('div');
root.appendChild(host);
const layout = createLayout(host, {
  columns: 3, rows: 1,
  closable: true, movable: true, resizable: true, maximisable: true, minimisable: true,
  windows: [
    { id: 'bare', xPos: 1, yPos: 1, xSize: 1, ySize: 1 },
    { id: 'opted-out', xPos: 2, yPos: 1, xSize: 1, ySize: 1, movable: false },
  ],
});
const frame = (id) => host.querySelector(`[data-window-id="${id}"]`);
const bareHasClose = !!frame('bare').querySelector('.lat-layout__close');
const bareHasGrip = !!frame('bare').querySelector('.lat-layout__grip');
const optedOutHasGrip = !!frame('opted-out').querySelector('.lat-layout__grip');
const canMaximise = layout.maximise('bare');
const canMinimise = layout.minimise('bare');
return (`close ${bareHasClose} | grip ${bareHasGrip} | opted-out-grip ${optedOutHasGrip} | maximise ${canMaximise} | minimise ${canMinimise}`);

Every layout-level default (closable, movable, resizable, maximisable, minimisable) applies to bare, which declares none of its own; opted-out's own movable: false beats the layout-level true, which is why it renders no grip. maximisable/minimisable are what let maximise()/minimise() succeed on a window that never declared either itself.

A layout-level corners default, and a window's own override, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { document, root } = createTestDom({ width: 400, height: 200 });
const host = document.createElement('div');
root.appendChild(host);
const layout = createLayout(host, {
  columns: 2, rows: 1, corners: 'square',
  windows: [
    { id: 'a', xPos: 1, yPos: 1, xSize: 1, ySize: 1 },
    { id: 'b', xPos: 2, yPos: 1, xSize: 1, ySize: 1, corners: 'rounded' },
  ],
});
const frame = (id) => host.querySelector(`[data-window-id="${id}"]`);
const a = frame('a').getAttribute('data-corners');
const b = frame('b').getAttribute('data-corners');
return (`a ${a} | b ${b}`);

The layout's corners: 'square' reaches a, which declares none of its own, and zeroes its radius (and its title bar's, and - were it minimised or maximised - that state's too, since all three are this same frame element). b's own corners: 'rounded' overrides the layout default back to today's look, which is why it carries no data-corners attribute at all - the default needs none, it is themed through --lattice-layout-radius instead.

The window list and a saved arrangement applied at mount, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { document, root } = createTestDom({ width: 600, height: 400 });
const host = document.createElement('div');
root.appendChild(host);
const layout = createLayout(host, {
  columns: 4, rows: 4, compact: 'none',
  windows: [
    { id: 'a', xPos: 1, yPos: 1, xSize: 1, ySize: 1 },
    { id: 'b', xPos: 2, yPos: 1, xSize: 1, ySize: 1 },
  ],
  layout: { columns: 4, rows: 4, windows: [{ id: 'a', xPos: 3, yPos: 2, xSize: 1, ySize: 1 }] },
});
const ids = layout.windows();
const snap = layout.getLayout();
const aPlaced = snap.windows.find((w) => w.id === 'a');
const bPlaced = snap.windows.find((w) => w.id === 'b');
return (`${ids.join(',')} | a@${aPlaced.xPos},${aPlaced.yPos} | b@${bPlaced.xPos},${bPlaced.yPos}`);

windows declares two windows, a at column 1 and b at column 2; the mount-time layout arrangement then moves a to (3, 2), overriding its own declared placement, while b - not named in layout - stays exactly where windows put it.

Move and resize before-events, independently gated and paired with their cancellations, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { document, root } = createTestDom({ width: 600, height: 400 });
const host = document.createElement('div');
root.appendChild(host);
const moved = [];
const resized = [];
const cancelledMove = [];
const cancelledResize = [];
const layout = createLayout(host, {
  columns: 4, rows: 4, compact: 'none',
  windows: [{ id: 'a', xPos: 1, yPos: 1, xSize: 1, ySize: 1 }],
  onWindowMoved: (e) => moved.push(e),
  onWindowResized: (e) => resized.push([e.id, e.xSize, e.ySize]),
  onBeforeWindowMove: (e) => (e.to.xPos === 4 ? e.preventDefault('pinned') : true),
  onWindowMoveCancelled: (e) => cancelledMove.push(e.reason),
  onBeforeWindowResize: (e) => (e.to.xSize === 3 ? e.preventDefault('too-wide') : true),
  onWindowResizeCancelled: (e) => cancelledResize.push(e.reason),
});
const okMove = await layout.move('a', { xPos: 2 });
const vetoedMove = await layout.move('a', { xPos: 4 });
const okResize = await layout.move('a', { xSize: 2 });
const vetoedResize = await layout.move('a', { xSize: 3 });
return (`moved ${okMove}/${vetoedMove} to xPos ${layout.getLayout().windows[0].xPos} | resized ${okResize}/${vetoedResize} to xSize ${layout.getLayout().windows[0].xSize} | cancelled-move ${cancelledMove.join(',')} | cancelled-resize ${cancelledResize.join(',')} | moved-events ${moved.length} | resized-events ${resized.length}`);

move(id, to) resolves to a resize or a move from what changed. The first move and the first resize both succeed and fire onWindowMoved/onWindowResized once each; the second of each is vetoed by its own before-hook - onBeforeWindowMove never sees the resize and onBeforeWindowResize never sees the move - firing onWindowMoveCancelled/onWindowResizeCancelled with the veto's reason and leaving the window exactly where it was.

Close before-event and layout:changed, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { document, root } = createTestDom({ width: 600, height: 400 });
const host = document.createElement('div');
root.appendChild(host);
const closed = [];
const cancelledClose = [];
const changed = [];
const layout = createLayout(host, {
  columns: 4, rows: 4, compact: 'none',
  windows: [
    { id: 'a', xPos: 1, yPos: 1, xSize: 1, ySize: 1, closable: true },
    { id: 'locked', xPos: 2, yPos: 1, xSize: 1, ySize: 1, closable: true },
  ],
  onWindowClosed: (e) => closed.push(e.id),
  onBeforeWindowClose: (e) => (e.id === 'locked' ? e.preventDefault('unsaved') : true),
  onWindowCloseCancelled: (e) => cancelledClose.push(e.reason),
  onLayoutChanged: (e) => changed.push(e.cause),
});
const okClose = await layout.close('a');
const vetoedClose = await layout.close('locked');
return (`closed ${okClose}/${vetoedClose} | ids ${closed.join(',')} | cancelled ${cancelledClose.join(',')} | changed-causes ${changed.join(',')} | remaining ${layout.windows().join(',')}`);

Closing a succeeds, firing onWindowClosed and onLayoutChanged (cause 'close'); closing locked is vetoed by onBeforeWindowClose, firing onWindowCloseCancelled with the reason instead, and it survives in windows().

The insights panel: element, tools, enable, maxColumns, reconcile, onNarrative, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');
const dom = createTestDom({});
const el = dom.document.createElement('div');
const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'a' }, { field: 'b' }],
  rows: [{ id: 1, a: 1, b: 2 }, { id: 2, a: 3, b: 4 }],
});
const narrated = [];
const ai = createAI(grid, {
  ask: async () => ({ text: 'There are 2 rows. Confidence 900%.' }),
  element: el,
  tools: false,
  maxColumns: 1,
  reconcile: 'flag',
  enable: ['narrative'],
  onNarrative: (r) => narrated.push(r.text),
});
ai.insights();
const result = await ai.explain({ kind: 'view' });
const cappedFacts = ai.facts({ kind: 'view' }).facts.length;
const uncapped = createAI(grid, { ask: async () => ({ text: '' }) }).facts({ kind: 'view' }).facts.length;
return (`${result.text} | narrated ${narrated.length} | flagged ${result.flagged.join(',')} | panel ${!!el.querySelector('.lat-ai__btn')} | facts ${cappedFacts}/${uncapped}`);

element + tools: false (packet mode, no function-calling) are what make ai.insights() mount a real panel button; enable: ['narrative'] is what lets that mounting succeed at all - leaving it out of enable would return with no panel. enable gates only the three DOM-mounting convenience methods (insights(), askBar(), actorBar()): the ai.explain() call right below still runs and returns a result even though 'insights'/'query'/'ask'/'actor' are absent from this enable list - the programmatic API is never gated, so a host that wants no AI surface at all simply never calls these methods. reconcile: 'flag' keeps the ungrounded "900%" in the text (the default strips it instead) while still reporting it in flagged; onNarrative fires with the same result explain() returns; maxColumns: 1 is why the capped run gathers 12 facts against 34 uncapped.

Ask-your-data: autoApply, schemaOptions, redact, router, onQuery, onError, executed

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createDataRouter } = await import('../packages/modules/data-router/index.js');
const { createAI } = await import('../packages/modules/ai/index.js');

const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'region' }, { field: 'ssn' }],
  rows: [
    { id: 1, region: 'EMEA', ssn: 'a' },
    { id: 2, region: 'AMER', ssn: 'b' },
    { id: 3, region: 'EMEA', ssn: 'c' },
  ],
});
const chart = createHeadlessGrid({ rowKey: 'id', columns: [{ field: 'id' }, { field: 'region' }] });
const router = createDataRouter({ rowKey: 'id', overlap: true });
router.attach(chart, () => true);

const errors = [];
const queried = [];
let capturedSchema = null;
const ask = async (req) => {
  capturedSchema = req.schema;
  return { actions: [{ type: 'setFilters', filters: { col: 'region', op: 'eq', value: 'EMEA' } }] };
};
const ai = createAI(grid, {
  ask, router, autoApply: true, schemaOptions: { maxColumns: 2 }, redact: ['ssn'],
  onQuery: (r) => queried.push(r.ok), onError: (e) => errors.push(e),
});
await ai.query('EMEA only');
const chartIds = [];
for (let i = 0; i < chart.rows.count(); i++) chartIds.push(chart.rows.get(i).key);
return (`queried ${queried.join(',')} | schema-cols ${capturedSchema.columns.map((c) => c.id).join(',')} | chart ${chartIds.sort().join(',')} | errors ${errors.length}`);

schemaOptions: { maxColumns: 2 } is why the model is shown only id,region - ssn is also stripped by redact, so it never reaches the schema either way; autoApply runs the safe read the moment it resolves, with no confirm step; router, configured once here rather than passed to every call, is what fans the answer to the chart with no opts.router anywhere in this example; onQuery fires with the result, and onError is wired but silent because nothing failed.

The governed actor: onProposal, executed

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: 'name' }, { field: 'score', type: 'number', edit: { enabled: true } }],
  rows: [{ id: 1, name: 'Alpha', score: 10 }],
});
const proposals = [];
const ask = async () => ({ structured: { edits: [{ match: 'Alpha', column: 'score', value: 50 }] } });
const ai = createAI(grid, { ask, onProposal: (r) => proposals.push(r.ok) });
const result = await ai.propose('set Alpha score to 50');
const report = await ai.applyProposal(result);
return (`proposals ${proposals.join(',')} | diff ${result.diff.map((d) => `old ${d.oldValue} new ${d.newValue}`).join(',')} | applied ${report.applied} | score-now ${grid.rows.byKey('1').data.score}`);

onProposal fires with the built diff before any approval; applyProposal is the separate human-approval step that actually writes, through the grid's own gated edit path.

The tile hierarchy: tiles, an explicit separator, expanded, onNodeToggle, executed

const { createKPI } = await import('../packages/modules/kpi/index.js');

const HOSTS = [{ id: 1, cpu: 91, mem: 40, lat: 12 }, { id: 2, cpu: 30, mem: 55, lat: 40 }];
const toggled = [];
const kpi = createKPI(null, {
  rows: HOSTS, rowKey: 'id',
  tree: { separator: '/', expanded: true },
  tiles: [
    { id: 'compute/cpu', label: 'cpu', aggregation: 'max', field: 'cpu' },
    { id: 'compute/memory', label: 'memory', aggregation: 'avg', field: 'mem' },
    { id: 'network/latency', label: 'latency', aggregation: 'max', field: 'lat' },
  ],
  onNodeToggle: (e) => toggled.push([e.key, e.expanded]),
});
const topLevel = kpi.nodes().map((n) => n.label).sort();
const key = kpi.nodes()[0].key;
kpi.toggle(key);
return (`${topLevel.join(',')} | tiles ${kpi.model.tiles.length} | toggled ${toggled.map((t) => t.join(':')).join(',')}`);

tiles declares the three measured leaves; separator: '/' is what derives compute/network from ids that only contain /, not the default .; expanded: true opens every branch at construction, so the very first toggle() call closes one rather than opening it; onNodeToggle reports exactly that.

Grid-bound events: fields, onTileClick, onTileDblClick, onTileContextMenu, onChange, executed

const { createTestDom, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createKPI } = await import('../packages/modules/kpi/index.js');

const dom = createTestDom({});
const el = dom.document.createElement('div');
const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ id: 'id', field: 'id' }, { id: 'priority', field: 'priority' }],
  rows: [{ id: 1, priority: 'P1' }, { id: 2, priority: 'P2' }],
});
const clicks = [];
const dbl = [];
const ctx = [];
const changes = [];
const kpi = createKPI(el, {
  grid,
  fields: ['priority'],
  tiles: [{ id: 'p1', label: 'P1 jobs', aggregation: 'count', filter: (r) => r.priority === 'P1' }],
  onTileClick: ({ id }) => clicks.push(id),
  onTileDblClick: ({ id }) => dbl.push(id),
  onTileContextMenu: ({ id }) => ctx.push(id),
  onChange: (e) => changes.push(e.model.tiles[0].value),
});
const fig = el.querySelector('.lat-kpi__tile');
fig.dispatchEvent(new TestEvent('click', {}));
fig.dispatchEvent(new TestEvent('dblclick', {}));
fig.dispatchEvent(new TestEvent('contextmenu', {}));
return (`p1-jobs ${kpi.value('p1')} | click ${clicks.join(',')} | dbl ${dbl.join(',')} | ctx ${ctx.join(',')} | changes ${changes.length}`);

fields: ['priority'] is what lets the tile's filter read priority at all on a grid-bound panel - a field a tile does not itself declare is otherwise not projected; the three pointer events each route to their matching config callback, and onChange fires once, at construction.

A host catalogue and an unmeasured tile: messages, nullText, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createKPI } = await import('../packages/modules/kpi/index.js');

const dom = createTestDom({});
const el = dom.document.createElement('div');
const HOSTS = [{ id: 1, cpu: 91, mem: 40 }];
const kpi = createKPI(el, {
  rows: HOSTS, rowKey: 'id',
  tree: { expanded: true },
  nullText: 'n/a',
  messages: {
    t: (key, params) => {
      if (key === 'kpi.status.critical') return 'kritisch';
      if (key === 'kpi.node.worst') return `schlimmster Status ${params.status}`;
      return key;
    },
  },
  tiles: [
    { id: 'compute.cpu', label: 'cpu', aggregation: 'max', field: 'cpu', thresholds: { warn: 70, critical: 90, direction: 'lowerIsBetter' } },
    // A tile whose field names no column any row carries: measures nothing.
    { id: 'compute.disk', label: 'disk', aggregation: 'max', field: 'disk' },
  ],
});
const compute = kpi.nodes()[0];
const diskTile = kpi.tile('compute.disk');
return (`${el.querySelectorAll('.lat-kpi__node')[0].getAttribute('aria-label')} | disk-formatted ${diskTile.formatted} | disk-status ${diskTile.status}`);

messages translates the node's accessible name (falling back to English for a key the host catalogue omits); nullText is what the unmeasured disk tile renders instead of a fabricated zero. The heading counts that tile among the ones it could not grade - 1 unknown, beside the worst status it did grade - because a leaf with no reading is one of the two things a parent has to report, and a heading that named only the severity would be telling a reader the other leaf agreed.

What the movement line prints against a baseline: delta, executed

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createKPI } = await import('../packages/modules/kpi/index.js');

const dom = createTestDom({});
const el = dom.document.createElement('div');
// A rate series (4.10 vs a 4.30 baseline a year earlier): the percentage of a
// rate is meaningless, so a host names 'absolute' to keep the line without it.
const kpi = createKPI(el, {
  rows: [{ id: 1, rate: 4.10 }], rowKey: 'id',
  tiles: [
    { id: 'both', label: 'Default', aggregation: 'max', field: 'rate',
      baseline: 4.30, format: { decimals: 1, locale: 'en-US' } },
    { id: 'absolute', label: 'Difference alone', aggregation: 'max', field: 'rate',
      baseline: 4.30, format: { decimals: 1, locale: 'en-US' }, delta: 'absolute' },
    { id: 'relative', label: 'Percentage alone', aggregation: 'max', field: 'rate',
      baseline: 4.30, format: { decimals: 1, locale: 'en-US' }, delta: 'relative' },
  ],
});
const lines = ['both', 'absolute', 'relative'].map((id) => {
  const fig = [...el.querySelectorAll('.lat-kpi__tile')].find((f) => f.getAttribute('aria-label').startsWith(
    id === 'both' ? 'Default' : (id === 'absolute' ? 'Difference' : 'Percentage')));
  return `${id}:${fig.querySelector('.lat-kpi__delta').textContent}`;
});
return lines.join(' | ');

delta: 'absolute' | 'relative' | 'both' (default 'both', unchanged) chooses what a tile's movement line prints against its baseline - the difference alone, the percentage alone, or both together, exactly as before this option existed. The arrow and its colour follow the sign of the difference in every mode.

A stat tile in full: kind, aggregation, field, baseline, thresholds, bands, sparkline, executed

const { createKPI } = await import('../packages/modules/kpi/index.js');

const READINGS = [
  { id: 1, host: 'a', hour: 1, cpu: 41, up: true },
  { id: 2, host: 'a', hour: 2, cpu: 58, up: true },
  { id: 3, host: 'a', hour: 3, cpu: 77, up: true },
  { id: 4, host: 'b', hour: 1, cpu: 12, up: false },
];
const kpi = createKPI(null, {
  rows: READINGS, rowKey: 'id',
  tiles: [
    { kind: 'stat', id: 'cpu', label: 'CPU', aggregation: 'max', field: 'cpu',
      filter: (row) => row.up, baseline: 50, delta: 'absolute',
      thresholds: { warn: 60, critical: 85, direction: 'lowerIsBetter' },
      sparkline: { x: 'hour', y: 'cpu' } },
    { kind: 'stat', id: 'spread', label: 'Spread', aggregation: 'avg', field: 'cpu',
      bands: [{ max: 40, status: 'good' }, { min: 40, max: 60, status: 'warn' },
        { min: 60, status: 'critical' }] },
  ],
});
const [cpu, spread] = kpi.model.tiles;
return (`cpu ${cpu.value} ${cpu.status} | delta ${cpu.delta}`
  + ` | spark ${cpu.sparkline.join(',')} | spread ${spread.value} ${spread.status}`);

kind: 'stat' is the default and is written here only to sit beside the clock tile below. aggregation and field are the measurement; the filter is what makes the CPU tile read 77 rather than the whole panel's rows; baseline: 50 is what the movement line is measured from. thresholds grades against two cut points - here lowerIsBetter, so 77 is a warning - while bands is the explicit alternative, a list of half-open [min, max) ranges, first match winning. sparkline plots the tile's own rows in x order.

A feed that went quiet: maxAge, ageBy, executed

const { createKPI } = await import('../packages/modules/kpi/index.js');

const hosts = (at) => Array.from({ length: 200 }, (_, i) => (
  { id: 'h' + i, sev: 3, observedAt: at }));
const panel = (at) => createKPI(null, {
  rows: hosts(at), rowKey: 'id',
  maxAge: 60000, ageBy: 'observedAt',
  tiles: [{ id: 'sev1', label: 'Sev-1', aggregation: 'count', filter: (r) => r.sev === 1,
    thresholds: { warn: 1, critical: 5, direction: 'lowerIsBetter' } }],
});
const quiet = panel(Date.now() - 6 * 60 * 60 * 1000);
const live = panel(Date.now());
const read = (kpi) => {
  const tile = kpi.tile('sev1');
  return `${tile.status} ${tile.value === null ? 'no-number' : tile.value}${tile.stale ? ' stale' : ''}`;
};
const out = `quiet ${read(quiet)} | live ${read(live)}`;
quiet.destroy();
live.destroy();
return out;

Both panels hold the same 200 rows and the same tile, and that tile's filter matches none of them - a count of zero either way. They differ in one thing: when the rows arrived. maxAge (milliseconds) is how long the panel keeps grading what it holds after its feed last spoke, and ageBy names the clock that is measured on - the same two options, with the same two meanings, a source's rolling window takes. Inside the window the zero is graded, and “no Sev-1 incidents out of 200 healthy hosts” reads good, which is the news it is. Past it the panel stops grading: every stat tile reports unknown with no number and stale: true, and the tile captions itself “No recent data”, so a feed that died six hours ago cannot read as a healthy zero under lowerIsBetter cut points or as an alarm under higherIsBetter ones.

Omit ageBy and maxAge measures arrival instead - when rows last reached the panel, through rows.apply, setRows or the bound grid announcing that its own rows changed - which is what a feed with no timestamp column has to be judged on. A filter, a sort, an expansion and a refresh() are not arrivals, so a live feed whose rows are all filtered out of the grid beneath the panel reports the empty panel's unknown (“No data”, stale: false) rather than a silence, and an empty panel never goes stale. Declare no maxAge and the panel judges no freshness at all: nobody has said what recent means, so everything it holds is graded however old it is. A panel with a window checks itself on a low-frequency timer, because a silence is the absence of events and nothing else would notice one.

A clock tile: kind, seconds, date, executed

const { createKPI } = await import('../packages/modules/kpi/index.js');

const kpi = createKPI(null, {
  rows: [], rowKey: 'id', locale: 'en-GB',
  tiles: [
    { kind: 'clock', id: 'utc', label: 'UTC', timeZone: 'UTC' },
    { kind: 'clock', id: 'desk', label: 'Desk', timeZone: 'UTC', seconds: false, date: false },
  ],
});
const shape = (tile) => `${tile.clock.time.split(':').length === 3 ? 'hh:mm:ss' : 'hh:mm'}`
  + `${tile.clock.date === null ? ' no date' : ' with date'}`;
const [full, plain] = kpi.model.tiles;
return `full ${shape(full)} | plain ${shape(plain)}`;

A clock tile measures nothing: kind: 'clock' takes a timeZone and a locale and prints the device clock, the date on one line and the time on the next. seconds: false drops the seconds from the time line and date: false drops the date line entirely, which is what a wall of city clocks along the top of a dashboard usually wants.

A per-route filter and transform, executed

const { createHeadlessGrid } = await import('../packages/core/src/index.js');
const { createDataRouter } = await import('../packages/modules/data-router/index.js');

const grid = createHeadlessGrid({
  rowKey: 'id',
  columns: [{ id: 'id', field: 'id' }, { id: 'type', field: 'type' }, { id: 'amt', field: 'amt', type: 'number' }, { id: 'label', field: 'label' }],
});
const router = createDataRouter({ key: 'type', rowKey: 'id' });
router.attach(grid, 'order', {
  filter: (row) => row.amt >= 20,
  transform: (row) => ({ id: row.id, type: row.type, amt: row.amt, label: `#${row.id}:${row.amt}` }),
});
router.load([
  { id: 'o1', type: 'order', amt: 10 },
  { id: 'o2', type: 'order', amt: 30 },
  { id: 'o3', type: 'order', amt: 20 },
]);
const ids = [];
for (let i = 0; i < grid.rows.count(); i++) ids.push(grid.rows.get(i).key);
return (`${ids.sort().join(',')} | label ${grid.rows.value('o2', 'label')}`);

filter gives the grid only the rows at or above 20 - the route decides what the grid ever sees, before any grid-level filter runs; transform derives the label field the columns declare, reshaping each row on the way in.