@toclocoinc/lattice-grid 1.54.0 → 1.56.0

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.54.0</p>
+    <p class="rail__sub">Developer guide · v1.56.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -553,7 +553,7 @@
         <a href="API.html">reference tables</a> are the shorter version for when you already know.
       </p>
       <p class="chips">
-        <span class="chip">Version 1.7.1</span>
+        <span class="chip">Version 1.56.0</span>
           <span class="chip">Zero dependencies</span>
         <span class="chip">No build step</span>
       </p>
@@ -585,6 +585,10 @@ createGrid(element, { locale: 'fr-FR', messages: FR_FR });</code></pre>
 
     <p><code>MESSAGE_KEYS</code> lists every key. <code>auditCatalogue(yours)</code> returns what is missing and what is not a real key, which is the quickest way to check a translation before shipping it.</p>
 
+    <h3>Keys seeded in English, awaiting translation</h3>
+    <p>A key added after a catalogue was written ships in British English only until a translator supplies it; <code>Messages</code> merges every catalogue over the default, so the grid says it in English rather than showing the key. The shipped catalogues do not carry an English copy under the guise of a translation, and the build's completeness test lists exactly which keys are in this state. As of 1.55 the most recent additions are the strings that had shipped as template literals, untranslated in every locale (BACKLOG-0001106): the presence live region and roster note, <code>a11y.presence.refused</code>, <code>presence.someoneElse</code> and <code>presence.hidden</code>; the comment panel's changed-since note, <code>comments.valueMoved</code>; the facet band's accessible name, <code>facets.filter</code>; the heading tooltip that names a reduction, <code>header.totalOf</code>; the audit-mode tooltip, <code>diff.before</code> and <code>diff.empty</code>; the kanban list names, <code>kanban.columnCards</code> and <code>kanban.laneCards</code>, both plural objects selected by <code>count</code>; and the gantt lag label, <code>gantt.lag</code> and <code>gantt.lead</code>. Supply any of them in <code>messages</code> to translate it today.</p>
+    <p>The kanban board and the gantt view are modules and do not import the catalogue. A board bound to a grid, or a plan created with one, borrows that grid's <code>messages</code>; otherwise pass <code>messages</code> — a grid's own, or any object with <code>t(key, params)</code> — to <code>createKanban</code> or to <code>gantt.mount</code>. With neither they render the English.</p>
+
     <div class="why">
       <p><strong>The grid is checked in the other direction too.</strong> <code>auditCatalogue</code> 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.</p>
       <p>So the build refuses one. Any literal reaching an element's text, or an announced attribute such as <code>aria-label</code>, <code>title</code> or <code>placeholder</code>, has to come from the catalogue. That is what stops a localised grid drifting back into English one plausible change at a time.</p>
@@ -668,8 +672,8 @@ createGrid(element, { direction: 'rtl' });    <span class="cmt">// or say so out
 
     <div class="example">
       <p class="example__label">jsDelivr, no npm install, no bundler</p>
-      <pre><code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.min.css"&gt;
-&lt;script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.min.js"&gt;&lt;/script&gt;
+      <pre><code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1/lattice-grid.min.css"&gt;
+&lt;script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1/lattice-grid.min.js"&gt;&lt;/script&gt;
 
 &lt;script&gt;
   <span class="kw">const</span> grid = LatticeGrid.createGrid(document.getElementById('grid'), config);
@@ -694,9 +698,10 @@ createGrid(element, { direction: 'rtl' });    <span class="cmt">// or say so out
 
     <div class="note">
       <p><strong>jsDelivr mirrors every version published to npm</strong> at
-      <code>cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@&lt;version&gt;/&lt;file&gt;</code>: pin an
-      exact version, e.g. <code>@1.7.1</code> rather than <code>@latest</code>, so a later release
-      does not change what a page already in production loads. The same convention reaches a
+      <code>cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1/&lt;file&gt;</code>. <code>@1</code> pins
+      the major: a page in production picks up fixes within 1.x and never a breaking release, where
+      <code>@latest</code> would. To freeze a page on one exact build, replace <code>@1</code> with
+      the full version <code>getVersion()</code> reports. The same convention reaches a
       module: <code>.../modules/htmx.esm.min.js</code>, <code>.../modules/dhtmlx-compat.esm.min.js</code>,
       and so on. Type declarations resolve automatically through npm's own <code>types</code> field;
       for editor tooling against the CDN or a plain script tag, point your <code>tsconfig</code> at
