@toclocoinc/lattice-grid 1.66.0 → 1.68.0

package/README.md

@@ -5,7 +5,7 @@ dependencies, no build step required. Optional adapters for React, Vue, Svelte
 and Web Components ship alongside it, and Angular has compiled components of its
 own at `@toclocoinc/lattice-grid/angular` — inside this package, not beside it.
 
-Version 1.66.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.68.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/angular/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.66.0",
+  "version": "1.68.0",
   "type": "module",
   "sideEffects": false,
   "module": "./fesm2022/toclocoinc-lattice-grid-angular.mjs",

package/docs/API.html

@@ -325,6 +325,9 @@
 
   .chip--new { border-color: var(--accent); color: var(--accent); }
 
+  .chip--icon { display: inline-flex; align-items: center; gap: 4px; }
+  .chip-icon { width: 12px; height: 12px; flex: none; }
+
   footer {
     margin-top: 72px;
     padding-top: 22px;
@@ -360,7 +363,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">API reference · v1.66.0</p>
+    <p class="rail__sub">API reference · v1.68.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start</span>
@@ -453,7 +456,7 @@
     </header>
 
     <p class="chips">
-      <span class="chip">Version 1.66.0</span>
+      <span class="chip">Version 1.68.0</span>
       <span class="chip">Zero dependencies</span>
       <span class="chip"><a href="api-detail.html">Developer guide &rarr;</a></span>
     </p>
@@ -1957,7 +1960,7 @@ grid.destroy();
       <table>
         <thead><tr><th>Member</th><th>Returns</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.66.0'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
+          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.68.0'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
           <tr><td class="sig">get(key)</td><td class="type">unknown</td><td class="desc">Read any configuration key.</td></tr>
           <tr><td class="sig">set(key, value)</td><td class="type">void</td><td class="desc">Write one key. Every key is live; nothing needs a rebuild.</td></tr>
           <tr><td class="sig">setAll(values)</td><td class="type">void</td><td class="desc">Write several in one pass. Emits one <code>config:changed</code> for the batch, not one per key.</td></tr>
@@ -7363,7 +7366,7 @@ const kpi = createKPI(document.querySelector('#kpis'), {
   ],
   onTileClick: ({ tile }) =&gt; drillInto(tile.id),
 });</code></pre>
-    <p>Each tile names an <strong>aggregation</strong> (<code>sum</code>, <code>avg</code>, <code>min</code>, <code>max</code>, <code>count</code>, <code>countDistinct</code>, or a <code>custom</code> reducer <code>(rows, tile) =&gt; value</code>), the <strong>field</strong> it reads, and an optional <strong>filter</strong> predicate. Formatting (<code>number</code>/<code>currency</code>/<code>percent</code>/<code>compact</code>, with decimals, currency and locale), a <strong>baseline</strong> for a delta, and semantic <strong>threshold bands</strong> (two cut points with a direction, or an explicit <code>bands</code> list) are all per tile; the band is a semantic name (<code>good</code>/<code>warn</code>/<code>critical</code>), separate from any accent colour. An optional <strong>sparkline</strong> plots a <code>{ x, y }</code> series in sequence order. Each tile is a labelled <code>&lt;figure&gt;</code>, focusable and keyboard-activatable, its value announced; the sparkline transition respects <code>prefers-reduced-motion</code>.</p>
+    <p>Each tile names an <strong>aggregation</strong> (<code>sum</code>, <code>avg</code>, <code>min</code>, <code>max</code>, <code>count</code>, <code>countDistinct</code>, or a <code>custom</code> reducer <code>(rows, tile) =&gt; value</code>), the <strong>field</strong> it reads, and an optional <strong>filter</strong> predicate. Formatting (<code>number</code>/<code>currency</code>/<code>percent</code>/<code>compact</code>, with decimals, currency and locale), a <strong>baseline</strong> for a delta, and semantic <strong>threshold bands</strong> (two cut points with a direction, or an explicit <code>bands</code> list) are all per tile; the band is a semantic name (<code>good</code>/<code>warn</code>/<code>critical</code>), separate from any accent colour. <code>delta: 'absolute' | 'relative' | 'both'</code> (default <code>'both'</code>) chooses what the movement line prints against the baseline (BACKLOG-0001673) &mdash; the difference alone, the percentage alone, or both together, because the percentage of a rate series (4.10 vs a 4.30 baseline) is meaningless and a host needs to keep the line without it. An optional <strong>sparkline</strong> plots a <code>{ x, y }</code> series in sequence order. Each tile is a labelled <code>&lt;figure&gt;</code>, focusable and keyboard-activatable, its value announced; the sparkline transition respects <code>prefers-reduced-motion</code>.</p>
     <p><strong>A panel with no data says so.</strong> A tile's status is <code>good</code>, <code>warn</code>, <code>critical</code>, <code>null</code> (no thresholds) &mdash; or <code>unknown</code>, which means the tile <em>measured nothing</em>. Two things cause that: the panel holds <em>no rows at all</em>, or the tile's <code>field</code> names no column on the bound grid, so it never read a cell to reduce over. That fourth status is decided from data presence <em>before</em> any threshold is consulted, because an aggregation over nothing returns the identity of its operation (<code>sum</code> and <code>count</code> return 0) and 0 is a number a threshold grades: under <code>lowerIsBetter</code> cut points it grades <code>good</code>, so an empty panel would otherwise read as a healthy one. An <code>unknown</code> tile reports a <code>null</code> value, renders the <code>nullText</code> placeholder rather than a zero, and is marked with a dashed edge and a visible &ldquo;No data&rdquo; caption that also forms part of its accessible name &mdash; the state is never carried by colour alone. Because <code>unknown</code> is an explicit status rather than a severity, anything rolling tiles up can surface &ldquo;not measured&rdquo; instead of inheriting a false green.</p>
     <p><strong>A measured zero is still a measurement.</strong> A tile whose <code>filter</code> matches none of the rows the panel <em>does</em> hold is a different thing: no open incidents is genuinely good, so it reads <code>0</code> and is graded on its thresholds exactly as before. Only an empty panel is <code>unknown</code>.</p>
     <p><strong>Staleness is a different question, and a time-bounded source answers it.</strong> <code>unknown</code> is about the absence of rows, not their staleness: a panel over an unbounded store keeps showing the last values it was given when its feed goes quiet, because those rows are still there. Give the underlying source a <a href="#sources">rolling time window</a> (<code>maxAge</code> with <code>ageBy</code>) and its rows age out while the feed is silent, so the panel drains and reports <code>unknown</code> the next time it reads them &mdash; a grid-bound panel as the grid announces the change (or when the host calls <code>refresh()</code>), a routed one as the removals reach <code>rows.apply</code>.</p>
