@toclocoinc/lattice-grid 1.67.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.67.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.67.0",
+  "version": "1.68.0",
   "type": "module",
   "sideEffects": false,
   "module": "./fesm2022/toclocoinc-lattice-grid-angular.mjs",

package/docs/API.html

@@ -363,7 +363,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">API reference · v1.67.0</p>
+    <p class="rail__sub">API reference · v1.68.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start</span>
@@ -456,7 +456,7 @@
     </header>
 
     <p class="chips">
-      <span class="chip">Version 1.67.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>
@@ -1960,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.67.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>
@@ -7366,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>
@@ -7445,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: [
@@ -7461,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>
@@ -7471,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 = [
@@ -7482,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>
@@ -7491,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>
@@ -9719,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>
@@ -9785,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>
@@ -12539,7 +12542,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <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>
@@ -12625,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>
@@ -12663,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>
@@ -14901,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.67.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.67.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.67.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.67.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.67.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.67.0, type declarations
+ * Lattice Grid 1.68.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -7558,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;
 }
 
@@ -7670,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 {
   /**