Presence, comments and redaction

API reference › Presence, comments and redaction

grid.presence

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

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

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

The provider

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

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

Positions travel as row keys

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

Idle and removal

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

Locking is advisory

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

What is drawn

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

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

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

grid.comments

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

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

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

The provider

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

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

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

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

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

grid.redaction

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

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

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

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

grid.diff

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