@toclocoinc/lattice-grid 1.53.0 → 1.55.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.53.0</p>
+    <p class="rail__sub">Developer guide · v1.55.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.55.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.55.0'</span>
 LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid to hand</span></code></pre>
     </div>
     <p class="lead-in">
@@ -1354,6 +1359,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 +1999,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>
@@ -3306,7 +3343,17 @@ createGrid(right, {
       <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>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>
@@ -4743,6 +4790,17 @@ createChart({
       <code>kind: 'count'</code> is refused with a warning rather than quietly given a second
       meaning. The x column has to be continuous and carry wall-clock times &mdash; a banded or
       categorical axis has no domain to roll.</p>
+      <p><strong>A producer whose clock runs ahead.</strong> A reading stamped slightly ahead of the
+      viewer&rsquo;s clock carries the end of the domain forward with it, so the newest mark is
+      drawn. How far is bounded: <strong>a quarter of the span</strong> (15&nbsp;s on a
+      60&nbsp;s window). A reading further ahead than that is treated as a producer whose clock is
+      wrong &mdash; 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&rsquo;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.
+      <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>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
@@ -5357,6 +5415,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>
@@ -5706,10 +5775,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>
@@ -5717,6 +5787,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>
@@ -6991,7 +7065,7 @@ grid.import.apply(preview);</code></pre>
           <tr><td class="name">createKPI</td><td class="desc">A KPI / stat-tile view (module <code>kpi</code>) of a dataset as a panel of aggregate tiles — each tile a <code>sum</code>, <code>avg</code>, <code>min</code>, <code>max</code>, <code>count</code>, <code>countDistinct</code> or a <code>custom</code> reducer over the routed rows, with an optional <code>filter</code> predicate, number <code>format</code> (<code>number</code>/<code>currency</code>/<code>percent</code>/<code>compact</code>), a <code>baseline</code> for a delta, semantic threshold bands (<code>thresholds</code> with two cut points and a direction, or an explicit <code>bands</code> list, giving a <code>good</code>/<code>warn</code>/<code>critical</code> status kept separate from any accent), and an optional <code>sparkline</code> series. It is a dataset viewer like any other: it consumes data through the same keyed-diff <code>rows.apply({ add, update, remove })</code> contract a grid exposes, so a Data Router can <code>attach(value, kpi)</code> and drive a KPI panel beside a grid, a kanban and a chart off one feed. Updates are incremental — a delta adjusts each tile's running accumulator by only the rows it carries (an add contributes, a remove reverses, an update reverses-then-contributes), the two bounded exceptions being a <code>min</code>/<code>max</code> whose current extreme is removed (a rescan of that tile's own value multiset) and a <code>custom</code> reducer (recomputed over the filtered store, an arbitrary function having no inverse). Each tile is a labelled <code>&lt;figure&gt;</code>, focusable and keyboard-activatable, its value announced, the sparkline respecting <code>prefers-reduced-motion</code>; a <code>tile:click</code> event (also from the keyboard) lets a host drill down or filter a routed grid. Pass <code>null</code> as the element for a headless panel that computes the same tile model without a DOM. Not a dashboard layout engine (that is the parked dashboard generator) and no charting beyond the minimal sparkline (that is the charts module).</td></tr>
           <tr><td class="name">createAI</td><td class="desc">Create an AI narrative / insights controller (module <code>ai</code>) over a live grid. It produces a short, plain-language narrative of the grid's <em>computed</em> figures — a per-KPI / per-chart / per-column <code>explain</code>, or an <code>insights</code> panel over the current filtered view. The grid makes no AI call of its own: <code>createAI</code> imports no provider SDK, holds no key, and makes no network request; it calls one host callback, <code>ask({ system, messages, prompt, tools?, schema?, signal })</code> — your model, your key, your privacy decision — the same philosophy as the data adapters. Two grounding paths feed one guard: where the provider offers tool-use the model is given a curated read-only tool set (<code>getSchema</code>, <code>getProfile</code>, <code>getStatistics</code>, <code>getForecast</code>, <code>runQuery</code>) and the grid's own engine computes what it asks for; otherwise the module builds a facts packet from <code>grid.statistics</code>/the profile/forecasts/view counts and passes it in the prompt. Every figure in the narrative is reconciled against the values the engine produced this render — an ungrounded number is stripped before display (the number-reconciliation guard), so a hallucinated figure never reaches the user. The prompt is constrained to narrate-only; the layer is read-only and never mutates data. <code>redact</code> (a column id, a list, or a predicate) and <code>maxRows</code> bound what the module hands <code>ask()</code>, and the module sends nothing itself; an <code>ask()</code> error surfaces a friendly message and the grid stays fully usable, AI being additive rather than load-bearing. Complementary to <code>grid.ai</code> (the intent/plan skill layer): pass no <code>ask</code> and it adopts the grid's configured <code>ai.ask</code>, running the facts-packet path over it. Pass a headless grid for a DOM-free narrative; <code>facts(target)</code> returns the exact grounded packet without calling <code>ask()</code>. UMD global <code>LatticeGridAI</code>.</td></tr>
                     <tr><td class="name">createTabs</td><td class="desc">Create a tabbed grid (module <code>tabs</code>): a <code>role="tablist"</code> strip above a stack of <code>role="tabpanel"</code> regions, each hosting its own, independently-configured <code>createGrid</code> instance — "configure each tab as per a normal grid" rather than one grid whose state is swapped (<code>ColumnModel#applyState</code> only repositions/hides/resizes existing columns by id; it carries no field, type or row data, so a state-swap only works when every tab shares one schema). <code>createGrid</code> is injected (<code>createTabs(el, { createGrid, tabs })</code>), the same pattern the React/Vue/Svelte adapters use, so the module imports no engine code and adds nothing to a page that does not load it. A tab that names <code>from: '&lt;tabId&gt;'</code> gets a <code>source: { mode: 'derived', from: &lt;the parent tab’s live grid&gt;, where, group, join, … }</code> wired for it automatically — reusing the shipped derived-source mechanism rather than a new config-inheritance one — and activating a derived tab materialises its whole ancestor chain first; a cyclic <code>from</code> graph is refused (naming the exact cycle) when <code>createTabs</code> is called, not at first click. A tab’s grid mounts on first activation and then stays alive, hidden, so its scroll/selection/filters/sort/grouping/expansion — and an open cell/row editor, left exactly as it was, uncommitted and undiscarded — survive a switch natively; <code>destroy()</code> tears every mounted tab down. The strip is a real tablist with <code>aria-selected</code>, a roving <code>tabindex</code>, and manual-activation keyboard handling (arrows/Home/End move focus, Enter/Space or a click activates). Events: <code>tab:changed</code>, a cancellable <code>beforeTabChange</code> paired with <code>tabChange:cancelled</code>. UMD global <code>LatticeGridTabs</code>.</td></tr>
-          <tr><td class="name">createLayout</td><td class="desc">Create a reconfigurable dashboard layout (module <code>layout</code>): a cell grid inside an element, and a set of windows on it that a user can move, resize and close by drag <em>or</em> by keyboard &mdash; the surface a customer would otherwise reach for GridStack to get. It is <strong>payload-agnostic</strong>: a window body is a <code>div</code> with an <code>id</code> that the module creates, sizes and never reads, so it imports no engine code at all (not even <code>createGrid</code>) and its own code is 11,202 bytes gzipped, measured against a 62,206-byte fixed bundle floor. <code>columns</code>/<code>rows</code> divide the element; <code>overflowX</code> and <code>overflowY</code> are <em>independent</em> axes, each <code>'static'</code> (tracks divide the container with <code>minmax(0, 1fr)</code>) or <code>'scroll'</code> (tracks take a fixed <code>columnWidth</code>/<code>rowHeight</code> and the canvas extends past the viewport, so a column keeps the size it asked for &mdash; measured: shrinking a 600px host to 300px leaves a 200px column at 200px). Spacing takes a real CSS length: a number of pixels, or <code>'200px'</code>, <code>'25%'</code>, <code>'1fr'</code>, <code>'2rem'</code>; anything else is refused by name and replaced by the default, because the value reaches an inline style. Windows are placed by 1-based <code>xPos</code>/<code>yPos</code>/<code>xSize</code>/<code>ySize</code>, or auto-placed in the first free cell; <code>chrome</code> defaults on, and <code>closable</code>/<code>movable</code>/<code>resizable</code> all default <em>off</em>, so a fixed dashboard is fixed without opting out. <code>compact: 'vertical'</code> pushes displaced windows down then pulls them up (<code>window:moved</code> carries both <code>to</code> and <code>landed</code>); <code>'none'</code> keeps every window where it is put. <code>closable</code>/<code>movable</code>/<code>resizable</code> each also take a <em>layout-level</em> default of the same name, which a window's own boolean overrides, and <code>setInteractive(true|false|{movable, resizable, closable})</code> changes that default at runtime &mdash; the &ldquo;Edit layout&rdquo; button &mdash; without destroying the layout or any payload in it, with <code>getInteractive()</code> reading it back. Locking always wins and unlocking never overrides an opt-out: <code>setInteractive(false)</code> pins a window that declared <code>movable: true</code>, while <code>setInteractive(true)</code> leaves a window that declared <code>movable: false</code> pinned. The config key and the method are deliberately different: <code>movable: false</code> in the config states the <em>default</em> for windows that declare nothing and takes nothing away from one that opted in, whereas <code>setInteractive(false)</code> is an <em>active lock</em>. <code>getInteractive()</code> is three-valued &mdash; <code>undefined</code> for unset, <code>true</code>, or <code>false</code> for a lock &mdash; and a key carrying <code>undefined</code> is treated as absent, so <code>setInteractive(getInteractive())</code> is a no-op in every state. It moves both halves of the enforcement, the rendered handles <em>and</em> the pointer and keyboard gesture checks, and fires no event because a mode is not an arrangement &mdash; <code>getLayout()</code> neither carries it nor restores it. A locked layout is not a read-only dashboard: what is inside a window is configured with that payload's own settings. Keyboard parity with the drag: a focusable handle per window running the kanban board's grab/move/drop/cancel model, with a polite live region announcing grabbed, every tentative position, dropped, cancelled and reverted. It owns exactly <strong>one</strong> <code>ResizeObserver</code> for the whole layout, over two targets, and tells payloads their new content box through <code>window:resized</code> &mdash; it never calls into a payload, because it cannot know what one is. Events: <code>window:moved</code>, <code>window:resized</code>, <code>window:closed</code>, <code>layout:changed</code>, the cancellable <code>beforeWindowMove</code>/<code>beforeWindowResize</code>/<code>beforeWindowClose</code> and their <code>*:cancelled</code> pairs; drag progress is not emitted per frame. <code>getLayout()</code>/<code>setLayout()</code> round-trip the arrangement as plain JSON, and <code>getState()</code>/<code>setState()</code> are the versioned pair. Closing a window does <strong>not</strong> destroy its payload &mdash; the container is handed back on <code>window:closed</code> and the host owns that lifecycle. UMD global <code>LatticeGridLayout</code>.</td></tr>
+          <tr><td class="name">createLayout</td><td class="desc">Create a reconfigurable dashboard layout (module <code>layout</code>): a cell grid inside an element, and a set of windows on it that a user can move, resize and close by drag <em>or</em> by keyboard &mdash; the surface a customer would otherwise reach for GridStack to get. It is <strong>payload-agnostic</strong>: a window body is a <code>div</code> with an <code>id</code> that the module creates, sizes and never reads, so it imports no engine code at all (not even <code>createGrid</code>) and its own code is 12,890 bytes gzipped, measured against a 62,206-byte fixed bundle floor. <code>columns</code>/<code>rows</code> divide the element; <code>overflowX</code> and <code>overflowY</code> are <em>independent</em> axes, each <code>'static'</code> (tracks divide the container with <code>minmax(0, 1fr)</code>) or <code>'scroll'</code> (tracks take a fixed <code>columnWidth</code>/<code>rowHeight</code> and the canvas extends past the viewport, so a column keeps the size it asked for &mdash; measured: shrinking a 600px host to 300px leaves a 200px column at 200px). Spacing takes a real CSS length: a number of pixels, or <code>'200px'</code>, <code>'25%'</code>, <code>'1fr'</code>, <code>'2rem'</code>; anything else is refused by name and replaced by the default, because the value reaches an inline style. Windows are placed by 1-based <code>xPos</code>/<code>yPos</code>/<code>xSize</code>/<code>ySize</code>, or auto-placed in the first free cell; <code>chrome</code> defaults on, and <code>closable</code>/<code>movable</code>/<code>resizable</code> all default <em>off</em>, so a fixed dashboard is fixed without opting out. <code>compact: 'vertical'</code> pushes displaced windows down then pulls them up (<code>window:moved</code> carries both <code>to</code> and <code>landed</code>); <code>'none'</code> keeps every window where it is put. <code>closable</code>/<code>movable</code>/<code>resizable</code> each also take a <em>layout-level</em> default of the same name, which a window's own boolean overrides, and <code>setInteractive(true|false|{movable, resizable, closable})</code> changes that default at runtime &mdash; the &ldquo;Edit layout&rdquo; button &mdash; without destroying the layout or any payload in it, with <code>getInteractive()</code> reading it back. Locking always wins and unlocking never overrides an opt-out: <code>setInteractive(false)</code> pins a window that declared <code>movable: true</code>, while <code>setInteractive(true)</code> leaves a window that declared <code>movable: false</code> pinned. The config key and the method are deliberately different: <code>movable: false</code> in the config states the <em>default</em> for windows that declare nothing and takes nothing away from one that opted in, whereas <code>setInteractive(false)</code> is an <em>active lock</em>. <code>getInteractive()</code> is three-valued &mdash; <code>undefined</code> for unset, <code>true</code>, or <code>false</code> for a lock &mdash; and a key carrying <code>undefined</code> is treated as absent, so <code>setInteractive(getInteractive())</code> is a no-op in every state. It moves both halves of the enforcement, the rendered handles <em>and</em> the pointer and keyboard gesture checks, and fires no event because a mode is not an arrangement &mdash; <code>getLayout()</code> neither carries it nor restores it. A locked layout is not a read-only dashboard: what is inside a window is configured with that payload's own settings. <code>maximise(id)</code>, <code>minimise(id)</code> and <code>restore(id)</code> are the display modes, with <code>maximised()</code> and <code>minimised()</code> reading them back: maximise fills the <em>layout host</em> rather than the browser window (no <code>position: fixed</code>, whose containing block is the nearest ancestor with a <code>transform</code> or a <code>contain</code>; no reparenting; nothing that can disturb the page around the dashboard), hides the other windows, runs <strong>no compaction at all</strong> and keeps the payload container as the very same DOM node &mdash; and <kbd>Escape</kbd> restores it from anywhere inside the layout. <code>minimise</code> draws a window as a single row and hides its payload while its chrome stays to carry the way back, so the windows below pull up on screen; in the arrangement nothing moves at all, because the collapse is a projection of the dashboard rather than a change to it, so restoring gives back exactly the arrangement that was there in <em>any</em> order and with any number of other windows still collapsed. A <code>chrome: false</code> window is refused by name. Both controls are opt-in per window (<code>maximisable</code>, <code>minimisable</code>) with a layout-level default of the same name, and <code>setInteractive()</code> deliberately does not touch either: a mode is not an arrangement, so neither appears in <code>getLayout()</code>, which reports the underlying placement in both states. Keyboard parity with the drag: a focusable handle per window running the kanban board's grab/move/drop/cancel model, with a polite live region announcing grabbed, every tentative position, dropped, cancelled and reverted. It owns exactly <strong>one</strong> <code>ResizeObserver</code> for the whole layout, over two targets, and tells payloads their new content box through <code>window:resized</code> &mdash; it never calls into a payload, because it cannot know what one is. Events: <code>window:moved</code>, <code>window:resized</code>, <code>window:closed</code>, <code>layout:changed</code>, the cancellable <code>beforeWindowMove</code>/<code>beforeWindowResize</code>/<code>beforeWindowClose</code> and their <code>*:cancelled</code> pairs; drag progress is not emitted per frame. <code>getLayout()</code>/<code>setLayout()</code> round-trip the arrangement as plain JSON, and <code>getState()</code>/<code>setState()</code> are the versioned pair. Closing a window does <strong>not</strong> destroy its payload &mdash; the container is handed back on <code>window:closed</code> and the host owns that lifecycle. UMD global <code>LatticeGridLayout</code>.</td></tr>
           <tr><td class="name">createDevtools</td><td class="desc">Mount the devtools panel against a grid, including its accessibility checks.</td></tr>
           <tr><td class="name">createGantt</td><td class="desc">Create a project-planning Gantt controller (module <code>gantt</code>) over a task list and a dependency list. A CPM engine (<code>computeSchedule</code>) computes each task's early/late start and finish, its slack and the zero-float critical path, honouring the four link types (<code>LINK_TYPES</code>: FS/SS/FF/SF) with lag, and recomputes on every edit — emitting <code>schedule</code> or, on a dependency cycle or bad input, <code>error</code> (a code from <code>SCHEDULE_ERROR</code>). Milestones are zero-duration points; summary (WBS) tasks are derived from their children (earliest start, latest finish, weighted progress) rather than scheduled; <code>findViolations</code> flags a task placed earlier than its predecessors allow, and <code>toISODate</code> maps an engine day-number back to a calendar date.</td></tr>
           <tr><td class="name">createLatticeGridElement</td><td class="desc">Build the element class without registering it, for a custom registry.</td></tr>
@@ -7462,7 +7536,7 @@ grid.licence.state();   <span class="cmt">// 'licensed' | 'localhost' | 'trial'<
 
     <footer>
       <p>
-        Lattice Grid 1.7.1 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+        Lattice Grid 1.55.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>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.53.0, type declarations
+ * Lattice Grid 1.55.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -250,11 +250,6 @@ export interface NumberFormat {
    * leaves the remainder in English rather than showing raw keys.
    */
   messages?: Record<string, string | Record<string, string>>;
-  /**
-   * Writing direction. Omit to settle it from the element's own `dir` and then
-   * from `locale`: `ar`, `he`, `fa` and the rest resolve to `rtl`.
-   */
-  direction?: 'ltr' | 'rtl';
   scale?: number;
 }
 
@@ -1747,6 +1742,14 @@ export interface GridConfig {
   /** Page the rows rather than scrolling them. */
   pagination?: PaginationConfig | boolean;
   locale?: string;
+  /**
+   * Writing direction. Omit it, or say `'auto'`, to settle it from the
+   * element's own computed `dir` and then from `locale`: `ar`, `he`, `fa` and
+   * the rest resolve to `rtl`. In a right-to-left grid the logical alignments
+   * `start`/`end` mirror while the physical `left`/`right` do not (see
+   * {@link Align}).
+   */
+  direction?: 'ltr' | 'rtl' | 'auto';
   /**
    * IANA zone every date column formats in, e.g. 'Europe/London' or 'UTC'.
    * Omit to use each viewer's own zone. A column's own `format.timeZone` wins.
@@ -4410,6 +4413,22 @@ export interface ColumnsApi {
    */
   decorate(id: string, decoration: DecorationName | DecorationSpec | null, opts?: { variant?: VariantSpec }): void;
   autoSize(ids?: string | string[]): void;
+  /**
+   * Size the visible resizable columns so that every column the grid draws,
+   * together, exactly fills the width the cells occupy: the body viewport's
+   * client width at the moment of the call, which excludes the vertical
+   * scrollbar when the grid draws one and is the full inner width when it does
+   * not. Columns it does not size keep their width and are taken out of that
+   * width first: `resizable: false` columns and the grid's own selection
+   * checkbox, detail expander, group and tree columns. The rest share what is
+   * left in proportion to their current widths, within each `min`/`max`. If
+   * that leaves less than their minimums, each is set to its minimum (never
+   * below), the grid scrolls horizontally, and a `[lattice]` warning says so.
+   * Rows given to `createGrid` or `rows.load()` before the call are counted.
+   * One-shot: it sets fixed widths once (a `flex` column included) and does not
+   * follow later changes; after a resize, or after rows arriving later bring a
+   * vertical scrollbar in, call it again.
+   */
   fit(): void;
   group(ids: string | string[]): void;
   pivot(ids: string | string[]): void;
@@ -5520,13 +5539,21 @@ export interface PaginationApi {
 /** What a cell-menu builder and a host item's `action` are handed. */
 export interface CellMenuParams {
   key: string;
-  colId: string;
+  /**
+   * The column under the pointer, or `null` when the row belongs to no column:
+   * a right-click in the empty tail of a row beyond the last column
+   * (BACKLOG-0001153), or on a group row, pivot group row or full-width row.
+   * The grid-level menu stands in that case (BACKLOG-0001068).
+   */
+  colId: string | null;
+  /** The cell's value; `undefined` when there is no column. */
   value: unknown;
   /** The row wrapper. */
   row: Row;
   /** Your original row object. */
   data: unknown;
-  column: ResolvedColumn;
+  /** The resolved column; `undefined` when `colId` is `null`. */
+  column: ResolvedColumn | undefined;
   index: number;
   grid: Grid;
 }
@@ -8715,14 +8742,17 @@ declare module 'lattice-grid/modules/kpi' {
     value: unknown;
     formatted: string;
     /**
-     * The tile's semantic band, or `unknown` when the panel holds no rows at
-     * all. `unknown` is decided from data presence before any threshold is
+     * The tile's semantic band, or `unknown` when the tile measured nothing.
+     * `unknown` is decided from data presence before any threshold is
      * consulted: an aggregation over nothing returns the identity of its
      * operation (`sum` and `count` return 0), and 0 is a number a threshold
-     * grades, so without it an empty panel would report as a healthy one. A
-     * tile whose `filter` matches none of the rows the panel *does* hold has
-     * measured a real zero and is banded normally. `null` means the tile has no
-     * thresholds or bands configured.
+     * grades, so without it an empty panel would report as a healthy one.
+     *
+     * Two things make a tile `unknown`: the panel holds no rows at all, or the
+     * tile's `field` names no column on the bound grid, so it never read a cell
+     * to reduce over. A tile whose `filter` matches none of the rows the panel
+     * *does* hold is neither — it has measured a real zero and is banded
+     * normally. `null` means the tile has no thresholds or bands configured.
      */
     status: 'good' | 'warn' | 'critical' | 'unknown' | null;
     target?: number;
@@ -8746,6 +8776,14 @@ declare module 'lattice-grid/modules/kpi' {
     rows?: KPIRow[];
     grid?: unknown;
     rowKey?: string | ((row: KPIRow) => unknown);
+    /**
+     * Extra columns of the bound `grid` to project onto the rows a tile `filter`
+     * sees, beyond the fields the tiles themselves declare. A grid-bound panel
+     * hands a filter a projection, not a whole grid row, so a filter over a
+     * column no tile names would otherwise read `undefined` and report a
+     * confident zero. Ignored on a panel over a plain `rows` array.
+     */
+    fields?: string[];
     tiles?: KPITile[];
     columns?: number;
     ariaLabel?: string;
@@ -9348,6 +9386,21 @@ declare module 'lattice-grid/modules/layout' {
     movable?: boolean;
     /** Whether the window can be resized by drag or keyboard (default `false`). */
     resizable?: boolean;
+    /**
+     * Whether to offer a maximise control in the chrome (default `false`).
+     *
+     * Maximising fills the **layout host**, not the browser window, and hides
+     * every other window for the duration. Escape restores it, unless a payload
+     * has already claimed the key.
+     */
+    maximisable?: boolean;
+    /**
+     * Whether to offer a minimise control in the chrome (default `false`).
+     *
+     * A window with `chrome: false` cannot be minimised whatever this says:
+     * there would be nothing left on screen to restore it with.
+     */
+    minimisable?: boolean;
     /** Padding inside the window; the layout's `padding` (default `'5px'`) otherwise. */
     padding?: number | string;
     /** The `id` given to the payload container (default `` `${id}-body` ``). */
@@ -9469,6 +9522,16 @@ declare module 'lattice-grid/modules/layout' {
     resizable?: boolean;
     /** The default `closable` for windows that declare none (default `false`); see `movable`. */
     closable?: boolean;
+    /**
+     * The default `maximisable` for windows that declare none (default `false`).
+     *
+     * Not touched by `setInteractive()`: a display mode neither moves nor resizes
+     * a window in the arrangement, so a locked dashboard can still be blown up
+     * to read.
+     */
+    maximisable?: boolean;
+    /** The default `minimisable` for windows that declare none (default `false`); see `maximisable`. */
+    minimisable?: boolean;
     /** The windows, in mount order. */
     windows?: LayoutWindow[];
     /** An arrangement to apply at mount, as produced by `getLayout()`. */
@@ -9513,7 +9576,51 @@ declare module 'lattice-grid/modules/layout' {
     move(id: string, to: Partial<LayoutPlacement>): boolean | Promise<boolean>;
     /** Close a window through `beforeWindowClose`; the payload is not destroyed. */
     close(id: string): boolean | Promise<boolean>;
-    /** The full current arrangement. */
+    /**
+     * Blow one window up to fill the layout host, hiding the rest.
+     *
+     * It fills the **host element**, not the browser window, so there is no
+     * `position: fixed` (whose containing block is the nearest ancestor carrying
+     * a `transform` or a `contain`, which is why the same rule fills the screen
+     * on one page and lands in a 300px box on the next), no reparenting and
+     * nothing that can disturb the page around the dashboard.
+     *
+     * **Nothing moves**: no compaction runs, no placement changes, and the
+     * payload container is the same DOM node throughout. **Escape restores it**,
+     * from anywhere inside the layout — a focused grid body cell or column
+     * heading included — unless a payload has already claimed the key: an open
+     * cell editor, filter menu or column menu closes first, and the next Escape
+     * restores the window. Afterwards focus lands on the window's maximise
+     * control. A minimised window is expanded first, and maximising a second
+     * window restores the first.
+     */
+    maximise(id: string): boolean;
+    /**
+     * Collapse one window to a single row: its payload is hidden and its chrome
+     * stays, carrying the control that brings it back.
+     *
+     * On screen it becomes one row and the windows below pull up into the space
+     * under `compact: 'vertical'`. In the arrangement nothing moves at all — the
+     * collapse is a projection of it — so `restore()` gives back exactly the
+     * arrangement that was there, in **any** order and with any number of other
+     * windows still collapsed.
+     *
+     * A window with `chrome: false` is refused, with a warning naming it.
+     */
+    minimise(id: string): boolean;
+    /** Leave whichever display mode a window is in; `false` when it was in none. */
+    restore(id: string): boolean;
+    /** The id of the window filling the host, or `null`. At most one. */
+    maximised(): string | null;
+    /** The ids of every currently minimised window, in mount order. */
+    minimised(): string[];
+    /**
+     * The full current arrangement.
+     *
+     * **A mode is not an arrangement**: this reports the *underlying* placement
+     * of a maximised or minimised window — where it will be when restored — never
+     * the geometry it is drawn at.
+     */
     getLayout(): LayoutSnapshot;
     /** Restore an arrangement; never throws on garbage. */
     setLayout(incoming: LayoutSnapshot | LayoutWindow[]): number;