@toclocoinc/lattice-grid 1.56.0 → 1.57.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.56.0</p>
+    <p class="rail__sub">Developer guide · v1.57.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.56.0</span>
+        <span class="chip">Version 1.57.0</span>
           <span class="chip">Zero dependencies</span>
         <span class="chip">No build step</span>
       </p>
@@ -1278,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.56.0'</span>
+      <pre><code>grid.getVersion();          <span class="cmt">// '1.57.0'</span>
 LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid to hand</span></code></pre>
     </div>
     <p class="lead-in">
@@ -2755,13 +2755,94 @@ createGrid(right, { columns, rows,
       <table>
         <thead><tr><th>Event</th><th>Fired on</th><th>Carries</th></tr></thead>
         <tbody>
-          <tr><td class="name">row:received</td><td class="desc">the target</td><td class="desc"><code>{ data, at, rejected }</code></td></tr>
+          <tr><td class="name">beforeRowReceive</td><td class="desc">the target, before the insert</td><td class="desc"><code>{ data, at, overKey, source }</code>, cancellable</td></tr>
+          <tr><td class="name">rowReceive:cancelled</td><td class="desc">the target, on a veto</td><td class="desc"><code>{ data, at, overKey, source, reason }</code></td></tr>
+          <tr><td class="name">row:received</td><td class="desc">the target</td><td class="desc"><code>{ data, at, overKey, rejected }</code></td></tr>
           <tr><td class="name">row:sent</td><td class="desc">the source, on a move</td><td class="desc"><code>{ key, data, mode }</code></td></tr>
           <tr><td class="name">row:copied</td><td class="desc">the source, on a copy</td><td class="desc"><code>{ key, data, mode }</code></td></tr>
         </tbody>
       </table>
     </div>
 
+    <p class="lead-in">
+      Those events all describe a drag that has <em>settled</em>. To follow one while it is
+      happening — to highlight a candidate row, drive your own drop indicator, or update a side
+      panel as the row travels — there are four more, and they all fire on the grid the drag
+      <strong>started</strong> in, for a same-grid reorder and a cross-grid transfer alike. A drag is
+      one gesture with one owner, and the source is the only grid present for the whole of it, where
+      the pointer may cross several others or none; <code>over</code> names whichever grid the event
+      is about, so one subscription can decorate any of them.
+    </p>
+
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th><th>Carries</th></tr></thead>
+        <tbody>
+          <tr><td class="name">rowDrag:started</td><td class="desc">the press passed the drag threshold</td><td class="desc"><code>{ key, data, over, at, overKey }</code></td></tr>
+          <tr><td class="name">rowDrag:moved</td><td class="desc">the pointer is over a candidate position; <strong>at most once per animation frame</strong></td><td class="desc"><code>{ key, data, over, at, overKey }</code></td></tr>
+          <tr><td class="name">rowDrag:left</td><td class="desc">the pointer left a grid; <code>over</code> is the grid it left</td><td class="desc"><code>{ key, data, over, at: null, overKey: null }</code></td></tr>
+          <tr><td class="name">rowDrag:ended</td><td class="desc">the gesture ended, drop or no drop</td><td class="desc"><code>{ key, data, over, at, overKey, dropped }</code></td></tr>
+        </tbody>
+      </table>
+    </div>
+
+    <div class="example">
+      <p class="example__label">Highlight the row a drag is hovering, and clean up however it ends</p>
+      <pre><code>backlog.on('rowDrag:moved', (e) =&gt; {
+  <span class="cmt">// e.over is the grid under the pointer, null over none.</span>
+  paintCandidate(e.over, e.overKey);       <span class="cmt">// overKey is null where there is no row to name</span>
+});
+backlog.on('rowDrag:left', (e) =&gt; clearCandidate(e.over));
+backlog.on('rowDrag:ended', (e) =&gt; {
+  clearCandidate(e.over);                  <span class="cmt">// always fires, even released off every grid</span>
+  <span class="kw">if</span> (!e.dropped) toast('Nothing moved');
+});</code></pre>
+    </div>
+
+    <div class="why">
+      <p><strong>Notifications, not gates.</strong> None of the four is cancellable and none carries
+      <code>preventDefault</code>. The drop is already vetoable twice over — <code>beforeRowMove</code>
+      for a reorder, <code>beforeRowReceive</code> 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.</p>
+      <p><strong><code>rowDrag:moved</code> is coalesced to one event per animation frame</strong>,
+      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 <code>rowDrag:moved</code> is ever delivered after <code>rowDrag:ended</code>.</p>
+      <p><strong>Read, measure and draw in these handlers; do not mutate.</strong> 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 <code>data</code> 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 <code>beforeRowReceive</code>,
+      which is asked before the insert, or in the settled events afterwards.</p>
+      <p><strong>The end is always reported.</strong> Exactly one <code>rowDrag:ended</code> follows
+      every <code>rowDrag:started</code>, including a release outside every grid, where
+      <code>over</code> 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 <code>rowDrag:ended</code>.</p>
+    </div>
+
+    <p class="lead-in">
+      A drop can mean something other than a move. Dragging a backlog row onto a row in another
+      grid often means <em>assign this to that</em>: the host wants to know which row it landed on,
+      record the relationship, and keep the row where it was. <code>beforeRowReceive</code> fires on
+      the receiving grid before the insert, naming the row under the pointer as <code>overKey</code>
+      (null past the last row, on empty space, on the header or on a pinned row) and the grid it came
+      from as <code>source</code>. <code>preventDefault(reason)</code> stops the insert, and the source
+      grid is untouched: the row stays, and neither <code>row:sent</code> nor <code>row:copied</code>
+      fires. The handler may be <code>async</code>, as every before-event may; a drop whose row under
+      the pointer, or source row, is gone by the time it settles is cancelled as <code>'stale'</code>.
+    </p>
+
+    <div class="example">
+      <p class="example__label">Assign on drop, rather than move</p>
+      <pre><code>assigned.on('beforeRowReceive', (e) =&gt; {
+  <span class="kw">if</span> (e.overKey === <span class="kw">null</span>) <span class="kw">return</span>;   <span class="cmt">// dropped on no row: let it move</span>
+  e.preventDefault('assigned');           <span class="cmt">// the backlog row stays in the backlog</span>
+  assign(e.data.id, e.overKey);           <span class="cmt">// the relationship is the change</span>
+});
+assigned.on('rowReceive:cancelled', (e) =&gt; console.log(e.reason));  <span class="cmt">// 'assigned'</span></code></pre>
+    </div>
+
     <div class="why">
       <p><strong>Off by default, and both ends have to agree.</strong> 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
@@ -4839,6 +4920,14 @@ grid.selection.extendRange(34, 'cap');  <span class="cmt">// grows the block jus
       normally with <code>mode: 'single'</code> — the checkbox remains the only way to change
       which one row is selected.
     </p>
+    <p class="lead-in">
+      With <code>mode: 'single'</code>, checking a row's box selects that row and replaces
+      whichever one was selected before; unchecking the selected row clears the selection.
+      <code>grid.selection.set(keys)</code> itself keeps only the <em>first</em> key of whatever
+      array it is given when <code>mode</code> is <code>'single'</code> — that contract is
+      unchanged (BACKLOG-0001233) — so the checkbox column never builds a two-key array to hand
+      it; it sets the one key it just toggled.
+    </p>
 
     <div class="why">
       <p><strong>Ctrl+Shift+Arrow is the keyboard form of ctrl-dragging.</strong> The first press
@@ -7309,7 +7398,7 @@ grid.import.apply(preview);</code></pre>
           <tr><td class="name">deriveRangeSpec</td><td class="desc">Decide what a chart of a range should be without drawing it: the type, the category column, the measures, and a spec ready for <code>createChart</code>.</td></tr>
           <tr><td class="name">regressionPlots</td><td class="desc">Turn a fitted regression model into diagnostic chart specs ready for <code>createChart</code>: the fit line with its confidence band, residuals-vs-fitted, a QQ plot of the residuals, and a multicollinearity correlogram with the model’s VIF. The plots that need a per-row or per-coefficient quantity the grid has no column for (scale-location, residuals-vs-leverage, the coefficient forest) are returned as a null spec carrying the reason rather than dropped.</td></tr>
           <tr><td class="name">createDataRouter</td><td class="desc">Split one arriving stream or dataset across many grids by what each record is — a property or a predicate — driving each grid through the public keyed <code>rows.apply</code> path so a snapshot is a diff, a delta is applied in place, a moved partition moves the row rather than duplicating it, and an unmatched record is counted, sunk and never dropped. By default routing is first-match-wins (<code>overlap: false</code>); to fan one partition value to several viewers at once (a grid <em>and</em> a KPI panel <em>and</em> a chart off one feed) create the router with <code>overlap: true</code> — with the default, a second viewer on the same value receives nothing and the router emits a one-time dev warning naming the clash. v2 adds cross-grid selection filtering: <code>link(source, target, relation)</code> makes a selection in one grid filter what another receives — by a key map or a predicate function, multi-select as an IN set, debounced — re-pushed through the same keyed-diff path so the target stays dumb. v5 adds wedge-conversion primitives: <code>subscribe(value, handler)</code> routes a slice to any non-grid view (KPI tile, detail pane, map, form) as the same keyed diff a grid gets; <code>alert(value, condition, handler)</code> evaluates a condition over a slice and emits (edge-triggered, debounced) rather than rendering; and <code>configure(spec)</code> (or <code>createDataRouter({ config })</code>) takes the whole routing graph as one declarative data spec that desugars to the imperative API and composes with it. v3 also adds per-route reshaping — <code>transform</code>/<code>filter</code>/<code>sort</code> and <code>rollup</code> ({ groupBy, aggregate }) summaries — a relationship graph (<code>relate(edges)</code>: multi-hop, several-into-one AND, and mutual edges) that scales v2's pairwise <code>link</code>, and stream hygiene: a <code>seq</code>/version orders and de-duplicates a feed (stale/duplicate deltas dropped, counted in <code>dropped</code>), <code>push</code> with a <code>batch</code>/<code>coalesce</code> buffers a high-frequency feed (<code>flushStream</code> for a deterministic point), and <code>lastSeq</code>/<code>checkpoint</code>/<code>seenThrough</code> resume precisely after a dropped socket. v4 adds time-travel: <code>buffer({ window, max })</code> records the ordered stream into a bounded ring over a moving base, so <code>scrubTo</code> reconstructs a past point, <code>replay</code> (with <code>pause</code>/<code>resume</code>) walks a range, and <code>live</code> returns to the head — every state pushed by the same keyed diff, <code>traveling</code>/<code>buffered</code> reporting the state. v6 adds cross-tab sync: <code>broadcast({ channel })</code> mirrors the ordered, de-duplicated deltas to other tabs/windows over a BroadcastChannel with no echo loop, a popped-out grid joining the same feed with no second socket and resyncing mid-stream via the reconnect path. v7 adds query-slice routing: <code>query(adapter, request)</code> sources the router from a DFQL/DuckDB (or any pushdown) adapter, partitioning one result across the routes; a route-level <code>where</code> is pushed down where the adapter's capabilities allow and the residual finished client-side, with <code>lastQueryPlan</code> reporting the split. v8 adds write-back: a <code>writable</code> route captures the grid's committed edits off its public edit surface and routes them to <code>onWrite(change, ctx)</code> (per-route or router-global), reverting on reject, re-entering an accepted write as a delta, and surfacing a last-write-wins <code>onConflict</code>; a derived route cannot be writable. v9 adds fan-in: <code>addSource(feed, { map, key })</code> returns a per-feed handle (<code>load</code>/<code>apply</code>/<code>push</code>/<code>remove</code>) whose rows are normalized and namespaced so many feeds merge into one keyed store without id collisions, <code>removeSource</code> dropping exactly a feed's rows and <code>sources</code> listing them. v10 adds observability: <code>metrics()</code> is a cheap snapshot of per-route/per-source counts and throughput plus the global unrouted/dropped/buffered/lag figures, <code>on('metrics')</code> drives a periodic emit (off unless a listener is registered), and <code>mountDevtools(el)</code> renders a live panel from the module's own DOM file. Detaches its grids on <code>destroy</code>; the host owns them.</td></tr>
-          <tr><td class="name">createKanban</td><td class="desc">A board (kanban) view of rows as cards, grouped into columns by a configurable property (a status, a stage, a state field), with per-column card count and an optional points sum, a WIP over-limit flag, configured columns shown even when empty, granular readonly (whole board / per column / per card), field-mapped card templates that reuse the grid’s own column formatters when a grid is bound, and the core pointer events (<code>card:click</code>, <code>card:dblclick</code>, <code>card:contextmenu</code>). 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, board)</code> and drive a kanban beside a grid and a chart off one feed. Accessibility is built in from the start — a labelled group of labelled column lists, cards in a roving-tabindex focus ring with arrow-key navigation, and a polite live region. Every structural property is named in config (<code>columnProperty</code>, <code>pointsProperty</code>, <code>orderProperty</code>, <code>swimlaneProperty</code>, <code>sprintProperty</code>, <code>epicProperty</code>) so it maps DemandFlow and any customer schema without code change. Pass <code>null</code> as the element for a headless board that computes the same model without a DOM. Cards drag between columns (writing the column property) and within a column into a position (writing the order property with fractional ranking), and the same move is keyboard-accessible — <kbd>Space</kbd> to grab, arrows to choose a target, <kbd>Space</kbd>/<kbd>Enter</kbd> to drop, <kbd>Escape</kbd> to cancel — announced on the live region; multi-select drags every selected card. A move calls <code>onBeforeMove(card, from, to, index)</code> first (return <code>false</code> to veto) and then persists through the grid’s shipped write-back path — grid-bound via <code>grid.edit.setCells</code> (the same public edit-commit path inline editing uses, so the grid’s pipeline owns optimistic apply / confirm / revert), standalone with a revert when <code>onCardMove</code> rejects — emitting <code>card:move</code>. A configurable per-card <code>contextMenu</code> replaces the <code>card:contextmenu</code> event when present. With <code>swimlanes: true</code> it renders a 2D lane&times;column grid grouped by <code>swimlaneProperty</code> (per-lane count/points, columns aligned across lanes, a cross-lane drag writing the swimlane property); columns and lanes collapse (state surviving a keyed-diff update), columns reorder by header drag, and <code>setQuickFilter</code>/<code>setFilter</code>/<code>facets</code> drive search and faceting. <code>setSprint</code>/<code>showBacklog</code>/<code>sprints</code> give a sprint view, switcher and backlog; <code>setEpic</code>/<code>epicRollup</code>/<code>rollup</code> give an epic view and rollups (count, points, progress toward the <code>done</code> columns). A card can pop out a nested grid of its children (an epic's stories, a story's tasks, recursively) via a <code>childrenProperty</code> and/or <code>loadChildren(card)</code>: the child is a full composed <code>createGrid</code> (or, with <code>asBoard</code>, a nested board) opened in a drawer/modal/inline container — reuse by composition, no grid-core coupling — emitting <code>card:expand</code>/<code>card:drill</code>. Live updates arrive through the same keyed-diff contract a grid uses, so a Data Router drives the board directly (<code>attach(board, predicate)</code>); a live <code>rows.apply</code> re-renders preserving scroll, focus, selection, collapse and any open pop-out. <code>virtualize</code> renders only a scroll window of a tall column; <code>getState</code>/<code>setState</code> (and <code>config.state</code>) save and restore collapse, order, filter and sprint/epic selection; <code>setLoading</code>/<code>setError</code> give loading and error states. The move is fully keyboard-driven — Space to grab, arrows for column/position, Alt+Up/Down across swimlanes, Space/Enter to drop, Escape to cancel — announced on a live region. A field opted in with <code>card: { title: { field, edit: true } }</code> edits inline (double-click or <code>editCard</code>): grid-bound through the grid's own field editor via its public edit path, standalone through a host editor factory or a default input with an <code>onCardEdit</code> revert; a per-column add-card (<code>config.addCard</code>/<code>onAddCard</code>, or <code>grid.edit.addRow</code>) creates a card and opens it in edit. The module imports nothing from the grid's DOM package.</td></tr>
+          <tr><td class="name">createKanban</td><td class="desc">A board (kanban) view of rows as cards, grouped into columns by a configurable property (a status, a stage, a state field), with per-column card count and an optional points sum, a WIP over-limit flag, configured columns shown even when empty, granular readonly (whole board / per column / per card), field-mapped card templates that reuse the grid’s own column formatters when a grid is bound, and the core pointer events (<code>card:click</code>, <code>card:dblclick</code>, <code>card:contextmenu</code>). 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, board)</code> and drive a kanban beside a grid and a chart off one feed. Accessibility is built in from the start — a labelled group of labelled column lists, cards in a roving-tabindex focus ring with arrow-key navigation, and a polite live region. Every structural property is named in config (<code>columnProperty</code>, <code>pointsProperty</code>, <code>orderProperty</code>, <code>swimlaneProperty</code>, <code>sprintProperty</code>, <code>epicProperty</code>) so it maps DemandFlow and any customer schema without code change. Pass <code>null</code> as the element for a headless board that computes the same model without a DOM. Cards drag between columns (writing the column property) and within a column into a position (writing the order property with fractional ranking), and the same move is keyboard-accessible — <kbd>Space</kbd> to grab, arrows to choose a target, <kbd>Space</kbd>/<kbd>Enter</kbd> to drop, <kbd>Escape</kbd> to cancel — announced on the live region; multi-select drags every selected card. A move calls <code>onBeforeMove(card, from, to, index)</code> first (return <code>false</code> to veto) and then persists through the grid’s shipped write-back path — grid-bound via <code>grid.edit.setCells</code> (the same public edit-commit path inline editing uses, so the grid’s pipeline owns optimistic apply / confirm / revert), standalone with a revert when <code>onCardMove</code> rejects — emitting <code>card:move</code>. A configurable per-card <code>contextMenu</code> replaces the <code>card:contextmenu</code> event when present. With <code>swimlanes: true</code> it renders a 2D lane&times;column grid grouped by <code>swimlaneProperty</code> (per-lane count/points, columns aligned across lanes, a cross-lane drag writing the swimlane property); columns and lanes collapse (state surviving a keyed-diff update), columns reorder by header drag, and <code>setQuickFilter</code>/<code>setFilter</code>/<code>facets</code> drive search and faceting. <code>setSprint</code>/<code>showBacklog</code>/<code>sprints</code> give a sprint view, switcher and backlog; <code>setEpic</code>/<code>epicRollup</code>/<code>rollup</code> give an epic view and rollups (count, points, progress toward the <code>done</code> columns). A card can pop out a nested grid of its children (an epic's stories, a story's tasks, recursively) via a <code>childrenProperty</code> and/or <code>loadChildren(card)</code>: the child is a full composed <code>createGrid</code> (or, with <code>asBoard</code>, a nested board) opened in a drawer/modal/inline container — reuse by composition, no grid-core coupling — emitting <code>card:expand</code>/<code>card:drill</code>. Live updates arrive through the same keyed-diff contract a grid uses, so a Data Router drives the board directly (<code>attach(board, predicate)</code>); on a standalone board (not <code>grid</code>-bound, which ignores <code>rows.apply</code> and routes to the bound grid instead) <code>rows.apply({ update })</code> merges each patch into the row already stored under its key, matching the grid's own <code>rows.apply({ update })</code> — a field the patch omits is preserved, and a patch that does change the grouping property still moves the card — while <code>add</code> sets the row outright; a live <code>rows.apply</code> re-renders preserving scroll, focus, selection, collapse and any open pop-out. <code>virtualize</code> renders only a scroll window of a tall column; <code>getState</code>/<code>setState</code> (and <code>config.state</code>) save and restore collapse, order, filter and sprint/epic selection; <code>setLoading</code>/<code>setError</code> give loading and error states. The move is fully keyboard-driven — Space to grab, arrows for column/position, Alt+Up/Down across swimlanes, Space/Enter to drop, Escape to cancel — announced on a live region. A field opted in with <code>card: { title: { field, edit: true } }</code> edits inline (double-click or <code>editCard</code>): grid-bound through the grid's own field editor via its public edit path, standalone through a host editor factory or a default input with an <code>onCardEdit</code> revert; a per-column add-card (<code>config.addCard</code>/<code>onAddCard</code>, or <code>grid.edit.addRow</code>) creates a card and opens it in edit. The module imports nothing from the grid's DOM package.</td></tr>
           <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>
