@toclocoinc/lattice-grid 1.15.0 → 1.16.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.16.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
@@ -2474,6 +2598,37 @@ 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.</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,
+  ingest: { retainSource: <span class="kw">false</span> },
+});</code></pre>
+    </div>
+    <div class="why">
+      <p>The saving is the store's own copy of the object references, not the objects
+      themselves: whoever handed the grid its rows still owns them. The footprint drops
+      materially only when the grid becomes the sole holder of the data. Reach for this when
+      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: {
@@ -4490,6 +4645,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 +5191,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 +5714,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>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.15.0, type declarations
+ * Lattice Grid 1.16.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -341,6 +341,22 @@ export interface LookupSpec {
 export type DecorationName = 'plain' | 'fill' | 'pill' | 'dot' | 'bar' | 'heat' | 'icon';
 export type VariantName = 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'accent' | 'none' | (string & {});
 
+/** A built-in threshold icon set, mapping value bands to built-in glyphs. */
+export type IconSetName = 'trafficLights' | 'arrows' | 'trafficArrows' | 'ratings' | (string & {});
+
+/**
+ * One band of a threshold icon set. A value clears a band when it is at least
+ * `min`; the highest band it clears wins. Omit `min` on the last band to make
+ * it the catch-all. `label` is what assistive technology announces for the
+ * glyph, so a screen-reader user hears the band's meaning, not only the value.
+ */
+export interface IconBand {
+  min?: number;
+  icon: string;
+  label?: string;
+  variant?: VariantName;
+}
+
 export interface DecorationSpec {
   type: DecorationName;
   size?: 'sm' | 'md' | 'lg';
@@ -349,6 +365,10 @@ export interface DecorationSpec {
   edge?: boolean;
   position?: 'start' | 'end';
   name?: string | Record<string, string>;
+  /** icon only: a built-in threshold icon set, expanded to `bands`. */
+  iconSet?: IconSetName;
+  /** icon only: value bands mapped to glyphs, first match by descending `min`. */
+  bands?: IconBand[];
   min?: number;
   max?: number;
   origin?: number;
@@ -738,6 +758,59 @@ export interface Source {
 
 export interface MemorySourceConfig { mode: 'memory'; columnarBelow?: number }
 
+/**
+ * How rows are ingested into the column store.
+ */
+export interface IngestConfig {
+  /**
+   * Retain the caller's row objects by reference so identity round-trips.
+   * Default `true`, the historical behaviour: `rows.data()` returns the exact
+   * objects you supplied, `row === sourceObject` holds, and a custom renderer
+   * reading `row.sourceObject` works.
+   *
+   * Set `false` to keep only the packed columns and reconstruct a plain row
+   * object from them on demand. This drops roughly half the resident footprint,
+   * but changes three behaviours: `rows.data()` returns freshly reconstructed
+   * objects (new object each call, so `row === sourceObject` no longer holds),
+   * a custom renderer that reaches for `row.sourceObject` gets a reconstruction
+   * rather than the original, and equality against a row becomes value-based.
+   * The stored values are unchanged, so `get()`, `byKey()`, `value()` and
+   * `values()` are unaffected.
+   */
+  retainSource?: boolean;
+
+  /**
+   * Columnize `stream`-source ingest on a Worker so a large load does not block
+   * the main thread. Default `false`. When on, an arriving chunk that clears
+   * {@link IngestConfig.workerThreshold} is packed into typed column buffers on
+   * the Worker; the main thread merges the finished buffers into the store and
+   * renders, without running the per-field extraction pass that otherwise
+   * dominates ingest.
+   *
+   * This makes **stream** ingest non-blocking (remote sources already are).
+   * Memory and paged sources cannot be made non-blocking this way — the main
+   * thread must read the caller's own row objects — and are unaffected. The
+   * effect composes with `retainSource: false`: with it off the source keeps no
+   * caller-object array on the main thread at all, so the load is both
+   * non-blocking and lighter on memory.
+   *
+   * A column that reads through a closure — a `date` column's storage
+   * conversion, or a computed column — cannot cross the Worker boundary, so a
+   * grid with any such column columnizes on the main thread and says so once.
+   * Falls back silently to the main thread wherever a Worker cannot be created.
+   */
+  useWorker?: boolean;
+
+  /**
+   * Row count in a single stream chunk at or above which columnization is
+   * offloaded to the Worker when {@link IngestConfig.useWorker} is on. Default
+   * `10000`. A smaller first chunk is packed on the main thread, where the
+   * cost is trivial and the postMessage round trip would only add latency to
+   * time-to-first-row.
+   */
+  workerThreshold?: number;
+}
+
 export interface PagedSourceConfig {
   mode: 'paged';
   pageSize?: number;
@@ -968,6 +1041,15 @@ export interface EditConfig {
   commit?: (write: PendingWrite) => unknown;
   confirm?: 'auto' | 'manual';
   pendingTimeout?: number;
+  /**
+   * Show a preview of what a bulk paste will change before it commits (§12),
+   * with confirm/cancel. Off by default: a paste commits straight away, exactly
+   * as it always has. When on, a paste into more than one cell first opens a
+   * dialog listing every cell that changes (old → new) and every cell that would
+   * be rejected (permission, data-type, read-only); confirm commits precisely
+   * that set through the ordinary edit path, cancel commits nothing.
+   */
+  pastePreview?: boolean;
 }
 
 export interface PendingWrite {
@@ -1010,6 +1092,8 @@ export interface GridConfig {
   rowKey?: string | ((row: unknown) => string);
   /** Where rows come from: memory, paged, remote, stream or derived. */
   source?: SourceConfig;
+  /** How rows are ingested into the column store. */
+  ingest?: IngestConfig;
   /** Applied to every column before its own settings. */
   columnDefaults?: Column;
   /** Named bundles of column settings, referenced by a column's `preset`. */
@@ -1374,6 +1458,14 @@ export interface GridConfig {
   totalOnlyChangedColumns?: boolean;
   /** Put the total in the header rather than a footer row. */
   showTotalInHeader?: boolean;
+  /**
+   * Let the user pick a column's reduction from the column menu. On, the
+   * totalling entry becomes an "Aggregate" submenu offering the aggregates the
+   * column's type says are meaningful (§9.4); off, the menu keeps its plain
+   * "Total this column" toggle. Off by default, so an existing grid is
+   * unchanged.
+   */
+  aggregateChooser?: boolean;
   /** Render only the visible columns once there are more than this many. */
   columnVirtualisationAbove?: number;
   /** The bar beneath the grid, and which panels it carries. */
@@ -1391,6 +1483,23 @@ export interface GridConfig {
    */
   columnMenu?: boolean | ((p: ColumnMenuParams, defaults: MenuItem[]) => MenuItem[] | void);
 
+  /**
+   * Chart a selected cell range — the spreadsheet "chart this selection"
+   * gesture. Off by default, so a grid opts in.
+   *
+   * The DOM layer draws no charts itself — the charts module is optional and
+   * loaded by the host — so this is where the host wires the two together: a
+   * function, or an object carrying `onChart`, is called with the grid and the
+   * selected range when the reader chooses "Chart selection" from the cell
+   * menu. The handler typically calls `chartRange` from
+   * `lattice-grid/modules/charts`. `true` offers the item and emits nothing
+   * extra; supply a handler to have it actually draw.
+   */
+  rangeChart?:
+    | boolean
+    | ((grid: Grid, range: CellRange) => void)
+    | { onChart?: (grid: Grid, range: CellRange) => void };
+
   /**
    * The `?` keyboard shortcut overlay. `false` suppresses it, for a host
    * that wants `?` for itself. Default true.
@@ -1503,6 +1612,22 @@ export interface GridConfig {
     /** File name for the export action, without the extension. */
     exportName?: string;
   };
+  /**
+   * A drag-and-drop group-by strip above the column header — the pattern AG
+   * Grid calls the row-group panel. Drag a column heading into it to group by
+   * that column; the active groups show as removable, reorderable chips, and
+   * reordering the chips changes the nesting order. It is keyboard-operable
+   * (arrows navigate, Shift+arrow reorders, Delete ungroups, and an add control
+   * groups any column), and every change is announced through the live region,
+   * which is why it also addresses the drag-only complaint of BACKLOG-0000429.
+   *
+   * Off by default and non-breaking, matching `toolPanel`. It drives the same
+   * grouping model as `grid.columns.group()`; it reimplements nothing.
+   */
+  groupPanel?: boolean | {
+    /** Placeholder shown while nothing is grouped. */
+    hint?: string;
+  };
   /** The quick filter's initial text. */
   quickFilterText?: string;
   /**
@@ -2164,6 +2289,11 @@ export interface RowsApi {
 export interface ColumnsApi {
   /** Set or clear a column's totals-row reduction. */
   setTotal(id: string, fn: TotalName | TotalFn | null): void;
+  /**
+   * The aggregate names meaningful for a column, honouring its type's
+   * `totals.supported` declaration (§9.4). What the aggregate chooser offers.
+   */
+  aggregates(id: string): TotalName[];
   /** Every distinct value in a column, from the dictionary where there is one. */
   distinct(id: string): unknown[];
   get(id: string): ResolvedColumn | undefined;
@@ -2186,6 +2316,13 @@ export interface ColumnsApi {
   move(id: string, to: number): void;
   pin(id: string, side: 'start' | 'end' | null): void;
   resize(id: string, px: number): void;
+  /**
+   * Set, change or clear a column's decoration at runtime (§8.7). Pass `null` to
+   * clear it back to plain text. Presentation config: it is not on the undo
+   * timeline and is not carried in a saved view — use `grid.formatting` for
+   * durable, view-persisted conditional styling.
+   */
+  decorate(id: string, decoration: DecorationName | DecorationSpec | null, opts?: { variant?: VariantSpec }): void;
   autoSize(ids?: string | string[]): void;
   fit(): void;
   group(ids: string | string[]): void;
@@ -2269,6 +2406,18 @@ export interface EditApi {
   redo(): void;
   setCells(writes: { key: string; colId: string; value: unknown }[], type?: 'cell' | 'fill' | 'paste'): number;
   pasteInto(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): number;
+  /** Whether a bulk paste is previewed before it commits (`edit.pastePreview`, §12). */
+  readonly pastePreview: boolean;
+  /**
+   * Compute what a paste would change, without committing (§12). The engine
+   * behind `edit.pastePreview`: `changes` are the accepted writes with their old
+   * and new values (and whether each actually differs), `rejected` are the cells
+   * a commit would refuse, each with a reason.
+   */
+  previewPaste(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): {
+    changes: { key: string; colId: string; oldValue: unknown; newValue: unknown; changed: boolean }[];
+    rejected: { key: string; colId: string; value: unknown; reason: 'permission' | 'readOnly' | 'validation' | 'locked' | 'missing' }[];
+  };
   settle(id: string, ok: boolean, reason?: string): boolean;
   pending(): OpenWrite[];
   status(key: string, colId: string): 'pending' | null;
@@ -3623,6 +3772,12 @@ export interface ChartSpec {
   y?: string;
   /** Splits the measure into one series per distinct value. */
   series?: string;
+  /**
+   * The exact rows to chart, overriding the grid's own walk — an array, or a
+   * function returning one at draw time. `chartRange` uses it to bind a chart
+   * to the band of rows a selected range covers rather than the whole grid.
+   */
+  rows?: object[] | ((grid: Grid) => object[]);
   /** Several measures at once, for combo and candlestick. */
   measures?: ChartMeasure[];
   /** Endpoints, for sankey, chord and network. */
@@ -3753,6 +3908,39 @@ declare module 'lattice-grid/modules/charts' {
   export const SCHEMES: Readonly<Record<string, readonly string[]>>;
   export const PALETTE: readonly string[];
   export function createChart(spec: ChartSpec): Chart;
+  /**
+   * Chart a selected cell range. Derives the chart from the range's shape — a
+   * leading text column becomes the categories, the numeric columns become the
+   * measures — and returns the live chart, or null when the range has nothing
+   * to measure. Respects hidden and unreadable columns. The type is a sensible
+   * default the caller can change with `chart.update({ type })`.
+   */
+  export function chartRange(
+    grid: Grid,
+    opts: {
+      container: Element | string;
+      range?: CellRange;
+      type?: ChartType;
+    } & Partial<ChartSpec>,
+  ): Chart | null;
+  /** Would {@link chartRange} draw something for the grid's current selection? */
+  export function canChartRange(grid: Grid, opts?: { range?: CellRange }): boolean;
+  /**
+   * Decide what a chart of a range should be, without drawing it: the type, the
+   * category column, the measure columns, and a `spec` ready for `createChart`
+   * — or a `reason` naming why the range cannot be charted.
+   */
+  export function deriveRangeSpec(
+    grid: Grid,
+    opts?: { range?: CellRange; type?: ChartType },
+  ): {
+    spec: ChartSpec | null;
+    type: ChartType | null;
+    x: string | null;
+    measures: string[];
+    columns: string[];
+    reason: string | null;
+  };
   export function registerScheme(name: string, colours: readonly string[]): void;
   export function resolveScheme(spec?: object): object;
   export function schemeNames(): string[];