Columns, types and cell rendering

compute is handed the values it declared rather than the whole row, which is what lets the grid memoise it: the same inputs give the same answer, so the result is cached until one of them changes. Reach for ctx.data when you genuinely need the rest of the row, and set pure: false if the result depends on something the grid cannot see.

Declaring deps is what makes this cheap. Without it the grid would have to assume any change might affect any computed column and recompute all of them on every edit. A cycle is caught at compile time with the full path named, rather than becoming a stack overflow at render time.

Ambiguous units are refused, not guessed. A US gallon and an imperial gallon differ by about a fifth, and "ton" means three different masses. Each has its own symbol: gal (US), ton (UK), and the bare word is claimed by all of them, so typing it is rejected rather than resolved. A gal silently taken as US in a UK deployment is data corruption that reads as rounding.

The same rule catches case: mV and MV are a billion apart, so both exact spellings work and the case-folded mv is refused.

Customary units are accepted but never chosen. display: 'auto' walks the coherent SI ladder only. With the calorie, the BTU and the kilojoule all on one ladder, 4,000 J would render as 3.79 BTU: auto picks the largest unit that fits, and the BTU happens to be larger than the kilojoule. Ask for a BTU by name and you get one.

Angles wrap, so their mean is replaced. The average of 359° and 1° is 0°, and the arithmetic answer (180°) is a confident, plausible number pointing in exactly the wrong direction. A degrees or radians column averages by direction instead, and reports nothing where the angles cancel and there is no mean direction to give. The sum stays arithmetic, because a total rotation of 720° is two turns and that is a real figure.

Temperature is its own type, not a unit. Every other unit is a multiplication; Celsius to Fahrenheit carries an offset, and zero Celsius is not zero anything, so no factor converts it. celsius, fahrenheit and kelvin convert on input: type 72 F into a Celsius column and it stores 22.2, and refuse to be summed: twenty degrees plus twenty degrees is not forty degrees, and a footer saying so would be believed.

What declaring a type buys you, and what it does not. Sorting is not the reason. The default comparator is value-aware, so an undeclared column of numbers already sorts 2.5 before 10 rather than lexicographically, and an undeclared column of IPv4 addresses already orders correctly across 128.0.0.1.

What a type settles is everything around the sort: which editor opens, how typed text is parsed back into a value, how the value is formatted, which filter kind the header offers, how the column is stored, and what lands in Excel and on the clipboard. That is what inference supplies for free on a plain column, and what naming a type explicitly gives you where the data cannot say it, a duration, a byte count, a network address.

The bug it avoids: new Date('2024-03-11') is midnight UTC. Render that in New York and it is the 10th. A user in London sets a delivery date, a colleague in Mumbai opens the same grid and sees the day before. Storing the wall-clock string means the date a user typed is the date everyone sees, because there is no instant to convert.

It is also faster and smaller: ISO 8601 sorts lexicographically in the same order it sorts chronologically, so a date column sorts as text, and repeated dates dictionary-encode well.

When you genuinely mean an instant (a log timestamp) use datetime and set format.timeZone.

radix is 2, 8 or 16, or the names binary, octal and hex. Base 10 is not among them and is not an oversight: a decimal number is what the number type is for, with grouping, decimals, currency and notation that a radix formatter has no concept of. Passing radix: 10 names the supported set in the console and falls back to hex rather than producing something that looks like a number column but is not one.

Variants are semantic tokens rather than colours: danger, not #c22b2b. The theme decides what danger looks like, and it looks the same in the status pill, the filter chip and the validation message. Changing the palette is one custom property, not a search for hex codes.

refresh returning true is the contract that makes recycling work: it means "I updated in place, keep this element". Return false and the grid rebuilds the cell. A renderer that only implements render still works, it is just rebuilt on every reuse.

The flag permits markup, not code. Without it, {{ }} escapes and a {{{ }}} segment is refused outright. With it, an interpolated value may carry presentational markup: <b>, <a href>, a <span>, and everything executable is still stripped from it: <script>, <iframe>, <style> and the other code-bearing tags, every on* handler attribute, and javascript: or data: URLs including entity-encoded spellings of them. The same rules apply to a string returned from cell.render, which is the same gate.

