Lattice Grid

The grid is checked in the other direction too. auditCatalogue tells you a catalogue is complete: that a translator covered every key. It cannot tell you the grid only ever renders text that came from a catalogue in the first place, and a string written into the source passes every test, because the tests assert on the English the grid happens to produce.

So the build refuses one. Any literal reaching an element's text, or an announced attribute such as aria-label, title or placeholder, has to come from the catalogue. That is what stops a localised grid drifting back into English one plausible change at a time.

Why it matters to you: sorting a column is a sort over one contiguous array of numbers, not a walk over a hundred thousand objects. Filtering produces a bitmask rather than a new array of rows. Both stay fast at sizes where the row-object approach has already given up, and neither allocates much, so the browser is not collecting garbage while the user is scrolling.

Change a sort and the filter stage is not recomputed: its inputs did not change. Edit a cell in a column nobody sorts, filters or groups on and none of the first five run; only the totals move. This is why a grid that is heavily filtered and grouped still feels immediate when you type in a cell.

A large share of enterprise line-of-business frontends are built without a bundler, and they are usually treated as second-class by grid vendors. Here the script tag is the first example in the documentation, not an appendix.

On rowKey: it names the field that identifies a row. Set it if you have one. Without it the grid assigns keys per row object, which is enough for sorting, filtering, selection and copying within a session, but not across a reload, because new objects are new rows. Change tracking, streaming dedupe, selection persistence and remote reload all want a real key, and the grid warns once, naming them.

You pass the framework in. Every adapter is a factory taking the framework and createGrid, rather than importing either. Lattice ships zero dependencies and the bundler rejects bare specifiers outright, so an adapter could not import React from 'react' even if it wanted to. The same choice keeps each bundle small: the bundler inlines whatever it can resolve, so an adapter that imported the grid would carry a second copy of it. Passing both in leaves each adapter a few kilobytes of glue, and means the adapter cannot disagree with the grid version you already loaded.

Hold your props steady. Change detection is reference equality, because deep-comparing a million-row array on every render would cost more than the reload it avoids. Build columns once outside the component, or memoise it; a fresh array literal on each render tells the grid the columns changed and it will rebuild them. Rows are the same: hand back a new array when the data actually changes, not before.

StrictMode is handled. React 18 deliberately mounts, unmounts and mounts again in development; the effect cleanup destroys the first grid, so the second starts clean and nothing leaks.

Every viewer is a component now. Before 1.63 the adapter wrapped createGrid and nothing else, so a React application wrote its own useEffect for the KPI panel, for each chart, for the board, for the Gantt — and its own tab strip, because the tabs module builds its tabs' grids itself and a grid built that way is not a component. createLatticeKPI, createLatticeChart, createLatticeKanban, createLatticeGantt, createLatticeLayout and createLatticeTabs each return one component; createLatticeViewer is the generic behind them, for anything not yet named, and createViewerController is the framework-free lifecycle underneath.

A viewer finds its grid through context, not a ref. A KPI panel and a chart are built against a grid instance, and that instance does not exist until after the first render. Writing to a ref re-renders nobody, so a sibling never learns the grid arrived. createLatticeGridContext returns { LatticeGridProvider, useLatticeGrid }: a grid publishes itself under its name, a viewer takes it by gridName, and the viewer is built the moment it appears. A page with one grid names nothing.

A tab's content is yours. createLatticeTabs keeps the module's tablist semantics, keyboard handling, lazy first mount and live badges, and renders each tab's React content into the module's own panel element through a portal — so a tab's grid is a real <LatticeGrid> with props, a ref and the surrounding context. A tab with no content is left to the module, so both kinds mix on one strip.

The router is owned by a hook. createLatticeRouter returns useLatticeRouter, which creates the router in an effect and destroys it in that effect's cleanup — never in a useState initialiser, which React calls more than once by design and whose discarded copy is never destroyed. It returns null on the first render and the router on the second. <LatticeGrid route="…"> attaches to whichever router LatticeRouterProvider published, and detaches before the grid is destroyed so the router never holds a dead grid.

A live feed needs no ref. rowUpdates is a keyed diff handed to grid.rows.apply() whenever the object's identity changes. predicates maps { name: fn } to grid.filters.where(name, fn), which composes with whatever filter the reader set — unlike the filters prop, which replaces the whole tree.

What is a live prop is declared, not guessed. The grid takes any changed configuration key through one call; no other viewer does. So each viewer lists the props it can take while running (VIEWER_APPLY) and everything else is mount-time configuration. A mount-time prop that changes is neither ignored nor silently remounted: it is named once, with the remedy — a key that changes when you want the rebuild, or the ref. VIEWER_EVENTS and viewerHandlerName are the matching event surface (card:move becomes onCardMove), and DEFAULT_GRID_NAME is the name a grid publishes under when you choose none.

React 18 and 19, client only. Nothing uses an API added in 19 or removed in 19. Every component owns a real DOM element, so there is no SSR and no React Server Component support.

Events are re-emitted under dashed names: cell:changed becomes @cell-changed, because a colon in a Vue template is directive syntax and cannot be bound. Every event in the table below is declared in emits.

An action, not a component. Svelte's action contract is { update, destroy } over a node the caller already owns, which is exactly the shape of the work: create, push changes, tear down. A component wrapper would add an element and a props layer to arrive back at the same three calls. It is also the only adapter here that needs nothing but createGrid, since an action is a plain function with no framework runtime behind it. Grid events arrive as CustomEvents on the node, with the grid event as detail. If you want a component, four lines around this gets you one.

Reaching the grid. The action's return value is Svelte's { update, destroy } and cannot carry the instance, so — at parity with React's ref.current.grid and Vue's expose({ grid }) — there are two documented routes to the same object the vanilla examples use, for charts, statistics and imperative pivot. Pass an onGrid callback in the action params and it is called once with the live grid the moment it is created (synchronously, before the first render); it is consumed by the adapter and never reaches the grid config. Or read it off the ready event, whose detail carries { grid } alongside the event's own fields — ready fires a turn later, so use onGrid when you need it up front.

What the adapters do not do. They add no features and wrap no API: the grid instance is the same object the vanilla examples use, and anything without a prop is reached through it directly — via the ref in React, expose in Vue, or onGrid / the ready event in Svelte, as the table above shows. Nothing is proxied, so nothing can lag behind the grid.

Do not load it alongside createGrid in the same page. You would get two independent copies of the grid, and the cost is not the download, it is that each copy keeps its own registries. A renderer, editor, data type or variant registered through one is invisible to the other, and a licence key validated in one is not validated in the other. Nothing errors; the custom renderer you registered simply never appears.

Pick one route per application. The other three adapters take createGrid as an argument and so share whatever copy you already loaded, and can be mixed with direct API use freely.

What is covered: column definitions (header, width, sortable, resizable, hidden, editorType, editorConfig, options, template, summary); .data's add/update/remove/ removeAll/parse/load/find/ findAll/exists/getItem/getId/ getIndex/getLength/forEach/serialize/ sort/filter/resetFilter; .selection's setCell/getCell/getCells/isSelectedCell/ removeCell; .history's undo/redo/ canUndo/canRedo/clear/getHistory; .export.csv/.xlsx; and the events cellClick, cellDblClick, cellRightClick, afterEditStart, afterEditEnd, afterSort, filterChange, afterColumnDrop, resize, afterResizeEnd, afterColumnHide, afterColumnShow, afterExpand, afterCollapse, afterSelect, afterUnSelect, afterCopy, afterRowDrop and scroll. Grid-level dragItem: 'row' becomes rowReorder: true: same-grid drag-to-reorder.

cellClick, cellDblClick, cellRightClick, afterEditStart, afterEditEnd and afterSort call your handler with dhtmlx's own positional arguments: (row, column, event), not Lattice's own event object, because that is dhtmlx's own documented signature for them. afterRowDrop calls your handler with (data, event), firing from either a same-grid reorder settling or a row landing here from another grid, dhtmlx has one event name for what Lattice models as two. Every other mapped event calls your handler with Lattice's own event object, under Lattice's own field names, since a wrong guess at a fabricated positional shape is worse than an honest one.

Index means current display order: after sort, filter and grouping: everywhere .data takes or returns one. dhtmlx is not fully consistent about this across its own methods; this is the one meaning, held everywhere.

Cross-grid dragging needs an explicit rowTransfer. dhtmlx lets any two grids with dragItem: 'row' on the same page exchange rows by default; Lattice's rowTransfer is deliberately opt-in per pair, with no dhtmlx property to derive it from, so a caller wanting that behaviour passes rowTransfer straight through as a bonus config key.

What is not. Every before*/can*/cancel* event is unmapped: dhtmlx's convention lets a handler return false to cancel the action, and Lattice has no cancelable-event model to honour that with: approximating one would silently ignore a return false a caller depends on. Row and column drag-negotiation events (beforeRowDrag, dragRowOut, canRowDrop, cancelRowDrop, beforeRowDrop and their column equivalents) are unmapped for the same reason: each can refuse or steer a drag mid-gesture, which Lattice has no live protocol to offer. export.pdf() and export.png() throw: there is no raster export to translate to. .rangeSelection is offered on a best-effort basis and its range shape is this wrapper's own design, not dhtmlx's, a genuine RangeSelection module is a separate part of dhtmlx's own product, and this wrapper does not know its exact shape. Classic dhtmlXGridObject (pre-Suite 5, string-configured, index-addressed) is a different product in every respect that matters here and is not covered at all.

Calling an unmapped event name does not fail silently: the first subscription logs which name has no Lattice equivalent, so a caller relying on it finds out in development rather than in production.

One file, not two. autoInit comes from modules/htmx itself here, not from the base package: this module already carries a complete, independently-bundled copy of createGrid and everything it depends on, the same way every module built this way does (a bundle inlines what it imports; it has no way to reach across to a copy some other <script> tag happens to have loaded). Left unexported, a page using htmx integration would load that engine twice: once for modules/htmx, again for the base package's own createGrid. This module re-exports createGrid, autoInit, hydrateTable, readTable, serialiseState and restoreState precisely so a page never has to choose between the two, it is the complete package for anything touching htmx, not an add-on alongside the base one.

Surviving a swap. autoInit(root) builds a grid on every [data-lattice-grid] element under root it has not already built one for: idempotent, so calling it again after a swap only picks up what is new. A sibling <script type="application/json" data-lattice-config> supplies columns and options; without one, a <table> element is hydrated instead, reading its header row for columns and its body rows for data, then replacing itself with the grid. Once imported, this module listens for htmx's own htmx:beforeCleanupElement and htmx:load and calls grid.destroy() / autoInit at the right moments automatically, a grid inside a swapped-out subtree is torn down before htmx detaches it; a grid inside newly-loaded content is built without re-scanning the whole page. A page with JavaScript disabled sees the plain <table>, still readable, since it is only ever replaced once the grid has actually mounted.

Finding a live grid from its element works everywhere in this library, not just through autoInit: element.__lattice holds the instance for any element createGrid was called on, and is cleared when the grid is destroyed.

Two triggers, two elements, deliberately. A sort or filter change and a scroll asking for more rows are different operations: one replaces every loaded row, the other appends to them, and there is no way to tell the two apart once a response has landed if they share a trigger. Each function configures the request (offset, limit, sort, filters, a small, stable convention any server-side language can read with a JSON parser and a slice) and reads the response back into the grid itself, so hx-swap="none" is required on both: htmx sends the request and nothing else, since a grid is not an HTML swap target.

The sentinel's own trigger names two events for a reason. revealed is htmx's own once-per-element mechanism and gets the very first chunk, firing the moment htmx has processed the element: reliable because it needs nothing from this module's own timing. Every chunk after that fires through lattice:scroll-near-end, which driveInfiniteScroll dispatches once the grid's own visible row window comes within opts.threshold rows (default 20) of what is loaded. That split matters for a fixed-height, virtualised grid specifically: nothing about it ever leaves the page's own viewport once first revealed: new rows land inside the grid's own scroll area, not the page's, so a page-scroll-only trigger would fire exactly once and then go silent. Reading the grid's own render position instead is what makes every later chunk fire on genuine scroll, not on the repaint a successful load causes by itself.