@@ -7466,6 +7555,10 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">row:moved</td><td class="desc">A row was dragged to a new position.</td></tr>
           <tr><td class="name">row:received</td><td class="desc">A row arrived from a source.</td></tr>
           <tr><td class="name">row:sent</td><td class="desc">A row was written back to a source.</td></tr>
+          <tr><td class="name">rowDrag:started</td><td class="desc">A row drag began. Fires on the grid the drag started in, as do rowDrag:moved, rowDrag:left and rowDrag:ended.</td></tr>
+          <tr><td class="name">rowDrag:moved</td><td class="desc">The drag is over a candidate position. Coalesced to one event per animation frame, carrying that frame's latest pointer position.</td></tr>
+          <tr><td class="name">rowDrag:left</td><td class="desc">The pointer left a grid; over names the grid it left. Emitted on the transition, not on a frame.</td></tr>
+          <tr><td class="name">rowDrag:ended</td><td class="desc">The gesture ended, whether or not a drop followed, including a release outside every grid. dropped says whether the release is being acted on. Notifications only — none of the four is cancellable.</td></tr>
           <tr><td class="name">rows:changed</td><td class="desc">The row set changed. See what a change firing promises: identified means the three arrays name the rows that moved, companion marks a duplicate announcement of a change already made with identity, and a firing with neither is a real change of unknown extent.</td></tr>
           <tr><td class="name">rows:deferred</td><td class="desc">Updates were held rather than applied, because an edit is in flight.</td></tr>
           <tr><td class="name">rows:paused</td><td class="desc">A live feed was paused; updates queue from here.</td></tr>