@@ -1273,7 +1278,7 @@ off();                                       <span class="cmt">// every subscrip
     </p>
     <div class="example">
       <p class="example__label">Which version am I running?</p>
-      <pre><code>grid.getVersion();          <span class="cmt">// '1.7.1'</span>
+      <pre><code>grid.getVersion();          <span class="cmt">// '1.56.0'</span>
 LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid to hand</span></code></pre>
     </div>
     <p class="lead-in">
@@ -1281,6 +1286,46 @@ LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid
       "the grid on this page", and whoever reads it has a grid rather than the module it was built
       from.
     </p>
+
+    <h3 id="headless-vs-dom">A headless grid is not a smaller grid, it is a grid without a renderer</h3>
+    <p class="lead-in">
+      <code>createGrid</code> builds this same core and attaches the DOM renderer to it;
+      <code>createHeadlessGrid</code> stops one step earlier. Everything the core owns — data, state,
+      sort, filter, group, total, pivot, formulas and computed columns, editing and optimistic
+      write-back, export, and every event — runs unchanged with no renderer attached, which is why
+      most of the examples in this guide that call <code>createHeadlessGrid</code> are settling real
+      API questions, not toy snippets. What it does not have is the renderer: no layout, no
+      measurement, no scrolling geometry, no focus, and <code>grid.element</code> is <code>null</code>.
+    </p>
+    <div class="why">
+      <p><strong>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.</strong> The visible row window is computed from the
+      container's own height; a container that is detached from the document, or sits under a
+      <code>display: none</code> 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 <em>no computed size</em>, not about being visually off-screen: a
+      container positioned outside the browser's visible area with real, explicit dimensions (for
+      example <code>position: fixed; left: -9999px</code> with a width and height) still gets a real
+      box and renders fully.</p>
+      <p><strong>The in-repo test DOM (<code>testdom.js</code>) is a stub, not a browser, and says so
+      in its own header comment.</strong> It implements exactly the surface the renderer touches —
+      element creation, attributes, <code>classList</code>, <code>style</code>, children,
+      <code>textContent</code>, event dispatch, injected geometry, and shims for
+      <code>ResizeObserver</code> and <code>requestAnimationFrame</code> — 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
+      (<code>test/*-browser.test.js</code>) that drive an actual headless Chrome instead. It also does
+      not model real focus semantics — its <code>focus()</code> simply records which element is
+      "focused" with no check for visibility, tab order or focusability. Since BACKLOG-0001181,
+      <code>classList.add</code> does throw on a token containing a space, the same
+      <code>InvalidCharacterError</code> a real <code>DOMTokenList</code> throws, closing the specific
+      gap where a two-word class name passed every headless test and then blanked a real page.</p>
+    </div>
+
     <h2 id="columns-guide">Defining columns</h2>
     <p class="lead-in">
       A column is an object with a <code>field</code> (the path to read from your data) and
@@ -1341,6 +1386,55 @@ LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid
       A cycle is caught at compile time with the full path named, rather than becoming a stack
       overflow at render time.</p>
     </div>
+    <p>When a computed value is re-run, stated plainly:</p>
+    <ul>
+      <li>A pure compute (the default) runs at ingest and is cached. It runs again when its row is
+        replaced through <code>rows.apply({ update })</code> or the data through
+        <code>rows.load()</code> &mdash; unconditionally, since a value derived from data that is
+        gone is stale by definition; when the grid a derived grid follows changes; and when you ask
+        with <code>rows.refresh({ rows, columns, force: true })</code>. A sort, a filter, a state
+        restore or an edit to a column outside its <code>deps</code> does not re-run it. An in-place
+        cell edit to one of its <code>deps</code> does not currently re-run it either.</li>
+      <li>Naming a column re-runs what depends on it: <code>refresh({ columns: ['p'], force: true })</code>
+        recomputes a <code>q</code> whose <code>deps</code> include <code>p</code>;
+        <code>refresh({ columns: ['q'] })</code> does not recompute <code>p</code>.</li>
+      <li><code>pure: false</code> guarantees the compute is re-evaluated on every read and every
+        paint. It is never served from a cache.</li>
+      <li>Whenever a compute re-runs, <code>rows.text()</code> and the painted cell show the new
+        result, and so do a sort or filter on the column: every cache the grid keeps for that cell
+        &mdash; the one behind the text and the paint, and the one sort and filter handles read
+        &mdash; is invalidated together.</li>
+      <li>Without <code>force</code>, a targeted <code>refresh({ rows, columns })</code> behaves
+        differently by store mode, and which one you get flips at <code>columnarBelow</code>. On a
+        grid below that row count the named cell is re-run on its next read; on a columnar one the
+        stored value stands until you pass <code>force: true</code>. This is behaviour to plan for,
+        not a tuning detail: the same call on the same data recomputes or does not purely according
+        to how many rows arrived. Pass <code>force: true</code> when you want the same answer
+        whatever the row count.</li>
+    </ul>
+    <div class="example">
+      <p class="example__label">An answer that arrives later</p>
+      <pre><code><span class="cmt">// A lookup the grid cannot see: show a placeholder, fill the table, then</span>
+<span class="cmt">// tell the grid which cells to recompute. The compute stays pure, so it is</span>
+<span class="cmt">// not re-run on every paint &mdash; only when you say the answer changed.</span>
+const names = new Map();
+const column = {
+  id: 'owner', title: 'Owner',
+  value: {
+    deps: ['ownerId'],
+    compute: (deps) =&gt; names.get(deps.ownerId) ?? 'Loading…',
+  },
+};
+
+const missing = [...new Set(grid.rows.data().map((r) =&gt; r.ownerId))].filter((id) =&gt; !names.has(id));
+const resolved = await fetchNames(missing);        <span class="cmt">// { id: name }</span>
+for (const id of missing) names.set(id, resolved[id]);
+const rows = grid.rows.data().filter((r) =&gt; missing.includes(r.ownerId)).map((r) =&gt; r.id);
+grid.rows.refresh({ rows, columns: ['owner'], force: true });
+
+<span class="cmt">// Or declare the column `pure: false` and it re-reads `names` on every</span>
+<span class="cmt">// paint; then a plain grid.rows.refresh() after the fetch is enough.</span></code></pre>
+    </div>
 
     <h3>Sizing and pinning</h3>
     <div class="example">
@@ -1354,6 +1448,31 @@ LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid
       <code>grid.columns.fit()</code> distributes the viewport width across visible columns, and
       <code>autoSize</code> measures content.
     </p>
+    <p>The width <code>fit()</code> distributes is the space the cells actually occupy: the body
+      viewport&rsquo;s client width, read when you call it. When the grid has enough rows to
+      scroll vertically, that width excludes the scrollbar, so the columns end flush with it
+      instead of running under it; when there is no vertical scrollbar, it is the full inner
+      width. Rows you passed to <code>createGrid</code> or <code>grid.rows.load()</code> before
+      the call are counted, so calling it straight after either works.</p>
+    <p>Every column the grid draws counts toward that width, not only the ones <code>fit()</code>
+      sizes. It sizes your resizable columns. A column it does not size keeps its width, and that
+      width comes off the target first: a column declared <code>resizable: false</code>, and the
+      grid&rsquo;s own selection checkbox, detail expander, group and tree columns. Your resizable
+      columns then share what is left in proportion to their current widths, within each
+      <code>min</code> and <code>max</code>; a column held at a bound stays there and the others
+      share the rest, so all the drawn columns together still come to the viewport width
+      exactly. Under a pivot every column drawn is one the grid generates, so <code>fit()</code>
+      has nothing to size and leaves the widths as they are.</p>
+    <p>If what is left is less than those columns&rsquo; minimums, which happens when the columns
+      <code>fit()</code> does not size already take the width, each resizable column is set to its
+      <code>min</code> (40px when it declares none). None goes below its minimum, and none is
+      squeezed to nothing: the grid scrolls horizontally instead, and a <code>[lattice]</code>
+      warning in the console names the widths that ran out.</p>
+    <p><code>fit()</code> is one-shot. It sets a fixed width on each column once, including a
+      <code>flex</code> column, and does not follow the grid afterwards. If the width changes
+      later, because the container is resized or because rows that arrive afterwards bring a
+      vertical scrollbar in, call it again. A column that should keep tracking the width by
+      itself wants <code>flex</code> instead of <code>fit()</code>.</p>
     <p>Both are also on the column menu: Move left, Move right, Move to start, Move to end, and
       a Width submenu, and bound to the keyboard with a heading focused: <kbd>Alt</kbd> with a
       left or right arrow resizes, <kbd>Shift</kbd> with one moves the column. Neither operation
@@ -1969,9 +2088,16 @@ grid.edit.setCells([
 <span class="cmt">// → the number of cells written</span></code></pre>
     </div>
     <p class="lead-in">
-      This is the full path, not a shortcut: it validates, emits <code>cell:changed</code>,
+      This is the full path, not a shortcut: it validates, emits <code>cell:changed</code> per cell,
       re-sorts if the column is sorted on, records one undo entry, and returns <code>0</code> for a
-      column the user may not write.
+      column the user may not write. It then announces the whole call <strong>once</strong> as
+      <code>rows:changed</code> (<code>identified: true</code>, <code>edit: true</code>, the
+      <code>updated</code> rows and the <code>columns</code> written), after the per-cell events, so
+      a derived grid, a statistic tile or anything else that follows <code>rows:changed</code>
+      re-reads once for a twenty-cell paste rather than twenty times. An editor commit, a fill, a
+      paste, an undo, a redo and an optimistic rollback each announce themselves the same way, once
+      per batch. Earlier releases announced nothing here, and a derived view of an edited grid went
+      silently stale.
     </p>
 
     <h3>High-frequency updates</h3>
@@ -2068,6 +2194,59 @@ grid.filters.quick('');          <span class="cmt">// clear</span></code></pre>
       <code>notBlank</code> work everywhere.
     </p>
 
+    <h3 id="where-guide">Filters your application owns: <code>where</code></h3>
+    <p class="lead-in">
+      A condition tree can only test what is in a column. Plenty of real filters cannot be written
+      that way &mdash; whether this user may see the row, whether you hold an exchange rate for its
+      currency, whether it came back from your last search call. Those go in as <strong>named
+      predicates</strong>, and they compose with everything above.
+    </p>
+
+    <div class="example">
+      <p class="example__label">A permission filter and a toggle, side by side</p>
+      <pre><code>grid.filters.where('visibleToMe', row =&gt; row.owner === me, { pinned: true });
+grid.filters.where('rateKnown', row =&gt; rates.has(row.ccy), { deps: ['ccy'] });
+
+grid.filters.where();              <span class="cmt">// ['visibleToMe', 'rateKnown']</span>
+grid.filters.where('rateKnown', null);   <span class="cmt">// remove just that one</span>
+grid.filters.reapply('rateKnown');       <span class="cmt">// the rate table arrived late</span></code></pre>
+    </div>
+
+    <div class="why">
+      <p>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.</p>
+    </div>
+
+    <p class="lead-in">
+      Three options shape one. <code>deps</code> names the columns the predicate reads, exactly as
+      <code>value.deps</code> does for a computed column: the verdict is then cached per row and
+      re-run when one of <em>those</em> columns changes on that row, not when an unrelated one does.
+      Leave it off and the predicate is assumed to read the whole row, so it runs every pass and can
+      never be stale. <code>pinned</code> makes a predicate survive
+      <code>filters.clear()</code>, which is what you want for permissions and tenant scoping and
+      not much else. <code>condition</code> gives the predicate a declarative twin that is pushed to
+      the source while the function stays as the residual, so a pushdown engine narrows the fetch
+      instead of your code filtering a page.
+    </p>
+
+    <div class="why">
+      <p><strong>Migrating from AG Grid's external filter:</strong> its three pieces become two.
+      <code>isExternalFilterPresent()</code> goes away, because registration is presence.
+      <code>doesExternalFilterPass(node)</code> becomes the predicate itself.
+      <code>onFilterChanged()</code> becomes <code>deps</code> where the grid can watch the change
+      for you, and <code>reapply(name?)</code> where it cannot.</p>
+    </div>
+
+    <div class="why">
+      <p><strong>What travels in a saved view is the name, not the function.</strong>
+      <code>state.get()</code> carries <code>where: string[]</code>; 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 <em>reports</em> the skip instead of quietly showing a wider row set,
+      and never removes a predicate the view did not mention.</p>
+    </div>
+
     <h2 id="grouping">Grouping, totals and pivot</h2>
     <div class="example">
       <p class="example__label">Group by one or more columns</p>
@@ -3305,12 +3484,84 @@ createGrid(right, {
       hundred updates against a two hundred thousand row source cost under 300 ms in total. Set
       <code>refresh</code> to <code>live</code>, <code>manual</code> or a number of milliseconds to
       change the coalescing; <code>idle</code> is the default and settles to a frame.</p>
+      <p><strong><code>manual</code> means the host says when, and <code>rows.load()</code> is how it
+      says it.</strong> A <code>manual</code> 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
+      <code>rows.load()</code> <em>on the derived grid</em>, with no argument, and it re-reads its
+      <code>from</code> there and then and replaces its rows; call it again whenever you want the next
+      reading. A derived grid takes its rows from <code>from</code>, so anything passed to
+      <code>load</code> is not used. The derived grid's own sort and filters stay as they were. Press
+      it as often as you like &mdash; the source is left exactly as one press leaves it, and
+      destroying the panel leaves nothing of it attached there.</p>
       <p><strong>Derived grids are read-only.</strong> There is one copy of the data and it lives in
-      the source. Write there and the derived grid follows.</p>
+      the source. Write there and the derived grid follows: an edit through the source's editing
+      API (<code>edit.setCells</code>, an inline commit, a fill, a paste, an undo, a redo or an
+      optimistic rollback) is announced once per batch, after the per-cell
+      <code>cell:changed</code> 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
+      <code>where</code>, an <code>unnest</code>, a producer, or an edit to a column the source
+      filters on re-reads in full, at the cost measured above. <strong>Use <code>idle</code> when a
+      derived child follows an editable grid.</strong> Under <code>live</code> 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; <code>idle</code> defers it to the next frame and
+      folds a burst of edits into one.</p>
       <p><strong>The key comes for free.</strong> A derived grid keys on <code>__key</code>, 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 <code>rowKey</code> only to override it.</p>
     </div>
+    <div class="example" id="derived-manual-refresh">
+      <p class="example__label">A frozen panel, refreshed on a button press, executed</p>
+      <pre data-run="js" data-expect="20 20 10 10 5; steady; released" data-covers="config:refresh method:rows method:diagnostics"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+
+<span class="kw">const</span> detail = createHeadlessGrid({
+  rowKey: 'id',
+  columns: [{ field: 'region' }, { field: 'capacity', type: 'number' }],
+  rows: Array.from({ length: <span class="num">20</span> }, (_, i) =&gt; ({ id: i, region: i % <span class="num">2</span> ? 'North' : 'South', capacity: i })),
+});
+detail.rows.count();
+
+<span class="cmt">// What the detail grid is listening with before any panel is attached.</span>
+<span class="kw">const</span> listening = () =&gt; Object.values(detail.diagnostics.events()).reduce((a, b) =&gt; a + b, <span class="num">0</span>);
+<span class="kw">const</span> alone = listening();
+
+<span class="cmt">// A summary that derives once, then waits to be told.</span>
+<span class="kw">const</span> panel = createHeadlessGrid({
+  columns: [{ field: 'region' }, { field: 'sites', type: 'number' }],
+  source: { mode: 'derived', from: detail, groupBy: 'region',
+    select: { sites: { fn: 'count' } }, refresh: 'manual' },
+});
+
+<span class="cmt">// The Refresh button. In a page this is your &lt;button&gt;; here any EventTarget will do.</span>
+<span class="kw">const</span> button = <span class="kw">new</span> EventTarget();
+button.addEventListener('click', () =&gt; panel.rows.load());   <span class="cmt">// no argument</span>
+
+<span class="kw">const</span> sites = () =&gt; {
+  <span class="kw">let</span> n = <span class="num">0</span>;
+  panel.rows.forEach((row) =&gt; { n += panel.rows.value(row.key, 'sites'); });
+  <span class="kw">return</span> n;
+};
+<span class="cmt">// Longer than any automatic refresh would take to land, so "frozen" is a finding.</span>
+<span class="kw">const</span> settle = () =&gt; <span class="kw">new</span> Promise((done) =&gt; setTimeout(done, <span class="num">50</span>));
+
+<span class="kw">const</span> attached = listening();
+<span class="kw">const</span> seen = [sites()];                                   <span class="cmt">// 20</span>
+detail.filters.set({ col: 'capacity', op: 'lt', value: <span class="num">10</span> });
+<span class="kw">await</span> settle(); seen.push(sites());                      <span class="cmt">// 20: the source moved, the panel did not</span>
+button.dispatchEvent(<span class="kw">new</span> Event('click'));
+seen.push(sites());                                       <span class="cmt">// 10: re-derived on the press</span>
+detail.filters.set({ col: 'capacity', op: 'lt', value: <span class="num">5</span> });
+<span class="kw">await</span> settle(); seen.push(sites());                      <span class="cmt">// 10: frozen again</span>
+button.dispatchEvent(<span class="kw">new</span> Event('click'));
+seen.push(sites());                                       <span class="cmt">// 5</span>
+
+<span class="cmt">// Pressing it any number of times leaves the detail grid as one press does,</span>
+<span class="cmt">// and destroying the panel leaves nothing of it behind there.</span>
+<span class="kw">const</span> steady = listening() === attached ? 'steady' : 'grew';
+panel.destroy();
+<span class="kw">const</span> released = listening() === alone ? 'released' : 'left behind';
+detail.destroy();
+<span class="kw">return</span> `${seen.join(' ')}; ${steady}; ${released}`;</code></pre>
+    </div>
 
     <h3>Other shapes</h3>
     <div class="table-wrap">
@@ -3514,7 +3765,11 @@ createGrid(right, {
       next frame; a <strong>number</strong> is a debounce in milliseconds; <code>'live'</code>
       derives on every change and is the one to avoid for an expensive analysis over a ticking feed;
       <code>'manual'</code> stops automatic derivation entirely, leaving the host to drive the
-      source. Below a few tens of thousands of rows none of this matters.</p>
+      source: call <code>rows.load()</code> on the derived grid, with no argument, whenever the
+      analysis should be brought up to date &mdash; from a Refresh button, when its tab is shown, or
+      on a timer of your own. Each call re-derives once, at the cost in the table above;
+      <a href="#derived-manual-refresh">a frozen panel refreshed on a button press</a> is executed
+      above. Below a few tens of thousands of rows none of this matters.</p>
 
     <h2 id="cross-filter">Cross-filtering</h2>
     <p class="lead-in">
@@ -4563,6 +4818,27 @@ grid.selection.extendRange(34, 'cap');  <span class="cmt">// grows the block jus
       Selected rows carry <code>aria-selected</code> and the class
       <code>lat-row--selected</code>, which the theme styles.
     </p>
+    <div class="example">
+      <p class="example__label">A row with its own click action</p>
+      <pre><code>selection: { mode: 'multiple', checkbox: <span class="kw">true</span>, checkboxOnly: <span class="kw">true</span> }</code></pre>
+    </div>
+    <p class="lead-in">
+      <code>checkboxOnly: true</code> restricts row selection to the checkbox column:
+      clicking the checkbox selects or deselects the row, and clicking anywhere else in the
+      row does neither. This is for a host that binds its own action — typically opening a
+      record's detail view — to a plain click on the row: without it, that click also
+      selects the row, and a bulk action run afterwards operates on rows the user never
+      chose to select. The same restriction applies to the keyboard: Space still toggles
+      selection while focus is on the checkbox cell, and does nothing elsewhere. Cell ranges
+      and the fill handle are unaffected either way. Off by default, so a plain click still
+      selects a row exactly as it always has.
+    </p>
+    <p class="lead-in">
+      <code>checkboxOnly</code> only narrows which gesture may change selection; it does not
+      grant selection where <code>mode: 'none'</code> has already refused it, and it composes
+      normally with <code>mode: 'single'</code> — the checkbox remains the only way to change
+      which one row is selected.
+    </p>
 
     <div class="why">
       <p><strong>Ctrl+Shift+Arrow is the keyboard form of ctrl-dragging.</strong> The first press
@@ -4696,6 +4972,15 @@ createChart({
       chart stops moving, even though time is still passing &mdash; and the silence is usually the
       thing worth seeing. <code>maxAge</code> is a span of wall clock, so it means the same thing
       whatever the feed is doing.</p>
+      <p><strong>An empty reduction is a gap, not a zero.</strong> <code>fn: 'avg'</code> above
+      &mdash; and <code>sum</code>, <code>mean</code>, <code>min</code>, <code>max</code>,
+      <code>first</code> and <code>last</code> beside it &mdash; read as <code>null</code> 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. <code>count</code> and <code>countValues</code> are the deliberate
+      exception: they are already honest at zero, a tally of rows or of values actually present, so
+      reach for <code>countValues</code> when the reading you actually want is &ldquo;how many
+      arrived&rdquo; and zero has to be drawn as zero rather than as a gap.</p>
       <p><strong>Two bounds, one eviction path.</strong> <code>maxAge</code> and
       <code>maxRows</code> 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.
@@ -4754,6 +5039,16 @@ createChart({
       that far ahead the chart shows its empty state, with the same warning.
       <code>chart.data().windowed</code> counts the readings dropped at either edge of the
       window. The fix for the warning is the producer&rsquo;s clock, not a wider window.</p>
+      <p><strong>The other edge: a producer that has simply stopped.</strong> The case above is a
+      clock running fast; the opposite is a feed that has gone quiet for longer than the window
+      (BACKLOG-0001088) &mdash; 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 <strong>per
+      chart instance</strong>, naming the span and how old the newest reading actually is, so a dead
+      feed reads as &ldquo;no data&rdquo; rather than as a chart that quietly stopped moving. Two
+      charts bound to the same stale column each get their own warning &mdash; 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.</p>
       <p><strong>Idle costs nothing.</strong> Both halves advance on a plain interval &mdash; a
       quarter of the window, clamped to between 50&nbsp;ms and one second &mdash; and never on an
       animation frame. The source&rsquo;s wake returns after a single number comparison unless a
@@ -5368,6 +5663,17 @@ grid.annotate.use(null);                     <span class="cmt">// hand the grid
     <h3>Keyboard</h3>
     <p>Every operation is reachable without a pointer. Resizing and reordering a column were once
       drag-only; both now have key bindings and menu items, so nothing depends on dragging.</p>
+    <p><strong>Entering the grid.</strong> The grid is one stop in the page's tab order. Pressing
+      <kbd>Tab</kbd> into a grid that has not been used yet puts focus on the grid itself, and the
+      grid draws a focus ring around its own edge at once, in the theme's focus colour, so a keyboard
+      user can see where focus went before pressing anything else. In Windows High Contrast Mode
+      the ring is drawn in the system text colour. A screen reader announces the grid (or tree grid),
+      its row and column counts and whether it is read-only. The first arrow key, <kbd>Home</kbd>
+      or <kbd>Ctrl</kbd>+<kbd>Home</kbd> moves focus to a cell, and the ring moves with it. From then
+      on the cell you were on is the grid's tab stop: <kbd>Shift</kbd>+<kbd>Tab</kbd> from the first
+      cell leaves the grid, and <kbd>Tab</kbd> back into the grid returns to that cell. The grid takes
+      the tab stop back only when that cell is outside the rendered rows, and then draws its own
+      ring again.</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Keys</th><th>Does</th></tr></thead>
@@ -5717,10 +6023,11 @@ grid.edit.pasteInto(text);                        <span class="cmt">// Excel's t
           <tr><td class="sig">Delete / Backspace</td><td class="desc">Clear the selected cells.</td></tr>
           <tr><td class="sig">Enter</td><td class="desc">Start editing; commit and step down.</td></tr>
           <tr><td class="sig">Tab</td><td class="desc">Commit and step across.</td></tr>
-          <tr><td class="sig">Escape</td><td class="desc">Cancel the edit; restore a maximised grid once nothing else wants it.</td></tr>
+          <tr><td class="sig">Escape</td><td class="desc">Cancel the edit; restore a maximised grid once nothing else wants it. Coming back from full screen, whether by Escape or the rail's restore button, puts focus back on the cell you were on, not on the page.</td></tr>
           <tr><td class="sig">Ctrl/Cmd + F</td><td class="desc">Open the <a href="#find">find bar</a>; in it, Enter / Shift+Enter step through the matches and Escape closes.</td></tr>
           <tr><td class="sig">Space</td><td class="desc">Toggle the row's selection.</td></tr>
           <tr><td class="sig">Home / End, Page Up / Down</td><td class="desc">Jump; with Ctrl, to the ends of the grid.</td></tr>
+          <tr><td class="sig">Ctrl/Cmd + Alt + H</td><td class="desc">Move focus to the column heading. On a heading, ArrowLeft / ArrowRight move between headings, Enter or Space sort by the column (Shift to add it to the sort), Alt + arrows resize, Shift + arrows move the column, Alt + ArrowDown opens the column menu, and ArrowDown or Escape return you to the data. The full list is in the <a href="#accessibility-guide">accessibility guide</a>.</td></tr>
         </tbody>
       </table>
     </div>
@@ -5728,6 +6035,10 @@ grid.edit.pasteInto(text);                        <span class="cmt">// Excel's t
       <p>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.</p>
+      <p>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.</p>
     </div>
 
     <h2 id="rules-guide">Conditional formatting</h2>
@@ -7224,7 +7535,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">filter:changed</td><td class="desc">The condition tree or the quick filter changed.</td></tr>
           <tr><td class="name">page:changed</td><td class="desc">Fired after the rows have moved, whether the page changed by API or by the pager control.</td></tr>
           <tr><td class="name">sort:changed</td><td class="desc">The full sort entry list.</td></tr>
-          <tr><td class="name">state:changed</td><td class="desc">report lists anything a restore could not apply.</td></tr>
+          <tr><td class="name">state:changed</td><td class="desc">Every state change, whether a user gesture or a programmatic call, announced exactly once — with one known gap, filters.where (BACKLOG-0001235), which changes the where section and the rows on screen without raising it. cause is 'user', 'apply' or 'reset'; sections names the GridState keys that moved; report lists anything a restore could not apply. A save layer subscribes to this one event and ignores cause 'reset'.</td></tr>
           <tr><td class="name">state:reset</td><td class="desc">The grid was returned to its baseline.</td></tr>
           <tr><td class="name">timeline:attached</td><td class="desc">A time brush was connected to the grid.</td></tr>
           <tr><td class="name">timeline:detached</td><td class="desc">The brush was removed.</td></tr>
@@ -7471,9 +7782,31 @@ grid.licence.state();   <span class="cmt">// 'licensed' | 'localhost' | 'trial'<
 });</code></pre>
     </div>
 
+    <h3 id="wrapping-creategrid-recipe">House-wide defaults, without patching <code>createGrid</code></h3>
+    <p class="lead-in">
+      <code>createGrid</code> is exported through a getter with no setter, so
+      <code>LatticeGrid.createGrid = myWrapper</code> does not replace it — silently in a plain
+      script, with a <code>TypeError</code> in a module (see the <a
+      href="API.html#wrapping-creategrid">reference</a> for the exact descriptor). Own the seam
+      yourself instead: one module that every call site imports from.
+    </p>
+    <div class="example">
+      <pre><code><span class="cmt">// lattice.js</span>
+<span class="kw">import</span> { createGrid <span class="kw">as</span> baseCreateGrid } <span class="kw">from</span> '@toclocoinc/lattice-grid';
+
+<span class="kw">export function</span> createGrid(element, config) {
+  <span class="kw">return</span> baseCreateGrid(element, { theme: 'house', locale: 'en-GB', ...config });
+}</code></pre>
+    </div>
+    <p class="lead-in">
+      There is no shipped <code>defaults()</code> call that does this for you today (a separate card,
+      BACKLOG-0001187, is considering one) — a wrapping module you own and every call site imports is
+      the supported pattern until then.
+    </p>
+
     <footer>
       <p>
-        Lattice Grid 1.7.1 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+        Lattice Grid 1.56.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
         Written against the shipped source. Where this guide and the code disagree, the code wins,
         please <a href="https://www.latticegrid.dev">tell us</a>.
       </p>