Out-of-band updates. driveOobUpdates(grid, opts) watches for htmx's own out-of-band swaps landing on an element carrying data-lattice-row="<key>", reads the swapped fragment as that row's cells, and applies it to the grid in place: scroll position, selection and filter state are untouched, since nothing about the view is reloaded.

Browser history. On htmx:beforeHistorySave, every live grid's state (serialiseState: sort, filters, column order and widths, scroll position and selection, base64url-encoded and diffed against defaults so an untouched grid costs almost nothing) is written onto its element as data-lattice-state, which rides along in htmx's own history snapshot. On htmx:historyRestore, it is read back and applied: browser back returns a visitor to the sort, filter and scroll position they had, not a blank slate. A cache miss (the page was re-fetched from the server) restores nothing, since a fresh response is already the truth.

A failed request leaves the grid alone. driveServerMode and driveInfiniteScroll both listen for htmx:responseError/htmx:sendError; the grid's rows are never touched by a failed request, and a recoverable message is shown through grid.overlay rather than the grid going blank.

What this does not do. It does not call fetch or htmx.ajax() anywhere: htmx owns every request end to end; this only supplies the moment and the parameters, and reads the response back in. It does not import htmx: every htmx-specific call goes through globalThis.htmx, read at call time, so loading this module never requires htmx to already be on the page, only to be present by the time a driven request actually fires. It ships as ESM and as a plain <script src> build with no bundler required, with zero runtime dependencies beyond the grid itself and, at call time, htmx, but because it references the grid's own internals directly rather than the copy already on the page, the bundle carries a full copy of the grid core alongside its own code, the same trade-off the web component and dhtmlx wrappers already make.

value and text are different questions and the difference bites people. A currency column's value is 1234.5; its text is £1,234.50. Sorting and filtering use the value. Copying, exporting and searching use the text, because that is what the user can see and what they typed against.

origin tells you where a change came from: 'user', 'api', 'init', 'undo'. It is what stops a feedback loop when you persist changes: a handler that writes to a server on cell:changed should usually ignore its own 'undo' traffic, or at least know that is what it is looking at.

A grid mounted where it has no rendered box paints only a handful of rows, not the whole dataset — by design, not as a bug. The visible row window is computed from the container's own height; a container that is detached from the document, or sits under a display: none ancestor, measures zero, and the virtualiser falls back to a small band around the top of the data (the overscan margin, five rows with the default configuration) rather than nothing at all. A harness that builds a grid off in a hidden or unattached container and then asserts on what is visible reads far fewer rows than it loaded and looks broken; giving the container a real, measured box before asserting is what fixes it. Note that this is about the container having no computed size, not about being visually off-screen: a container positioned outside the browser's visible area with real, explicit dimensions (for example position: fixed; left: -9999px with a width and height) still gets a real box and renders fully.

The in-repo test DOM (testdom.js) is a stub, not a browser, and says so in its own header comment. It implements exactly the surface the renderer touches — element creation, attributes, classList, style, children, textContent, event dispatch, injected geometry, and shims for ResizeObserver and requestAnimationFrame — which is enough to drive the renderer's logic in Node for most of the suite. It does not compute a cascade or a layout, so a class or style change that a stylesheet then overrides, or a box that depends on CSS rather than on the geometry a test injected, is invisible to it; those need the real-browser tests (test/*-browser.test.js) that drive an actual headless Chrome instead. It also does not model real focus semantics — its focus() simply records which element is "focused" with no check for visibility, tab order or focusability. Since BACKLOG-0001181, classList.add does throw on a token containing a space, the same InvalidCharacterError a real DOMTokenList throws, closing the specific gap where a two-word class name passed every headless test and then blanked a real page.

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.

Currency is its own type, not a unit either. A currency's “factor” is an exchange rate that moves, so a value carries an amount and a code and never a fixed factor. The grid ships and fetches no rates: pass a rate source through createCurrencyType({ display, rates }), and a rate that is needed but absent renders as a loud marker (missingRate), never as zero. A column totalling in a display currency refuses to add unlike currencies until every value can reach that currency. The shipped currency, usd, eur, gbp and jpy types cover the single-currency case; a rate table is denominated in a base you can state with rateBase.

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, an audit time) use timestamp — see below. datetime stays a wall clock, deliberately.

Stored as an instant. A value ingests from epoch-millis, a Date, or a zone-bearing ISO string (…Z / …+01:00) and is stored as epoch-millis UTC. Because storage is numeric, sort, filter and compare operate on the instant, never on rendered text — two rows from different origin zones order by true chronology, and changing the display zone never reorders them.

Shown in a display zone you control. The cell renders in the zone resolved by precedence: the column's typeOptions.timeZone, then the grid's config.timeZone, then the viewer's local zone. The resolved zone is nameable (e.g. Europe/London (BST)) so a reader always knows which clock they are reading; set typeOptions.showOrigin: true to also show the origin zone when it differs, and when no origin was recorded the cell says so rather than assuming local.

Grouped by civil day in the display zone. Grouping a timestamp column buckets by civil day by default — group: { granularity: 'week' | 'month' | 'instant', weekStart: 1 } chooses week (Monday-start by default), month, or the exact instant. Buckets are computed by projecting the instant to a civil date in the display zone, so a 23- or 25-hour daylight-saving day still collapses to one bucket rather than splitting.

Excel export. Excel has no zone, so the display-zone wall clock is written as a plain numeric datetime serial (yyyy-mm-dd hh:mm) — what you saw on screen, with the zone named in the docs and column header, never shifted silently to UTC.

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.

An icon set is a restatement of the value, not a replacement for it: the value still renders beside the glyph, and the band's label is set as the glyph's aria-label, so a screen-reader user hears "on target 92%" rather than a bare number with the status lost. The glyphs are the grid's own inline sprites (§16), so an icon set adds no dependency and makes no request. Built-in sets: trafficLights, arrows, trafficArrows, ratings.

A decoration is presentation, so columns.decorate is a live setter like grid.set('theme', …): it is not on the undo timeline and does not travel in a saved view. For conditional styling that a user edits and a view remembers, reach for grid.formatting below, which holds colour and weight rules as durable state.

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.

All of these are re-evaluated on every repaint and remove what they added last time first. That is not caution. Rows and cells come from pools, so an element that carried a class for one row will later carry a different row, a class written once and left alone smears down the grid as the user scrolls.

Why this is needed at all. A grid is mounted inside somebody else's stylesheet. A rule as ordinary as section { padding: 5.5rem 0 }, a marketing page, a CMS theme, a Tailwind preflight: matches by tag name, and the grid builds parts of its own interface from those tags: the tool panel's filter rows are <section> elements. Without the reset, 5.5rem of somebody else's padding lands on every one of them.

The reset uses no !important. It is specificity (0,1,1) and every rule that dresses a grid element is (0,2,0) or higher, so the grid's own styling always wins and the reset only fills a gap. Yours wins too, on the same terms: a rule aimed at a Lattice class, .lattice .lat-cell { … }: outranks it, so overriding the grid deliberately works exactly as before. Only bare-tag rules are shut out.

It touches box model and decoration only. Nothing in it sets display, position or any dimension: those belong to the renderer, and a reset that reached them would break virtualisation rather than protect it.

An update is a patch. Fields absent from it are untouched, so a delta arriving from a websocket or coming back from a save can be applied as-is without reading the row first. This has to be said explicitly because the opposite: assigning the patch over the row: looks identical for a caller who happens to send whole rows and silently destroys data for one who does not.

Coalescing merges fields rather than keeping the last message. A feed sending {price} and {volume} as separate messages inside one window keeps both. Coalescing may reorder work; it may not lose it.

Flushing happens on a frame, with a timer behind it. A queued batch lands on a paint boundary, which is what makes "ten thousand updates, one repaint" true rather than usually true, a timer can fire twice between two paints. But requestAnimationFrame is not guaranteed to fire at all: a backgrounded tab stops firing it entirely. So a frame and a timer are armed together and the first to arrive wins. In a foreground tab the frame always wins, at ~16ms against a 50ms fallback; in a hidden tab the timer keeps the feed applying instead of the grid silently stalling with every caller's promise unresolved.

A long flush defers rather than blocks. updates.budgetMs caps how long one flush spends applying; over budget, the remainder returns to the queue and lands next frame, and the promise a caller is holding resolves when their rows actually land rather than when the first slice does. Slicing is by row and only for updates, a partially applied row is not a state the store should be in, and splitting a structural change would re-run the pipeline twice for one batch. stats().deferrals rising steadily means the feed is arriving faster than the grid can apply it.

Rejections are reported, never thrown. Throwing would abandon the rows that were fine. An update or remove naming a row that is not here is unknown-id; an add whose key already exists is duplicate-id and is refused, because selection, expansion, comments and the key index all resolve one key to one row and admitting a second corrupts every one of them at once.

This runs the minimum pipeline. An update touching no sorted, filtered or grouped column skips those stages entirely and only the totals and the affected cells refresh. Adds and removals are structural and re-run everything.

Removals tombstone in place rather than compacting, so every existing index stays valid, which is what lets selection, expansion state and cached permutations survive a delete.

A remote or paged source holds the page it has fetched, not the whole set, so there is nothing there to walk past the filters. It warns and walks what it has rather than quietly returning the filtered rows, a caller who asked for everything and silently received a subset gets a number that looks entirely plausible and is wrong.

That structure is a published wire protocol, not an internal detail. It is what grid.state.get() serialises, what a saved view carries, and what you can send to a server to evaluate the same filter against the full dataset. A remote source hands it straight to your backend.

There is deliberately no "a filter is present" flag. That flag is a second piece of state describing the first, and the two drift: the classic symptom is a grid that filters while the UI insists it is not, or insists it is filtering while every row passes. Here, registering a predicate is what puts it in force, and removing it is what takes it out.

Migrating from AG Grid's external filter: its three pieces become two. isExternalFilterPresent() goes away, because registration is presence. doesExternalFilterPass(node) becomes the predicate itself. onFilterChanged() becomes deps where the grid can watch the change for you, and reapply(name?) where it cannot.

What travels in a saved view is the name, not the function. state.get() carries where: string[]; your predicates are your code and the grid will not pretend it can serialise them. Applying a view that names a predicate you have not registered reports the skip instead of quietly showing a wider row set, and never removes a predicate the view did not mention.

It answers the question the pivot took apart. Pivoting by Country turns one Sales column into one per country, and the number a reader most often wants next is the one that was there before: sales across all of them. 'before' puts that group at the near edge, beside the row headings; 'after' puts it at the far edge, which is where a spreadsheet puts a grand total.

It costs a column, not a pass. A pivoted group row still carries its reduction over every one of its leaves, which is exactly the total across all pivot values, so these columns read a number that has already been computed. They also count towards maxColumns, since they are columns like any other.

Opt in. Omitted, a pivot has the columns it has always had, so the option cannot quietly change what an existing grid exports or what a saved view restores.

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.

The API. groupColumns(ids, { title, groupId }) wraps columns in a new band or adds them to an existing one; pass id instead of groupId to create a new band with a caller-chosen, stable id you can address later (groupColumns(ids, { title: 'Traffic', id: 'g-traffic' })). ungroupColumn(id) takes a column out (dissolving a band it empties); renameGroup(id, title), dissolveGroup(id) and moveGroup(id, to) do the rest. Each emits columngroup:changed. A band's columns are always contiguous, and a nested band dissolves into its parent, not the root.

The keyboard (WCAG 2.1.1). From a focused header cell: Ctrl+Shift+←/→ groups the column with its neighbour on that side (joining an adjacent band, or forming a new one); Ctrl+Shift+↑ takes it out of its band; and Alt+Shift+←/→ moves the whole band as a unit. Every action is announced through the live region, and a refusal — "not in a band", "cannot be moved there" — is announced too, never silent.

