@toclocoinc/lattice-grid 1.13.1 → 1.15.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.13.0</p>
+    <p class="rail__sub">Developer guide · v1.15.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -884,6 +884,14 @@ createGrid(element, { direction: 'rtl' });    <span class="cmt">// or say so out
       <code>.events</code> namespaces: sitting on top of a real Lattice grid underneath.
       Swap the import and, for the surface below, the calling code does not change.
     </p>
+    <p class="lead-in">
+      The wrapper shares the core the page already loads rather than carrying its own,
+      so load <code>@toclocoinc/lattice-grid</code> alongside it: a bundler wires the shared
+      import automatically (it dedupes against the core your app already imports), and a
+      plain <code>&lt;script src&gt;</code> page loads the global build first. The pay-off is
+      that a licence set on that one core applies to these grids too, and the module is a
+      few kilobytes of translation rather than a second copy of the grid.
+    </p>
 
     <div class="example">
       <p class="example__label">A drop-in constructor</p>
@@ -4813,12 +4821,22 @@ createStat({
   grid,
   container: tile,
   title: 'Total capacity',
+  <span class="cmt">// A leading icon beside the title and value. Same three forms as a menu</span>
+  <span class="cmt">// item: a sprite name, a character/emoji, or your own markup.</span>
+  icon: '&lt;i class="fa-light fa-gauge-high"&gt;&lt;/i&gt;',
   value: { of: 'capacity', fn: 'sum' },
   baseline: (g) =&gt; lastMonth,
   bands: { good: 5000, warn: 3000, direction: 'up' },
   interval: (v, g) =&gt; g.statistics.interval('capacity'),
 });</code></pre>
     </div>
+    <p class="lead-in">
+      <code>icon</code> is optional and lays out to the side without disturbing the change indicator,
+      threshold bands or confidence interval; omit it for the plain tile. It uses the same
+      <a href="#custom-menu">icon contract</a> as a menu item — a sprite name, a single character or
+      emoji, or author-supplied markup such as a Font Awesome glyph or an
+      <code>&lt;img&gt;</code>.
+    </p>
     <div class="why">
       <p><strong><code>bands</code> and <code>goodWhen</code> judge different things.</strong>
       <code>goodWhen</code> says whether a rise is good news, and colours the change indicator.
@@ -4919,6 +4937,33 @@ r.ok ? r.value : r.error;   <span class="cmt">// 42</span></code></pre>
       <code>{ key, colId, value, row, data, column, index, grid }</code>. <code>data</code> is your
       original row object, so an item can reach fields the grid never displayed.
     </p>
+    <div class="example">
+      <p class="example__label">An item with your own icon</p>
+      <pre><code>createGrid(el, {
+  contextMenu: (params, defaults) =&gt; [
+    ...defaults,
+    { separator: <span class="kw">true</span> },
+    <span class="cmt">// A registered sprite name — the built-in items use these.</span>
+    { name: 'Download', icon: 'download', action: () =&gt; save(params.data) },
+    <span class="cmt">// A single character or emoji, rendered as text.</span>
+    { name: 'Star', icon: '★', action: () =&gt; star(params.data) },
+    <span class="cmt">// Your own markup — a Font Awesome glyph, an inline SVG, an image.</span>
+    <span class="cmt">// It is inserted into the icon slot as an element, at the same trust</span>
+    <span class="cmt">// as the item's action, and never into the label.</span>
+    { name: 'Export', icon: '&lt;i class="fa-light fa-file-export"&gt;&lt;/i&gt;', action: exportRow },
+  ],
+});</code></pre>
+    </div>
+    <p class="lead-in">
+      A <code>MenuItem</code>'s <code>icon</code> accepts three forms, told apart automatically so
+      existing definitions keep working: a registered sprite <strong>name</strong>
+      (<code>'download'</code>), a single <strong>character</strong> or emoji (<code>'↑'</code>),
+      or author-supplied element <strong>markup</strong>
+      (<code>'&lt;i class="fa-light fa-download"&gt;&lt;/i&gt;'</code>). Markup is rendered as an
+      element rather than shown as text — the misbehaviour it replaces — and is written only into
+      the icon slot, so a definition can never inject markup into the label. It is trusted like the
+      item's <code>action</code>: a menu definition is code you wrote, not user data.
+    </p>
     <div class="why">
       <p><strong>Handed the defaults, rather than replacing them.</strong> A builder that had to
       return every item in order to append one would be written once as a copy of the built-ins and