@@ -7535,7 +7628,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">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:changed</td><td class="desc">Every state change, whether a user gesture or a programmatic call — including a named filters.where predicate registered, replaced, removed or reapplied (BACKLOG-0001235) — announced exactly once. 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>
@@ -7600,6 +7693,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">beforeDelete</td><td class="desc">Before an optimistic row delete applies — the canonical confirm-before-delete hook. Paired with delete:cancelled.</td></tr>
           <tr><td class="name">beforeRowMove</td><td class="desc">Before a row reorder applies. Paired with rowMove:cancelled.</td></tr>
           <tr><td class="name">beforeGroup</td><td class="desc">Before a group/tree expand or collapse applies. Paired with group:cancelled.</td></tr>
+          <tr><td class="name">beforeRowReceive</td><td class="desc">Before a row dragged from another grid is inserted into this one; fires on the receiving grid and names the row under the pointer (overKey). A veto leaves the source grid untouched. Paired with rowReceive:cancelled.</td></tr>
           <tr><td class="name">edit:cancelled</td><td class="desc">A beforeEdit was vetoed; reason is 'stale' when a live delta moved the cell during an async gate.</td></tr>
           <tr><td class="name">sort:cancelled</td><td class="desc">A beforeSort was vetoed.</td></tr>
           <tr><td class="name">filter:cancelled</td><td class="desc">A beforeFilter was vetoed.</td></tr>
