Renderers, formatting and charts

API reference › Renderers, formatting and charts

Built-in renderers and editors

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

Cell renderers, for cell.render:

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

grid.formatting

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

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

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

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

Rules that describe the data, not a threshold

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

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

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

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

grid.highlight

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

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

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

Conditional formatting

Rules compile into the function cell.style already takes, so a compiled rule set installs exactly like a hand-written style function.

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

{ field: 'margin', cell: { style: compileRules([
  { when: { op: 'lt', value: 0 },              style: { background: '#fdecea', colour: '#b91c1c' } },
  { when: { op: 'between', value: 0, value2: 5 }, style: { background: '#fdf3e0' } },
  { scale: { min: 0, max: 100, colours: ['#f8f9fa', '#1a6bc7'] } },
]) } }

In-cell charts

Eleven chart renderers for a cell. Each is a single SVG whose path data is the only thing a repaint writes, so they cost the same as any other cell as rows recycle.

{ id: 'trend',  field: 'readings', cell: 'line' }
{ id: 'spend',  field: 'monthly',  cell: { render: 'column', props: { min: 0, max: 100 } } }
{ id: 'mix',    field: 'split',    cell: { render: 'donut', props: { hole: 0.55 } } }
{ id: 'sla',    field: 'uptime',
  cell: { render: 'bullet', props: { target: 80, bands: [60, 85], max: 120 } } }

// When the series lives on another property than the cell's value.
{ id: 'trend', field: 'latest', cell: { render: 'line', props: { series: 'readings' } } }

Built-in names

Every registry accepts a custom entry under the same name, which then wins over ours.

Data types

Seven built-in, and seventy-four in the extended catalogue. Inference only ever reaches the built-in names: the candidates are tried in registration order, and every string settles on text and every number on number before an extended type is reached. So a column asks for an extended type by name.

Editors

Cell renderers

Filters and aggregations

Icons

Inline SVG sprites, overridable by name through registerIcon(name, def).

Styling and your page's CSS

Forced colours. In Windows High Contrast Mode the grid translates state that is normally a background tint into borders and system colours: selection takes the system's own selection colours, pinned regions swap their shadow for a rule, and diff states are told apart by border style rather than by hue. A colour swatch and a collaborator's presence colour keep their own colour, because there the colour is the information.

Every selector is namespaced under .lattice, so the grid cannot restyle your page. Since 1.4.0 the reverse holds too: the elements the grid builds are given a floor for the properties a host page commonly sets on a bare tag: margin, padding, border, radius, background, shadow, text transform, letter spacing, and type and colour on form controls. A rule such as section { padding: 5.5rem 0 } no longer reaches inside the grid.

No !important is involved. The reset is specificity (0,1,1); every rule that dresses a grid element is (0,2,0) or higher, and so is any rule of yours aimed at a Lattice class. Deliberate overrides work exactly as before: only bare-tag rules are shut out. The reset covers box model and decoration only, never display, position or any dimension.