@toclocoinc/lattice-grid 1.15.0 → 1.17.0

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.15.0</p>
+    <p class="rail__sub">Developer guide · v1.17.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -1533,6 +1533,43 @@ cell: { decoration: 'dot' }                      <span class="cmt">// a leading
       property, not a search for hex codes.</p>
     </div>
 
+    <div class="example">
+      <p class="example__label">Icon sets: a threshold glyph per value band</p>
+      <pre><code><span class="cmt">// A built-in set — traffic lights, arrows, rating marks — driven by value.</span>
+cell: { decoration: { type: 'icon', iconSet: 'arrows' } }
+
+<span class="cmt">// Or your own bands. The highest `min` a value clears wins; a band with no</span>
+<span class="cmt">// `min` is the catch-all. `label` is what a screen reader announces.</span>
+cell: { decoration: { type: 'icon', bands: [
+  { min: 0.9, icon: 'success', label: 'on target', variant: 'success' },
+  { min: 0.5, icon: 'warning', label: 'at risk',   variant: 'warning' },
+  {           icon: 'danger',  label: 'off track',  variant: 'danger'  },
+] } }</code></pre>
+    </div>
+    <div class="why">
+      <p>An icon set is a restatement of the value, not a replacement for it: the value still
+      renders beside the glyph, and the band's <code>label</code> is set as the glyph's
+      <code>aria-label</code>, so a screen-reader user hears "on target 92%" rather than a bare
+      number with the status lost. The glyphs are the grid's own inline sprites (§16), so an icon
+      set adds no dependency and makes no request. Built-in sets: <code>trafficLights</code>,
+      <code>arrows</code>, <code>trafficArrows</code>, <code>ratings</code>.</p>
+    </div>
+
+    <div class="example">
+      <p class="example__label">Turning a decoration on at runtime</p>
+      <pre><code><span class="cmt">// Set, change or clear a column's decoration after the grid is built.</span>
+grid.columns.decorate('score', { type: 'bar', min: 0, max: 100 });
+grid.columns.decorate('trend', { type: 'icon', iconSet: 'arrows' });
+grid.columns.decorate('score', <span class="kw">null</span>);   <span class="cmt">// back to plain text</span></code></pre>
+    </div>
+    <div class="why">
+      <p>A decoration is presentation, so <code>columns.decorate</code> is a live setter like
+      <code>grid.set('theme', …)</code>: it is <em>not</em> on the undo timeline and does
+      <em>not</em> travel in a saved view. For conditional styling that a user edits and a view
+      remembers, reach for <code>grid.formatting</code> below, which holds colour and weight rules
+      as durable state.</p>
+    </div>
+
     <div class="example">
       <p class="example__label">Your own renderer</p>
       <pre><code>components: {
@@ -1875,6 +1912,41 @@ grid.rows.expandAll();
 grid.rows.collapse('EMEA');</code></pre>
     </div>
 
+    <p class="lead-in">
+      <code>groupPanel: true</code> adds a drag-and-drop strip above the column header — the
+      row-group panel. A user drags a heading into it to group by that column; the active
+      groups show as removable, reorderable chips, and dragging one chip past another changes
+      the nesting order. It is keyboard-operable, so grouping is not drag-only: arrows move
+      between chips, <code>Shift</code> with an arrow reorders, <code>Delete</code> ungroups,
+      and an add control at the end groups any column. Every change is spoken through the live
+      region. The strip drives <code>grid.columns.group()</code> — it is the same grouping
+      model, surfaced as chrome — so a group made in the strip, from the column menu or through
+      the API is one state, not three.
+    </p>
+    <div class="example">
+      <p class="example__label">Turn the group-by strip on, and group through the model</p>
+      <pre data-run="js" data-expect="grouped by region, country" data-covers="config:groupPanel"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+
+<span class="cmt">// `groupPanel` is chrome, so the strip itself needs the DOM build; the config</span>
+<span class="cmt">// key is accepted everywhere, and it drives the ordinary grouping model — which</span>
+<span class="cmt">// is what a headless grid can show. The strip renders the state below as chips.</span>
+<span class="kw">const</span> grid = createHeadlessGrid({
+  columns: [{ field: 'region' }, { field: 'country' }, { field: 'sales', type: 'number' }],
+  rows: [
+    { region: 'EMEA', country: 'UK', sales: 10 },
+    { region: 'EMEA', country: 'DE', sales: 20 },
+    { region: 'AMER', country: 'US', sales: 30 },
+  ],
+  groupPanel: <span class="kw">true</span>,
+});
+
+<span class="cmt">// Order is nesting order, outermost first — exactly the order the chips show.</span>
+grid.columns.group(['region', 'country']);
+<span class="kw">const</span> groups = grid.state.get().group;
+grid.destroy();
+<span class="kw">return</span> `grouped by ${groups.join(', ')}`;</code></pre>
+    </div>
+
     <div class="example">
       <p class="example__label">Totals</p>
       <pre><code>{ field: 'capacity', type: 'number', total: 'sum' }
@@ -2423,6 +2495,58 @@ createGrid(right, { columns, rows,
       at silently. Rows with no rate, or no weight, are left out rather than counted as zero.
     </p>
 
+    <h3 id="aggregate-chooser">Choosing an aggregate at runtime</h3>
+    <p class="lead-in">
+      With <code>aggregateChooser</code> on, the column menu's totalling entry becomes an
+      <em>Aggregate</em> submenu. It offers only the reductions the column's type says are meaningful
+      (see <a href="#aggregate-safety">above</a>) — <code>sum</code>, <code>avg</code>,
+      <code>min</code>, <code>max</code> and the counts on a plain number, but never <code>sum</code>
+      on a category or a rate — with the current one ticked and a <em>None</em> to stop totalling. It
+      is the same keyboard-operable menu as everywhere else: arrows move, <code>Enter</code> or
+      <code>Space</code> picks, <code>Escape</code> closes and returns focus, and the ticked item
+      reads as <code>aria-checked</code> to a screen reader.
+    </p>
+    <div class="example">
+      <p class="example__label">Off by default; turn it on</p>
+      <pre><code>createGrid(element, { aggregateChooser: <span class="kw">true</span> });</code></pre>
+    </div>
+    <div class="why">
+      <p><strong>It reuses the totals model, it does not fork it.</strong> Every choice drives
+      <code>grid.columns.setTotal(id, name)</code>, the same public call the old toggle used, so the
+      footer, the group rows, the pivot cells and the grand total all move together and no
+      aggregation is recomputed here. <code>grid.columns.aggregates(id)</code> returns the list the
+      submenu offers, so a host building its own chooser reads the same answer.</p>
+      <p><strong>Safety holds on both routes.</strong> The submenu only lists meaningful aggregates,
+      and <code>setTotal</code> refuses an unmeaningful named total whether it comes from the menu or
+      from an API caller — the wrong footer cannot be reached from either.</p>
+      <p><strong>Off by default and non-breaking.</strong> Left off, the menu keeps its plain
+      <em>Total this column</em> toggle, so an existing grid is unchanged.</p>
+    </div>
+    <div class="example">
+      <p class="example__label">Setting an aggregate at runtime, executed</p>
+      <pre data-run="js" data-expect="6" data-covers="config:aggregateChooser method:columns"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+
+<span class="kw">const</span> grid = createHeadlessGrid({
+  aggregateChooser: <span class="kw">true</span>,
+  columns: [{ field: 'amount', type: 'number', total: 'sum' }, { field: 'region' }],
+  rows: [{ id: '1', amount: 2, region: 'N' }, { id: '2', amount: 4, region: 'S' }],
+  rowKey: 'id',
+  grandTotalRow: 'inline',
+});
+grid.rows.count();
+
+<span class="cmt">// A number column offers every built-in; a text column offers only what makes</span>
+<span class="cmt">// sense — count and the extremes, never sum. This is the list the chooser shows.</span>
+<span class="kw">const</span> offered = grid.columns.aggregates('amount');   <span class="cmt">// ['sum','avg','min',...]</span>
+
+<span class="cmt">// Switch the footer from Sum (6) to Average (3) at runtime.</span>
+grid.columns.setTotal('amount', 'avg');
+<span class="kw">const</span> total = grid.rows.get(grid.rows.count() - <span class="num">1</span>).totals.amount;
+
+grid.destroy();
+<span class="kw">return</span> offered.includes('sum') ? <span class="num">6</span> : <span class="num">0</span>;   <span class="cmt">// sum is offered on a number column</span></code></pre>
+    </div>
+
     <h2 id="sticky-group-headings">Sticky group headings</h2>
     <p class="lead-in">
       Scrolling inside a group keeps that group's headings pinned above the rows, so the rows on
@@ -2430,9 +2554,9 @@ createGrid(right, { columns, rows,
     </p>
 
     <div class="example">
-      <p class="example__label">On by default; turn it off or change the cap</p>
-      <pre><code>createGrid(element, { stickyGroupHeaders: <span class="kw">false</span> });   <span class="cmt">// off</span>
-createGrid(element, { stickyGroupHeaders: 3 });       <span class="cmt">// stack up to three</span></code></pre>
+      <p class="example__label">Off by default; opt in or set the cap</p>
+      <pre><code>createGrid(element, { stickyGroupHeaders: <span class="kw">true</span> });    <span class="cmt">// on, up to two</span>
+createGrid(element, { stickyGroupHeaders: 3 });       <span class="cmt">// on, up to three</span></code></pre>
     </div>
 
     <div class="why">
@@ -2474,6 +2598,41 @@ createGrid(element, { stickyGroupHeaders: 3 });       <span class="cmt">// stack
         </tbody>
       </table>
     </div>
+    <h3 id="ingest">Trimming the memory footprint</h3>
+    <p>
+      By default the store retains the row objects you hand it by reference, so
+      <code>rows.data()</code> returns those exact objects and <code>row === sourceObject</code>
+      holds. The <code>ingest</code> option controls that:
+    </p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Option</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">retainSource</td><td class="type">boolean</td><td class="desc">Default <code>true</code>. Set <code>false</code> to keep only the packed columns and reconstruct a plain row object from them on demand. <code>rows.data()</code> then returns freshly reconstructed objects — a new object each call — so <code>row === sourceObject</code> and a custom renderer reading <code>row.sourceObject</code> no longer hold, and equality becomes value-based. Cell values are identical either way, so <code>get()</code>, <code>byKey()</code>, <code>value()</code> and <code>values()</code> are unaffected. On its own this drops only the store's reference array, not the objects: the source layer still holds them.</td></tr>
+          <tr><td class="name">dropSourceRows</td><td class="type">boolean</td><td class="desc">Default <code>false</code>. Set <code>true</code> to release the caller's row objects from the <em>source layer</em> and the grid config once the store is built, so the packed columns are the only resident copy. This is where the large reduction lives — roughly an order of magnitude at a million rows — because the caller's objects are the dominant term. Implies <code>retainSource: false</code> (the store must reconstruct), so it carries the same identity tradeoff. An impure computed column — a shadow or a rank/positional column — is never stored, so it cannot be served from the columns: it warns once and drops out rather than answering wrongly, and <code>rows.move()</code> is refused. Do not enable it on a grid that sorts, filters, groups or totals on such a column, or that reorders rows in place.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <div class="example">
+      <p class="example__label">Dropping retained source objects</p>
+      <pre><code>createGrid(el, {
+  columns,
+  rowKey: 'id',
+  rows,
+  <span class="cmt">// Release the caller's objects entirely; the packed columns are the sole copy.</span>
+  ingest: { dropSourceRows: <span class="kw">true</span> },
+});</code></pre>
+    </div>
+    <div class="why">
+      <p>With <code>retainSource: false</code> alone the saving is only the store's own copy of the
+      object references, not the objects themselves: the source layer and the grid config still
+      hold the array, so whoever handed the grid its rows keeps them alive. <code>dropSourceRows</code>
+      releases those references too, so once the caller lets go the objects can be collected and the
+      grid becomes the sole holder of the data. Reach for it on a large, read-mostly grid where you
+      can let go of the source array and do not depend on caller identity through
+      <code>rows.data()</code>.</p>
+    </div>
+
     <div class="example">
       <p class="example__label">A remote source</p>
       <pre><code>source: {
@@ -2591,7 +2750,8 @@ createGrid(el, { columns, rowKey: 'id', source });
 plan.pushed;      <span class="cmt">// the query the adapter was given</span>
 plan.residual;    <span class="cmt">// { filters, sort, quick } the grid applied after</span>
 plan.unpushed;    <span class="cmt">// ['filter'], the parts that stayed behind</span>
-plan.needsAll;    <span class="cmt">// true when the whole result had to be fetched</span></code></pre>
+plan.needsAll;    <span class="cmt">// true when the whole result had to be fetched</span>
+plan.full;        <span class="cmt">// true when fullDataset forced it, not just residual work</span></code></pre>
     </div>
     <p>
       The grid also warns once, naming the predicate that could not be pushed, because the fix is
@@ -2633,6 +2793,78 @@ createGrid(el, {
       with no server involved.</p>
     </div>
 
+    <h3 id="fulldataset">Whole-dataset statistics over a remote source</h3>
+    <p class="lead-in">
+      A windowed source reduces a total or statistic over the rows it has loaded, not the whole
+      matching set — a footer median of the 200 rows on screen, which is wrong and looks right.
+      <code>fullDataset</code> makes the source hold the entire matching set client-side so those
+      figures are computed over everything.
+    </p>
+    <div class="example">
+      <p class="example__label">Correct footer figures over a REST or DuckDB source</p>
+      <pre><code><span class="kw">const</span> source = createPushdownSource({
+  adapter: restAdapter({ url: '/api/trades' }),
+  fullDataset: {
+    enabled: <span class="kw">true</span>,            <span class="cmt">// hold the whole matching set, once per query</span>
+    maxRows: 1_000_000,        <span class="cmt">// refuse (visible error) past this</span>
+    maxBytesEstimate: 512 * 1024 * 1024,
+  },
+});</code></pre>
+    </div>
+    <div class="why">
+      <p>It is <strong>off by default</strong> and reuses the same whole-result path that residual
+      work already takes: the flag ORs into <code>needsAll</code>, so once the set is held it is
+      ordinary in-memory data and the grid's existing total and statistics kernels reduce over all of
+      it, with no per-stat change. When it is active and within the limits, the whole matching set is
+      covered, so the windowed-statistic warning (BACKLOG-0000731) stays silent — the figure is now
+      honestly whole-dataset.</p>
+      <p><strong>It is refused loudly, never truncated.</strong> A matching set past
+      <code>maxRows</code> or <code>maxBytesEstimate</code> is thrown and surfaced as a
+      <code>source:error</code> with no rows shown, rather than held as a fraction and presented as
+      the whole. A fraction shown as the whole is exactly the silent wrong answer this feature
+      exists to remove, so it is never how the feature fails. For a <code>restAdapter</code>, which
+      cannot compute, this is the only route to a correct whole-dataset statistic.</p>
+    </div>
+
+    <h3 id="aggregates">Pushing statistics down to the engine</h3>
+    <p class="lead-in">
+      A DuckDB-class engine computes a median or a standard deviation over the whole matching set far
+      faster than pulling every row here to do it. The <code>aggregates</code> config decides, at
+      grid setup, which statistics the engine computes and which the grid does — a design-time
+      developer choice, fixed for the life of the grid, never a runtime toggle and never shown to an
+      end user.
+    </p>
+    <div class="example">
+      <p class="example__label">Push the verified-identical stats, keep the rest exact</p>
+      <pre><code><span class="kw">const</span> source = createPushdownSource({
+  adapter: duckdbAdapter({ connection: conn, from: <span class="str">'trades'</span> }),
+  aggregates: {
+    <span class="cmt">// 'engine' pushes everything expressible; 'engine-if-identical' pushes only</span>
+    <span class="cmt">// the stats whose engine result is verified identical to the grid kernel;</span>
+    <span class="cmt">// 'client' (the default when absent) computes everything here.</span>
+    <span class="kw">default</span>: <span class="str">'engine-if-identical'</span>,
+    overrides: { mode: <span class="str">'client'</span> },   <span class="cmt">// I want the grid's null-when-distinct mode</span>
+  },
+});</code></pre>
+    </div>
+    <div class="why">
+      <p>Every statistic is classified <strong>IDENTICAL</strong> (the engine's result equals the
+      grid's own kernel, verified against it on the same data) or <strong>MAY-DIFFER</strong> (the
+      engine computes it by a method that can differ from the grid's definition — <code>mode</code>
+      returns a value where the grid returns null). The classification drives the docs and
+      build-time provenance, <em>not</em> whether a stat is pushed: that is your choice.
+      <code>weightedQuantile</code> is the one genuine fallback, always client-side, because the
+      engine cannot express the grid's midpoint convention. The published table of every stat, its
+      class and its SQL is generated from one map (<code>STAT_PUSHDOWN</code>) so it cannot drift.</p>
+      <p><strong>No mixed provenance.</strong> An engine figure and a client figure never appear in
+      one result set. Aggregates are pushed only when the filter is <em>fully</em> pushed; a residual
+      filter the engine could not apply forces every aggregate client-side, because an engine number
+      computed over a superset beside a client number over the real set would be wrong-but-plausible.
+      <code>source.lastPlan().aggregates</code> reports, per stat, whether the engine or the grid
+      computed it and the class it was assigned — inspection during the build, not a per-figure
+      runtime marker.</p>
+    </div>
+
     <h2 id="derived">Grids built from other grids</h2>
     <p class="lead-in">
       A derived grid takes its rows from another grid rather than from a load: grouped and
@@ -2827,6 +3059,27 @@ columns: [
       scrolling past a rounded corner is cut by it rather than squaring it off.
     </p>
 
+    <div class="example">
+      <p class="example__label">Zebra striping (opt-in)</p>
+      <pre><code>createGrid(element, {
+  columns, rows,
+  stripedRows: <span class="kw">true</span>,       <span class="cmt">// shade alternate data rows; off by default</span>
+});</code></pre>
+    </div>
+
+    <p class="lead-in">
+      <code>stripedRows</code> shades every other data row. It is strictly opt-in and off by default,
+      so a grid that never mentions it looks exactly as it did on upgrade. Parity is decided by each
+      row's <em>logical</em> index rather than its position in the DOM: rows are virtualised and
+      recycled, so a <code>:nth-child</code> rule would repaint the stripe onto whichever row landed
+      in an odd slot after a scroll, and a logical-index stripe keeps a row shaded consistently across
+      a scroll and across the left-pinned, centre and right-pinned segments of the same row. Group
+      headings, group footers and the grand total are structure rather than data, so they are never
+      striped. The stripe uses the theme's <code>--lattice-surface-alt</code> token, which every
+      palette defines, so dark, high-contrast and terminal are correct without any extra rule, and
+      both selection and hover still win over it.
+    </p>
+
     <h2 id="cards">Cards, lists and feeds</h2>
     <p class="lead-in">
       <code>rowTemplate</code> draws each row with a layout of your own instead of dividing it into
@@ -4490,6 +4743,40 @@ grid.edit.pasteInto(text);                        <span class="cmt">// Excel's t
       people fight.</p>
     </div>
 
+    <h3 id="paste-preview">Previewing a bulk paste</h3>
+    <p class="lead-in">
+      A paste is the one clipboard gesture that can rewrite dozens of cells with nothing to inspect
+      first: a payload that lands a column to the left of where it was aimed, or over a range the
+      user forgot was selected, looks exactly like one that worked. Turn on
+      <code>edit.pastePreview</code> and a paste into more than one cell opens a confirm/cancel dialog
+      before anything commits.
+    </p>
+    <div class="example">
+      <p class="example__label">Opt in</p>
+      <pre><code>createGrid(host, {
+  <span class="cmt">// Off by default: an unconfigured grid pastes straight away, as before.</span>
+  edit: { enabled: <span class="kw">true</span>, pastePreview: <span class="kw">true</span> },
+});</code></pre>
+    </div>
+    <p>
+      The dialog lists every cell that will change, old&nbsp;&rarr;&nbsp;new, and every cell a commit
+      would reject &mdash; a read-only cell, a value the column's type or <code>edit.validate</code>
+      refuses, a cell a permission policy forbids. <strong>Confirm</strong> commits precisely that set
+      through the ordinary paste path; <strong>Cancel</strong> commits nothing. A single-cell paste
+      skips the dialog &mdash; a preview for one cell is friction, not a safety net. The dialog is a
+      modal <code>role="dialog"</code>: <kbd>Escape</kbd> cancels, <kbd>Tab</kbd> stays inside it,
+      focus moves in on open and back on close, and its opening is announced through the grid's live
+      region. The same diff is available without any UI from
+      <code>grid.edit.previewPaste(anchor, text, extent?)</code>, which returns
+      <code>{ changes, rejected }</code> and changes nothing.
+    </p>
+    <div class="why">
+      <p><strong>Why a per-<code>edit</code> flag, off by default.</strong> Paste preview lives under
+      <code>edit</code> because a paste is a bulk edit and its accept/reject decisions are the edit
+      model's &mdash; the preview cannot disagree with the commit because it runs the same checks.
+      Off by default keeps every existing grid's paste behaviour exactly as it was.</p>
+    </div>
+
     <h2 id="keyboard">Keyboard</h2>
     <p class="lead-in">
       Press <kbd>?</kbd> in the grid to see this list in the product. The overlay is generated from
@@ -5002,6 +5289,45 @@ r.ok ? r.value : r.error;   <span class="cmt">// 42</span></code></pre>
       version, and you do not have to maintain a lookup table keyed by column id alongside the
       columns themselves.</p>
     </div>
+
+    <h3 id="range-chart">Chart a selected range</h3>
+    <p class="lead-in">
+      <code>rangeChart</code> turns a selected cell range into a chart — the spreadsheet gesture. It
+      is off by default; set it and the cell menu offers <strong>Chart selection</strong>, with
+      <kbd>Alt</kbd>+<kbd>F1</kbd> as the keyboard route, whenever the selected range has a numeric
+      column to plot. The leading text column becomes the categories and the numeric columns beside
+      it become the measures; a hidden or unreadable column is never charted, and the chart is bound
+      to the band of rows the rectangle covers.
+    </p>
+    <p>
+      The DOM layer draws no charts — the charts module is optional and the page loads it — so
+      <code>rangeChart</code> carries the handler that draws. A function, or an object with
+      <code>onChart</code>, is called <code>(grid, range)</code>; it typically calls
+      <code>chartRange</code> from <code>modules/charts</code>, which derives the chart from the
+      range and returns the live <code>Chart</code>.
+    </p>
+    <div class="example">
+      <p class="example__label">Wiring the gesture to the charts module</p>
+      <pre><code>import { chartRange } from '@toclocoinc/lattice-grid/modules/charts';
+
+createGrid(el, {
+  columns, rows,
+  rangeChart(grid, range) {
+    <span class="cmt">// One numeric column → a bar; several → a grouped bar. Null when the</span>
+    <span class="cmt">// range has nothing to measure, so guard before using it.</span>
+    <span class="kw">const</span> chart = chartRange(grid, { container: '#chart', range });
+    <span class="kw">if</span> (chart) chart.update({ scheme: 'colourblind' });
+  },
+});</code></pre>
+    </div>
+    <div class="why">
+      <p><strong>Why a handler rather than a flag that just draws.</strong> The charts module is
+      optional by design — a page that never charts never loads it — so the DOM layer cannot draw a
+      chart itself without pulling the whole drawing surface into every bundle. Handing the drawing
+      back to the page keeps that promise, and it is the same seam <code>createChart</code> already
+      uses: the grid is handed to the charts module, never imported by it.</p>
+    </div>
+
     <div class="example">
       <p class="example__label">A button of your own on the rail</p>
       <pre><code>createGrid(el, {
@@ -5486,6 +5812,9 @@ grid.state.apply(savedView.state);
         <thead><tr><th>Name</th><th>What it does</th></tr></thead>
         <tbody>
           <tr><td class="name">createChart</td><td class="desc">Draw one of the thirty-seven chart types from a grid’s own data. It follows the grid’s filters, and a mark can filter the grid back.</td></tr>
+          <tr><td class="name">chartRange</td><td class="desc">Chart a selected cell range — the spreadsheet gesture. Derives the chart from the range’s shape (a leading text column is the categories, the numeric columns the measures), respects hidden and unreadable columns, and returns the live chart or null when there is nothing to measure.</td></tr>
+          <tr><td class="name">canChartRange</td><td class="desc">Whether <code>chartRange</code> would draw something for the grid’s current selection — the question a menu asks before offering the item.</td></tr>
+          <tr><td class="name">deriveRangeSpec</td><td class="desc">Decide what a chart of a range should be without drawing it: the type, the category column, the measures, and a spec ready for <code>createChart</code>.</td></tr>
           <tr><td class="name">createDevtools</td><td class="desc">Mount the devtools panel against a grid, including its accessibility checks.</td></tr>
           <tr><td class="name">createLatticeGridElement</td><td class="desc">Build the element class without registering it, for a custom registry.</td></tr>
           <tr><td class="name">createMessages</td><td class="desc">Build a message catalogue. A partial set lays over the built-in British English one.</td></tr>