@@ -7611,6 +7705,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">delete:cancelled</td><td class="desc">A beforeDelete was vetoed; reason is 'stale' when the row was already gone.</td></tr>
           <tr><td class="name">rowMove:cancelled</td><td class="desc">A beforeRowMove was vetoed; reason is 'stale' when the row had moved.</td></tr>
           <tr><td class="name">group:cancelled</td><td class="desc">A beforeGroup was vetoed.</td></tr>
+          <tr><td class="name">rowReceive:cancelled</td><td class="desc">A beforeRowReceive was vetoed; nothing was inserted and the source still holds the row. reason is 'stale' when the row under the pointer or the source row was gone by the time an async handler settled.</td></tr>
           <tr><td class="name">export:request</td><td class="desc">A remote export was requested. Past-tense notification.</td></tr>
           <tr><td class="name">export:done</td><td class="desc">A remote export completed. Past-tense notification.</td></tr>
           <tr><td class="name">shortcuts:opened</td><td class="desc">The keyboard-shortcuts help overlay opened. Past-tense notification.</td></tr>
@@ -7806,7 +7901,7 @@ grid.licence.state();   <span class="cmt">// 'licensed' | 'localhost' | 'trial'<
 
     <footer>
       <p>
-        Lattice Grid 1.56.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+        Lattice Grid 1.57.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>