@toclocoinc/lattice-grid 1.7.0 → 1.8.0

package/README.md

@@ -4,7 +4,7 @@
 dependencies, no build step required. Optional adapters for React, Vue, Svelte
 and Web Components ship alongside it.
 
-Version 1.7.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.8.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 
@@ -27,6 +27,98 @@ runtime, not a CDN, not a font, not an icon sprite.
 
 ---
 
+## What it does
+
+A short tour. The [API reference](docs/API.html) has the whole of it; this is
+enough to know whether the grid covers what you need.
+
+### Data and scale
+
+- **Virtualised rows and columns.** Hundreds of thousands of rows on a typed-array
+  column store, with dictionary encoding and presence bitsets. Row height can be
+  fixed, per-row, or measured from content.
+- **Sort, filter, group, pivot and aggregate**, each as an independent stage
+  over the same data. Multi-column sort, a filter grammar with typed operators,
+  row grouping to any depth, full pivoting, and a totals row that reduces by any
+  of the built-in kernels or one of your own.
+- **Live data.** `rows.apply({add, update, remove})` patches in place: the grid
+  re-queries the stages a change actually touched and repaints the cells that
+  moved. A feed can be paused and resumed with the queue held.
+- **Any source.** Rows in memory, or a source you write — server-side paging,
+  infinite scroll, streaming, or an async provider. Sorting and filtering can be
+  handed to the server or left to the grid.
+
+### Working with the data
+
+- **Editing.** Cell, row and form editing, with over twenty editors — text,
+  number, date, time, select, multi-select, colour, rating, slider, segmented,
+  code, password, icon picker and more. Validation, async commits, optimistic
+  updates with rollback, and a full undo history.
+- **Selection and ranges.** Cell, row, column and rectangular range selection,
+  with clipboard behaviour that round-trips through Excel.
+- **Fill, copy and paste** across a range, including formulas.
+- **Formulas.** A closed, safe expression language — no `eval`, no host access —
+  with maths, text, logic, date and statistical functions, evaluated against
+  other columns.
+- **Export.** CSV with fields sanitised against formula injection, real `.xlsx`
+  written without a ZIP dependency, the clipboard as TSV with a matching paste
+  parser, and print. All of them take the filters, sort and grouping the user is
+  looking at, or the whole set.
+
+### Seeing the data
+
+- **Charts.** `modules/charts` draws thirty chart types from the grid's own
+  data — line, bar, area, scatter, pie, donut, sunburst, treemap, radar, gauge,
+  funnel, heatmap, histogram, box plot, candlestick, combo, geomap, sankey,
+  chord, network, stream, violin, gantt and more. They follow the grid's
+  filters, and clicking a mark can filter it in turn.
+- **Statistics.** `grid.statistics` profiles a column in one pass — count,
+  missing, distinct, five-number summary, standard deviation, outliers and a
+  histogram — and answers correlations and weighted averages. Twenty-eight
+  reduction kernels are available to the totals row, and you can register your
+  own.
+- **Shadow columns.** Values the grid maintains about itself: how many times a
+  row has changed, what a value was when the page loaded, how fast it is moving,
+  its rank, percentile or share of the total. Real columns — sortable,
+  filterable, exportable, saved into a view.
+- **Conditional formatting** as runtime state a user can change, with rules that
+  either name a threshold or describe the data: the top decile, the outliers,
+  two deviations above the mean.
+- **In-cell charts**, sparklines, data bars, progress, ratings and pills.
+- **Header histograms** that double as a filter.
+
+### The interface
+
+- **Tool panels** for columns, filters, views, quick filter, formatting and
+  statistics, docked or as an icon rail.
+- **Saved views** — the whole grid state as a named, shareable object, stored
+  on your server or in the browser.
+- **Column menu, context menu and status bar**, each extensible with your own
+  items.
+- **Pinned columns and rows**, column groups, resize, reorder, autosize, and a
+  density control.
+- **Master–detail rows**, tree data, and full-width rows.
+- **Presence** — live cursors, selections and edit locks for collaborative use,
+  carrying intent and never values.
+- **Comments** threaded on cells, and an annotation layer for presenting.
+- **Full-screen mode**, print, and image capture.
+
+### Quality of the thing itself
+
+- **Accessible.** Keyboard operable throughout, ARIA grid semantics, a live
+  region for announcements, honours reduced motion, forced colours and large
+  target sizes. The devtools module runs the accessibility checks in place.
+- **Internationalised.** Eighteen complete locales, right-to-left layout, and
+  locale-aware number, date and currency formatting throughout.
+- **Themeable** through CSS custom properties, with light and dark built in and
+  a reset that keeps a host page's stylesheet out.
+- **Typed.** Complete TypeScript declarations, checked against the runtime on
+  every build.
+- **Zero runtime dependencies.** Nothing is fetched at runtime — not a CDN, not
+  a font, not an icon sprite.
+
+---
+
 ## Quick start
 
 ### No build step