Why the value is treated differently from the template. You wrote the template and can audit it; the value is row data and usually arrives from somewhere you cannot. A template is refused at compile time for a dangerous tag, but that refusal says nothing about what a value interpolated into it might contain.

It is a narrow allowance, not a sanitiser. It exists so a grid cell can show emphasis and a link. To render arbitrary third-party HTML, sanitise it yourself and return an element from cell.render.

Only image URLs load. http, https, blob: and data:image/ are permitted; everything else is refused, including a data: URL claiming to be anything other than an image. Relative URLs pass, since they cannot name a scheme. A grid drawing URLs that arrived in a data feed is exactly where a bad one gets through. Note this differs from the link renderer, which refuses data: outright: correct for an anchor, wrong for a picture.

A missing or broken image never moves the column. The box is sized from the row height whether or not the picture loads, and a failed load leaves it empty rather than showing the browser's broken-image glyph, which is a different size in every engine.

Exports carry the URL. CSV, Excel and the clipboard all get the text, not markup. Values are dictionary-encoded, which pays unusually well here: one URL per user or per company repeats down the whole column.

It needs the room. Two lines do not fit in a 28px row. Pair it with density: 'comfortable' or 'spacious', or a rowHeight of 40 or more. Nothing stops you using it in a shorter row; the second line is simply clipped.

The second line reads the row's data, not another column. It is usually a field nobody wants a column of, and requiring one would mean declaring a column purely to hide it. A path that does not resolve leaves the line empty rather than throwing, and a cell with no second line collapses to one centred line rather than leaving a gap.

Both lines truncate; neither wraps. A wrapped second line would change the row height, and in a fixed-height grid that means being cut off mid-descender instead. The accessible name carries both lines as one string, so a screen reader gets the half of the cell that disambiguates the first.

The template compiles; it does not call back. There is deliberately no "here is a container, build what you like for this row" hook. That shape is easy to offer and would be used to allocate DOM per row, and at that moment the virtualisation stops paying for itself: quietly, and in a way nobody can attribute to a change. A row template is the same declarative string a cell template is: parsed once, built into real DOM the first time an element is used, and afterwards updated by writing text into the few nodes the bindings own. Scrolling ten thousand records through a hundred pooled cards allocates nothing.

Everything underneath is unchanged. Sorting, filtering, grouping, selection, permissions, redaction, saved views, undo, export and the remote source all apply exactly as they do to a table: only the drawing changes. That is the reason to build a card view on a grid rather than beside one.

It is announced as a list, not a grid. A card has no columns, so the grid role, which promises columns, gridcell children and a two-dimensional keyboard model: would misdescribe it completely. The layer is a list, each card a listitem carrying its position and the size of the whole set, and the column header is not drawn. role and itemRole override both, for a presentation that is really a listbox.

Measured on the container, not the viewport. A media query is the obvious way and the wrong one: a grid inside a 400px panel on a large monitor is narrow, and a grid filling a small tablet is not. The grid already watches its own element for size changes, so the same observer answers this.

The state a user built survives the switch. Rotating a phone must not lose the sort, the filters, the selection or the scroll position, and it does not, it is one grid throughout, and only the drawing changes. An open cell editor is closed, since the cell it belonged to stops existing.

A protected column cannot be read raw. Binding {{data.password}} on a secret or redacted column would print the value the column exists to hide, while the table beside it shows dots. Such a binding reads the masked text instead and says once that it did, a card must not become the hole a redaction closes.

The scroll height counts lines, not records. Four records on a line means the content is a quarter as tall as the row model alone would make it, and a scrollbar sized per record would be four times too long, the last several screens empty. The tiled layout works out its own window from the scroll position for the same reason: the window it would otherwise be handed counts one record per line and would leave the bottom of the screen bare. Pooling is unaffected; scrolling a tiled gallery reuses its elements exactly as a list does.

A full-width row is still one of your data rows. It is counted by rows.count(), sorted, filtered and exported like any other; only its presentation changes. That is the difference between this and pinned rows, and it is the thing to get straight before choosing between them: full-width changes how a row looks, pinned changes whether a row is data at all.

So if your banners must not appear in an export or a row count, they should not be in the data. If they are section headings that belong with the records they head, and should sort, filter and export alongside them: this is the right tool.