Pinning and visibility. A band lives in one pin region and draws over its visible columns there: hiding a column shrinks the band's span without changing the band definition, and hiding the last visible column hides the band. A band is exposed to assistive technology as one role="columnheader" cell with an aria-colspan.

A string here is markup, and in fullWidth.render it is text. That difference is deliberate, and it is the difference between the two features. A full-width row renders one of your data rows, and §8.9 keeps host markup behind allowUnsafeTemplates everywhere a data value reaches the page. A group heading has no data row at all — the grid synthesised it from the grouping — so its string can only be a template you wrote in your own source. That is the same footing the board's cardRenderer already stands on, and the header this exists for (a chevron, a bar) is unwritable without it. If you interpolate a value that came from outside your application, escape it yourself, or build a node and return that instead.

Your chevron is yours to wire. The grid's own expander binds a click handler to the button it built; a string cannot carry a handler, so that chevron would be dead. Any element in your markup carrying data-lat-group-toggle expands or collapses the group it sits in, and toggle() does the same from a node you built yourself.

leaves() is a function on purpose. A group is unbounded and the renderer runs as rows are painted. Handing every group an array of its members would cost a hundred thousand rows on a heading nobody looked at. Call it when you need the rows; read leafCount when you need the size.

The order is your data, not a view of it. A move reorders the array you gave the grid and tells you it happened; writing it somewhere permanent is yours, because only you know where the order lives. A grid that rearranged rows on screen and stopped there would look finished and lose the order on the next load, which is worse than not offering the feature.

If the save fails, move it back: grid.rows.move(key, from).

Notifications, not gates. None of the four is cancellable and none carries preventDefault. The drop is already vetoable twice over — beforeRowMove for a reorder, beforeRowReceive for a drop into another grid — and a third veto on the same gesture would be a third place to look when a drop does not happen.

rowDrag:moved is coalesced to one event per animation frame, carrying that frame's latest pointer position. A pointer produces several hundred moves a second and a handler that draws cannot usefully run faster than the display, so the rate is capped at the display's rather than the pointer's. The other three fire on the transition itself, and no rowDrag:moved is ever delivered after rowDrag:ended.

Read, measure and draw in these handlers; do not mutate. The drag resolves where it would land against the display order, so changing rows, sort, filters or grouping mid-gesture moves the ground under the drop — and data is the source row's own object rather than a copy, so writing to it edits a row that is still in the grid without announcing the change. Work that changes the grid belongs in beforeRowReceive, which is asked before the insert, or in the settled events afterwards.

The end is always reported. Exactly one rowDrag:ended follows every rowDrag:started, including a release outside every grid, where over is null. A press that never passes the drag threshold is a click and raises none of them; a grid destroyed mid-drag raises no rowDrag:ended.

Off by default, and both ends have to agree. Rows leaving a grid is a data change you have to want: a grid that quietly let its rows be dragged away would lose one to a mis-drag, and there is no gesture a user would think to try to get it back. A one-way relationship is a declaration on both grids rather than a convention, the sender refuses to receive, and the receiver never starts a drag.

The target adds before the source removes. If the add is refused: a duplicate key, most likely: nothing is removed, so a rejected transfer loses no data. The other order would delete a row and then discover it had nowhere to go.

The row object is cloned, not shared. Two grids holding the same object would edit each other's rows through it, which is the sort of coupling nobody goes looking for when a cell changes in a grid they were not touching.

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.

The count and the filter are the same question. The chip is not a second detector: it reads the anomalyFlag shadow column, so the number it shows is the number of rows that column marks, and the click sets a filter on that same column ({ col, op: 'eq', value: true }). The count comes from grid.statistics.anomalies() over the shadow's base column, so the chip adds no detection of its own — the score is the API's, shown with its method, never an opaque verdict.

Off by default, and it draws nothing unless a column carries an anomalyFlag shadow. When more than one does, column names the base to summarise.

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.

The failure this prevents is a confident wrong number. You cannot add decibels: 90 dB and 90 dB make 93 dB, not 180. The mean of a column of rates is not the mean, a 100% conversion on two visits and a 1% conversion on ten thousand average to 1.02%, not 50.5%. Both mistakes produce a plausible figure rather than an error, and a footer nobody can check gets used. A missing total gets asked about; a wrong one does not.

It reuses the totals model, it does not fork it. Every choice drives grid.columns.setTotal(id, name), the same public call the old toggle used, so the footer, the group rows, the pivot cells and the grand total all move together and no aggregation is recomputed here. grid.columns.aggregates(id) returns the list the submenu offers, so a host building its own chooser reads the same answer.

Safety holds on both routes. The submenu only lists meaningful aggregates, and setTotal refuses an unmeaningful named total whether it comes from the menu or from an API caller — the wrong footer cannot be reached from either.

Off by default and non-breaking. Left off, the menu keeps its plain Total this column toggle, so an existing grid is unchanged.

The group subtotals and the grand total can reduce differently. By default one total drives both, and that is unchanged. When a column needs, say, an average per group under a sum of everything, set the two independently with the scope option: setTotal(id, 'avg', { scope: 'group' }) and setTotal(id, 'sum', { scope: 'grand' }). A scope with no override falls back to total, and passing no scope sets the shared total and clears both overrides — so the one-property behaviour is exactly what it was. The same split is declarable on a column as groupTotal / grandTotal, and it persists in saved views alongside total.

This could not be position: sticky. The heading row is very often not in the page at all: the grid renders a window of rows, and a heading five hundred rows above the viewport was recycled long ago. So the pinned heading is synthesised from whichever group the top visible row belongs to, which the grid answers by binary search over an index it builds while flattening the rows, the ten-thousandth row of a group costs what the second one does.

The cap exists because each heading costs a row of viewport. A five-level grouping without one would spend a third of the screen describing what the other two thirds contain.

With retainSource: false alone the saving is only the store's own copy of the object references, not the objects themselves: the source layer and the grid config still hold the array, so whoever handed the grid its rows keeps them alive. dropSourceRows releases those references too, so once the caller lets go the objects can be collected and the grid becomes the sole holder of the data. Reach for it on a large, read-mostly grid where you can let go of the source array and do not depend on caller identity through rows.data().

The request also carries groupBy, groupPath, pivotBy, totals and your own context, so a server that can group and aggregate does that work instead of the browser. Blocks are fetched as the viewport reaches them and cached; changing the sort or the filter invalidates the cache and re-queries.

The filters your callback receives is the same condition tree documented above. You are not handed an opaque object to reverse-engineer, it is the published format, and the same shape you would have written by hand.

Everything is off unless declared. An adapter that declares nothing still works: the grid fetches and does all the work itself. That is the safe direction to be wrong in. Declaring an operator the engine does not really apply is the unsafe one, because the grid will trust it and stop checking.

Splitting a filter is not symmetric. An and group narrows with each condition, so the supported conjuncts go to the engine and the rest stay behind: the engine returns a superset and the grid narrows it. An or group widens with each branch, so pushing only the supported branches would return fewer rows than the filter allows, and the grid cannot recover rows that were never fetched. A disjunction that is not fully supported therefore stays whole on the client. The same asymmetry governs column pruning in the facet path.

Residual work needs the whole result. When anything is left over, the source stops asking for windows and asks for everything, applies the remainder, and pages from what it holds. Filtering a window on the client is not a slower route to the right answer, it is a fast route to a wrong one: the rows that belong on page one may sit on page nine, and the total is whatever the engine happened to count.

from is any FROM expression, so read_parquet('s3://bucket/*.parquet') is as valid as a table name. Values are bound through prepared statements; a connection without prepare is used only for unfiltered queries, because interpolating a user's filter into SQL is the one thing worse than not filtering at all.

Column and table names are checked against an identifier pattern rather than escaped, and a name that fails is refused. Integers past the safe range are kept as strings instead of being rounded into a plausible lie.

A timestamp or date filter is bound through a typed placeholder — "ts" >= CAST(? AS TIMESTAMP) — because a prepared statement binds an ISO string as VARCHAR and DuckDB will not compare that with a TIMESTAMP, TIMESTAMP WITH TIME ZONE or DATE column. The adapter reads the column types once from the engine (DESCRIBE) and falls back to the grid column's declared type, so both a typed and an untyped grid column over a timestamp filter correctly, including a time window. Send instants ending in Z, as the grid's date filter does: the cast is the engine's, and its zone rules apply (see the reference for the TIMESTAMPTZ and naive-string cases).

demo/duckdb.html runs this against a Parquet file of several million readings with no server involved, including a time-window filter on its TIMESTAMP column.

Measured against a 1.5 MB Parquet file on GitHub Pages (BACKLOG-0001324): without LOAD httpfs;, DuckDB-Wasm 1.32.0's default HTTP path issued zero Range requests and read the whole file — 100% — for every query, chip filters included. With it loaded on the connection first, the same query issued 25 Range requests and read 30% of the file. DuckDB-Wasm 1.29.0 read 119% of the file on the same test (its ranges overlapped), so treat the exact percentages as a version's behaviour, not a fixed promise — re-measure against the DuckDB build you ship.

The file host has to cooperate too: it must answer HEAD, advertise Accept-Ranges: bytes, and answer a range request with 206 Partial Content and a Content-Range header (GitHub Pages does all three). Cross- origin, its CORS policy must also expose Content-Range and Content-Length, or the browser cannot read them back. Any of that missing, and DuckDB falls back to a full read with nothing said.

A file registered with db.registerFileBuffer(...) is always downloaded whole, whatever version is loaded or however the host answers: a buffer has already been fetched in full before DuckDB ever opens it, so there is nothing left to range-read. There is no force_download option — it does not exist in DuckDB-Wasm; registering a buffer is the way to force a whole download.

It is off by default and reuses the same whole-result path that residual work already takes: the flag ORs into needsAll, so once the set is held it is ordinary in-memory data and the grid's existing total and statistics kernels reduce over all of it, with no per-stat change. When it is active and within the limits, the whole matching set is covered, so the windowed-statistic warning (BACKLOG-0000731) stays silent — the figure is now honestly whole-dataset.

It is refused loudly, never truncated. A matching set past maxRows or maxBytesEstimate is thrown and surfaced as a source:error with no rows shown, rather than held as a fraction and presented as the whole. A fraction shown as the whole is exactly the silent wrong answer this feature exists to remove, so it is never how the feature fails. For a restAdapter, which cannot compute, this is the only route to a correct whole-dataset statistic.

Off by default, refused loudly. Filtering or sorting a fraction of the result does not lose rows quietly, it returns the wrong rows, so the default throws rather than warns — nothing fails silently (§8) means a wrong answer is never preferred to a visible failure. The fix is an adapter that follows the engine's own paging, or holding the data in memory. allowPartialResults: true is the deliberate opt-out — a caller who accepts the permissive behaviour keeps the warn-once path — and it is never the default. It does not touch the fullDataset memory guard or the no-residual short-return warning, both of which stand regardless.

Why a limit at all. A pushdown source exists so a host does not download ten million rows. Honouring a twinless predicate means holding the whole matching set, so wiring it in without a gate would let one filter function silently convert a windowed grid into a full download — trading one silent surprise for another. Under the limit the predicate really runs and the counts are whole-dataset counts; at or past it the predicate is not applied, the rows it would exclude stay on screen, and one warning names the adapter, the matching-set size, the limit and the way out.

No row total counts as over the limit. The only way to learn the size from an adapter that cannot count is to fetch the set — which is the download being guarded against — so the source refuses rather than guesses its way into it.

A refusal costs nothing extra. Where the predicate alone would force the whole result, the size is learned from a bounded probe that is exactly the window fetch the request would otherwise have made, and that result is used as that fetch. A host over the limit pays what it paid before the gate existed.