package/docs/API.html

@@ -360,7 +360,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">API reference · v1.7.0</p>
+    <p class="rail__sub">API reference · v1.7.1</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start</span>
@@ -397,6 +397,7 @@
         <a href="#presentation">grid.presentation</a>
         <a href="#redaction">grid.redaction</a>
         <a href="#formatting">grid.formatting</a>
+        <a href="#statistics">grid.statistics</a>
         <a href="#highlight">grid.highlight</a>
         <a href="#views">grid.views</a>
         <a href="#diff">grid.diff</a>
@@ -437,7 +438,7 @@
     </header>
 
     <p class="chips">
-      <span class="chip">Version 1.7.0</span>
+      <span class="chip">Version 1.7.1</span>
       <span class="chip">Zero dependencies</span>
       <span class="chip"><a href="api-detail.html">Developer guide &rarr;</a></span>
     </p>
@@ -455,8 +456,8 @@
 
     <p>Or straight from jsDelivr — no npm install, no bundler, no local copy at all:</p>
 
-    <pre><code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.0/lattice-grid.min.css"&gt;
-&lt;script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.0/lattice-grid.min.js"&gt;&lt;/script&gt;
+    <pre><code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.min.css"&gt;
+&lt;script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.min.js"&gt;&lt;/script&gt;
 
 &lt;script&gt;
   <span class="kw">const</span> grid = LatticeGrid.createGrid(document.getElementById('grid'), config);
@@ -467,7 +468,7 @@
     <pre><code><span class="cmt">// With a renderer, in a browser. Any of:</span>
 <span class="kw">import</span> { createGrid } <span class="kw">from</span> './dist/lattice-grid.esm.js';
 <span class="cmt">// import { createGrid } from '@toclocoinc/lattice-grid';</span>
-<span class="cmt">// import { createGrid } from 'https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.0/lattice-grid.esm.min.js';</span>
+<span class="cmt">// import { createGrid } from 'https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.esm.min.js';</span>
 <span class="kw">const</span> grid = createGrid(document.getElementById('grid'), config);
 
 <span class="cmt">// Headless: the same API without a renderer. Data, filters, sort,</span>
@@ -479,7 +480,7 @@
 
     <div class="note"><p>jsDelivr mirrors every version published to npm at
     <code>cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@&lt;version&gt;/&lt;file&gt;</code>. Pin an exact
-    version for anything shipped — <code>@1.7.0</code>, not <code>@latest</code> — so a release does
+    version for anything shipped — <code>@1.7.1</code>, not <code>@latest</code> — so a release does
     not change what a page already in production loads. The same convention reaches any module:
     <code>.../modules/htmx.esm.min.js</code>, <code>.../modules/react.esm.min.js</code>, and so on.</p></div>
 
@@ -793,7 +794,7 @@ autoInit(document); <span class="cmt">// builds every [data-lattice-grid] under
         <tbody>
           <tr><td class="name">statusBar</td><td class="type">boolean | { panels }</td><td class="desc">Composable panels along the bottom. Default set: <code>rowCount</code>, <code>selectedCount</code>, <code>aggregation</code>, <code>comments</code>, <code>updates</code>, <code>progress</code>. Each is silent when it has nothing to report.</td></tr>
           <tr><td class="name">maximise</td><td class="type">boolean</td><td class="dflt">true</td><td class="desc"><code>false</code> removes the rail button and <code>grid.maximise</code>, for an application with its own full-screen mode.</td></tr>