@@ -7442,7 +7445,7 @@ const kpi = createKPI(document.querySelector('#kpis'), {
 kpi.destroy();
 <span class="kw">return</span> [shapes, shaped, ignoredAgg].join(' | ');</code></pre>
     <h3 id="kpi-tree">The KPI tree: top-level items that expand to the indicators beneath them</h3>
-    <p>Set <code>tree</code> and the panel becomes a <strong>rail</strong> instead of a grid of tiles: a small number of top-level items, each expanding to the indicators underneath it, with the parent telling you at a glance whether anything below needs attention. <code>Compute</code> expands to <code>psi</code> and <code>cpu</code>; collapsed, it still shows you that one of them is in breach.</p>
+    <p>Set <code>tree</code> and the panel becomes a <strong>rail</strong> instead of a grid of tiles: a small number of top-level items, each expanding to the indicators underneath it, with the parent telling you at a glance whether anything below needs attention. <code>Compute</code> expands to <code>psi</code> and <code>cpu</code>; collapsed, it still shows you that one of them is in breach. <code>tree</code> is the opt-in (BACKLOG-0001673): a dotted tile id is not a hierarchy on its own &mdash; with <code>tree</code> unset, the ids you see below would stay plain, unsplit tile ids and the panel would render every tile flat, warning once that setting <code>tree</code> is how the hierarchy is reached.</p>
     <pre><code>const kpi = createKPI(document.querySelector('#rail'), {
   rows, rowKey: 'id',
   tiles: [
@@ -7458,7 +7461,7 @@ kpi.destroy();
 
 kpi.nodes()[0].rollup;               <span class="cmt">// 'critical' — even with the branch shut</span>
 kpi.expand(kpi.nodes()[0].key);      <span class="cmt">// open it</span></code></pre>
-    <p><strong>Where the shape comes from &mdash; two sources, in this order.</strong> <em>Declared:</em> <code>tree: { path }</code> or <code>tree: { parentKey }</code> over the <em>tile specs</em>, the same two shapes the grid's <a href="#tree-data">tree data</a> and the tree-select editor already take, so a hierarchy you have configured once needs no second vocabulary. A <code>path</code> is the tile's <em>own</em> place, its own segment last &mdash; <code>['System','Compute','cpu']</code>, exactly as <code>['EMEA','UK','Colchester']</code> is Colchester's path and not its parent's &mdash; and levels no tile represents are synthesised, so <code>System</code> and <code>Compute</code> appear without a tile of their own. <em>Derived:</em> with neither declared, the tile ids are split on <code>separator</code> (default <code>.</code>), so <code>system.compute.cpu</code> files itself. A panel whose ids carry no separator is flat and renders exactly as it always did; <code>tree: false</code> keeps it flat whatever the ids look like. A tile's <code>field</code> is never a source &mdash; a dot there already means a nested object property, and overloading it would make <code>field: 'cpu.util'</code> ambiguous.</p>
+    <p><strong>Where the shape comes from &mdash; two sources, in this order, once <code>tree</code> is set.</strong> <em>Declared:</em> <code>tree: { path }</code> or <code>tree: { parentKey }</code> over the <em>tile specs</em>, the same two shapes the grid's <a href="#tree-data">tree data</a> and the tree-select editor already take, so a hierarchy you have configured once needs no second vocabulary. A <code>path</code> is the tile's <em>own</em> place, its own segment last &mdash; <code>['System','Compute','cpu']</code>, exactly as <code>['EMEA','UK','Colchester']</code> is Colchester's path and not its parent's &mdash; and levels no tile represents are synthesised, so <code>System</code> and <code>Compute</code> appear without a tile of their own. <em>Derived:</em> with neither declared, the tile ids are split on <code>separator</code> (default <code>.</code>), so <code>system.compute.cpu</code> files itself &mdash; but only once <code>tree</code> is given an object (<code>{}</code> included); unset, a dot in an id means nothing and the panel warns once rather than building a hierarchy you never asked for. A panel whose ids carry no separator is flat and renders exactly as it always did even with <code>tree</code> set; <code>tree: false</code>, same as leaving it unset, keeps it flat whatever the ids look like, silently. A tile's <code>field</code> is never a source &mdash; a dot there already means a nested object property, and overloading it would make <code>field: 'cpu.util'</code> ambiguous.</p>
     <p><strong>No value rolls up; severity does.</strong> A parent shows no aggregated number. That is not a simplification: the running accumulators expose <code>add</code>/<code>remove</code>/<code>value</code> and no merge, so <code>avg</code>, <code>countDistinct</code> and a <code>custom</code> reducer cannot be composed from their children without rescanning, and a per-aggregation exception list would be a number that is right for a sum and wrong for an average. A parent that has a tile of its own still shows <em>that tile's</em> reading. What does roll up is the status: <code>rollup</code> is the worst severity at or below the node, across as many levels as you have, and it is what a collapsed branch reports.</p>
     <p><strong>Nothing measured is not good news, and it does not win the roll-up either.</strong> A leaf that measured nothing is <code>unknown</code> (see above), and <code>unknown</code> is deliberately excluded from <code>rollup</code>: ranking &ldquo;not measured&rdquo; as the worst thing beneath a parent would hide a real warning under it. It is surfaced separately instead &mdash; <code>node.unknown</code> counts the descendants that measured nothing, and the node renders it in words (&ldquo;2 unknown&rdquo;) and puts it in its accessible name. So neither way of being wrong is available: silence cannot read as green, and it cannot bury an amber.</p>
     <p><strong>Accessible by construction.</strong> The rail is a real <code>role="tree"</code> with the APG keyboard model &mdash; <kbd>&rarr;</kbd> opens a closed branch and otherwise steps into it, <kbd>&larr;</kbd> closes an open one and otherwise steps out to its parent, <kbd>&uarr;</kbd>/<kbd>&darr;</kbd> walk what is visible, <kbd>Home</kbd>/<kbd>End</kbd> jump to its ends, <kbd>Enter</kbd>/<kbd>Space</kbd> activate &mdash; with a roving tabindex, and <code>aria-level</code>, <code>aria-posinset</code> and <code>aria-setsize</code> on every node, because a reader cannot count what a collapsed branch has left out of the DOM. Status carries a <strong>shape</strong> as well as a colour (a filled circle, a triangle, a square, a hollow circle), not one dot in three colours, and a parent's rolled-up status is <em>in its accessible name</em>: &ldquo;Compute, 6 items, worst status critical&rdquo;, announced as one string. Every phrase is a catalogue key: pass <code>messages</code> (any <code>{ t(key, params) }</code>, including a grid's own) to translate the panel, and a key your catalogue lacks falls back to English rather than printing the key.</p>
@@ -7468,8 +7471,10 @@ kpi.expand(kpi.nodes()[0].key);      <span class="cmt">// open it</span></code><
     <p><strong>A collapsed branch costs data, not paint.</strong> Every node's status is computed whether or not you can see it &mdash; that is what makes the rail worth having &mdash; while a collapsed branch contributes no DOM at all. It is the same division the grid's grouping already makes between its totals walk and its display walk. Expansion is patched in place, keyed on the node, so a live routed feed does not throw a keyboard user off the node they are standing on.</p>
     <h3 id="kpi-tree-example">A collapsed parent reports the red leaf underneath it, executed</h3>
     <p class="section-note">Two subsystems from dotted tile ids, one of them in breach, with nothing expanded; then the same
-    rail with no data at all. Run headless on every build.</p>
-    <pre data-run="js" data-expect="compute false critical | cpu critical | null 2" data-covers="export:createKPI"><code><span class="kw">const</span> { createKPI } = <span class="kw">await</span> import('../packages/modules/kpi/index.js');
+    rail with no data at all. <code>tree</code> is the opt-in (BACKLOG-0001673) &mdash; a dotted id alone does
+    not build a hierarchy, so this example sets <code>tree: {}</code> deliberately, the way any host must. Run
+    headless on every build.</p>
+    <pre data-run="js" data-expect="compute false critical | cpu critical | null 2" data-covers="export:createKPI config:tree"><code><span class="kw">const</span> { createKPI } = <span class="kw">await</span> import('../packages/modules/kpi/index.js');
 
 <span class="kw">const</span> fewerIsBetter = { warn: 70, critical: 90, direction: 'lowerIsBetter' };
 <span class="kw">const</span> tiles = [
@@ -7479,8 +7484,9 @@ kpi.expand(kpi.nodes()[0].key);      <span class="cmt">// open it</span></code><
     thresholds: { warn: 100, critical: 300, direction: 'lowerIsBetter' } },
 ];
 
-<span class="cmt">// No `tree` block: the dots in the tile ids are the hierarchy.</span>
-<span class="kw">const</span> kpi = createKPI(null, { rows: [{ id: 'h1', cpu: 94, mem: 40, latency: 12 }], rowKey: 'id', tiles });
+<span class="cmt">// `tree: {}` is the opt-in: without it, these dotted ids would stay flat tiles</span>
+<span class="cmt">// and the panel would warn once instead of building a hierarchy.</span>
+<span class="kw">const</span> kpi = createKPI(null, { rows: [{ id: 'h1', cpu: 94, mem: 40, latency: 12 }], rowKey: 'id', tree: {}, tiles });
 
 <span class="kw">const</span> compute = kpi.nodes()[0];
 <span class="cmt">// Nobody has opened it, and it reports the breach anyway.</span>
@@ -7488,7 +7494,7 @@ kpi.expand(kpi.nodes()[0].key);      <span class="cmt">// open it</span></code><
 <span class="kw">const</span> leaf = [compute.children[0].label, compute.children[0].status].join(' '); <span class="cmt">// cpu critical</span>
 
 <span class="cmt">// Nothing delivered: the parent reports the silence rather than a false green.</span>
-<span class="kw">const</span> quiet = createKPI(null, { rows: [], rowKey: 'id', tiles });
+<span class="kw">const</span> quiet = createKPI(null, { rows: [], rowKey: 'id', tree: {}, tiles });
 <span class="kw">const</span> silent = String(quiet.nodes()[0].rollup) + ' ' + quiet.nodes()[0].unknown; <span class="cmt">// null 2</span>
 
 <span class="kw">return</span> [shut, leaf, silent].join(' | ');</code></pre>
@@ -8200,15 +8206,65 @@ createGrid(el, {
 
     <h3>Icons</h3>
     <p>Inline SVG sprites, overridable by name through <code>registerIcon(name, def)</code>.</p>
+    <!-- icon-gallery:start -->
     <div class="chips">
-      <span class="chip">chevronRight</span><span class="chip">chevronDown</span><span class="chip">chevronUp</span><span class="chip">chevronLeft</span>
-      <span class="chip">check</span><span class="chip">dash</span><span class="chip">close</span><span class="chip">plus</span><span class="chip">minus</span>
-      <span class="chip">info</span><span class="chip">success</span><span class="chip">warning</span><span class="chip">danger</span>
-      <span class="chip">clock</span><span class="chip">lock</span><span class="chip">link</span><span class="chip">external</span><span class="chip">filter</span>
-      <span class="chip">sortAsc</span><span class="chip">sortDesc</span><span class="chip">menu</span><span class="chip">drag</span>
-      <span class="chip">star</span><span class="chip">heart</span><span class="chip">circleFilled</span><span class="chip">square</span><span class="chip">bolt</span><span class="chip">flag</span><span class="chip">thumbUp</span>
-      <span class="chip">eye</span><span class="chip">eyeOff</span><span class="chip">copy</span><span class="chip">present</span><span class="chip">blank</span>
-    </div>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3.5 10.5 8 6 12.5"></path></svg>chevronRight</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 6 8 10.5 12.5 6"></path></svg>chevronDown</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 10 8 5.5 12.5 10"></path></svg>chevronUp</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10 3.5 5.5 8 10 12.5"></path></svg>chevronLeft</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 8.5 6.5 11.5 12.5 4.5"></path></svg>check</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 8h8"></path></svg>dash</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 4l8 8M12 4l-8 8"></path></svg>close</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3.5v9M3.5 8h9"></path></svg>plus</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 8h9"></path></svg>minus</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Zm.75 4a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0ZM7.25 7h1.5v4.5h-1.5Z"></path></svg>info</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Zm3.2 4.4-4 4.6-2.4-2.3 1-1.1 1.3 1.2 3-3.4Z"></path></svg>success</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.5 15 14H1Zm-.75 4v4h1.5v-4Zm0 5v1.5h1.5V10.5Z"></path></svg>warning</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Zm-.75 3h1.5v5h-1.5Zm0 6h1.5V12h-1.5Z"></path></svg>danger</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13Zm-.75 3h1.5v3.7l2.5 1.5-.75 1.3-3.25-2Z"></path></svg>clock</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M4.5 7V5a3.5 3.5 0 1 1 7 0v2H13v7H3V7Zm1.5 0h4V5a2 2 0 1 0-4 0Z"></path></svg>lock</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M6.5 9.5a3 3 0 0 1 0-4l2-2a3 3 0 0 1 4 4l-1 1M9.5 6.5a3 3 0 0 1 0 4l-2 2a3 3 0 0 1-4-4l1-1"></path></svg>link</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M6.5 3.5h-3v9h9v-3M9.5 3.5h3v3M12.5 3.5 7 9"></path></svg>external</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M2 3h12l-4.5 5.2V13L6.5 11.5V8.2Z"></path></svg>filter</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M4.5 3h2.5v10H4.5zM9 3h2.5v10H9z"></path></svg>pause</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M4.5 3l8 5-8 5z"></path></svg>play</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 13.5h11"></path><path d="M4.5 13.5v-4"></path><path d="M8 13.5v-8"></path><path d="M11.5 13.5v-6"></path></svg>chart</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.5a6.5 6.5 0 0 0 0 13c.7 0 1.2-.5 1.2-1.1 0-.3-.1-.6-.3-.8a1.1 1.1 0 0 1 .8-1.9h1.4A3.4 3.4 0 0 0 14.5 7c0-3-2.9-5.5-6.5-5.5Z"></path><path d="M4.6 7.6a1 1 0 1 0 0-2 1 1 0 0 0 0 2ZM6.7 4.6a1 1 0 1 0 0-2 1 1 0 0 0 0 2ZM9.9 4.7a1 1 0 1 0 0-2 1 1 0 0 0 0 2ZM11.9 6.9a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z"></path></svg>palette</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8h6.5a3.25 3.25 0 0 1 0 6.5H6M3 8l3-3M3 8l3 3"></path></svg>undo</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M13 8H6.5a3.25 3.25 0 0 0 0 6.5H10M13 8l-3-3M13 8l-3 3"></path></svg>redo</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 2.5h11v11h-11zM6.5 2.5v11M10 2.5v11"></path></svg>columns</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2.5v7.5M8 10 5 7M8 10l3-3M2.5 12.5h11"></path></svg>download</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8a5 5 0 1 0 1.6-3.7M3 3v2.8h2.8"></path></svg>restore</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 2.5h10v11H3zM3 6h10M3 9.5h10M6.5 6v7.5"></path></svg>spreadsheet</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4.5 6V2.5h7V6M4.5 11.5h-2V6h11v5.5h-2M4.5 9.5h7v4h-7z"></path></svg>print</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 6V2.5H6M10 2.5h3.5V6M13.5 10v3.5H10M6 13.5H2.5V10"></path></svg>maximise</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M6 2.5V6H2.5M13.5 6H10V2.5M10 13.5V10h3.5M2.5 10H6v3.5"></path></svg>minimise</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 2.5h8v11L8 11l-4 2.5z"></path></svg>views</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7 2.5a4.5 4.5 0 1 0 0 9 4.5 4.5 0 0 0 0-9M10.4 10.4 13.5 13.5"></path></svg>search</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 11.2 11 2.7l2.3 2.3-8.5 8.5-3 .7z"></path></svg>pencil</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 4.5h10M6.5 4.5V3h3v1.5M4.5 4.5l.7 8.5h5.6l.7-8.5M6.8 7v3.7M9.2 7v3.7"></path></svg>trash</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M11.5 5.5a1.8 1.8 0 1 0 0-3.6 1.8 1.8 0 0 0 0 3.6M4.5 9.8a1.8 1.8 0 1 0 0-3.6 1.8 1.8 0 0 0 0 3.6M11.5 14.1a1.8 1.8 0 1 0 0-3.6 1.8 1.8 0 0 0 0 3.6M6.1 7.1l3.8-1.9M6.1 8.9l3.8 1.9"></path></svg>share</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2v6M5 8h6l1 2.5H4zM8 10.5V14"></path></svg>pin</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 3.5 12 8H4Z"></path></svg>sortAsc</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 12.5 4 8h8Z"></path></svg>sortDesc</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11"></path></svg>menu</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M6 3.5h1.5V5H6Zm3 0h1.5V5H9ZM6 7.25h1.5v1.5H6Zm3 0h1.5v1.5H9ZM6 11h1.5v1.5H6Zm3 0h1.5v1.5H9Z"></path></svg>drag</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 1.6l1.96 3.97 4.38.64-3.17 3.09.75 4.36L8 11.6l-3.92 2.06.75-4.36L1.66 6.21l4.38-.64Z"></path></svg>star</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 14.2 2.4 8.6a3.3 3.3 0 0 1 4.67-4.67L8 4.86l.93-.93A3.3 3.3 0 0 1 13.6 8.6Z"></path></svg>heart</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 2a6 6 0 1 0 0 12A6 6 0 0 0 8 2Z"></path></svg>circleFilled</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M3 3h10v10H3Z"></path></svg>square</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M9.5 1.5 3.5 9h3.2l-.7 5.5L12.5 7H9.3Z"></path></svg>bolt</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M4 1.5h1.5v13H4Zm1.5 1h7.5l-1.6 2.6L13 7.7H5.5Z"></path></svg>flag</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 13 12.5 3.5"></path><path d="M7.5 3.5H12.5V8.5"></path></svg>arrow</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 11 10 5l2 2-6 6H4z"></path><path d="M3 14.5h10"></path></svg>highlight</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M5.5 6.8 8.6 1.5a1.6 1.6 0 0 1 1.5 2.1L9.4 6h3.4a1.4 1.4 0 0 1 1.35 1.78l-1.3 4.6A1.9 1.9 0 0 1 11 13.8H5.5ZM4 6.5H1.5v7.3H4Z"></path></svg>thumbUp</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d="M8 3.2c3.3 0 6 3 6.6 4.5C14 9.3 11.3 12.3 8 12.3S2 9.3 1.4 7.7C2 6.2 4.7 3.2 8 3.2Zm0 2a2.5 2.5 0 1 0 0 5 2.5 2.5 0 0 0 0-5Z"></path></svg>eye</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.2 2.9 13.1 13.8M8 3.2c3.3 0 6 3 6.6 4.5a9.4 9.4 0 0 1-1.9 2.4M5 4.2A9 9 0 0 0 1.4 7.7C2 9.3 4.7 12.3 8 12.3c.9 0 1.7-.2 2.5-.5M6.3 6a2.5 2.5 0 0 0 3.4 3.5"></path></svg>eyeOff</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M5.5 2.5h8v8M2.5 5.5h8v8h-8Z"></path></svg>copy</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2 2.5h12v8H2Z"></path><path d="M8 10.5v3"></path><path d="M6 13.5h4"></path></svg>present</span>
+      <span class="chip chip--icon"><svg class="chip-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false" fill="currentColor"><path d=""></path></svg>blank</span>
+    </div>
+    <!-- icon-gallery:end -->
 
     <h2 id="operators">Filter grammar</h2>
     <p class="section-note">
@@ -9666,7 +9722,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
       </table>
     </div>
     <h3 id="type-ChartAnnotation">ChartAnnotation</h3>
-    <p class="section-note">One declarative annotation (BACKLOG-0000744, extended by BACKLOG-0000953). A reference or target line, a shaded band, a callout, or an `event` marker. Its value is a constant `value` (or `from`/`to` for a band), or a `compute` reduction of the data it annotates — `mean`, `median`, `min`, `max`, or `p95` for a percentile — so it follows the data as the grid is filtered. A band with `orient: 'vertical'` shades an x-range instead — an event window, a maintenance period — and an `event` marker is a labelled vertical rule with a flag at a position on the x axis. Every annotation names the axis it reads, which on a dual-axis chart is what stops it being placed against the wrong scale, and is written into the accessible table as a sentence — a vertical marker and an event stating the position they sit at, because a screen-reader user needs where and when, not only that a marker exists.</p>
+    <p class="section-note">One declarative annotation (BACKLOG-0000744, extended by BACKLOG-0000953). A reference or target line, a shaded band, a callout, or an `event` marker. Its value is a constant `value` (or `from`/`to` for a band), or a `compute` reduction of the data it annotates — `mean`, `median`, `min`, `max`, or `p95` for a percentile — so it follows the data as the grid is filtered. A band with `orient: 'vertical'` shades an x-range instead — an event window, a maintenance period — and an `event` marker is a labelled vertical rule with a flag at a position on the x axis. Every annotation names the axis it reads, which on a dual-axis chart is what stops it being placed against the wrong scale, and is written into the accessible table as a sentence — a vertical marker and an event stating the position they sit at, because a screen-reader user needs where and when, not only that a marker exists. An annotation the chart cannot place — an x value it cannot resolve on the axis, or a band whose edges are off-scale — is dropped with one console warning naming the annotation's kind, the axis and the reason, rather than vanishing without a trace (BACKLOG-0001672).</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
@@ -9732,7 +9788,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">fn</td><td class="type">TotalName</td><td class="desc">A reduction name, as the totals row uses. <small>(optional)</small></td></tr>
           <tr><td class="name">type</td><td class="type">'bar' | 'line' | 'area'</td><td class="desc">The mark this measure draws with, on a combo chart. <small>(optional)</small></td></tr>
           <tr><td class="name">axis</td><td class="type">'left' | 'right'</td><td class="desc">Which axis it belongs to, on a combo chart. <small>(optional)</small></td></tr>
-          <tr><td class="name">title</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">title</td><td class="type">string</td><td class="desc">The series label a combo's legend and axis titles use (BACKLOG-0001672). `label` is read too, as an undeclared alias, for a caller already using it; `title` wins when both are given. Falls back to the measure column's own `title`, then to `col`, when neither is set. <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>
@@ -11670,7 +11726,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">edit</td><td class="type">EditConfig | boolean</td><td class="desc">Editing, and how a change is committed and validated. <small>(optional)</small></td></tr>
           <tr><td class="name">pagination</td><td class="type">PaginationConfig | boolean</td><td class="desc">Page the rows rather than scrolling them. <small>(optional)</small></td></tr>
           <tr><td class="name">locale</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
-          <tr><td class="name">direction</td><td class="type">'ltr' | 'rtl' | 'auto'</td><td class="desc">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}). <small>(optional)</small></td></tr>
+          <tr><td class="name">direction</td><td class="type">'ltr' | 'rtl' | 'auto'</td><td class="desc">Writing direction. An explicit `'ltr'` or `'rtl'` always wins. Omit it, or say `'auto'`, to settle it from the mount or the nearest ancestor carrying a `dir="ltr"`/`dir="rtl"` attribute, and only then from `locale`: `ar`, `he`, `fa` and the rest resolve to `rtl`. A page-level `dir="ltr"` therefore wins over an RTL locale — a host that wants RTL inside an LTR page sets `direction: 'rtl'` explicitly. In a right-to-left grid the logical alignments `start`/`end` mirror while the physical `left`/`right` do not (see {@link Align}). <small>(optional)</small></td></tr>
           <tr><td class="name">timeZone</td><td class="type">string</td><td class="desc">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. <small>(optional)</small></td></tr>
           <tr><td class="name">theme</td><td class="type">Theme</td><td class="desc">The visual theme. <small>(optional)</small></td></tr>
           <tr><td class="name">density</td><td class="type">Density</td><td class="desc">Row height and padding as a named step, rather than pixel by pixel. <small>(optional)</small></td></tr>
@@ -12098,7 +12154,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
           <tr><td class="name">el</td><td class="type">unknown | null</td><td class="desc"><small>(read-only)</small></td></tr>
-          <tr><td class="name">rowKey</td><td class="type">string | ((row: KanbanRow) =&gt; unknown)</td><td class="desc"><small>(read-only)</small></td></tr>
+          <tr><td class="name">rowKey</td><td class="type">string | ((row: KanbanRow) =&gt; string | number)</td><td class="desc">The resolved card identity; see `KanbanConfig.rowKey`. <small>(read-only)</small></td></tr>
           <tr><td class="name">rows</td><td class="type">KanbanRows</td><td class="desc"></td></tr>
           <tr><td class="name">sla</td><td class="type">KanbanSla</td><td class="desc">The card-aging / SLA monitor, present only when a `sla` config was supplied (BACKLOG-0000960). <small>(optional)</small></td></tr>
           <tr><td class="name">columns</td><td class="type">(): KanbanColumn[]</td><td class="desc"></td></tr>
@@ -12233,7 +12289,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         <tbody>
           <tr><td class="name">rows</td><td class="type">KanbanRow[]</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">grid</td><td class="type">unknown</td><td class="desc"><small>(optional)</small></td></tr>
-          <tr><td class="name">rowKey</td><td class="type">string | ((row: KanbanRow) =&gt; unknown)</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">rowKey</td><td class="type">string | ((row: KanbanRow) =&gt; string | number)</td><td class="desc">Card identity (a field or fn, returning a string or number); default 'id'. Composite (`string[]`) keys are core-grid-only: a board keys its own card identity from one value, so there is nothing for an array to join into here (BACKLOG-0001669). <small>(optional)</small></td></tr>
           <tr><td class="name">columnProperty</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">columns</td><td class="type">KanbanColumnDef[]</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">columnOrder</td><td class="type">string[]</td><td class="desc"><small>(optional)</small></td></tr>
@@ -12421,7 +12477,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
           <tr><td class="name">el</td><td class="type">unknown | null</td><td class="desc"><small>(read-only)</small></td></tr>
-          <tr><td class="name">rowKey</td><td class="type">string | ((row: KPIRow) =&gt; unknown)</td><td class="desc"><small>(read-only)</small></td></tr>
+          <tr><td class="name">rowKey</td><td class="type">string | ((row: KPIRow) =&gt; string | number)</td><td class="desc">The resolved row identity; see `KPIConfig.rowKey`. <small>(read-only)</small></td></tr>
           <tr><td class="name">tree</td><td class="type">boolean</td><td class="desc">Whether the panel renders as a hierarchy rather than a flat tile grid. <small>(read-only)</small></td></tr>
           <tr><td class="name">rows</td><td class="type">KPIRows</td><td class="desc"></td></tr>
           <tr><td class="name">tiles</td><td class="type">(): KPITileModel[]</td><td class="desc"></td></tr>
@@ -12479,14 +12535,14 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         <tbody>
           <tr><td class="name">rows</td><td class="type">KPIRow[]</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">grid</td><td class="type">unknown</td><td class="desc"><small>(optional)</small></td></tr>
-          <tr><td class="name">rowKey</td><td class="type">string | ((row: KPIRow) =&gt; unknown)</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">rowKey</td><td class="type">string | ((row: KPIRow) =&gt; string | number)</td><td class="desc">Row identity (a field or fn, returning a string or number); default 'id'. Composite (`string[]`) keys are core-grid-only: a panel keys its own tile identity from one value, so there is nothing for an array to join into here (BACKLOG-0001669). <small>(optional)</small></td></tr>
           <tr><td class="name">fields</td><td class="type">string[]</td><td class="desc">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. <small>(optional)</small></td></tr>
           <tr><td class="name">tiles</td><td class="type">KPITile[]</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">columns</td><td class="type">number</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">ariaLabel</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">nullText</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">locale</td><td class="type">string</td><td class="desc">The default locale a clock tile formats in when the tile itself declares none (BACKLOG-0001640); falls back to the browser's default. No effect on a stat tile, which takes its own `format.locale`. <small>(optional)</small></td></tr>
-          <tr><td class="name">tree</td><td class="type">KPITreeConfig | false</td><td class="desc">Arrange the tiles as a hierarchy; `false` keeps the panel flat. <small>(optional)</small></td></tr>
+          <tr><td class="name">tree</td><td class="type">KPITreeConfig | false</td><td class="desc">Arrange the tiles as a hierarchy; unset or `false` keeps the panel flat. Opt-in (BACKLOG-0001673): a dotted tile id is not a hierarchy until `tree` is set, and warns once while it is not. <small>(optional)</small></td></tr>
           <tr><td class="name">messages</td><td class="type">{ t(key: string, params?: Record&lt;string, unknown&gt;): string }</td><td class="desc">The catalogue the panel's own text is read from. A panel routinely has no grid to borrow one off — two of its three input modes have none — so this is the first-class way to translate it. A grid's own `messages` satisfies the shape; a key it does not carry falls back to English. <small>(optional)</small></td></tr>
           <tr><td class="name">onTileClick</td><td class="type">(event: KPIEvent) =&gt; void</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">onTileDblClick</td><td class="type">(event: KPIEvent) =&gt; void</td><td class="desc"><small>(optional)</small></td></tr>
@@ -12572,6 +12628,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">format</td><td class="type">KPIFormat</td><td class="desc">Value formatting. <small>(optional)</small></td></tr>
           <tr><td class="name">target</td><td class="type">number</td><td class="desc">A comparison target rendered alongside the value. <small>(optional)</small></td></tr>
           <tr><td class="name">baseline</td><td class="type">number</td><td class="desc">A baseline the tile's delta is measured against. <small>(optional)</small></td></tr>
+          <tr><td class="name">delta</td><td class="type">'absolute' | 'relative' | 'both'</td><td class="desc">What the movement line prints against `baseline` (BACKLOG-0001673, F-FRED-G): `'absolute'` the difference alone, `'relative'` the percentage alone, `'both'` (the default, unchanged) both together. A rate series (4.10 vs 4.30) makes the percentage a percent-of-a-percent and meaningless, so `'absolute'` is how a host keeps the line without it. The arrow and its colour follow the sign of the difference either way. <small>(optional)</small></td></tr>
           <tr><td class="name">thresholds</td><td class="type">KPIThresholds</td><td class="desc">Threshold bands, either two cut points or an explicit band list. <small>(optional)</small></td></tr>
           <tr><td class="name">bands</td><td class="type">KPIBand[]</td><td class="desc">Explicit status bands (an alternative to `thresholds`). <small>(optional)</small></td></tr>
           <tr><td class="name">sparkline</td><td class="type">KPISparkline | string</td><td class="desc">A trend sparkline series. <small>(optional)</small></td></tr>
@@ -12610,13 +12667,14 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">delta</td><td class="type">number | null</td><td class="desc"></td></tr>
           <tr><td class="name">deltaPercent</td><td class="type">number | null</td><td class="desc"></td></tr>
           <tr><td class="name">deltaFormatted</td><td class="type">string</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">deltaMode</td><td class="type">'absolute' | 'relative' | 'both'</td><td class="desc">What the movement line prints; see `KPIStatTile.delta`. Always present once `baseline` is. <small>(optional)</small></td></tr>
           <tr><td class="name">count</td><td class="type">number</td><td class="desc"></td></tr>
           <tr><td class="name">sparkline</td><td class="type">number[] | null</td><td class="desc"></td></tr>
         </tbody>
       </table>
     </div>
     <h3 id="type-KPITreeConfig">KPITreeConfig</h3>
-    <p class="section-note">The hierarchy a KPI panel arranges its tiles into (BACKLOG-0001059): a rail of top-level items that expand to the indicators beneath them, each parent highlighted with the worst status below it. The shape is declared with `path` or `parentKey` — the same two shapes the grid's tree data and the tree-select editor take — over the **tile specs**, not the rows. With neither declared, one is derived by splitting the tile ids on `separator`, so `system.compute.cpu` files itself under Compute under System. A panel whose ids carry no separator stays flat, and `false` keeps it flat whatever they look like. A tile's `field` is never a source: a dot there already means a nested object property.</p>
+    <p class="section-note">The hierarchy a KPI panel arranges its tiles into (BACKLOG-0001059): a rail of top-level items that expand to the indicators beneath them, each parent highlighted with the worst status below it. `tree` is an opt-in (BACKLOG-0001673): omitted or `false`, the panel is flat whatever its tile ids look like, and a dotted id seen with `tree` unset is reported once rather than silently turned into a hierarchy. Given any object (`{}` included), the shape is declared with `path` or `parentKey` — the same two shapes the grid's tree data and the tree-select editor take — over the **tile specs**, not the rows. With neither declared, one is derived by splitting the tile ids on `separator`, so `system.compute.cpu` files itself under Compute under System. A panel whose ids carry no separator stays flat even with `tree` set. A tile's `field` is never a source: a dot there already means a nested object property.</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
@@ -14848,7 +14906,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
 <!-- END GENERATED TYPE REFERENCE -->
 
     <footer>
-      Lattice Grid 1.66.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+      Lattice Grid 1.68.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
       This document describes the behaviour of the shipped library. Where this guide and the code
       disagree, the code wins: please <a href="https://www.latticegrid.dev">tell us</a>.
     </footer>

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.66.0</p>
+    <p class="rail__sub">Developer guide · v1.68.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -554,7 +554,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.66.0</span>
+        <span class="chip">Version 1.68.0</span>
           <span class="chip">Zero dependencies</span>
         <span class="chip">No build step</span>
       </p>
@@ -1492,7 +1492,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.66.0'</span>
+      <pre><code>grid.getVersion();          <span class="cmt">// '1.68.0'</span>
 LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid to hand</span></code></pre>
     </div>
     <p class="lead-in">
@@ -9035,7 +9035,7 @@ return (`proposals ${proposals.join(',')} | diff ${result.diff.map((d) =&gt; `ol
 
     <h3 id="kpi-config-examples">KPI config keys, executed</h3>
     <p class="lead-in">
-      Three examples covering the eleven KPI config keys not already demonstrated elsewhere in this
+      Four examples covering the twelve KPI config keys not already demonstrated elsewhere in this
       guide.
     </p>
 
@@ -9145,6 +9145,41 @@ return (`${el.querySelectorAll('.lat-kpi__node')[0].getAttribute('aria-label')}
       </p>
     </div>
 
+    <div class="example">
+      <p class="example__label">What the movement line prints against a baseline: delta, executed</p>
+      <pre data-run="js" data-expect="both:▼ -0.2 (-4.7%) | absolute:▼ -0.2 | relative:▼ -4.7%" data-covers="config:delta"><code>const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
+const { createKPI } = await import('../packages/modules/kpi/index.js');
+
+const dom = createTestDom({});
+const el = dom.document.createElement('div');
+// A rate series (4.10 vs a 4.30 baseline a year earlier): the percentage of a
+// rate is meaningless, so a host names 'absolute' to keep the line without it.
+const kpi = createKPI(el, {
+  rows: [{ id: 1, rate: 4.10 }], rowKey: 'id',
+  tiles: [
+    { id: 'both', label: 'Default', aggregation: 'max', field: 'rate',
+      baseline: 4.30, format: { decimals: 1 } },
+    { id: 'absolute', label: 'Difference alone', aggregation: 'max', field: 'rate',
+      baseline: 4.30, format: { decimals: 1 }, delta: 'absolute' },
+    { id: 'relative', label: 'Percentage alone', aggregation: 'max', field: 'rate',
+      baseline: 4.30, format: { decimals: 1 }, delta: 'relative' },
+  ],
+});
+const lines = ['both', 'absolute', 'relative'].map((id) =&gt; {
+  const fig = [...el.querySelectorAll('.lat-kpi__tile')].find((f) =&gt; f.getAttribute('aria-label').startsWith(
+    id === 'both' ? 'Default' : (id === 'absolute' ? 'Difference' : 'Percentage')));
+  return `${id}:${fig.querySelector('.lat-kpi__delta').textContent}`;
+});
+return lines.join(' | ');
+</code></pre>
+      <p>
+        <code>delta: 'absolute' | 'relative' | 'both'</code> (default <code>'both'</code>, unchanged)
+        chooses what a tile's movement line prints against its <code>baseline</code> &mdash; the
+        difference alone, the percentage alone, or both together, exactly as before this option
+        existed. The arrow and its colour follow the sign of the difference in every mode.
+      </p>
+    </div>
+
     <h3 id="route-options-examples">Data Router route options, executed</h3>
     <div class="example">
       <p class="example__label">A per-route filter and transform, executed</p>
@@ -9651,7 +9686,7 @@ grid.licence.state();   <span class="cmt">// 'licensed' | 'localhost' | 'trial'<
 
     <footer>
       <p>
-        Lattice Grid 1.66.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+        Lattice Grid 1.68.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.66.0, type declarations
+ * Lattice Grid 1.68.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -2071,11 +2071,14 @@ export interface GridConfig {
   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}).
+   * Writing direction. An explicit `'ltr'` or `'rtl'` always wins. Omit it, or
+   * say `'auto'`, to settle it from the mount or the nearest ancestor
+   * carrying a `dir="ltr"`/`dir="rtl"` attribute, and only then from
+   * `locale`: `ar`, `he`, `fa` and the rest resolve to `rtl`. A page-level
+   * `dir="ltr"` therefore wins over an RTL locale — a host that wants RTL
+   * inside an LTR page sets `direction: 'rtl'` explicitly. 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';
   /**
@@ -7555,6 +7558,12 @@ export interface ChartMeasure {
   type?: 'bar' | 'line' | 'area';
   /** Which axis it belongs to, on a combo chart. */
   axis?: 'left' | 'right';
+  /**
+   * The series label a combo's legend and axis titles use.
+   * `label` is read too, as an undeclared alias, for a caller already using
+   * it; `title` wins when both are given. Falls back to the measure column's
+   * own `title`, then to `col`, when neither is set.
+   */
   title?: string;
 }
 
@@ -7667,7 +7676,11 @@ export interface ChartTrend {
  * which on a dual-axis chart is what stops it being placed against the wrong
  * scale, and is written into the accessible table as a sentence — a vertical
  * marker and an event stating the position they sit at, because a screen-reader
- * user needs where and when, not only that a marker exists.
+ * user needs where and when, not only that a marker exists. An annotation the
+ * chart cannot place — an x value it cannot resolve on the axis, or a band
+ * whose edges are off-scale — is dropped with one console warning naming the
+ * annotation's kind, the axis and the reason, rather than vanishing without a
+ * trace.
  */
 export interface ChartAnnotation {
   /**