Prefer the twin. A predicate registered with a { condition } twin is pushed to the engine, which narrows the fetch itself — no limit applies, nothing is held here, and it works at any size. Reach for whereRowLimit only when what you are testing genuinely cannot be written as a condition. On a paged or remote source the twin is the only route: those hold a block cache indexed by the server's own ranges and cannot run a host function at all, and the grid warns once when you register one without a twin.

Every statistic is classified IDENTICAL (the engine's result equals the grid's own kernel, verified against it on the same data) or MAY-DIFFER (the engine computes it by a method that can differ from the grid's definition — mode returns a value where the grid returns null). The classification drives the docs and build-time provenance, not whether a stat is pushed: that is your choice. weightedQuantile is the one genuine fallback, always client-side, because the engine cannot express the grid's midpoint convention. The published table of every stat, its class and its SQL is generated from one map (STAT_PUSHDOWN) so it cannot drift.

No mixed provenance. An engine figure and a client figure never appear in one result set. Aggregates are pushed only when the filter is fully pushed; a residual filter the engine could not apply forces every aggregate client-side, because an engine number computed over a superset beside a client number over the real set would be wrong-but-plausible. source.lastPlan().aggregates reports, per stat, whether the engine or the grid computed it and the class it was assigned — inspection during the build, not a per-figure runtime marker.

A change is patched, not re-derived. When a row changes in the source, the derived grid updates the groups that row belongs to rather than rebuilding the lot. Five hundred updates against a two hundred thousand row source cost under 300 ms in total. Set refresh to live, manual or a number of milliseconds to change the coalescing; idle is the default and settles to a frame.

manual means the host says when, and rows.load() is how it says it. A manual derived grid never re-derives on its own: the source can filter, edit and tick underneath it and the panel keeps showing what it last derived. Call rows.load() on the derived grid, with no argument, and it re-reads its from there and then and replaces its rows; call it again whenever you want the next reading. A derived grid takes its rows from from, so anything passed to load is not used. The derived grid's own sort and filters stay as they were. Press it as often as you like — the source is left exactly as one press leaves it, and destroying the panel leaves nothing of it attached there.

Derived grids are read-only. There is one copy of the data and it lives in the source. Write there and the derived grid follows: an edit through the source's editing API (edit.setCells, an inline commit, a fill, a paste, an undo, a redo or an optimistic rollback) is announced once per batch, after the per-cell cell:changed events, and the derived grid re-derives once for the batch. A grouped derivation patches the groups the edited rows belong to; a derivation with a where, an unnest, a producer, or an edit to a column the source filters on re-reads in full, at the cost measured above. Use idle when a derived child follows an editable grid. Under live the derivation runs synchronously inside the edit call, so a keystroke's commit on a 200k-row source pays the whole re-read before the editor closes; idle defers it to the next frame and folds a burst of edits into one.

The key comes for free. A derived grid keys on __key, which the source writes onto every row it produces: the group value, the profiled column, or the source row's own key when nothing is grouped. Set rowKey only to override it.

__source is not optional. Every combined row carries it — the entry's label, or its index when unlabelled — and it is an ordinary field to where, groupBy and select. Leaving it out would mean a combined list that cannot say where any row came from, which defeats most of the reason to combine several sources in the first place.

The union of fields, never a merge. A field only one source has is undefined on the others' rows, not fabricated and not type-coerced — two sources disagreeing about what a field means is yours to resolve with map, not something the union guesses at. And there is no dedup: two sources reporting the same fact both appear as separate rows. There is no UNION-vs-UNION-ALL distinction to draw; reach for join when rows should be matched on a key rather than stacked.

The key is namespaced, only where it needs to be. Two sources can easily share row identifiers, so the derived __key is qualified by the source tag when nothing is grouped. Grouped, __key is the group value exactly as it always has been, and rows from different sources landing in the same group is what grouping a union is for, not a collision.

An empty source is fine; a broken one is loud. A source with no rows contributes nothing. A source that throws while being read is named in a console warning and skipped for that pass — a silently missing source would make "worst across both" quietly wrong, so it is reported rather than swallowed.

A cycle is refused when the source is built. If a union's sources include the grid being derived, directly or through a chain of other derived grids, it is refused up front, naming the offending source, rather than being recursed into.

A union never patches — know the cost before you reach for one at scale. A lone from maintains its grouping incrementally: an edit that names the rows it touched re-reduces only the groups those rows belong to. A union does not do this for any of its sources — every change on any parent re-reads and re-derives the whole combined set from scratch. On a synthetic 200,000-row union across four sources, one row changed on one parent cost on the order of 800 ms–3 s (machine-dependent; run node bench/union-parents.mjs against your own shape), against a few milliseconds for the equivalent patched change on a lone from over the same row count. And because a union is watched by as many independent change streams as it has sources, that full-rescan cost is paid once per source that moves, not once per union — four active parents each firing their own updates pay it four times over. Below a few tens of thousands of combined rows this is unlikely to matter; above that, or with several sources each updating on their own live feed, budget for it, keep refresh away from every tick (idle, or a debounce), and prefer fewer, larger sources over many small ones where the shape of your data allows it.

Not supported alongside a union. crossFilter has no single target once there is more than one parent; profile and statistics reduce one grid's own columns. All three are refused with a warning rather than guessed at, and the top-level follow is ignored in favour of each source's own.

A panel does not filter itself. The filter a summary pushes onto its source is excluded when that same summary re-derives. Without that, clicking one region collapses the panel to the single row you just clicked, and there is nothing left to click next. With it, the panel keeps its full set of regions with the chosen one marked, which is what makes a second click possible at all.

Several panels compose. Each pushes its own filter onto the shared source and each excludes only its own, so region and status narrow the detail together while both panels stay navigable.

A left join is usually the one you want. An inner join quietly drops the rows that did not match, and those are often the finding: the site with no owner, the payment with no invoice. left keeps them visible with the partner's fields empty, so the gap is something you can see and sort by rather than something you have to notice is missing.

First match wins. The join is a lookup, not a cross product: a row on the left produces exactly one row out, so a grid of ten thousand rows stays a grid of ten thousand rows and cannot silently multiply.

Both sides are live. A change on either grid updates the join, and it is patched from whichever side changed rather than rebuilt.

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 picker opens when it is asked to. A popup editor, a date, a dropdown, a tree, a colour, a code panel: is its panel: in a cell it opens the moment the cell does, which is right, because the user has just asked to edit that one cell. A form builds every field at once, so on a form the field shows the current value on a control and the panel opens over it when clicked. Choosing puts the panel away again and updates the control.

The panel opens before the record arrives. A click that does nothing for half a second reads as a click that was missed, and the user clicks again. So the panel appears immediately with a loading state and fills in when the record lands.

A failure keeps the panel open and offers a retry inside it. Closing would discard the intent and leave the user nothing to act on but the row they already double-clicked.

And a load that never answers is a failure too. A promise that neither resolves nor rejects is what a dropped request looks like from the page; left alone it spins until the user gives up, which reads as an application that has hung rather than a request that failed. After timeout milliseconds, two seconds unless you say otherwise, the form stops waiting and shows the same message and retry as any other failure. Set timeout: false to wait indefinitely, which is right only where your own loader already has a limit and would rather report that one. A record that turns up after the form gave up on it is discarded rather than dropped into a panel the user may have moved on from.

The form takes the double click. On an editable grid that gesture also opens a cell editor, and the two cannot both own it, a form that quietly did nothing where a cell happened to be editable would be worse than no form. So where rowForm is configured, double-clicking a row opens the form and the cell editor stays reachable by Enter or by typing into the cell. Set trigger: false to leave opening entirely to form.open() and keep double-click for cells.

A form in your own container is not modal. It sits beside the grid rather than over it, so it takes nothing away: it is announced as a region rather than a dialog, and Tab moves out of it into the rest of your page instead of being trapped. Claiming otherwise would tell a screen reader user the page had gone away when it plainly has not. Escape still closes it, and it still takes focus when it opens.

Nothing changes unless you ask for it. With no commit hook the grid behaves exactly as before: the value is written, history is recorded, cell:changed fires, and there is no pending state to think about. Subscribe to cell:changed, fire your request and ignore the result: that keeps working and costs nothing.

The mode is declared, never guessed. A websocket or event-sourced backend acknowledges on a different channel from the one the write went out on, so there is no promise to resolve. confirm: 'manual' says so explicitly. The grid does not infer it from what commit returns, because then a synchronous hook that happens to return nothing would leave every cell pending for ever with nothing in your code that looks wrong. If a write does stay pending, you get a console warning naming the cell: tune the threshold with pendingTimeout.

Rollback goes to the last confirmed value, not the previous one. This is the part that is easy to get wrong by hand. Suppose a cell holding 1 is edited to 2, then to 3, then to 4, all before any answer comes back. If the second write fails, restoring “the value before it” would put back 2, a value the server never held, and one the user has since replaced twice. So each cell remembers the newest value a confirmation has actually vouched for, and a write that a later edit has superseded reports its failure without writing anything back. You will see cell:reverted with applied: false for those.

The rejected value travels on the event as rejected, so you can offer a retry rather than losing what the user typed.

Two behaviours worth knowing. An unconfirmed edit goes through the normal pipeline, so if it changes a sorted or filtered column the row moves immediately and moves back if the write fails. And undo of an in-flight edit issues a compensating write, a fresh write back to the previous value, itself tracked: rather than pretending to cancel a request that has already gone out.

Ctrl+Shift+Arrow is the keyboard form of ctrl-dragging. The first press opens a block at the focused cell without discarding what is already selected; the presses after it extend that block, so holding the chord draws one rectangle rather than a new one per key repeat. A plain Shift+Arrow goes back to extending a single block, and clicking anywhere ends the run.

What multiple ranges do and do not support. Painting, cells() and the status-bar summary all work over the union of the selected blocks. Copy is narrower, because tab-separated text is a rectangle: blocks stacked over the same columns, or joined over the same rows, copy fine, a diagonal pair has no rectangular form, so rangeText() returns '' and clipboard:copy reports reason: 'discontiguous' rather than emitting misaligned rows. Filling is narrower still: with more than one block selected there is no single source to extend, so the fill handle is hidden and fillTo and fillDown decline.

Months step as months. 15 January to 15 February is thirty-one days, and continuing in days would land on 18 March and drift further every step. A month step holds the date the user picked, and clamps where the month is short: 31 January plus a month is 28 February, not 3 March.

Month ends are their own case. 31 Jan, 28 Feb is a month series whose second value has already been clamped, so the two share no day of month and the day-preserving rule cannot see it. Where every source value is the last day of its own month, the fill stays on the month end: 31 March, 30 April, 31 May, and 29 February in a leap year. Values that share a day of month keep the day-preserving answer, so 30 Apr, 30 Jun still gives 30 August rather than the 31st.

One limit worth knowing. Filling upwards is not supported; the handle extends downwards only.

A domain series (order codes, fiscal periods, seat numbers) is not something the grid can infer, so selection.fill takes precedence when you supply it. It must return one value per target row; anything else is ignored in favour of the built-in detection, rather than being partly applied.

Pausing is a button, not a guess. Inferring it from whether the user looks busy sounds friendlier and is wrong in both directions: too broad and a mouse resting on the grid freezes the feed until someone reloads, too narrow and rows jump the instant somebody stops moving in order to read. An explicit control has no heuristic to get wrong and no invisible state to explain.

Merging continues while paused, so a long pause costs one entry per changed row rather than one per update. Forty updates to one row are one row of work when play is pressed, and coalesced is the thirty-nine, which is the number nobody could see before.

Bounding the rows themselves is separate. The log bounds change history; a streaming source also needs to bound row retention, or a grid left up overnight holds every row it was ever sent. Set source.maxRows and the stream becomes a sliding window, dropping the oldest as new ones arrive and reporting how many it let go through evicted on the progress report.

A count window drifts, and it freezes. maxRows equals “the last five minutes” only while the feed rate is steady: a burst silently shrinks the window to two minutes, a quiet spell stretches it to twenty, and the x axis changes span under the reader. Worse, when the feed goes quiet nothing is evicted and the chart stops moving, even though time is still passing — and the silence is usually the thing worth seeing. maxAge is a span of wall clock, so it means the same thing whatever the feed is doing.

An empty reduction is a gap, not a zero. fn: 'avg' above — and sum, mean, min, max, first and last beside it — read as null when a bucket carries no rows to reduce (BACKLOG-0001088), so a producer that has stopped sending is drawn as a break in the line rather than a value dropping to zero, which would read as a real observation nobody made. count and countValues are the deliberate exception: they are already honest at zero, a tally of rows or of values actually present, so reach for countValues when the reading you actually want is “how many arrived” and zero has to be drawn as zero rather than as a gap.

Two bounds, one eviction path. maxAge and maxRows are independent and compose: both are applied on the same pass and whichever bites first is simply the one that drops rows. Neither is silently ignored. Age eviction reuses the count bound’s machinery outright, so evicted on the progress report and the stream:evicted event carry age evictions exactly as they always carried count evictions — an existing “dropped off the back of the window” readout keeps working with nothing changed.

The span is a bound, not a guillotine. A row lives a little past the span before it goes, and two things add to that. First the eviction slack, ten per cent of the span — exactly the overshoot maxRows already allows on its count — so the row permutation is rebuilt once per block rather than once per arriving row. Second, when the feed is idle, up to one tick of the eviction timer, which runs at a quarter of the span clamped to between 50 ms and one second. The real ceiling is therefore about span × 1.1 + tick, and because the tick has a floor it is proportionally larger the shorter the window: about 10% over at a five-minute window, around 1.25× at ten seconds, and as much as ~1.35× at three. That is the deliberate price of an idle grid that costs no CPU, and it is why the number to reach for is the window you want the reader to see rather than a hard retention limit. The chart’s domain is exact either way — it ends at now — so the extra rows sit off the left edge rather than being drawn.

Which clock: ageBy, or arrival. Given ageBy — a column id, a dotted path, or a function of the row returning a Date, epoch milliseconds or an ISO string — the window follows the data’s own clock, so it means what the producer means. That also inherits the producer’s clock skew: if their clock runs five minutes fast, their rows live five minutes longer than yours. Omit ageBy and rows age from arrival time, when the row reached the source. Arrival time needs no timestamp column and cannot be skewed, but it is not event time — a row delayed in transit is treated as young. A synthetic or metric feed usually wants arrival; a log or event feed usually wants ageBy. A row whose time value cannot be read is never aged out: dropping data because a timestamp was malformed is the worse failure.

Out of order is handled, not reordered. With ageBy the row’s clock need not be monotonic in arrival order, so eviction scans the window rather than walking the head; a late row that is already older than the span is dropped on the same pass it arrived on and counted as evicted, rather than being painted and then withdrawn a moment later. Nothing is re-sorted: a row’s position is still arrival order, only its retention is decided by its time.

The chart axis rolls independently. The axis takes the same WindowSpec vocabulary rolling statistics use — window: { kind: 'time', span } — and its domain ends at now rather than at the newest point, which is what makes the chart keep scrolling with zero new rows. It works with or without maxAge on the source; set both to the same span and the retained data and the drawn domain agree. Only kind: 'time' applies to an axis: a count window over a chart is the source’s maxRows, and kind: 'count' is refused with a warning rather than quietly given a second meaning. The x column has to be continuous and carry wall-clock times — a banded or categorical axis has no domain to roll.

A producer whose clock runs ahead. A reading stamped slightly ahead of the viewer’s clock carries the end of the domain forward with it, so the newest mark is drawn. How far is bounded: a quarter of the span (15 s on a 60 s window). A reading further ahead than that is treated as a producer whose clock is wrong — it does not move the window, it is not drawn, and the chart warns once, naming the column, how many readings were left out and how far ahead they were. Without the bound, one device two minutes fast moved a one-minute window past every other device’s recent readings and the chart drew a single dot (BACKLOG-0001123). If every reading in the window is that far ahead the chart shows its empty state, with the same warning. chart.data().windowed counts the readings dropped at either edge of the window. The fix for the warning is the producer’s clock, not a wider window.

The other edge: a producer that has simply stopped. The case above is a clock running fast; the opposite is a feed that has gone quiet for longer than the window (BACKLOG-0001088) — every reading is older than the span, so every mark would fall to the left of the domain, off the plot, while the axes and legend keep drawing as if the chart were healthy. Rather than draw that, the chart shows its empty state and warns once per chart instance, naming the span and how old the newest reading actually is, so a dead feed reads as “no data” rather than as a chart that quietly stopped moving. Two charts bound to the same stale column each get their own warning — the key is scoped to the chart, not just the column, so a dashboard of tiled charts sharing one timestamp column does not lose the second warning to the first.

Idle costs nothing. Both halves advance on a plain interval — a quarter of the window, clamped to between 50 ms and one second — and never on an animation frame. The source’s wake returns after a single number comparison unless a row is actually due, and the chart’s wake does nothing at all when the document is hidden or the chart is detached. Both timers are cleared on destroy. Measured over a five-minute window holding 50,000 rows with no feed at all, the window’s CPU cost is inside the run-to-run noise of the same source with no bound set: under 0.04% of one core (bench/idle-window.mjs).

The log keeps the raw sequence, not the merged one. Merging is right for applying a backlog quickly and wrong for looking at what happened, because the intermediate states are exactly what a time scrubber would move between. It survives the flush, pending is what is waiting, the log is what happened, and it is capped, so a grid paused over lunch holds the recent past and reports how much it dropped rather than taking the tab with it.

Two message kinds, two entry points. A snapshot (the whole current world, sent once on connect or on resume) goes to router.load(rows) — a plain array of records; it re-partitions everything and applies a keyed diff per route, so rows that did not change do not repaint. A delta (an incremental change) goes to router.apply(deltas) — an array of { op: 'upsert'|'delete', row, seq? } — which adds, updates or removes in place by rowKey, moving a row between routes if its partition changed rather than duplicating it. Getting this backwards is the mistake this guide exists to prevent: load() on every message re-partitions the whole world on every tick (correct only for a snapshot); apply() on the opening snapshot never seeds the store, so every route starts empty. There is no third method for “a WebSocket message” — the host reads kind (or whatever field its own wire format uses) and picks one of these two.

No transport lock-in, and that is a benefit, not a gap. The router takes rows, never a URL and never a socket object, so a real WebSocket, an EventSource, a change-data-capture feed, a long-poll loop or an existing message-bus client all wire up the same way — whatever arrives, hand the router the snapshot array or the delta array. Nothing in packages/modules/data-router/ constructs a socket, so nothing there needs to change when the transport does.

Without a seq, two rules to know. Within one apply() call, last-writer-wins per rowKey — the last element of the array for a given key is what lands, regardless of which one is “newer” in real time. Across separate calls (separate socket messages), the router has no way to tell a late, stale packet from a fresh one, so it applies whatever arrives, whenever it arrives — an out-of-order delta lands out of order. Configuring seq (a field name or fn(row)) fixes both: within a batch the router sorts by seq before applying, and across calls it keeps a running seqSeen per record and drops (into router.dropped) anything not newer than what it already applied — which is exactly the reconnect/resume gate below, working the same way for ordinary live reordering.

A fast feed: push plus batch/coalesce. Call router.push(delta) instead of apply() and, with coalesce: true or a batch: { intervalMs } configured, deltas buffer instead of applying immediately; rapid updates to the same key settle to a single apply on the timer (or on an explicit flushStream(), useful for a deterministic point such as an animation frame). With no batching mode configured, push applies at once, so it is always safe to feed a socket through push rather than choosing between it and apply up front.

The pattern is snapshot-plus-replay, and the dedupe gate does the rest. On reconnect, load a fresh snapshot (a keyed diff, so unchanged rows do not repaint) and let the feed replay from around the last known point; any delta the router already applied — because its seq is not newer than what checkpoint() holds for that record — is dropped, so only genuinely new deltas advance the state. seenThrough(mark) primes that same checkpoint from a persisted map (e.g. after a page reload), so an early replay is dropped even before the router has applied anything itself in this session. None of this requires the socket to be gone — the router has no idea whether it is talking to the first connection or the fifth.

addSource(id) returns a per-feed handle — its own load/apply/push/remove — so each socket is wired to its own handle exactly as a single feed is wired to the router directly; the router merges every source into one keyed store, namespaced by key when two feeds' ids could otherwise collide. There is no separate lookup method to re-fetch a handle later — keep the reference addSource returns, the same way the code above keeps orders and inventory.

The API came first and the panel second, on purpose. Instrumentation written behind a UI gets shaped by the layout: it reports what is convenient to display rather than what is true, and it cannot be tested. An API that stands on its own can be asserted against, and the assertion above is not one most grids can support.

Most of it already existed and was unreachable. The renderer had counted cell writes, row updates and paints all along; the column store could already report a real byte footprint per column, summing backing array, presence bitset and dictionary. Neither was reachable from the public API. Exposing what a system already knows is usually a better first move than measuring something new.

Warnings are mostly collection, not detection. The grid has 160 places that warn once per cause, each already carrying a stable de-duplication key, which is exactly the stable identifier a support conversation needs. They went to the console and nowhere else. The console interleaves with your own logging, does not survive a reload, and cannot be asked what it has already complained about. They are now kept as records too.

Every warning names values, not just a condition. "Something is slow" is a warning nobody can act on. Each carries the specific numbers, a stable id, and is dismissible for the session but not permanently, a permanently dismissible warning is one nobody sees again after the person who dismissed it leaves.

The checks are tested for silence as much as for detection. A clean grid must raise nothing. A checker that cries wolf is one developers learn to ignore, and then it is worth less than no checker at all. The accessibility checks found two false positives in themselves during development: first comparing aria-rowcount against the row count when ARIA counts header rows too, then counting header row *elements*, of which a single-level header has three because the header is built once per pinned region.

Instrumentation must not change what it measures. Counters are integers incremented where the work already happened. Render phases are four performance.now() marks around existing sections. Timings are sampled, a bounded window of recent operations, and every report names which of its figures are sampled, because a number whose provenance is unclear is worse than no number. Paint wait is the browser's and is deliberately not claimed.

Render causes are captured, not inferred. By the time a paint runs, several distinct causes have collapsed into the same dirty flags, so working backwards gives a plausible answer rather than a true one. The renderer records the structural reason when the invalidation arrives; the semantic one (filter, sort, data) is only knowable from the event that preceded it, so the DOM layer supplies that and the structural reason is the fallback.

Providers are wrapped where they are installed, not at each call site, so one added later is instrumented by construction. The wrapper returns exactly what the original returned and re-throws exactly what it threw. Failures are kept, because a provider failure is usually swallowed by the host application's own error handling before a developer sees it, and "the grid is behaving strangely" is where that conversation otherwise starts.

The heat overlay uses two colours because there are two findings. A cell written with a value it did not hold is work the grid had to do. A cell rewritten with the value already in it is work it did not. Only the second is waste, and a counter alone will never tell you where it is. The overlay records a baseline when switched on, because otherwise the first paint has nothing to compare against and tints nothing, which reads as broken rather than as empty.

The module imports nothing. Not the grid, not a shared helper. The bundler inlines whatever a module imports: the framework adapters stay small because createGrid is handed to them, while the web component carries the grid with it because it imports it. A devtools module that imported anything from core would put the whole grid inside a bundle whose entire promise is that deployments not using it pay nothing.

The support bundle carries no row data. Configuration, query state, timing, warnings, provider statistics, version and environment, and nothing from your data. Stated as a guarantee because a bundle that had to be inspected for confidential values before sending is a bundle that never gets attached to the ticket.

It observes and never mutates. A configuration editor in a debug panel is tempting and would create a second path into grid state that has to be kept correct forever. No telemetry: nothing leaves the browser unless you export a bundle yourself.

Presence carries intent, never values. This is the line that matters most. A peer's committed edit reaches the grid as data, through the channel you already use for data. Presence is throttled, lossy and ephemeral by design, so a value carried on it is a value that can be dropped, and that is the class of bug that appears once a month in production and cannot be reproduced on demand.

Positions are row keys, resolved against your view at render time. Peers sort and filter independently, so index 12 is a different record on every screen. Publishing an index would put a colleague's cursor on an unrelated row the moment either of you sorted. The cost of this is real: the grid resolves a key to a position rather than reading one, and it is the difference between the feature working and the feature lying.

Idle is measured from when a message arrived, not from what it says. Clocks between clients disagree by seconds routinely and by minutes occasionally. Keying idle detection on the sender's timestamp means a peer with a fast clock never goes idle and one with a slow clock is idle immediately. The sender's timestamp is kept for inspection and decides nothing.

Publishing throttles rather than debounces. A debounce sends nothing until the user stops moving, so every peer sees a cursor that teleports on pause instead of moving. The leading edge goes out immediately and the trailing edge carries wherever it settled.

Publishing stops while the tab is hidden. Nobody is moving that cursor. Receiving continues, so coming back to the tab shows the current state rather than an empty roster filling in slowly.

A peer's cursor is dashed; your focus ring is solid. The distinction has to be in the kind of line, not only its colour. Colour alone fails for anyone who cannot separate two hues and fails for everyone at a glance, and the palette originally contained the exact value of --lattice-focus-color, so the first peer assigned drew a cursor identical to the local user's own selection. An active edit is solid and tinted, because an edit is not a cursor and those two must not be confused with each other either.

Nothing is inserted into the grid. Every treatment is an attribute and a custom property written onto a cell that already exists, drawn with an outline and a pseudo-element. That is what keeps presence from shifting layout, covering an in-cell chart or swallowing a click: none of which survives an implementation that appends overlay elements. The overlay layer is pointer-transparent and presence deliberately does not opt back in; only the roster does, because it is a control.

The roster is the part people use. More than the cursors, in practice. It carries the name as well as the colour, because colour alone is not a signal everyone can read, and it reports peers whose rows are not in your view rather than omitting them, an absent peer reads as a disconnection that has not happened.

A parked cursor does not fade. The label does, after a couple of seconds, because permanent labels over a dense grid are unreadable. The border stays, dims at idle, and goes only on removal: a cursor that vanished while its owner was still connected would report exactly the thing this feature exists to prevent.

Locking is advisory, and the documentation says so because a developer who believes otherwise will skip the conditional write. Presence is throttled and can arrive out of order; two clients can enter an edit in the same instant. What actually resolves the conflict is the conditional write in edit.commit, which returns a conflict and rolls the optimistic edit back. Locking narrows the window. It does not close it. A stale claim is disregarded after a much shorter window than peer removal, because a lock held by someone who shut their laptop blocks a cell nobody is editing.

Not in this release: transport, reconnection or authentication; operational transform or CRDT merging; presence history; text-level cursors inside a cell editor; follow mode; chat.

Comments are not row data, and never enter the column store. They have a different lifecycle: append-mostly, sparse against the row count, carrying their own identity and timestamps, subject to their own permissions, and outliving the values they annotate. Putting them in the store would mean columnarising a field that is empty for almost every row and rebuilding it on every write.

Two levels of data, and only one of them is cheap. The index maps a cell to { count, unresolved, updated } and nothing else; it is consulted on every repaint, so it must never carry bodies. A thread is the bodies for one cell, loaded when the thread opens and dropped when it closes. Holding every thread a user opened would accumulate the whole comment dataset over a long session to render a few triangles.

Stable row identity is a hard requirement, enforced rather than documented. A comment is keyed on row identity plus field. Row index changes under sort, filter and grouping, so a comment keyed on it reattaches to whichever row later occupies that position, and a comment on the wrong row is worse than no comment at all. A grid with no rowKey disables comments and names them in the same single warning as the other identity-dependent features.

Identity has to survive more than the session. Comments outlive the page that wrote them, so a key that is stable only within one load (anything derived from arrival order, for instance) is not enough. Reload the data in a different order and every thread points somewhere else. If you have only used the grid client-side you may never have needed a durable identity before; you do now.

Writes are optimistic, and rejections are taken back. The author sees their own comment at once, faded until the provider confirms. A rejection removes it rather than leaving the grid displaying something the server refused. The same pattern as cell editing, for the same reason.

The grid authorises nothing. A comment may carry can: { edit, delete, resolve } and the affordances follow it, but that is a convenience for the person looking at the screen. It is not a control, and the documentation says so here rather than leaving it to be assumed: hiding a button stops nobody who opens the console. Reject in the provider.

A body is user input that has round-tripped through your storage. That is the exact shape of a stored cross-site script, so the default path sets text and nothing else. Turning on markdown buys emphasis, code and links: three constructs, built as elements rather than parsed as markup, with any scheme other than http, https and mailto refused. A refused link still shows its label, so nothing the author wrote vanishes without trace.

The marker cannot move the cell's contents. It is a corner triangle drawn with a border on a pseudo-element, so it occupies no space in the layout: no shifted text, no rewrapped number, no displaced sparkline. That constraint is why it is a corner rather than a badge: every other position in a cell is already spoken for. Only the corner opens a thread; a click elsewhere belongs to selection, and taking it would make commented cells behave unlike every other cell. The hit region is larger than the drawn mark, because at compact density the triangle is about seven pixels across.

A comment shows the value it was written against whenever that no longer matches the cell. Without it, a note reading "this looks too high" sits beside a number it never described and the reader concludes the comment is wrong. Changing a value never deletes or invalidates a comment.

Filtered-out comments are hidden, not lost, and the grid says so. hiddenUnresolved() reports what is still outstanding on rows the filter is hiding, because a user who filters and sees no markers should not conclude there is nothing left to deal with. The status bar carries this: its comments panel reads “3 unresolved comments on hidden rows” and is silent whenever the count is zero, so a grid with nothing outstanding gains no permanent furniture. The panel is in the default set, and can be placed explicitly like any other:

statusBar: { panels: ['rowCount', 'comments'] }

The count returns zero rather than a number it cannot stand behind: it is only meaningful once the index covers every row, so it stays at zero, and the panel stays silent, until loadAll() has resolved.

The comments-only filter is refused rather than approximated. Restricting the grid to rows carrying comments needs the index to cover the whole row set, not just what has been scrolled past, a partial answer would hide precisely the rows the user opened it to find. Call loadAll() first; until complete is true, filterToCommented() returns false and does nothing.

Comments stay available while streaming, unlike header histograms: a comment does not move when new rows arrive. Index loads for new rows follow the same debounced viewport path. A thread whose row is evicted by a bounded window closes with a short explanation rather than hovering over a row that has gone.

Keyboard and screen reader. Alt+M opens the thread on the focused cell: Alt because the grid binds nearly every unmodified key to navigation and editing. The panel traps Tab, which it has to: the grid behind it is still there and still focusable, so without the trap a keyboard user would be moving through cells with a dialog open over them. Focus returns to the originating cell on close rather than being dropped at the top of the document. Cells announce their comment count and unresolved count through aria-description rather than their label, because the label is the cell's value and burying a count inside it would make every commented cell read as something other than what it holds.

Not in this release: mentions, notifications, rich text, attachments, reactions, row-level and column-level comments, and export of comments. The grid opens no transport of its own: if your application pushes updates, call refresh() and the index reloads.

The column being filtered is not counted against its own filter. Every other active filter applies; that column's own conditions are pruned out of the tree before counting. This is the whole of faceted browsing and it is the part that is easy to get subtly wrong, a self-filtered chart collapses to a single bar the moment you click one, and there is then no way to see what you excluded or to widen the selection. Getting it wrong does not degrade the feature, it removes it.

Pruning is not symmetric across operators. An and group narrows with each condition, so dropping one widens the result, the direction faceting wants. An or group widens with each branch, so dropping one would show fewer rows than the user's actual filter. There is no partial answer that is correct, so a disjunction naming the column is dropped whole.

Bucket edges are placed once and kept. They are computed against the unfiltered column and survive every filter change until the data is replaced. Not only an optimisation: bars that resized on every click would make the chart unusable as a control, because the thing you are pointing at would move as you pointed at it.

Each bar carries two readings. Its full height is the bucket's share of the unfiltered column; the solid fill inside is how much survives the current filters. Either alone misleads: scaling to the filtered maximum draws a full-height chart out of three surviving rows, and scaling everything down together flattens the whole chart into a few pixels the moment anyone filters anything.

The filters are ordinary filters. They go through the same filters.set as everything else, so they undo, serialise into saved views, and appear in whatever filter UI already exists. Nothing downstream can tell a filter made by clicking a bar from one typed into the filter panel. A drag emits a between range rather than a set of bucket indices, so it still means the same thing after the data is replaced and the edges move.

Selection is derived, never stored. Which buckets look selected is read back out of the filter tree. Remove the filter through the filter panel, an undo or a saved view and the chart is correct without anything having to tell it.

High-cardinality columns are refused, and it costs nothing to know. Text columns are dictionary-encoded in the store, so the distinct count is a property read rather than a scan. The first column anyone points this at is a name or an id, and one hairline per customer looks like a rendering fault rather than a distribution. Above cardinalityLimit the chart is suppressed, or shows a top-N with an aggregated remainder if you ask for aboveLimit: 'topN': aggregated rather than truncated, because silently dropping the tail would misrepresent the bars it did draw.

Nulls are never dropped. They land in a terminal bucket, always last, and the counts always sum to the row count. A column where nine thousand of ten thousand rows are empty is a fact about the data, and a chart that quietly showed the thousand would be lying about the shape. NaN joins them rather than forming its own bucket: it is the same answer to the same question.

Live streams suppress the charts. Constantly shifting distributions are unreadable, recounting on every batch is wasteful, and a filter control whose buckets move under the pointer is actively hostile. Filters already made stay applied, because they are ordinary filters. Pausing the stream brings the charts back, a paused stream is a still one: unless you set whilePaused: false.

Counting runs off the main thread above workerThreshold. A distribution was the first work the grid moved to a Worker: nothing waits on a histogram, which is what made it offloadable without an async pipeline. A portable sort — a built-in collation with no custom comparator — now also recomputes off-thread above the threshold, serving the prior order until the new one lands. Filtering and grouping still run on the main thread. The column is copied, or shared where cross-origin isolation makes SharedArrayBuffer available; it is never transferred, because transferring would detach the buffer the grid is still rendering from.

The Worker settings. useWorker and workerThreshold decide whether and when a distribution is offloaded. Two more control how the Worker is built, and both are settled when it is constructed: changing either discards the running Worker so the next offload builds a new one.

grid.diagnostics.renders().worker reports what the Worker host is actually doing: whether one was spawned, how many calls ran locally versus remotely, and the threshold, sharedMemory and workerUrl it was built with.

Server-side sources need a provider, and its absence is silent. A grid holding one page of data cannot compute a distribution over the whole set. Supply a function and it receives the column, the pruned filter state and the bucketing settings, and returns counts. Without one the charts are simply absent, no error, because most deployments will never supply one. Be clear-eyed about the load: results are cached against the filter state, but this is one query per column per filter change, and a grid with eight faceted columns asks eight questions every time a filter moves.

Keyboard and screen reader. Focus enters the chart from the header and arrows move between buckets, so a column costs one tab stop rather than twenty. Enter toggles, Shift with arrows extends a range on ordered columns, Escape clears. Selected buckets carry an outline as well as a colour. Beyond per-bucket labels the chart carries a sentence describing the distribution's shape, because twenty bucket readings do not add up to "most of the mass is at the low end", and that shape is the entire value of the chart.

Attaching puts a control on the grid. A slider along the bottom with two readings beside it: how long ago, and the clock time. Relative answers the question actually being asked; absolute is what someone reads out to the person next to them. It moves the grid while the handle is dragged rather than on release, and it turns accent-coloured the moment you are off live, because a grid quietly showing stale data is the failure this control can cause. It removes itself on detach().

It reads the data, not your actions. Undo history records what the user did (sorts, filters, edits) which is rarely the question. This reads the change log: a bounded, timestamped, deliberately unmerged record of everything that arrived, so the intermediate states are all still there to move between.

Nothing is scrubbable before attach(). What a value used to be is not recoverable after the fact (no other part of the grid remembers it) so recording has to be switched on before there is a past to move through. It is off by default because reading a row per key on every change is real cost on a hot feed, and paying it for a scrubber nobody opened would be the wrong default.

Scrubbed back, the grid is not live. Changes keep being recorded but are not applied, because applying them would fight the position being held. Returning to the present applies everything missed.

Value changes reverse; row additions and removals do not. An add would need a removal and a remove would need re-insertion at its old position, and neither is recoverable from what the log holds. A window containing them scrubs over the value changes and leaves the row set alone: stated plainly because the alternative is a scrubber that silently half-works.

What moved is marked. Seeking compares each affected row before and after and marks the cells whose value changed, in --lattice-timeline-changed. Without it a scrub is nearly unreadable: the grid moves, and on a row twelve columns wide the one number you are hunting for goes past unseen.

The mark is held, not flashed. It stays until the next seek clears it. Every other transient signal in the grid fades on a timer, and this one deliberately does not, a scrub is someone hunting for what changed, and a highlight they can miss while reading the other end of the row helps nobody. timeline:seeking fires before any change is applied, so a five-step drag clears once and marks once rather than strobing per entry.

It compares column values, not raw fields. A computed column has no field of its own; diffing the source row would leave it silently unmarked while its number visibly moved. Reading through the column instead costs a little more and marks what the viewer can actually see change, which is the only definition of "changed" that matters here.

The window is bounded by rows, not only by changes. A cap on entries alone does not bound memory, because an entry is not a fixed size: one carrying a single changed cell and one carrying a fifty-thousand-row batch both count as one. So the log holds at most updates.logLimit changes (2000) and updates.logRows rows between them (100,000), dropping oldest-first on whichever it meets. It matters more here than it looks: the log is what keeps superseded row objects alive after the source has swapped in their replacements, so on a feed delivering five thousand rows a batch an entry-only cap retains twenty million of them. The one exception is a single change larger than the whole cap, which is kept: emptying the log would be worse than being briefly over, and it would drop the newest change rather than the oldest. Watch held against heldLimit in grid.updates.stats(); rows is a lifetime total and says nothing about memory.

Charts scrub like anything else. A sparkline column redraws to the series the row held at that point, and its cell is marked with the rest. The exception is the delta renderer: it samples on a wall-clock timer and compares against its own previous sample, so it reads a seek as a genuine movement and draws an arrow for it. Keep it off a grid you intend to scrub.

The scale multiplies your density, it does not replace it. A grid built at spacious presented at 1.5x is still recognisably that grid, half as big again, which is what makes a presentation look like the product rather than like a different one. Virtualisation follows the enlargement, so rows are positioned at the size they are drawn.

Full-screen is the maximiser, not a second implementation. A grid the user had already maximised stays maximised when the presentation ends: leaving it would be undoing something the presentation did not do. Chrome hidden on entry is recorded and put back, so an element the host had already hidden is not revealed on exit.

Events are presentation:started, presentation:ended, presentation:scale and presentation:changed: colon-separated like every other grid event rather than the camelCase the original brief used, so a host subscribing to them does not have to remember which family a name belongs to.

They are the saved views you already have. A view captures the column set, order, widths, filters, sorts, grouping and density; stepping applies each through the ordinary views.apply, as a single undo entry. Nothing about presenting changes what a view means.

The stepping keys only bind when there is a sequence, and never while something is being typed into. Without a deck those keys belong to the grid, a presenter with no slides still expects Page Down to scroll, and a quick filter answering a question from the room must not advance the deck on the space bar.

Stepping past either end sits there. It does not wrap: a presenter who sees the first slide again thinks the deck has restarted.

Transitions are a cross-fade, not continuous row motion. Rows are pooled and virtualised, so an element holding a row before a view change may hold a different row after it: only rows visible in both states could be animated between positions, and half a movement draws the eye to whichever rows happened to survive rather than to the change itself. prefers-reduced-motion removes it; a projected fade is far larger than one on a laptop, so someone who asked for less motion meant it.

Spotlight dims what it is not on, rather than lighting what it is. Rows and columns combine as an intersection, so naming both lights the cells where they meet. The dimming stops at 0.28 rather than going further: the audience has to see that there is more data and roughly what shape it is, or the spotlight reads as a filter and the room believes the other rows are gone. It is opacity alone, so a dimmed sparkline keeps its colours instead of flattening to grey.

A spotlight does not survive a view change. It belongs to the point being made, not to the deck: carried forward, it leaves the audience looking at a lit row that no longer means anything.

Redaction travels in views and undo. It is part of grid state, so a saved view carries its own masking and a view that redacts salary redacts it every time it is shown. Toggling is a tracked action, so it undoes like any other change.

Auto-advance wraps, unlike a keypress. An unattended display that stopped on the last view would show one screen for the rest of the day.

Escape ends the presentation, not just full screen. A presentation runs full screen with its chrome hidden, so leaving full screen without ending it would drop a chrome-less enlarged grid back into the page with no control left to turn it off. The maximiser stays the only listener on the key and the presentation follows it, which keeps one Escape doing one thing: an open editor or menu still closes first. A grid built with maximise: false binds the key directly instead.

Mounting the bar elsewhere needs the grid's class. Every rule that styles the prompt bar is scoped under .lattice, and every colour token is declared there, so a bar mounted into your own chrome through ai.element arrives unstyled. Add class="lattice" to the container, and the same data-theme the grid carries, if you have set one, and it picks up the theme.

It photographs the browser's own rendering. The grid is cloned, every computed style is inlined onto the clone, and the result is wrapped in an SVG foreignObject and drawn to a canvas, so the picture is what the browser drew, not a second renderer's guess at it. That matters here more than usual: every decoration, sparkline and pill the cell layer produces comes out right without being reimplemented.

Virtualisation makes it cheap. Only the rows on screen exist in the DOM, so capturing a million-row grid clones the thirty rows a camera could have seen anyway. A full-screen capture at scale: 2 takes around a second.

Cross-origin images are refused before the work starts. They taint the canvas, and a tainted canvas fails at the very last step with a SecurityError that names nothing, so the check runs first and the error names the offending URL. Serve the image same-origin, inline it as a data: URL, or hide the column.

Two further limits, both inherent to the technique: web fonts need embedding to appear (Lattice's default system-ui stack is unaffected), and CSS pseudo-elements are not captured.

It never touches data. Nothing in the layer reads a row or writes one. A grid with annotations sorts, filters and exports exactly as one without them.

It is inert unless a tool is chosen. The canvas is not even created until the first use(), and carries pointer-events: none whenever no tool is active, so scrolling, selection and editing pass straight through. A presenter who has finished drawing must not discover the grid has stopped responding.

Marks are anchored to the data, not the screen. They are stored in content coordinates and redrawn with the scroll offset subtracted, so a circle drawn round a cell travels with that cell rather than hanging over whatever scrolled underneath it.

They are transient. Marks annotate a moment, so they are cleared when the presentation ends. A capture taken while they are on screen includes them, the canvas bitmap is carried into the still deliberately, because cloneNode copies a canvas element and not one pixel of what was drawn on it.

No tool shortcuts are bound. The keys a presenter would want are already taken by stepping and by the grid itself, and a shortcut that silently shadows Page Down is worse than one the host chooses. Bind your own to use().

Density alone does not do this. It scales the header, the rows and the type, and leaves the affordances inside them exactly as they were: measured at every preset, the menu button stays 24 pixels, the filter 16 and the resize grip 10. A spacious grid has the room going spare and controls no larger than a compact one, which is the gap this fills.

Type does not scale with the rows. The row doubles from compact to spacious while the font moves about 18%. Scaling text against row height reads as a children's book long before the rows look generous, so height and spacing follow the scale directly and type is damped against it.

Virtualisation follows the token, not a separate number. Row positions are computed from the resolved --lattice-row-height, so a host that overrides that token by hand gets the virtualisation to agree. An explicit rowHeight in config outranks both, a host that names a number means it.

Height alone will not reproduce a modern app listing. Those designs pair generous rows with two-line cells (a bold title over a grey sub-label) and an avatar or thumbnail. spacious gives the room, an image column gives the picture, and twoline gives the second line.

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.

This is not a security control, and the difference matters. The values are still in the model, still in the DOM, still on the clipboard and still in every export. Anyone looking at the page can read them from devtools, or by turning off a single CSS rule. What redaction defeats is a camera and a screen recorder, which is the threat a presenter actually has, and the only one it claims to answer. For a value that must never reach the browser, use permissions with writeOnly: there the value is not sent, so there is nothing to reveal.

Headings stay readable, totals do not. The column heading is left alone deliberately, a redacted column still has to be identifiable, by the presenter who wants to turn it back on and by the audience who need to know what they are not being shown. The pinned totals row is redacted, because the sum of a column is not a hint at its values: filter to one row and the total is the value.

Swapping the treatment. --lattice-redaction-filter defaults to blur(5px) contrast(0.85) and takes anything the CSS filter property does. A blur is the default because it is GPU-composited and stays cheap across a scrolling viewport; point the token at an SVG mosaic filter if you prefer classic pixellation and can afford it per cell.

Pasting follows the spreadsheet convention: one cell into a range fills the range, one row into several rows repeats down, and a block larger than the target extends past it. People have twenty years of muscle memory for this and a grid that invents its own rules is a grid people fight.

Why a per-edit flag, off by default. Paste preview lives under edit because a paste is a bulk edit and its accept/reject decisions are the edit model's — the preview cannot disagree with the commit because it runs the same checks. Off by default keeps every existing grid's paste behaviour exactly as it was.

None of these fire while you are typing into an input, a filter box, an open editor, the view-name field. The grid checks where the keystroke came from before claiming it, which sounds obvious and is the sort of thing that is usually wrong.

A key a heading handles acts once, on the heading: Enter sorts and does not also open an editor on a body cell, ArrowRight reaches the next heading and not a cell beneath it. A key the heading declines still travels, which is how Escape reaches a maximised grid from a heading.

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.

Not yet in the panel: icon sets and data bars. Both 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.

Compiled once per query, not per row. A regular expression rebuilt for each of a hundred thousand rows is a hundred thousand compiles for one keystroke. The predicate is built in the filter stage and applied to a cached text blob per row, which is why typing stays responsive at scale.

An unfinished pattern does not blank the grid. foo( is what foo(bar) looks like halfway through typing. An invalid expression falls back to a literal search, so the list stays sensible until the pattern is valid again.

Fuzzy does not rank. Subsequence matching decides what stays; it never reorders. Sorting results by match quality would fight the sort the user chose, and a filter that quietly re-sorts is worse than one that matches too much.

Permissions still apply. The text blob is built only from columns the viewer may see. A hidden column is not searchable, or the row count becomes a way to probe the value behind it.

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 filters are part of the question. Every one of these reads the filtered rows. Narrow the grid and the statistics narrow with it, which is the behaviour you want when the filter is the analysis.

Kernels see arrival order, not display order. Anything order-dependent takes an explicit by rather than inferring one from the current sort, so the answer does not change when a user clicks a column header.

One declared tolerance, so nothing can disagree. The indices, the charts and any conditional format all read the same spec. A tolerance passed separately to each is a tolerance that eventually differs between them, and a capability report that contradicts the cell colouring is worse than neither.

Cp and Cpk use short-term variation, Pp and Ppk overall. The first pair comes from the moving range, which is what the process can do when it is behaving; the second from the whole spread, which is what it actually delivered. Ppk well below Cpk is the signal that the process drifted rather than that it is incapable.

A baseline finds a shift instead of absorbing it. baseline: 30 fixes the limits over the first thirty readings. Limits recomputed over all the data widen to accommodate the very shift you are looking for, and then report no violation.

The point estimate alone overstates the case. A Cpk of 1.35 measured on thirty parts has a lower bound below 1.0, so a process that has "passed" a 1.33 requirement on thirty parts has demonstrated very little. interval is reported alongside it for that reason.

The line the product draws. Lattice quantifies uncertainty. It does not adjudicate hypotheses: there are no p-values and no significance tests. An interval says how precisely a figure is known and leaves the judgement where it belongs. A tool that returns a verdict invites it to be read as one, and a grid is the wrong place for that.

Wilson, not the textbook formula. The normal approximation gives bounds below zero and above one at small counts, which is visibly wrong to anyone who reads it. The Wilson score stays inside the interval it is describing.

bands and goodWhen judge different things. goodWhen says whether a rise is good news, and colours the change indicator. bands judge the value itself. They are separate because a Cpk of 0.9 is bad news whether it rose or fell to get there.

The tile follows the grid by default. Filter the grid and the figure updates. scope chooses filtered, all or selected rows; live: false detaches it and leaves refresh() to you.

value also takes show, which reports a field from the row holding an extreme rather than the extreme itself: { of: 'sales', fn: 'max', show: 'rep' } is the name of the best rep. It needs min or max, because no single row holds an average.

References name columns, not cells. A spreadsheet can say A1 because its rows do not move. A grid sorts, filters, groups, pages and virtualises, so the row at position 1 is a different row a moment later and a formula written against it would silently change meaning. quantity * price means the same thing wherever the row goes.

No eval, no new Function. This is text a user typed into a cell. Handing it to the JavaScript engine would let anyone who can edit a cell read your cookies, call your API with your credentials, or post the grid's contents anywhere. It is a hand-written tokeniser and recursive-descent parser, and the only callable things are the built-in functions: constructor, globalThis and constructor.constructor("return 1")() all simply fail to resolve.

The result is stored, not the expression. A formula is a way of entering a value, exactly like 1,200 or (50) or 12%. It commits as one undo step, fires one cell:changed, and passes through the column's own validation.

The result is stored, not the formula. The expression is evaluated once, at the moment you commit it, and what lands in the cell is a value like any other, so it does not recalculate when a cell it referred to changes later. For a value that must stay in step with its inputs, use a computed column, which is re-evaluated whenever its dependencies move.

Bare arithmetic is deliberately not a formula. 2-1 is a plausible product code and 1/2 a plausible date. A reader that evaluated either on a guess would have to guess wrong sometimes, and the wrong answer is not a visible error but a plausible number: 2*3 stored as 23 looks like data. Arithmetic without a leading = is refused outright, so the cell keeps what it had rather than taking a number nobody typed.

Handed the defaults, rather than replacing them. A builder that had to return every item in order to append one would be written once as a copy of the built-ins and would then drift from them, the copy keeps the menu it was forked from, and stops gaining whatever the grid adds later. Spreading defaults costs one line and never goes stale.

Return the array you want shown: add, remove, reorder, or replace outright. An empty array suppresses the menu deliberately. Returning nothing leaves the defaults alone, because a missing return is a typo and deleting the whole menu is a harsh reading of one.

A chain, not a replacement. If the column level replaced the grid level, every column that wanted one extra item would have to restate everything the grid-level builder does — and would then stop tracking it the first time it changed. This is the same rule columnMenu already follows for the header: you are handed what came before so you can add to it rather than reproduce it.

Trust is unchanged. A MenuItem is the same object it always was, including icon markup being trusted at the same level as action. Declaring one on a column changes where it is written, not who is trusted to write it: a column definition is your code, exactly as a grid config is.

Your properties are on column.def, not on the column itself. column is the grid's resolved interpretation of your definition and carries only keys the grid understands; column.def is the object you wrote, untouched. Keeping them apart means an application property can never collide with one the grid adds in a later version, and you do not have to maintain a lookup table keyed by column id alongside the columns themselves.

Why a handler rather than a flag that just draws. The charts module is optional by design — a page that never charts never loads it — so the DOM layer cannot draw a chart itself without pulling the whole drawing surface into every bundle. Handing the drawing back to the page keeps that promise, and it is the same seam createChart already uses: the grid is handed to the charts module, never imported by it.

An explicit actions array replaces the default rather than extending it. That is what makes it useful (you choose the set and the order) but it also means a config written against an earlier version keeps exactly the buttons it named and silently misses anything added since. If you want whatever the current version offers, leave the key out.

Every action is gated on a predicate rather than always offered, so undo greys out when there is nothing to undo and "restore the default view" greys out when nothing has changed. A rail of seven icons where three do nothing is worse than a rail of four.

The element is moved, not just restyled. A position: fixed element is positioned against the nearest ancestor carrying a transform, filter, contain or will-change, which is to say any card, any animated panel, any sticky app shell, and against the viewport only when there is no such ancestor. A class alone would therefore fill the window on one page and land in a 300px box on the next, and would still be clipped by an overflow: hidden or buried by a stacking context. Reparenting to <body> removes every ancestor that could do any of that.

Coming back is a hidden placeholder left in the element's place, not a remembered parent and index, an index goes stale the moment your application inserts a sibling while the grid is away, and then silently reinserts in the wrong slot. The placeholder also holds the vacated space open at the size the grid had, so the page behind neither reflows nor loses its scroll position while you are looking at the grid.

The geometry is written as inline styles and every displaced property is handed back exactly as it was found, because the element being restyled is yours: most often one with an inline height on it, which is the ordinary way a grid gets sized and which nothing but an inline style can beat. While maximised, the element carries .lat-maximised and <body> carries .lat-maximised-host, as hooks for your own CSS.

Applying a view is a destination, not a patch. A view's state names only the sections it cares about, so applying one resets to the grid's starting state first. Without that, clicking "APAC capacity" after "Commercial" would inherit Commercial's hidden columns, the same view giving a different grid depending on what preceded it, which is the one thing a named view must not do.

Applying a view never throws and never refuses. It returns a report, { applied, skipped }: naming each thing it could not use and why. Refusing the whole view because one column has gone would lose a layout the user built deliberately, and throwing during a page load would lose the page. So a view degrades to as much of itself as still makes sense, and the host decides whether the user needs telling.

The other half of the same seam. views.storage above is where a developer plugs in their own backend, a real server, reached over the network. Not every grid has one to plug in, and a picker offering "Save" that quietly does nothing until a backend exists is worse than not offering it. views.local: true is the no-backend answer: saved views live in this browser's own localStorage, under a default key shared by every grid on the origin unless you pass one of your own, views: { local: { key: 'orders-grid-views' } }: to keep two grids' views apart. Given alongside an explicit storage, the explicit adapter always wins and local is silently (well, not silently: it warns once) ignored, so a page cannot end up writing to both without meaning to. The adapter itself is exported as createLocalViewStorage(opts), for anyone who wants it directly, a custom key without the shorthand, or a different Storage-shaped backing such as sessionStorage for views scoped to one tab rather than persisted across visits.

A button that says only "Undo" makes the user press it to find out what it does: and pressing it is the thing they were unsure about. "Undo sort by Region" is decided before the click rather than after.

The icons come from the grid, not from the chart. icon is a name in the grid’s own sprite registry — a built-in, or one you registered — and the chart reads it through grid.icons, the grid it is bound to. That is deliberate and it is the only route that works: the charts module ships as its own bundle, so an import of the registry there would hand the chart a second, empty copy, and a glyph you registered would be invisible to it. One registry, reached through the one object both sides already share. Unknown names warn once and draw a plain disc rather than nothing.

Pinning steers the layout without replacing it. A node with both x and y is a fixed body: it still pushes its neighbours apart and still pulls on its links, and the integration step skips it. Everything unpinned settles around it by the same deterministic relaxation as before — and pinning one node does not reshuffle the others, because the layout’s seeding draws for every node whether it is pinned or not, precisely so that it cannot. Half a position is not a position: a node with only x is laid out.

Parallel links are not summed. Three rows between the same pair are three lines, offset 4 px apart, symmetric about the pair’s own line, in row order. One line carrying their total would be a number nothing measured — three circuits at 40% do not make one at 120% — and the pointer picks out the line you are over rather than the pair, so each one’s own value is readable. Links are undirected: no arrowheads, and A,B is the same pair as B,A.

There is no chart-level threshold option, on purpose. The colour comes from grid.formatting.styleFor(col, value) — background, then backgroundColor, then color; a gradient is not a colour and is not read. A second place to say “red above 80” is a second place for the chart and the cell to disagree. The legend lists only the rules that fired, with their own labels and swatches, and changing a rule recolours the links on the next frame without the layout re-running, so nothing moves.

Clicking acts on rows, because a link is a row. With selection: true, clicking a link selects its row and clicking a node selects every row it is an end of; the grid’s selection then lights those marks and dims the rest. The types whose marks are aggregates are deliberately untouched: selecting the forty rows behind a bar is not what a click on a bar means.

The row is gone from the data and still in the snapshot. That is the only place it exists, and it is what these rows are built from, so they carry the values they had when the snapshot was taken, not any current ones.

One option answers both questions: whether to show it, and whether it counts. 'pinned' puts it beneath the rows, struck through and dimmed, outside the row set, so rows.count(), exports and selection all pass over it. 'data' appends it to the set instead, and all three include it. Omitted, nothing is shown and the grid is the one you already had.

Neither sorts or filters it among the live rows. A removed row's values are yesterday's; ordering them among today's presents two data sets as one, and lets a filter written for current values decide the fate of historical ones. Neither permits an edit either, a write aimed at a removed row is refused and returns 0, rather than being counted as applied against a record that is not there.

Nothing is executed on trust. The vocabulary is seven actions, setFilters, setSort, groupBy, showColumns, hideColumns, setQuick, clear, and a reply naming a column that does not exist is rejected with a reason while the valid actions in the same reply are kept. A model cannot be talked into an operation the vocabulary does not contain, because there is nothing else to call.

A saved view is a serialisable state object, so the server applies exactly what the user set up, using exactly the code the browser uses. The £1,234.50 in the file is the £1,234.50 on the screen because it came out of the same formatter. 50,000 rows filtered, sorted and written to CSV takes about 100ms.

Load this or the main bundle, not both. The module is self-contained: it carries the grid with it, so a page that also loads lattice-grid.esm.js downloads and evaluates the grid twice.

Assign before appending where you can. The element builds its grid once, at the end of the task in which it connects, so everything set in that task arrives as one configuration rather than as a series of updates. Setting properties later still works: they go through the live configuration path, but the grid is built empty first and repainted after, which is a visible flash on a large set.

Reading .grid forces the build immediately, so the property is never briefly null.

Every grid event is re-dispatched as a CustomEvent named lattice- plus the grid name with colons hyphenated, so cell:edit:start becomes lattice-cell-edit-start. The payload is event.detail. The prefix is not decoration: the grid emits an event called scroll, and an unprefixed CustomEvent of that name would be indistinguishable from the platform's own. Forwarding is a wildcard subscription, so events added to the grid later appear here with no change to the component.

Light DOM, deliberately. The element renders into itself rather than a shadow root, because the grid's generated decoration rules are injected into document.head and the theme stylesheet is a <link> the page owns: neither crosses a shadow boundary. A shadowed grid would be structurally correct and completely unstyled, and subtly so: the --lattice-* tokens do inherit through a shadow root, so the colours would arrive while every pill, bar and heat cell stayed bare. Light DOM keeps every documented theming route working unchanged.

Nothing ever refuses to render, and nothing is ever withheld. An expired key, a wrong domain, a key that will not read: all of them log one warning and show the watermark. Every feature keeps working. The failure to avoid is a customer's production screen going blank because a licence lapsed over a weekend, and a grid that quietly drops a feature is the same failure wearing a disguise.