-          <tr><td class="name">toolPanel</td><td class="type">boolean | object</td><td class="desc">Side dock. <code>panels</code>: <code>columns</code>, <code>filters</code>, <code>views</code>, <code>quick</code>, <code>formatting</code>. <code>side: 'left'</code> makes it the icon rail, which also turns on <code>actions</code> (<code>undo</code>, <code>redo</code>, <code>pause</code>, <code>restore</code>, <code>maximise</code>, then the export group: <code>export</code>, <code>excel</code>, <code>clipboard</code>, <code>print</code> — nine in all, and an array takes these names rather than the button labels) and <code>icons</code>. An explicit array <em>replaces</em> that list rather than extending it; a bare <code>'-'</code> in it renders a divider between groups. <code>exportName</code> names the CSV.</td></tr>
+          <tr><td class="name">toolPanel</td><td class="type">boolean | object</td><td class="desc">Side dock. <code>panels</code>: <code>columns</code>, <code>filters</code>, <code>views</code>, <code>quick</code>, <code>formatting</code>, <code>statistics</code>. <code>side: 'left'</code> makes it the icon rail, which also turns on <code>actions</code> (<code>undo</code>, <code>redo</code>, <code>pause</code>, <code>restore</code>, <code>maximise</code>, then the export group: <code>export</code>, <code>excel</code>, <code>clipboard</code>, <code>print</code> — nine in all, and an array takes these names rather than the button labels) and <code>icons</code>. An explicit array <em>replaces</em> that list rather than extending it; a bare <code>'-'</code> in it renders a divider between groups. <code>exportName</code> names the CSV.</td></tr>
           <tr><td class="name">contextMenu</td><td class="type">boolean | (p) =&gt; MenuItem[]</td><td class="desc">Right-click menu. The function form is <code>(params, defaults) =&gt; items</code> — see <a href="#custom-menu">custom items</a>. <code>false</code> suppresses it — what a read-only grid wants, since the default menu offers Paste, Clear and Fill down.</td></tr>
           <tr><td class="name">columnMenu</td><td class="type">boolean | (p) =&gt; MenuItem[]</td><td class="desc">The header's 3-dot menu, and a right-click on a column heading. The function form is <code>(params, defaults) =&gt; items</code>, with <code>params</code> carrying <code>colId</code>, <code>column</code> and <code>grid</code> — see <a href="#custom-menu">custom items</a>. <code>false</code> suppresses it.</td></tr>
           <tr><td class="name">shortcuts</td><td class="type">boolean</td><td class="dflt">true</td><td class="desc">The <kbd>?</kbd> keyboard shortcut overlay. <code>false</code> suppresses it, for a host that wants <kbd>?</kbd> for itself. See <a href="api-detail.html#keyboard">Keyboard</a>.</td></tr>
@@ -930,7 +931,7 @@ autoInit(document); <span class="cmt">// builds every [data-lattice-grid] under
       <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.7.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.7.1'</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>
@@ -1563,6 +1564,89 @@ grid.formatting.clear('margin');                  // or clear() for everything</
     </div>
     <div class="note"><p>A rule held here must be JSON: <code>style</code> may not be a function, because the rules are serialised into views and undo slices. Config-time <code>cell.style</code> still accepts one. Group rows are not formatted, matching the way decoration is dropped for them.</p></div>
 
