Presentation and timeline: JavaScript Data Grid API

API reference › Presentation and timeline

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, 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 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.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.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();

.my-toast { z-index: calc(var(--lattice-maximise-z) + 1); }

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { document } = createTestDom({ width: 800, height: 400 });
const host = () => { const el = document.createElement('div'); el.style.cssText = 'width:400px;height:200px'; document.body.appendChild(el); return el; };

// `container` fills a host element rather than the viewport; `zIndex` sets the layer.
const panel = document.createElement('div');
panel.style.position = 'relative';
document.body.appendChild(panel);
const h1 = host();
const one = createGrid(h1, { rowKey: 'id', rows: [{ id: 1, name: 'a' }], columns: [{ field: 'name' }], maximise: { zIndex: 500, container: panel } });
flushFrames();
one.maximise.enter();
const a = `z ${h1.style.zIndex} pos ${h1.style.position} in-panel ${panel.contains(h1)} active ${one.maximise.active()}`;
one.maximise.exit();

// The default is the --lattice-maximise-z token (1000) and fills the viewport.
const h2 = host();
const two = createGrid(h2, { rowKey: 'id', rows: [{ id: 1, name: 'a' }], columns: [{ field: 'name' }], maximise: true });
flushFrames();
two.maximise.enter();
const b = `z ${h2.style.zIndex} pos ${h2.style.position} in-body ${h2.parentNode === document.body} active ${two.maximise.active()}`;
two.maximise.exit();
two.destroy();
return `${a}; ${b}`;

grid.overlay

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');

const dom = createTestDom({ width: 400, height: 200 });
const grid = createGrid(dom.root, {
  rowKey: 'id',
  columns: [{ field: 'id' }, { field: 'region' }],
  rows: [{ id: '1', region: 'north' }, { id: '2', region: 'south' }],
  emptyMessage: (ctx) => ctx.reason === 'filtered' ? 'No rows match those filters' : 'No rows yet',
});
flushFrames();
const before = dom.root.querySelector('[data-overlay="empty"]') ? 'showing' : 'hidden';

grid.filters.set({ col: 'region', op: 'eq', value: 'nowhere' });
flushFrames();
const emptyEl = dom.root.querySelector('[data-overlay="empty"]');
const filtered = emptyEl ? emptyEl.querySelector('.lat-overlay-message')?.textContent : undefined;

grid.destroy();
return `before ${before} | filtered ${filtered}`;