@@ -5383,6 +5428,89 @@ grid.state.apply(savedView.state);
       to CSV takes about 100ms.</p>
     </div>
 
+    <h2 id="less-common">Options and calls you may not have met</h2>
+    <p class="lead-in">
+      The rest of the surface, in one place. Each of these is documented in full in the
+      <a href="API.html">reference</a>; this is here so that reading the guide end to end leaves
+      nothing you have never heard of, which is the difference between a guide and a tour of the
+      parts we found most interesting.
+    </p>
+    <h3>Configuration</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Name</th><th>What it does</th></tr></thead>
+        <tbody>
+          <tr><td class="name">autoHeight</td><td class="desc">autoHeight.</td></tr>
+          <tr><td class="name">bucketFn</td><td class="desc">Replace the built-in bucketing entirely. (optional)</td></tr>
+          <tr><td class="name">coalesceMs</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">columnGroups</td><td class="desc">Header grouping declared separately from the columns.</td></tr>
+          <tr><td class="name">columnPresets</td><td class="desc">Named bundles applied with preset: 'money'.</td></tr>
+          <tr><td class="name">columnVirtualisationAbove</td><td class="desc">Column count above which columns virtualise too.</td></tr>
+          <tr><td class="name">delimiter</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">enterMovesDown</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">fillHandle</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">granularity</td><td class="desc">hour &amp;hellip; year. Chosen from the span when omitted.</td></tr>
+          <tr><td class="name">groupFooter</td><td class="desc">A closing total row per group.</td></tr>
+          <tr><td class="name">groupSelectsChildren</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">groupSelectsFiltered</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">headerHeight</td><td class="desc">Per header row.</td></tr>
+          <tr><td class="name">historyBar</td><td class="desc">A standalone undo/redo toolbar with a timeline.</td></tr>
+          <tr><td class="name">hostFilter</td><td class="desc">An application-level predicate composed with the grid's own filters.</td></tr>
+          <tr><td class="name">idleMs</td><td class="desc">Silence after which a peer is shown idle. (optional)</td></tr>
+          <tr><td class="name">indexLimit</td><td class="desc">Cell descriptors held before the oldest are dropped. (optional)</td></tr>
+          <tr><td class="name">lineEnding</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">lockMs</td><td class="desc">Silence after which a peer's edit claim is disregarded. (optional)</td></tr>
+          <tr><td class="name">maxCachedPages</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">maxDecimals</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">me</td><td class="desc">(read-only)</td></tr>
+          <tr><td class="name">minDecimals</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">overscan</td><td class="desc">Rows rendered beyond the viewport.</td></tr>
+          <tr><td class="name">pageSizes</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">pinnedBottomRows</td><td class="desc">As pinnedTopRows, held below the body instead. Sits under the grand total when both are shown.</td></tr>
+          <tr><td class="name">pipes</td><td class="desc">Template pipes for cell.template.</td></tr>
+          <tr><td class="name">processCell</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">promoteToMemoryBelow</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">quickFilterText</td><td class="desc">Initial quick-filter term. Equivalent to grid.filters.quick(text).</td></tr>
+          <tr><td class="name">quote</td><td class="desc">(optional)</td></tr>
+          <tr><td class="name">removeMs</td><td class="desc">Silence after which a peer is dropped. (optional)</td></tr>
+          <tr><td class="name">showHeader</td><td class="desc">Draw the column headings at all. false removes the row, and removes it from the accessibility tree rather than only from view. Distinct from showColumnFunctions, which keeps the headings and drops only their sort, filter and menu controls.</td></tr>
+          <tr><td class="name">throttleMs</td><td class="desc">Milliseconds between published updates. Throttled, not debounced. (optional)</td></tr>
+          <tr><td class="name">totalFns</td><td class="desc">Custom aggregations, addressable from column.total.</td></tr>
+          <tr><td class="name">undoDepth</td><td class="desc">(optional)</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3>Factories and registration</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Name</th><th>What it does</th></tr></thead>
+        <tbody>
+          <tr><td class="name">createChart</td><td class="desc">Draw one of the thirty-seven chart types from a grid’s own data. It follows the grid’s filters, and a mark can filter the grid back.</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">createLatticeGridElement</td><td class="desc">Build the element class without registering it, for a custom registry.</td></tr>
+          <tr><td class="name">createMessages</td><td class="desc">Build a message catalogue. A partial set lays over the built-in British English one.</td></tr>
+          <tr><td class="name">defineLatticeGrid</td><td class="desc">Register &amp;lt;lattice-grid&amp;gt;, or your own tag name.</td></tr>
+          <tr><td class="name">defineUnit</td><td class="desc">Add one unit to a system, or override one of ours under the same name.</td></tr>
+          <tr><td class="name">registerModules</td><td class="desc">Install optional modules once, for every grid on the page.</td></tr>
+          <tr><td class="name">registerScheme</td><td class="desc">Add a colour scheme, or replace one of ours under the same name.</td></tr>
+          <tr><td class="name">restoreStateWithin</td><td class="desc">Put it back afterwards.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3>Grid methods</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Name</th><th>What it does</th></tr></thead>
+        <tbody>
+          <tr><td class="name">attachRenderer</td><td class="desc">Bind a renderer to a headless grid.</td></tr>
+          <tr><td class="name">emit</td><td class="desc">Emit on the grid's bus, for custom components.</td></tr>
+          <tr><td class="name">getPinnedRows</td><td class="desc">The objects pinned at one edge, as a copy.</td></tr>
+          <tr><td class="name">rendererHost</td><td class="desc">The host object a renderer reads: columns, rows, callbacks. Deliberately a plain bag rather than the grid itself, so a renderer cannot reach into core internals. You need this only when writing a renderer of your own.</td></tr>
+          <tr><td class="name">setAll</td><td class="desc">Write several in one pass. Emits one config:changed for the batch, not one per key.</td></tr>
+        </tbody>
+      </table>
+    </div>
+
     <h2 id="webcomponent-guide">Web component</h2>
     <p class="lead-in">
       <code>&lt;lattice-grid&gt;</code> is the grid as a custom element, shipped as a self-contained