One consequence worth stating plainly: sorting reorders banners along with everything else, because the predicate follows the row and not its position. Either do not offer sorting on such a grid, or sort on a key that keeps each section together.

A cell is a few hundred pixels seen for a second, so there are no axes, no gridlines and no legend. The chart carries one idea (a shape, a share, a comparison) and the number beside it carries the precision. Hide the number with label: false when the column next to it already says the same thing.

Pin min and max when columns are meant to compare. A sparkline scaled to its own data fills its cell whatever the magnitude, so two rows differing by an order of magnitude draw identically. Pinning the scale is what makes the column readable down its length rather than only across it.

A gap is not a zero. Entries that are not numbers break the line and omit the bar, rather than being drawn at the baseline: joining across a missing reading would draw a trend nobody measured, and drawing it at zero invents a dip.

Cost. Each chart is one SVG built once, with the paths' d attributes the only thing a repaint writes, and a bar chart is two paths rather than one element per bar. Rows recycle as you scroll, so this is what keeps a chart column the same price as a text one. Nothing measures the DOM, the drawing happens in a fixed coordinate space that CSS scales.

Accessibility. The chart is aria-hidden and the cell carries a summary: "12 points, 9 to 20, ending 18". A path cannot be read aloud, and a series announced value by value tells a listener less than the sentence does.

The operators are the filter's operators. gt, between and contains mean here exactly what they mean in the grid's filters. Anyone who has built a filter has already learned this, and two vocabularies for one idea is how a product ends up explaining itself twice.

First match wins, by default. "Red if overdue, amber if due this week" reads top to bottom and stops, the spreadsheet convention, and the one people expect. stopIfTrue: false lets rules combine: weight from one, colour from another.

A blank cell satisfies no comparison. Number(null) is zero, so a naive implementation sweeps every empty cell into "less than 100" and formats half a column that has no data in it.

Text still compares numerically. A rules panel produces strings, the box the user typed into yields "100", not 100, and comparing those as text puts "9" above "100".

A scale's bounds are given, not derived. Deriving them means scanning the column per cell, and a scale that rescaled as rows were filtered would change a cell's colour without its value changing, the opposite of what the colour is for.

Two scopes, one ordered list. A rule sits on a column id or on '*' for every column. Evaluation joins them: grid-wide first, then the column's own, so a column rule can override a grid-wide one, and stopIfTrue means the same thing across the join as it does within either half.

Saved views and undo came free. The rules are a section of GridState, and both saved views and the undo timeline are built on that. Nothing in the formatting model knows either exists.

Rules must be JSON. style cannot be a function here, because the rules are serialised into views and undo slices. Config-time cell.style still takes one, which is the right home for a rule a user should not be able to change.

Both paths coexist. Where a column has a cell.style and a runtime rule matches, the two are merged and written once; the runtime rule wins for the properties it names and leaves the rest of your styling alone.

Group rows are not formatted. A group row summarises many values rather than being an instance of one, which is the same reason decoration is dropped for it.

The panel is a form over that array and nothing more: every control is one call into grid.formatting, which is what makes each gesture undoable without the panel knowing undo exists. It exposes ordering because ordering is meaning: dragging a rule up can change which of two colours a cell takes.

Icon sets and data bars are column decorations rather than cell styles, the bar and icon decorations already render them, and driving those from the panel needs a runtime column-decoration API that persists and undoes alongside the rules. Building it as a second bar implementation inside the rule engine was the alternative, and the wrong one.

Only tagged columns are ever hidden. That is the rule the whole feature turns on. A financial grid with sixty month columns also has an account name, a total and a variance, and none of those belong to a year: if filtering hid them the view would be useless, and tagging every column merely to keep it visible would be busywork. So "show 2024" does not mean "hide everything else"; it means "hide tagged columns that are not 2024".

The same rule runs the other way: an untagged column you hid yourself stays hidden, because forcing it visible would undo a decision that has nothing to do with tags.

What is not shared is the design. If sort, filters and selection travelled too, this would not be a feature, it would be one grid with extra steps. The reason to have two is that the sections hold different data, so each keeps its own view of it.

Vertical scroll stays independent for the same reason: the grids hold different numbers of rows, and yoking them would make the shorter one run out.