+    <h3>Rules that describe the data, not a threshold</h3>
+    <p><code>gt: 100</code> needs somebody to know that 100 is the interesting number. Often nobody does — the interesting cells are <em>the top decile</em>, or <em>the outliers</em>, and where those fall is a property of the data rather than of the rule. These operators say that directly, and the grid works out the threshold from the column itself, over the filtered rows.</p>
+    <pre><code>grid.formatting.add('margin', { when: { op: 'outlier' }, style: { background: '#fbeceb' } });
+grid.formatting.add('qty',    { when: { op: 'topPercent', value: 10 }, style: { bold: true } });
+grid.formatting.add('score',  { scale: { from: 'quantile', colours: ['#f8f9fa', '#1a6bc7'] } });
+
+grid.formatting.distribution('margin');   // { n, min, max, mean, stddev, median, q1, q3, iqr }
+grid.formatting.restat();                 // re-derive every threshold from the data as it stands</code></pre>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Operator</th><th><code>value</code></th><th>Marks</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">topPercent</td><td class="type">10 or 0.1</td><td class="desc">The top tenth of the column. Written either way; both mean the same thing.</td></tr>
+          <tr><td class="sig">bottomPercent</td><td class="type">10 or 0.1</td><td class="desc">The bottom tenth.</td></tr>
+          <tr><td class="sig">topN</td><td class="type">5</td><td class="desc">The five largest, ties included — three rows sharing second place in a top three all take the colour.</td></tr>
+          <tr><td class="sig">bottomN</td><td class="type">5</td><td class="desc">The five smallest.</td></tr>
+          <tr><td class="sig">aboveMean / belowMean</td><td class="type">—</td><td class="desc">Either side of the mean.</td></tr>
+          <tr><td class="sig">aboveMedian / belowMedian</td><td class="type">—</td><td class="desc">Either side of the median, which is the one to reach for on a skewed column.</td></tr>
+          <tr><td class="sig">zAbove / zBelow</td><td class="type">2</td><td class="desc">That many standard deviations from the mean. A column with no spread marks nothing rather than everything.</td></tr>
+          <tr><td class="sig">outlier</td><td class="type">1.5</td><td class="desc">Outside Tukey's fences at that many IQRs — the same definition a box plot draws, so the marked cells are the ones its whiskers exclude.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <p>A colour scale can take its bounds the same way, with <code>from</code> in place of <code>min</code> and <code>max</code>: <code>'minmax'</code> spans the data, <code>'quantile'</code> spans <code>low</code> to <code>high</code> (5th to 95th percentile by default), <code>'stddev'</code> spans <code>deviations</code> either side of the mean. The quantile form is the better default on real data — one mistyped order of magnitude otherwise compresses every real value into the first swatch.</p>
+    <div class="note"><p>Thresholds are <strong>pinned</strong> when the rules compile and do not move on their own. That is deliberate: a boundary that re-derived itself as rows were filtered would repaint cells whose values had not changed, and nobody comparing two screenshots could tell which of the two things had moved. <code>grid.formatting.restat()</code> is how you move it, and a "recalculate" control is the natural place to put it.</p></div>
+
+    <h2 id="statistics">grid.statistics</h2>
+    <p>What the grid knows about its own numbers, and about how they have changed since the page loaded. Every figure is computed over the <em>filtered</em> rows, through the same column handles the totals row uses — so a median here and a median in the footer are the same number, by the same definition (R type 7).</p>
+    <pre><code>grid.statistics.profile('margin');
+// { column, rows, present, missing, distinct, min, max, mean, median,
+//   q1, q3, iqr, stddev, outliers, histogram: [{ from, to, count }, …] }
+
+grid.statistics.reduce('margin', 'p95');          // any registered kernel
+grid.statistics.correlation('spend', 'revenue');  // Pearson's r, clamped to [-1, 1]
+grid.statistics.weightedAverage('price', 'qty');
+
+grid.statistics.shadow('price', 'delta', 'R42');  // one row's shadow value
+grid.statistics.rebase('price');                  // "mark all" — today's values become the baseline
+grid.statistics.tracking();                       // { columns, rows, forgotten }</code></pre>
+    <p>The <code>statistics</code> tool panel is the end-user half of <code>profile()</code>: a column picker, the twelve figures and a histogram of the column's shape, all following the filters. Add it with <code>toolPanel: { panels: ['columns', 'statistics'] }</code>.</p>
+
+    <h3>Shadow columns</h3>
+    <p>A shadow column is declared against another column and maintained by the grid. It has no field in the data and it is not a pure computed column either, because its value depends on what happened <em>before</em>. It is a real column throughout: sortable, filterable, totalled, grouped, exported, saved into a view — which is what makes "show me every circuit repriced more than twice this session, most-changed first" one gesture rather than a report.</p>
+    <pre><code>columns: [
+  { field: 'price', type: 'number' },
+  { id: 'moved',  title: 'Change',  shadow: { of: 'price', kind: 'delta' } },
+  { id: 'churn',  title: 'Updates', shadow: { of: 'price', kind: 'updates' } },
+  { id: 'run',    title: 'Streak',  shadow: 'streak' },   // shorthand: shadows the column beside it
+]</code></pre>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Kind</th><th>Value</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">updates</td><td class="desc">How many times the row's value has changed. Arrival is not a change, so a freshly loaded grid reads zero rather than one.</td></tr>
+          <tr><td class="sig">updatedAt</td><td class="desc">When it last changed, as a <code>Date</code>.</td></tr>
+          <tr><td class="sig">sinceUpdate</td><td class="desc">Milliseconds since it last changed.</td></tr>
+          <tr><td class="sig">delta</td><td class="desc">Current value minus the baseline.</td></tr>
+          <tr><td class="sig">deltaPercent</td><td class="desc">The same as a percentage. A change from nothing has no percentage and reads null rather than infinity.</td></tr>
+          <tr><td class="sig">rate</td><td class="desc">Change per second, from the last two readings.</td></tr>
+          <tr><td class="sig">history</td><td class="desc">The recent readings, oldest first. <code>depth</code> sets how many; the default is 20.</td></tr>
+          <tr><td class="sig">firstValue</td><td class="desc">The baseline itself.</td></tr>
+          <tr><td class="sig">streak</td><td class="desc">Consecutive moves in one direction, signed. It resets on a turn, because "seven rises" means something and "seven changes" does not.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <p>A second family answers where the row sits among the others rather than what it did before. They share the same declaration and the same state — the tracker already holds every row's current value <em>and</em> its baseline, which is exactly what a rank and a rank <em>change</em> need.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Kind</th><th>Value</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">rank</td><td class="desc">Competition rank, largest first: ties share the better rank and the next value skips, so two firsts are followed by a third.</td></tr>
+          <tr><td class="sig">rankAsc</td><td class="desc">The same ranking read from the other end.</td></tr>
+          <tr><td class="sig">rankChange</td><td class="desc">Places climbed since the baseline. Positive means climbed, even though the rank number itself falls — this is the "top movers" column.</td></tr>
+          <tr><td class="sig">percentile</td><td class="desc">The share of rows at or below this one, 0 to 100.</td></tr>
+          <tr><td class="sig">quartile</td><td class="desc">1 to 4, agreeing with <code>percentile</code>: the 60th percentile is in the third quartile.</td></tr>
+          <tr><td class="sig">zScore</td><td class="desc">Deviations from the mean. A column with no spread reads null rather than zero.</td></tr>
+          <tr><td class="sig">shareOfTotal</td><td class="desc">The value over the column's total, as a percentage. A total of zero — a column of offsetting positions — reads null rather than a division by it.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <div class="note"><p>Positional kinds rank over every <em>tracked</em> row, not over the filtered set: a rank that changed as you filtered would make "the top ten movers" depend on what happened to be on screen, and the column would disagree with itself between two views of the same data. For the filtered answer, use <code>grid.statistics.profile()</code> or a distribution formatting rule.</p></div>
+    <div class="note"><p>Shadow state is keyed by row key, never by index — after any sort an index-keyed history would report one row's past against another row's present, and the wrong number would be <em>sortable</em>. Memory is capped at 200,000 tracked rows per column; past that the oldest are dropped and <code>tracking().forgotten</code> says how many, rather than a smaller number being reported as though it were the truth.</p></div>
+
     <h2 id="highlight">grid.highlight</h2>
     <p>One mechanism for two jobs: the flash a changed cell makes, and a marker you paint deliberately. A target is a cell (<code>{key, colId}</code>), a row (<code>{key}</code>, or a bare row key) or a column (<code>{colId}</code>). Cell beats row beats column, so a specific highlight is never hidden by a broad one laid over it.</p>
     <pre><code>createGrid(el, {
@@ -2110,10 +2194,13 @@ grid.filters.quickState();   <span class="cmt">// { text: 'acme london', mode: '
           <tr><td class="sig">Rounding</td><td><code>ROUND</code>, <code>ROUNDUP</code>, <code>ROUNDDOWN</code>, <code>FLOOR</code>, <code>CEILING</code></td></tr>
           <tr><td class="sig">Logic</td><td><code>IF</code>, <code>AND</code>, <code>OR</code>, <code>NOT</code>, <code>COALESCE</code></td></tr>
           <tr><td class="sig">Text</td><td><code>CONCAT</code>, <code>LEN</code>, <code>UPPER</code>, <code>LOWER</code>, <code>TRIM</code>, <code>LEFT</code>, <code>RIGHT</code></td></tr>
+          <tr><td class="sig">Statistics</td><td><code>MEDIAN</code>, <code>PERCENTILE</code>, <code>QUARTILE1</code>, <code>QUARTILE3</code>, <code>IQR</code>, <code>STDEV</code>, <code>STDEVP</code>, <code>VAR</code>, <code>VARP</code>, <code>COUNTDISTINCT</code></td></tr>
         </tbody>
       </table>
     </div>
 
+    <div class="note"><p>The statistical functions use R type 7 quantiles — the same definition as the totals row, <code>grid.statistics</code> and the distribution formatting rules, so the four never disagree about what a median is. <code>PERCENTILE</code> reads <code>90</code> and <code>0.9</code> as the same request. Over an empty set they return a number rather than null, because a formula is arithmetic and has to keep composing.</p></div>
+
     <p>Operators <code>+ - * / ^</code> with parentheses, comparison for <code>IF</code>, and postfix
     <code>%</code>. <code>^</code> is right-associative and unary minus binds tighter than it, so
     <code>-2^2</code> is 4 — Excel's answer rather than mathematics'.</p>
@@ -2332,7 +2419,7 @@ createGrid(el, {
     </div>
 
     <footer>
-      Lattice Grid 1.7.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+      Lattice Grid 1.7.1 · 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.7.0</p>
+    <p class="rail__sub">Developer guide · v1.7.1</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -537,7 +537,7 @@
         <a href="API.html">reference tables</a> are the shorter version for when you already know.
       </p>
       <p class="chips">
-        <span class="chip">Version 1.7.0</span>
+        <span class="chip">Version 1.7.1</span>
           <span class="chip">Zero dependencies</span>
         <span class="chip">No build step</span>
       </p>
@@ -652,8 +652,8 @@ createGrid(element, { direction: 'rtl' });    <span class="cmt">// or say so out
 
     <div class="example">
       <p class="example__label">jsDelivr — no npm install, no bundler</p>
-      <pre><code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.0/lattice-grid.min.css"&gt;
-&lt;script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.0/lattice-grid.min.js"&gt;&lt;/script&gt;
+      <pre><code>&lt;link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.min.css"&gt;
+&lt;script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.7.1/lattice-grid.min.js"&gt;&lt;/script&gt;
 
 &lt;script&gt;
   <span class="kw">const</span> grid = LatticeGrid.createGrid(document.getElementById('grid'), config);
@@ -679,7 +679,7 @@ createGrid(element, { direction: 'rtl' });    <span class="cmt">// or say so out
     <div class="note">
       <p><strong>jsDelivr mirrors every version published to npm</strong> at
       <code>cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@&lt;version&gt;/&lt;file&gt;</code> — pin an
-      exact version, e.g. <code>@1.7.0</code> rather than <code>@latest</code>, so a later release
+      exact version, e.g. <code>@1.7.1</code> rather than <code>@latest</code>, so a later release
       does not change what a page already in production loads. The same convention reaches a
       module: <code>.../modules/htmx.esm.min.js</code>, <code>.../modules/dhtmlx-compat.esm.min.js</code>,
       and so on. Type declarations resolve automatically through npm's own <code>types</code> field;
@@ -1168,7 +1168,7 @@ off();                                       <span class="cmt">// every subscrip
     </p>
     <div class="example">
       <p class="example__label">Which version am I running?</p>
-      <pre><code>grid.getVersion();          <span class="cmt">// '1.7.0'</span>
+      <pre><code>grid.getVersion();          <span class="cmt">// '1.7.1'</span>
 LatticeGrid.getVersion();   <span class="cmt">// the same, when you have no grid to hand</span></code></pre>
     </div>
     <p class="lead-in">
@@ -1652,9 +1652,10 @@ grid.set('theme', <span class="kw">null</span>);   <span class="cmt">// back to
     <div class="why">
       <p><strong>Why this is needed at all.</strong> A grid is mounted inside somebody else's
       stylesheet. A rule as ordinary as <code>section { padding: 5.5rem 0 }</code> — a marketing
-      page, a CMS theme, a Tailwind preflight — used to reach inside and put 88px of padding on every
-      filter row in the tool panel, because the grid builds those rows as <code>&lt;section&gt;</code>
-      elements and its own rules said nothing about padding there.</p>
+      page, a CMS theme, a Tailwind preflight — matches by tag name, and the grid builds parts of
+      its own interface from those tags: the tool panel's filter rows are
+      <code>&lt;section&gt;</code> elements. Without the reset, 5.5rem of somebody else's padding
+      lands on every one of them.</p>
       <p>The reset uses no <code>!important</code>. It is specificity (0,1,1) and every rule that
       dresses a grid element is (0,2,0) or higher, so the grid's own styling always wins and the
       reset only fills a gap. Yours wins too, on the same terms: a rule aimed at a Lattice class —
@@ -4440,10 +4441,11 @@ r.ok ? r.value : r.error;   <span class="cmt">// 42</span></code></pre>
     </p>
     <div class="why">
       <p><strong>Bare arithmetic is deliberately not a formula.</strong> <code>2-1</code> is a
-      plausible product code and <code>1/2</code> a plausible date. Evaluating either on a guess would
-      repeat the bug this replaced, where the number reader stripped the operator and stored
-      <code>2*3</code> as <strong>23</strong>. Arithmetic without a leading <code>=</code> is now
-      refused outright, so the cell keeps what it had rather than taking a plausible wrong number.</p>
+      plausible product code and <code>1/2</code> a plausible date. A reader that evaluated either on
+      a guess would have to guess wrong sometimes, and the wrong answer is not a visible error but a
+      plausible number — <code>2*3</code> stored as <strong>23</strong> looks like data. Arithmetic
+      without a leading <code>=</code> is refused outright, so the cell keeps what it had rather than
+      taking a number nobody typed.</p>
     </div>
 
     <h2 id="custom-menu">Your own menu items and buttons</h2>
@@ -5124,7 +5126,7 @@ grid.licence.state();   <span class="cmt">// 'licensed' | 'localhost' | 'trial'<
 
     <footer>
       <p>
-        Lattice Grid 1.7.0 · Copyright © 2026 TOCLOCO Inc. All rights reserved.
+        Lattice Grid 1.7.1 · 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.7.0 — type declarations
+ * Lattice Grid 1.8.0 — type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -1389,15 +1389,31 @@ export interface StateApplyReport {
 // ---------------------------------------------------------------------------
 
 export interface FormattingCondition {
-  op: Operator;
+  /**
+   * A filter operator compared against `value`, or a distribution operator
+   * whose threshold comes from the column itself — `{op: 'topPercent', value: 10}`,
+   * `{op: 'outlier'}`. Distribution thresholds are pinned when the rules
+   * compile; `grid.formatting.restat()` moves them.
+   */
+  op: Operator | DistributionOp;
   value?: unknown;
   value2?: unknown;
 }
 
 export interface FormattingScale {
-  min: number;
-  max: number;
+  /**
+   * Where the bounds come from when `min` and `max` are not given.
+   * `'minmax'` spans the data, `'quantile'` spans `low` to `high`
+   * (5th to 95th percentile by default), `'stddev'` spans `deviations`
+   * either side of the mean.
+   */
+  from?: 'minmax' | 'quantile' | 'stddev';
+  min?: number;
+  max?: number;
   mid?: number;
+  low?: number;
+  high?: number;
+  deviations?: number;
   colours?: string[];
 }
 
@@ -1421,6 +1437,58 @@ export interface FormattingRule {
 /** A column id, or `'*'` for every column. */
 export type FormattingScope = string;
 
+export interface StatisticsApi {
+  /** One shadow value for one row, by the column it shadows and the kind. */
+  shadow(colId: string, kind: ShadowKind, rowKey: string): unknown;
+  /** Make the current values the new baseline — "mark all". */
+  rebase(colId?: string): void;
+  /** What the shadow histories are costing. */
+  tracking(): { columns: string[]; rows: number; forgotten: number };
+  /** Reduce a column by a named kernel over the filtered rows. */
+  reduce(colId: string, fn: string): unknown;
+  /** Everything worth knowing about one column, in one pass each. */
+  profile(colId: string): ColumnProfile | null;
+  /** Pearson's correlation between two columns. */
+  correlation(a: string, b: string): number | null;
+  /** A weighted average of one column by another. */
+  weightedAverage(colId: string, weightId: string): number | null;
+  /** The key a row's data resolves to. */
+  keyOf(data: unknown): string | null;
+  /** Which reductions can be maintained against a change, and which rescan. */
+  readonly maintenance: Readonly<Record<string, 'maintained' | 'rescan'>>;
+}
+
+export type ShadowKind =
+  | 'updates' | 'updatedAt' | 'sinceUpdate' | 'delta' | 'deltaPercent'
+  | 'rate' | 'history' | 'firstValue' | 'streak'
+  /** Where the row sits among the others, over every tracked row. */
+  | 'rank' | 'rankAsc' | 'rankChange' | 'percentile' | 'quartile'
+  | 'zScore' | 'shareOfTotal';
+
+export interface ColumnProfile {
+  column: string;
+  rows: number;
+  present: number;
+  missing: number;
+  distinct: number;
+  min: number | null;
+  max: number | null;
+  mean: number | null;
+  median: number | null;
+  q1: number | null;
+  q3: number | null;
+  iqr: number | null;
+  stddev: number | null;
+  outliers: number;
+  histogram: HistogramBin[];
+}
+
+export interface HistogramBin {
+  from: number;
+  to: number;
+  count: number;
+}
+
 export interface FormattingApi {
   list(scope?: FormattingScope): FormattingRule[];
   all(): Record<FormattingScope, FormattingRule[]>;
@@ -1433,6 +1501,29 @@ export interface FormattingApi {
   replaceAll(rules: Record<FormattingScope, FormattingRule[]>): void;
   clear(scope?: FormattingScope): void;
   styleFor(colId: string, value: unknown): CellStyle | null;
+  /** Re-derive the thresholds of distribution rules from the data as it stands. */
+  restat(): void;
+  /** The five numbers a distribution rule resolves against for one column. */
+  distribution(colId: string): ColumnDistribution | null;
+}
+
+/** Operators that resolve against the column's own distribution (spec 8.12). */
+export type DistributionOp =
+  | 'topPercent' | 'bottomPercent' | 'topN' | 'bottomN'
+  | 'aboveMean' | 'belowMean' | 'aboveMedian' | 'belowMedian'
+  | 'zAbove' | 'zBelow' | 'outlier';
+
+export interface ColumnDistribution {
+  n: number;
+  min: number;
+  max: number;
+  mean: number;
+  stddev: number;
+  median: number;
+  q1: number;
+  q3: number;
+  iqr: number;
+  sorted: number[];
 }
 
 // ---------------------------------------------------------------------------
@@ -2430,6 +2521,7 @@ export interface Grid {
   readonly comments: CommentsApi;
   readonly presence: PresenceApi;
   readonly diagnostics: DiagnosticsApi;
+  readonly statistics: StatisticsApi;
   readonly formatting: FormattingApi;
   readonly maximise?: MaximiseApi;
   /**