@@ -5451,7 +5579,8 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
 
     <h2 id="events-guide">Events</h2>
     <p class="lead-in">
-      One bus, forty-odd events. These are the ones most applications actually use; the
+      One bus, 111 events. The table below is the working set, the ones most applications
+      actually reach for; a complete index by area follows it, and the
       <a href="API.html#events">reference</a> lists them all.
     </p>
     <div class="table-wrap">
@@ -5473,6 +5602,196 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
       </table>
     </div>
 
+    <h3>Every event, by area</h3>
+    <p class="lead-in">
+      The table above is the working set. This is the whole list, grouped by what it is about,
+      so a question like "can I hear about a column being pinned?" is answerable by scanning
+      rather than by reading the reference end to end.
+    </p>
+    <h4>Lifecycle</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">config:changed</td><td class="desc">A configuration key changed. Emitted after the grid has rebuilt, so a listener reading the grid back sees the change rather than what it replaced.</td></tr>
+          <tr><td class="name">destroy</td><td class="desc">grid.destroy() has run.</td></tr>
+          <tr><td class="name">licence:changed</td><td class="desc">A key was installed, and again when verification settles.</td></tr>
+          <tr><td class="name">ready</td><td class="desc">First layout is complete and the API is safe to drive.</td></tr>
+          <tr><td class="name">render:done</td><td class="desc">The cells are written and stable. Anything decorating them from outside must run after this, the cell layer rewrites each cell's className wholesale and would otherwise erase it.</td></tr>
+          <tr><td class="name">render:first</td><td class="desc">First paint, the number to measure time-to-first-row against.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Data</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">model:changed</td><td class="desc">Columns, grouping, pivot or another structural change.</td></tr>
+          <tr><td class="name">row:clicked</td><td class="desc">Emitted alongside the cell event, cell first.</td></tr>
+          <tr><td class="name">row:copied</td><td class="desc">A row was duplicated.</td></tr>
+          <tr><td class="name">row:dblclicked</td><td class="desc">A row was double-clicked. Emitted alongside the cell event, cell first.</td></tr>
+          <tr><td class="name">row:edit:end</td><td class="desc">In row mode an invalid cell blocks the whole commit and the session stays open.</td></tr>
+          <tr><td class="name">row:edit:start</td><td class="desc">Replaces the cell pair when edit.mode is 'row'.</td></tr>
+          <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">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>
+          <tr><td class="name">rows:queued</td><td class="desc">A batched change is waiting for the next frame.</td></tr>
+          <tr><td class="name">rows:resumed</td><td class="desc">The feed resumed and the queue drained.</td></tr>
+          <tr><td class="name">source:error</td><td class="desc">A source or block load failed.</td></tr>
+          <tr><td class="name">stream:chunk</td><td class="desc">A streamed chunk landed.</td></tr>
+          <tr><td class="name">stream:end</td><td class="desc">Streaming finished; promoted means it switched to in-memory.</td></tr>
+          <tr><td class="name">stream:evicted</td><td class="desc">A streaming source dropped rows to stay within its cap.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Cells and editing</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">cell:changed</td><td class="desc">A committed edit reached the data. undo distinguishes a rollback.</td></tr>
+          <tr><td class="name">cell:clicked</td><td class="desc">A cell was clicked. Announcement only: nothing is consumed, so editing and selection behave unchanged.</td></tr>
+          <tr><td class="name">cell:confirmed</td><td class="desc">The write reached the server.</td></tr>
+          <tr><td class="name">cell:contextmenu</td><td class="desc">Right-click on a cell.</td></tr>
+          <tr><td class="name">cell:dblclicked</td><td class="desc">A cell was double-clicked. Carries the row, column, value and text.</td></tr>
+          <tr><td class="name">cell:edit:end</td><td class="desc">It closed: committed or cancelled.</td></tr>
+          <tr><td class="name">cell:edit:start</td><td class="desc">An edit session opened.</td></tr>
+          <tr><td class="name">cell:pending</td><td class="desc">Applied optimistically, not yet durable. Only with edit.commit.</td></tr>
+          <tr><td class="name">cell:reverted</td><td class="desc">The write failed. applied: false means a newer edit owned the cell, so nothing was written back.</td></tr>
+          <tr><td class="name">form:closed</td><td class="desc">The row form closed without saving.</td></tr>
+          <tr><td class="name">form:error</td><td class="desc">A commit from the form failed validation or was rejected.</td></tr>
+          <tr><td class="name">form:opened</td><td class="desc">The row form opened.</td></tr>
+          <tr><td class="name">form:saved</td><td class="desc">The row form committed.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Columns</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">column:filter:open</td><td class="desc">Header filter popup opened.</td></tr>
+          <tr><td class="name">column:grouped</td><td class="desc">The row-group column list changed.</td></tr>
+          <tr><td class="name">column:menu:open</td><td class="desc">Header menu opened.</td></tr>
+          <tr><td class="name">column:moved</td><td class="desc">Reordered by drag or by API.</td></tr>
+          <tr><td class="name">column:pinned</td><td class="desc">side is 'start', 'end' or null.</td></tr>
+          <tr><td class="name">column:pivoted</td><td class="desc">The pivot configuration changed.</td></tr>
+          <tr><td class="name">column:resized</td><td class="desc">A column width settled after a drag or a keyboard resize.</td></tr>
+          <tr><td class="name">column:visible</td><td class="desc">Columns shown or hidden.</td></tr>
+          <tr><td class="name">columns:changed</td><td class="desc">The column set was replaced or reordered wholesale.</td></tr>
+          <tr><td class="name">columns:tagged</td><td class="desc">A column's tags changed.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Query and view</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">facet:computed</td><td class="desc">A header histogram finished counting. Carries the column and the buckets.</td></tr>
+          <tr><td class="name">facet:expanded</td><td class="desc">The facet band was opened or collapsed.</td></tr>
+          <tr><td class="name">facet:failed</td><td class="desc">A distribution could not be computed. Carries the reason.</td></tr>
+          <tr><td class="name">facet:filtered</td><td class="desc">A bucket or a dragged range was applied as a filter.</td></tr>
+          <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: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>
+          <tr><td class="name">timeline:seek</td><td class="desc">The brush settled on a range.</td></tr>
+          <tr><td class="name">timeline:seeking</td><td class="desc">The brush is being dragged. Throttled.</td></tr>
+          <tr><td class="name">view:applied</td><td class="desc">Emits no storage write: applying a view changes nothing to persist.</td></tr>
+          <tr><td class="name">view:default</td><td class="desc">view is null when the default was cleared.</td></tr>
+          <tr><td class="name">view:removed</td><td class="desc">A saved view was deleted.</td></tr>
+          <tr><td class="name">view:renamed</td><td class="desc">A saved view was renamed.</td></tr>
+          <tr><td class="name">view:saved</td><td class="desc">Carries the one view that moved: enough to POST a single record without diffing two lists.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Selection and interaction</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">detail:toggled</td><td class="desc">A master-detail row opened or closed.</td></tr>
+          <tr><td class="name">group:toggled</td><td class="desc">A group row opened or closed.</td></tr>
+          <tr><td class="name">history:applied</td><td class="desc">An action was undone or redone. Distinct from history:changed, which also fires when a new action is pushed onto the stacks and so cannot tell you anything was reversed.</td></tr>
+          <tr><td class="name">history:changed</td><td class="desc">Emitted after the entry is pushed, so a toolbar reading it names the right action. Repainting from sort:changed instead reads the timeline one action behind.</td></tr>
+          <tr><td class="name">range:changed</td><td class="desc">Cell range selection changed.</td></tr>
+          <tr><td class="name">scroll</td><td class="desc">Throttled to the frame.</td></tr>
+          <tr><td class="name">scroll:end</td><td class="desc">Scrolling settled, the moment to trigger deferred work.</td></tr>
+          <tr><td class="name">selection:changed</td><td class="desc">The selected rows changed. Carries the keys.</td></tr>
+          <tr><td class="name">size:changed</td><td class="desc">The viewport resized.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Presentation and formatting</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">formatting:changed</td><td class="desc">A conditional formatting rule was added, edited, reordered or restated.</td></tr>
+          <tr><td class="name">highlight:changed</td><td class="desc">A highlight was added or cleared.</td></tr>
+          <tr><td class="name">permissions:changed</td><td class="desc">The context moved and every column re-resolved.</td></tr>
+          <tr><td class="name">presentation:captured</td><td class="desc">A PNG was taken.</td></tr>
+          <tr><td class="name">presentation:changed</td><td class="desc">The options of a running presentation changed.</td></tr>
+          <tr><td class="name">presentation:ended</td><td class="desc">Presentation mode ended. Annotations are cleared here.</td></tr>
+          <tr><td class="name">presentation:scale</td><td class="desc">The presentation zoom changed.</td></tr>
+          <tr><td class="name">presentation:spotlight</td><td class="desc">A region was spotlit or released.</td></tr>
+          <tr><td class="name">presentation:started</td><td class="desc">Presentation mode began. Carries the scale, options, views and starting index. presentation:changed covers a later change to the same options, so a listener can tell entry from adjustment.</td></tr>
+          <tr><td class="name">presentation:view</td><td class="desc">The presentation advanced to another saved view.</td></tr>
+          <tr><td class="name">redaction:changed</td><td class="desc">A column was redacted or restored.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Collaboration</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">comment:added</td><td class="desc">A comment was posted.</td></tr>
+          <tr><td class="name">comment:deleted</td><td class="desc">A comment was removed.</td></tr>
+          <tr><td class="name">comment:edited</td><td class="desc">A comment was changed.</td></tr>
+          <tr><td class="name">comment:failed</td><td class="desc">A comment could not be saved. Carries the reason.</td></tr>
+          <tr><td class="name">comment:indexLoaded</td><td class="desc">The comment index finished loading, so indicators can paint.</td></tr>
+          <tr><td class="name">comment:resolved</td><td class="desc">A thread was marked resolved. Carries the cellKey.</td></tr>
+          <tr><td class="name">comment:threadClosed</td><td class="desc">A thread was closed or resolved.</td></tr>
+          <tr><td class="name">comment:threadOpened</td><td class="desc">A thread was opened in the panel.</td></tr>
+          <tr><td class="name">comment:unresolved</td><td class="desc">A resolved thread was reopened. Carries the cellKey.</td></tr>
+          <tr><td class="name">presence:failed</td><td class="desc">A presence transport error. Presence is lossy by design; this is informational.</td></tr>
+          <tr><td class="name">presence:joined</td><td class="desc">A peer was seen for the first time. Carries the peer.</td></tr>
+          <tr><td class="name">presence:left</td><td class="desc">A peer disconnected.</td></tr>
+          <tr><td class="name">presence:lockRefused</td><td class="desc">An edit was refused because a peer holds the cell.</td></tr>
+          <tr><td class="name">presence:published</td><td class="desc">This client's cursor or selection was broadcast.</td></tr>
+          <tr><td class="name">presence:updated</td><td class="desc">A known peer moved or changed selection. Carries the peer.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h4>Everything else</h4>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Event</th><th>Fires when</th></tr></thead>
+        <tbody>
+          <tr><td class="name">clipboard:copy</td><td class="desc">A copy left the grid.</td></tr>
+          <tr><td class="name">diff:changed</td><td class="desc">A snapshot was set or cleared.</td></tr>
+          <tr><td class="name">diff:swapped</td><td class="desc">The baseline and the current rows were exchanged.</td></tr>
+          <tr><td class="name">export:progress</td><td class="desc">Progress on a streamed export.</td></tr>
+          <tr><td class="name">header:contextmenu</td><td class="desc">A column heading was right-clicked.</td></tr>
+          <tr><td class="name">toolpanel:focus</td><td class="desc">The documented keyboard shortcut reached the tool panel.</td></tr>
+          <tr><td class="name">tree:loadAborted</td><td class="desc">A child fetch was cancelled, usually because the node collapsed.</td></tr>
+          <tr><td class="name">tree:loadFailed</td><td class="desc">A child fetch failed.</td></tr>
+          <tr><td class="name">tree:loaded</td><td class="desc">Children arrived. Carries the key and the count.</td></tr>
+          <tr><td class="name">tree:loading</td><td class="desc">Children are being fetched for a node.</td></tr>
+          <tr><td class="name">views:changed</td><td class="desc">The whole list, plus what moved and why.</td></tr>
+        </tbody>
+      </table>
+    </div>
+
     <h2 id="licensing">Licensing</h2>
     <p class="lead-in">
       <strong>There is one Lattice Grid and every copy is feature-identical.</strong> No community

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.13.1, type declarations
+ * Lattice Grid 1.15.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -1592,6 +1592,14 @@ export type PermissionPolicy =
 
 export interface MenuItem {
   name?: string;
+  /**
+   * An icon shown in the slot before the label. Three forms, told apart without
+   * a second option so existing definitions keep working: a registered sprite
+   * name (`'download'`), a single character or emoji (`'↑'`), or author-trusted
+   * element markup (`'<i class="fa-light fa-download"></i>'`), which is rendered
+   * as an element rather than shown as text. Markup is inserted into the icon
+   * slot only — never the label — at the same trust as `action`.
+   */
   icon?: string;
   shortcut?: string;
   action?: () => void;
@@ -1987,7 +1995,7 @@ export interface ColumnDistribution {
 export type EventName =
   /* Lifecycle */
   | 'ready' | 'destroy' | 'render:first' | 'render:done' | 'config:changed'
-  | 'licence:changed' | 'environment:changed'
+  | 'licence:changed'
   /* Data */
   | 'model:changed' | 'rows:changed' | 'rows:queued' | 'rows:deferred'
   | 'rows:paused' | 'rows:resumed' | 'row:received' | 'row:sent' | 'row:copied'
@@ -2017,12 +2025,15 @@ export type EventName =
   | 'view:renamed' | 'view:default'
   /* Formatting and presentation */
   | 'formatting:changed' | 'redaction:changed' | 'permissions:changed'
-  | 'presentation:changed' | 'presentation:ended' | 'presentation:view'
+  | 'presentation:changed' | 'presentation:started' | 'presentation:ended'
+  | 'presentation:view'
   | 'presentation:scale' | 'presentation:spotlight' | 'presentation:captured'
   /* Collaboration */
   | 'comment:added' | 'comment:edited' | 'comment:deleted' | 'comment:failed'
+  | 'comment:resolved' | 'comment:unresolved'
   | 'comment:threadOpened' | 'comment:threadClosed' | 'comment:indexLoaded'
-  | 'presence:published' | 'presence:left' | 'presence:failed' | 'presence:lockRefused'
+  | 'presence:published' | 'presence:joined' | 'presence:updated' | 'presence:left'
+  | 'presence:failed' | 'presence:lockRefused'
   /* Comparison and time */
   | 'diff:changed' | 'diff:swapped'
   | 'timeline:attached' | 'timeline:detached' | 'timeline:seek' | 'timeline:seeking'
@@ -3190,6 +3201,15 @@ export interface StatConfig extends StatValueSpec {
   /** An element, or a CSS selector resolved against the grid's document. */
   container: HTMLElement | string;
   title?: string;
+  /**
+   * An optional leading icon beside the title and value, using the same value
+   * contract as a menu item: a registered sprite name, a single character or
+   * emoji, or author-trusted element markup (`'<i class="fa-light fa-bolt">
+   * </i>'`, an `<img>`). It lays out to the side without disturbing the change
+   * indicator, threshold bands or confidence interval; omit it for the plain
+   * tile layout.
+   */
+  icon?: string;
   /** A literal value, a spec to reduce, or a function of the grid. */
   value?: unknown | StatValueSpec | ((grid: Grid) => unknown);
   /** Text under the value, or a function of it. */
@@ -3257,7 +3277,18 @@ export const NO_CAPABILITIES: Readonly<Required<PushdownCapabilities>>;
  * Resolve what an adapter says it can do against the defaults, giving a
  * complete capability set with no absent keys to test for.
  */
-export function capabilitiesOf(declared?: PushdownCapabilities): Required<PushdownCapabilities>;
+/**
+ * A capability set with every key present, as `capabilitiesOf` returns it.
+ *
+ * `operators` becomes a `Set` rather than staying an array: it is tested once
+ * per condition per query, and membership on an array is a scan. The declared
+ * form and the resolved form differ, which is why this is its own type.
+ */
+export type ResolvedCapabilities = Omit<Required<PushdownCapabilities>, 'operators'> & {
+  operators: ReadonlySet<string>;
+};
+
+export function capabilitiesOf(declared?: PushdownCapabilities): ResolvedCapabilities;
 
 /**
  * Split a filter tree into the half the engine takes and the half left over.
@@ -3271,7 +3302,7 @@ export function capabilitiesOf(declared?: PushdownCapabilities): Required<Pushdo
  */
 export function splitFilters(
   filters: object | null,
-  caps: Required<PushdownCapabilities>,
+  caps: ResolvedCapabilities,
 ): { pushed: object | null; residual: object | null };
 
 /**
@@ -3286,7 +3317,7 @@ export function splitFilters(
  */
 export function planQuery(
   request: RemoteRequest,
-  caps: Required<PushdownCapabilities>,
+  caps: ResolvedCapabilities,
 ): PushdownPlan;
 
 /**
@@ -3371,6 +3402,15 @@ export function dfqlAdapter(options: {
 
 export function createGrid(element: HTMLElement, config?: GridConfig): Grid;
 export function createHeadlessGrid(config?: GridConfig): Grid;
+
+/**
+ * The library version, e.g. `'1.13.1'`.
+ *
+ * The same value `grid.getVersion()` returns, available without a grid. The
+ * method was declared and the module-level function was not, though the
+ * reference documents both.
+ */
+export function getVersion(): string;
 export function registerModules(modules: GridModule[], opts?: { licence?: string }): void;
 export function setLicence(licence: string): LicenceInfo;
 
@@ -3801,7 +3841,16 @@ declare module 'lattice-grid/modules/htmx' {
 }
 
 declare module 'lattice-grid/modules/dhtmlx-compat' {
-  /** A dhtmlx Grid-shaped API over Lattice, for migrating a piece at a time. */
+  /**
+   * A dhtmlx Grid-shaped API over Lattice, for migrating a piece at a time.
+   *
+   * The module shares the page's one core rather than bundling its own: the
+   * grid it builds comes from the `lattice-grid` package the app already loads
+   * (or the `LatticeGrid` global a script tag publishes), so a licence set on
+   * that core applies to these grids too. Load the core alongside this module —
+   * a bundler wires the peer import for you; a `<script src>` page loads the
+   * global build first.
+   */
   export class Grid {
     constructor(container: Element | string, config?: object);
   }