flexdesk 0.16.0 → 0.17.0

package/src/ui/components/data_table.js

@@ -8,6 +8,7 @@
  * - Context menu (copy as TSV/CSV)
  * - Column sorting (internal or external via callback)
  * - Column drag-to-resize, and double-click-to-auto-size on the same grip
+ * - Column drag-to-reorder (`reorderable`, `columnOrder`; column_order.js)
  * - Per-column filtering (numeric operators, text substring)
  * - Column type detection (numeric/text alignment)
  * - Header icons
@@ -25,6 +26,11 @@ import {
 } from './table_values.js';
 import { isRowActivation, isRowControl } from './row_activation.js';
 import { createChipsFilter } from './table_filter_chips.js';
+import { CellGrid } from './cell_grid.js';
+import { ColumnReorder, cellOrder, isColumnOrder, moveInOrder, naturalOrder } from './column_order.js';
+import { ColumnGroups } from './column_groups.js';
+import { Crosstab } from './crosstab.js';
+import { STRUCTURE_OPTIONS, TableStructure } from './table_structure.js';
 
 // 0.7.0: the built-in chips filter control, for a consumer that wants to build
 // one outside a table (the same control `filterKinds: {kind: 'chips'}` draws).
@@ -401,8 +407,42 @@ const AUTOSIZE_MAX_PX = 520;
  * @property {boolean} [selectToggle=false] - STORY-0016. The table offers a SELECT MODE: a narrow leading column whose header holds a toggle button. While the mode is on, every row shows a checkbox there and the header a select-all box; a plain click (or Space) ticks or unticks one row, Shift-click adds the range from the last row ticked, and no gesture opens a row (`onRowActivate` is not called; `onRowClick` still is — a consumer that opens rows from it asks `isSelectMode()`). The arrows move a cursor without changing what is ticked. A right-click keeps the ticks. Escape clears the ticks, then leaves the mode. Needs a multi-row `selectable` (ignored, with a warning, on `false` or 'single'). The column is not resizable, is no data column (not in a copy, a CSV, `ctx.colIdx` or `hiddenColumns`), and remembered widths stay on their columns.
  * @property {boolean} [selectMode=false] - STORY-0016. Start in select mode. Draws the select column even without `selectToggle` (then there is no toggle: the consumer turns the mode off with `setSelectMode(false)`).
  * @property {Function} [onSelectModeChange] - STORY-0016. `(on) => void`, after every change of the mode (the toggle, Escape, `setSelectMode`).
- * @property {Function} [onColumnsChange] - STORY-0012. `(hidden) => void` with the hidden columns' indices, ascending, after every change of the set (the chooser, `setColumnVisible`, `setData({hiddenColumns})`).
+ * @property {Function} [onColumnsChange] - STORY-0012. `(hidden, {hidden, order}) => void` with the hidden columns' indices, ascending, after every change of the set (the chooser, `setColumnVisible`, `setData({hiddenColumns})`) — and (STORY-0086) of the order (a drag, `moveColumn`, `setData({columnOrder})`); `order` is `getColumnOrder()`.
+ * @property {boolean} [reorderable=false] - STORY-0086. Data columns can be dragged into a new order by their headers (a press on a resize grip resizes instead), and the header's right-click offers Move left / Move right. The row-number and select columns stay first: they do not move and nothing is dropped in front of them. The order is kept by data index, so `hiddenColumns`, the sort and the filters stay on their columns; copies and the CSV follow the order shown. With `persistKey` it is saved, and a saved order wins over `columnOrder` — unless it is no order of today's columns (another column count), when it is ignored and `columnOrder` is drawn, or the natural order when there is none. The same holds when the saved order arrives before the headers do.
+ * @property {number[]} [columnOrder] - STORY-0086. Every data index, in the order to draw them (`[0, 3, 1, 2]`). Not a permutation of the columns: ignored with a console warning, natural order (with no headers yet, checked and warned once when `setData` brings them). Works without `reorderable` (then only code moves columns). See `moveColumn`, `getColumnOrder`.
  * @property {boolean} [persistPage=false] - With `persistKey`: the client page is saved with the sort and the filters, and opened again on mount (on the last page, if the rows have shrunk since). OFF by default: a key shared by DIFFERENT row sets (ad-hoc filters, search results) must not reopen on a page of the last list. A sort under `resetPageOnSort` and a new filter save the first page, as they show it. A server's page (`onPageChange`, `dataSource`) is the consumer's and is not kept.
+ *
+ * ── STORY-0003, every one of them off unless asked for ─────────────────────
+ * @property {'rows'|'cells'} [selectionMode='rows'] - 'cells': CELL MODE (cell_grid.js, over cell_selection.js). A click selects one cell and puts the CURSOR on it, Shift+click selects the range from the anchor to it; every cell of the range is drawn `twm-dt-cell--selected` and the cursor `twm-dt-cell--cursor` (rows are not lit). On the focused table the arrows move the cursor (Shift extends), Ctrl+arrow jumps to the edge of the block of filled cells, Home/End go to the row's ends (Ctrl: the page's corners), Tab moves right and wraps to the next row (Shift+Tab back), Ctrl+A selects every cell of the page and Escape collapses the range onto the cursor. The cursor stays on the page drawn and is scrolled into view (under `virtualize` its row is drawn). `getSelection()` still answers ROWS — the original indices the range touches — and Ctrl+C copies those rows as before. A cell is `{row, col}`: `row` the position in the order shown (`getDisplayedRows()`), `col` the data column. Fixed for the table's life; `selectToggle`, `selectMode` and `keyboardNav` beside it are ignored with a console warning. See `getCellSelection`, `setCellSelection`.
+ * @property {boolean|number[]|Function} [editable=false] - Cell mode only (a warning, and ignored, without it). Which cells open an EDITOR: `true` every one, an array of data column indices, or `(colIdx, row, rowIdx) => boolean`. F2, Enter, a double-click or a printable key (which the editor starts with) opens it on the cursor cell; in it Enter commits and moves down, Tab commits and moves right, Escape restores the cell and calls nothing, and the focus leaving commits. While it is open a `render()` (a `setData` included) waits, and runs when it closes; its row leaving the virtual window commits it. An editor with no `getValue` (a factory's `{el}` around an element that is not an input, select or textarea) has no value to commit: Enter and Tab do nothing, the focus leaving does nothing, and its row leaving the window CANCELS it — it calls `commit(value)` itself.
+ * @property {Object} [editors] - `{[colIdx|type]: factory}`, the editor for a column (by index first, then by its type: `columnTypes`' or the detected 'num'/'text'). A factory is `({value, row, rowIdx, colIdx, column: {index, header, type}, initialText, commit(value), cancel()}) => Element | {el, getValue?, focus?, destroy?}`; an input, select or textarea returned as it is commits its `value`. Absent: a text box (cell_editor_host.js `createTextEditor`), which commits the value unchanged when left as it was.
+ * @property {Function} [onCellCommit] - `({rowIdx, colIdx, value, previous}) => void | {ok, error?} | Promise<…>`, once per commit (not for a value left as the cell showed it; `previous` is the value the row holds). Resolving `{ok: false, error}`, rejecting or throwing leaves the typed value in the cell drawn `twm-dt-cell--error` with the message as its `title` and `data-error`; until it settles the cell is `twm-dt-cell--pending`. Otherwise the value is written into the row the table holds for `rowIdx` when it settles (`rows[rowIdx][colIdx]`) and drawn. Committing a refused cell back to the row's value clears the mark without a call. New rows (`setData({rows})`) drop the marks.
+ * @property {Function} [onCellSelectionChange] - `(getCellSelection()) => void`, after every change of the cells selected.
+ * @property {Function} [headerMenu] - `(colIdx, {colIdx, header, hiddenColumns, table}) => items`, asked on a right-click on a data column's header (or its filter cell). The items (`{label, action, icon?, disabled?, danger?, title?}` or `{separator: true}`) open the table's menu; with `columnChooser` the chooser's items follow behind a separator. `[]` or `null` shows what would show without the hook: the chooser, or the page's own menu.
+ * @property {Function} [onHeaderMenuAction] - `(action, colIdx) => void`, when one of `headerMenu`'s items is chosen; the menu is hidden first.
+ *
+ * ── STORY-0088, off unless asked for ──────────────────────────────────────
+ * @property {boolean} [staged=false] - With `editable` (a warning, and ignored, without it): an editor's commit is STAGED instead of sent to `onCellCommit` (staged_edits.js). A staged cell shows its value drawn `twm-dt-cell--staged`; staging the value its row holds is no change. On the focused table Ctrl+Z takes the last staged edit back and Ctrl+Y (or Ctrl+Shift+Z) puts it back — a cell staged as `null` undoes to no change, not to a staged null. `commit()` sends every staged cell to `onCommit` at once; `discard()` drops them. While any cell is staged the sort, the filters and the pages are FROZEN: their controls are disabled with the reason on them (`data-refusal`, `title`), and `sortBy`, `setFilter`, `clearFilters`, `goToPage`, `goToRow` and the paging calls refuse with a console warning. New rows (`setData({rows})`) drop the staged cells and the ring.
+ * @property {number} [historyLimit=100] - With `staged`: the undo ring keeps this many entries — the limit counts entries, not cells; an entry is one cell's before/after change or one fill (a group of cell changes, undone together); the oldest fall off.
+ * @property {Function} [onCommit] - With `staged`: `({edits}) => void | {ok?, error?, errors?} | Promise<…>`, called once by `commit()` with every staged cell as `{rowIdx, colIdx, value, previous}` (by row, then column; `previous` is the value the row holds). Resolving `{errors: [{rowIdx, colIdx, error}]}` (non-empty) marks each of those cells `twm-dt-cell--error` with the message as its `title` and `data-error`, and every staged value stays; `{ok: false, error}`, a rejection or a throw marks every staged cell with the message. Anything else is success: the values are written into the rows the table holds, and the staged cells and the ring are cleared. While it is out no editor opens and Ctrl+Z, Ctrl+Y and `discard()` do nothing.
+ * @property {Function} [onStagedChange] - With `staged`: `({count, canUndo, canRedo, committing}) => void` after every change of the staged cells.
+ * @property {boolean} [fillHandle=false] - STORY-0089. With `staged` (a warning, and ignored, without it): a FILL HANDLE (fill_handle.js) on the bottom-right corner of the cell range (`.twm-dt-fill-handle`, in the corner cell). Dragging it up, down, left or right over the cells beyond the range previews them `twm-dt-cell--fill-preview` and, on release, stages their values as ONE undo entry: each column of the range (each row, filling sideways) is continued by `projectSeries` (series.js) — one cell repeats, numbers, dates and "Item 1"-style texts a constant step apart continue, anything else repeats in a cycle — and Ctrl (Cmd) held at release repeats the block instead. A target cell `editable` refuses is skipped and drawn `twm-dt-cell--fill-skipped` until the selection moves. The range then covers what was filled. Escape during the drag cancels it. See `fill`.
+ * @property {string|Function} [stagedRefusal] - With `staged`: the reason a frozen control carries, or `(count) => string`. Absent: "Sorting, filtering and paging are held while N changes are not committed. Commit or discard them first."
+ *
+ * ── STORY-0066, every one of them off unless asked for. THE CONSUMER OWNS THE DATA: each edit is a call, answered with `setData` ──
+ * @property {Array<{key: string|number, label?: string, columns: number[]}>} [columnGroups] - COLUMN GROUPS (column_groups.js). A second header row above the column headers: one cell per run of shown columns of a group, spanning them, and a blank cell over the row number / select column and over columns in no group. It is a table of its own in the header wrap (`table.twm-dt-groups`, cells `th.twm-dt-group`) that takes the header's column widths after every fit, auto-size and drag, and scrolls sideways with it. A column is in the first group that lists it. A group with NO columns keeps one PLACEHOLDER column (`th.twm-dt-col--placeholder`, `td.twm-dt-cell--placeholder` in every row), after the columns of the groups listed before it, so its add control is reachable; it is no data column (not in a copy, the CSV, `ctx.colIdx` or cell mode). `setData({columnGroups})` changes them.
+ * @property {Function} [groupActions] - `(group, {key, columns, table}) => items`, buttons in a group's header cell (`{action, icon?, label?, title?, disabled?}`); a click calls `onGroupAction(action, groupKey)`.
+ * @property {Function} [onGroupAction] - `(action, groupKey) => void`.
+ * @property {Function} [onColumnAdd] - `(groupKey) => void`. Puts an add button (`.twm-dt-group__add`) in every group's header cell and in a placeholder column's header.
+ * @property {Function} [columnActions] - `(colIdx, {colIdx, header, table}) => items`, buttons in a data column's header (`.twm-dt-col-action`, same items as `groupActions`); a click calls `onColumnAction(action, colIdx)` and does not sort.
+ * @property {Function} [onColumnAction] - `(action, colIdx) => void`.
+ * @property {Function} [onColumnRename] - `(colIdx, name) => void | false | {ok: false} | Promise<…>`. RENAMING IN PLACE through `attachInlineRenamer`: "Rename column" in the header's right-click menu, `renameColumn(colIdx)`, or (on a table that is not `sortable`) a double-click on the header's label opens it. Enter, or the focus leaving, with a different non-empty name calls it once; Escape, or the name unchanged, restores the header and calls nothing. The new name shows until the next render; `false` or `{ok: false}` restores the old one.
+ * @property {Function} [onColumnDelete] - `(colIdx) => void`, from "Delete column" in the header's right-click menu.
+ * @property {Function} [onRowAdd] - `(afterRowIdx|null) => void`, from "Insert row below" in a row's right-click menu (its original index) and "Add row" in the header's (null), so a table with no rows can get its first.
+ * @property {Function} [onRowDelete] - `(rowIdx) => void`, from "Delete row" in a row's right-click menu.
+ *
+ * ── STORY-0091, off unless asked for ──────────────────────────────────────
+ * @property {{labelColumns?: number, headerRows?: Array<Array<{label: string, columns: number[], className?: string|string[], title?: string}>>, emptyLabel?: string}} [crosstab] - A CROSSTAB (crosstab.js): one table in one scroller, the `thead` kept in the body table. `headerRows` draws rows of spans above the column headers (top first; a cell spans the run of drawn body columns it lists, a run in no cell is blank), the leading `labelColumns` drawn data columns are row labels, and header rows stick to the top and label columns (behind the select and row-number columns) to the left at offsets MEASURED after layout and again when a header row or pinned header cell changes size; the corner sticks to both. With no body column, one column headed `emptyLabel` ('(none)'). No header table is built, so the column fit, resize grips, header menu (and the header items of `table_structure`), `columnActions`, `reorderable` and `columnGroups` (ignored, with a warning) do not apply. A row's background is `--twm-dt-row-bg` on its `tr`, which the pinned cells lay over their surface, with every cell tint as a layer above it.
  */
 
 /** C10. When the scroll box has no layout — mounted hidden, or a DOM with no
@@ -548,13 +588,75 @@ export class DataTable {
             hiddenColumns: null,
             columnChooser: false,
             onColumnsChange: null,
+            // STORY-0086. Off — columns in their natural order, as in 0.16.
+            reorderable: false,
+            columnOrder: null,
             // STORY-0016. Off — no select column, as in 0.11 — until set.
             selectToggle: false,
             selectMode: false,
             onSelectModeChange: null,
+            // STORY-0003. Off — rows selected as in 0.16, no editing — until
+            // set. The typedef says what each does.
+            selectionMode: 'rows',
+            editable: false,
+            editors: null,
+            onCellCommit: null,
+            onCellSelectionChange: null,
+            headerMenu: null,
+            onHeaderMenuAction: null,
+            // STORY-0088. Off — commits go to onCellCommit — until set.
+            staged: false,
+            historyLimit: 100,
+            onCommit: null,
+            onStagedChange: null,
+            stagedRefusal: null,
+            // STORY-0066. Off — one header row, no structural edits — until
+            // set. The typedef says what each does.
+            columnGroups: null,
+            groupActions: null,
+            onGroupAction: null,
+            onColumnAdd: null,
+            columnActions: null,
+            onColumnAction: null,
+            onColumnRename: null,
+            onColumnDelete: null,
+            onRowAdd: null,
+            onRowDelete: null,
+            // STORY-0089. Off — no fill handle — until set.
+            fillHandle: false,
             ...config,
         };
 
+        // STORY-0003. Cell mode is the table's for its whole life. The row
+        // modes it replaces are ignored beside it, out loud.
+        this._cellGrid = null;
+        // STORY-0066. Built the first time their options are set (see
+        // `_colGroups`, `_structure`); a table without them never builds either.
+        this._columnGroups = null;
+        this._tableStructure = null;
+        // STORY-0091. Built the first time `crosstab` is read (`_crosstab`).
+        this._crosstabLayout = null;
+        if (this.config.selectionMode === 'cells') {
+            const clash = ['selectToggle', 'selectMode', 'keyboardNav'].filter((k) => !!this.config[k]);
+            if (clash.length) {
+                console.warn(`[DataTable] ${clash.join('/')} cannot be combined with selectionMode: 'cells'; ignored.`);
+                for (const k of clash) this.config[k] = false;
+            }
+            this._cellGrid = new CellGrid(this);
+        } else if (this.config.editable) {
+            console.warn("[DataTable] `editable` needs selectionMode: 'cells'; ignored.");
+        }
+        if (this.config.staged && !this._cellGrid) {
+            console.warn('[DataTable] `staged` needs `editable`; ignored.');
+        }
+        if (this.config.fillHandle && !this._cellGrid) {
+            console.warn('[DataTable] `fillHandle` needs `staged`; ignored.');
+        }
+        // STORY-0091. A crosstab has no group row: its spans are `headerRows`.
+        if (Array.isArray(this.config.columnGroups) && this.config.columnGroups.length && this._crosstab()) {
+            console.warn('[DataTable] `columnGroups` cannot be combined with `crosstab` (use crosstab.headerRows); ignored.');
+        }
+
         // STORY-0016. The select column is drawn for the table's whole life or
         // not at all, so the drawn column indices (and the widths kept by them)
         // never move when the mode flips.
@@ -584,6 +686,15 @@ export class DataTable {
         // below, which may replace them with the remembered set.
         this._hidden = new Set();
         this._setHidden(this.config.hiddenColumns);
+        // STORY-0086. The order asked for (null: natural), before the restore
+        // below, which may replace it with the remembered one.
+        this._order = null;
+        this._askedOrder = null;
+        this._askedUnchecked = false;
+        if (!this._setOrder(this.config.columnOrder, true)) {
+            console.warn('[DataTable] columnOrder is not an order of the columns; ignored.');
+        }
+        this._reorder = this.config.reorderable ? new ColumnReorder(this) : null;
 
         // 0.5.0. The open row's key, and the failure on show (`setError`).
         this._activeKey = this.config.activeRow == null ? null : String(this.config.activeRow);
@@ -723,6 +834,11 @@ export class DataTable {
             this._setHidden(blob.hidden);
             applied = true;
         }
+        // STORY-0086. The order, before the widths for the same reason. One
+        // saved for a different number of columns is no order of these.
+        if (Array.isArray(blob.order) && this._setOrder(blob.order)) {
+            applied = true;
+        }
         if (blob.colWidths && typeof blob.colWidths === 'object') {
             // Stored under string keys (JSON) → coerce back to ints.
             this._colWidths = {};
@@ -756,7 +872,11 @@ export class DataTable {
             + (this.config.showRowNumbers ? '|#' : '')
             // STORY-0012. Widths are by drawn column, so a different set drawn
             // is a different schema — unless `setColumnVisible` carried them.
-            + (this._hidden?.size ? `|-${this.getHiddenColumns().join(',')}` : '');
+            + (this._hidden?.size ? `|-${this.getHiddenColumns().join(',')}` : '')
+            // STORY-0086. And a different order — unless `moveColumn` carried them.
+            + (this._columnOrder() ? `|>${this._columnOrder().join(',')}` : '')
+            // STORY-0066. A placeholder column moves the drawn indices too.
+            + (this._colGroups()?.sig() || '');
     }
 
     /** Snapshot the persistable slice of state to the project store.
@@ -777,6 +897,8 @@ export class DataTable {
             // STORY-0012. Only for a table that hides columns or lets them be
             // hidden.
             ...(this._columnsOn() ? { hidden: this.getHiddenColumns() } : {}),
+            // STORY-0086. Only for a table that orders its columns.
+            ...(this._orderOn() ? { order: this.getColumnOrder() } : {}),
         });
     }
 
@@ -807,7 +929,36 @@ export class DataTable {
     /** The cells a drawn row has: the shown columns, and the row number. */
     _domColCount() {
         const n = Math.max(0, (this.config.headers?.length || 0) - this._hidden.size);
-        return n + this._lead().all;
+        // STORY-0066: an empty group's placeholder column is drawn too.
+        return n + this._lead().all + (this._colGroups()?.placeholderCount() || 0)
+            // STORY-0091: an empty axis's one column.
+            + (this._crosstab()?.extraColumns() || 0);
+    }
+
+    /** STORY-0066. The column groups (column_groups.js) while `columnGroups`
+     *  holds any; null otherwise. */
+    _colGroups() {
+        const spec = this.config.columnGroups;
+        if (!Array.isArray(spec) || !spec.length) return null;
+        // STORY-0091. A crosstab's spanned rows are its `headerRows`; the
+        // split layout's group row has no header table to stand in.
+        if (this._crosstab()) return null;
+        return (this._columnGroups ||= new ColumnGroups(this));
+    }
+
+    /** STORY-0091. The crosstab layout (crosstab.js) while `crosstab` is an
+     *  object; null otherwise. */
+    _crosstab() {
+        const spec = this.config.crosstab;
+        if (!spec || typeof spec !== 'object') return null;
+        return (this._crosstabLayout ||= new Crosstab(this));
+    }
+
+    /** STORY-0066. The structural edits (table_structure.js) while any of
+     *  their options is set; null otherwise. */
+    _structure() {
+        if (!STRUCTURE_OPTIONS.some((k) => typeof this.config[k] === 'function')) return null;
+        return (this._tableStructure ||= new TableStructure(this));
     }
 
     /** STORY-0016. The drawn columns in front of the data: the select column
@@ -817,25 +968,36 @@ export class DataTable {
         return { select, all: select + (this.config.showRowNumbers ? 1 : 0) };
     }
 
+    /** The data columns drawn, in the order drawn (STORY-0086): the order
+     *  without the hidden ones. */
+    _shownColumns() {
+        return this._rowColumns(this.config.headers?.length || 0);
+    }
+
+    /** The data indices of a row of `count` cells to draw, in order: the
+     *  shown columns, and any cell past the headers after them. */
+    _rowColumns(count) {
+        return cellOrder(this._columnOrder(), count).filter((c) => !this._isHidden(c));
+    }
+
     /** A data column's drawn index (row number included), or -1 when hidden. */
     _domIdxOf(colIdx) {
-        if (this._isHidden(colIdx)) return -1;
-        let dom = this._lead().all;
-        for (const h of this._hidden) if (h < colIdx) dom--;
-        return dom + colIdx;
+        // STORY-0066. With a placeholder drawn, the groups' layout says.
+        const slot = this._colGroups()?.slotOf(colIdx) ?? -1;
+        if (slot >= 0) return this._lead().all + slot;
+        const at = this._shownColumns().indexOf(colIdx);
+        return at < 0 ? -1 : this._lead().all + at;
     }
 
     /** A drawn cell's data column, or null for the row number. */
     _dataIdxOfDom(domIdx) {
-        let i = domIdx - this._lead().all;
+        const i = domIdx - this._lead().all;
         if (i < 0) return null;
-        const n = this.config.headers?.length || 0;
-        for (let c = 0; c < n; c++) {
-            if (this._isHidden(c)) continue;
-            if (i === 0) return c;
-            i--;
-        }
-        return null;
+        // STORY-0066. With a placeholder drawn, the groups' layout says (and
+        // a placeholder is no data column).
+        const slot = this._colGroups()?.slotAt(i);
+        if (slot !== undefined) return slot;
+        return this._shownColumns()[i] ?? null;
     }
 
     /** The columns not drawn, by data index, ascending. */
@@ -868,12 +1030,24 @@ export class DataTable {
      *  that stay drawn to their new places, and tell whoever listens. */
     _applyHidden(next) {
         const before = this.getHiddenColumns();
+        this._carryWidths(() => this._setHidden([...next]));
+        const after = this.getHiddenColumns();
+        if (before.join() === after.join()) return;
+        this._savePersisted();
+        if (this._wrapperEl) this.render();
+        this._columnsChanged();
+    }
+
+    /** STORY-0012/0086. Run `change` (a new hidden set or order), carrying
+     *  the drawn widths of the columns drawn before and after to their new
+     *  places. */
+    _carryWidths(change) {
         const n = this.config.headers?.length || 0;
         const old = this._colWidths;
         const kept = this._colWidthsSig === this._colSig();
         const domBefore = [];
         for (let c = 0; c < n; c++) domBefore[c] = this._domIdxOf(c);
-        this._setHidden([...next]);
+        change();
         if (kept) {
             const widths = {};
             for (let i = 0; i < this._lead().all; i++) if (old[i] != null) widths[i] = old[i];
@@ -885,21 +1059,109 @@ export class DataTable {
             this._colWidths = widths;
             this._colWidthsSig = this._colSig();
         }
-        const after = this.getHiddenColumns();
-        if (before.join() === after.join()) return;
-        this._savePersisted();
-        if (this._wrapperEl) this.render();
-        try { this.config.onColumnsChange?.(after); } catch (err) {
+    }
+
+    /** `onColumnsChange(hidden, {hidden, order})`, after a change of either. */
+    _columnsChanged() {
+        const hidden = this.getHiddenColumns();
+        try { this.config.onColumnsChange?.(hidden, { hidden, order: this.getColumnOrder() }); } catch (err) {
             console.error('[DataTable] onColumnsChange threw', err);
         }
     }
 
-    /** `columnChooser`: the header's right-click menu, one checkable item a
-     *  column. */
-    _showColumnChooser(clientX, clientY) {
+    // ─────────────────────────────────────────────────────────────────
+    // STORY-0086 — the order the columns are drawn in (column_order.js)
+    // ─────────────────────────────────────────────────────────────────
+
+    /** Whether this table orders its columns at all (and so saves the order). */
+    _orderOn() {
+        return !!this.config.reorderable || Array.isArray(this.config.columnOrder) || !!this._orderTouched;
+    }
+
+    /** Take `list` as the order (`asked`: it is `columnOrder`, kept apart as
+     *  the fallback). Refused (false, nothing changed) when it is no
+     *  permutation of the columns; a table with no headers yet keeps it for
+     *  the headers `setData` brings, and `_checkAskedOrder` checks it then. */
+    _setOrder(list, asked = false) {
+        const n = this.config.headers?.length || 0;
+        if (list != null && (!Array.isArray(list) || (n && !isColumnOrder(list, n)))) return false;
+        this._order = list == null ? null : list.map(Number);
+        if (asked) {
+            this._askedOrder = this._order;
+            this._askedUnchecked = !!this._order && !n;
+        }
+        return true;
+    }
+
+    /** The first headers have come: a `columnOrder` taken before them, unchecked,
+     *  that is no order of them is dropped with the same warning a table with
+     *  headers gives at once — once, as the check is made once. */
+    _checkAskedOrder() {
+        const n = this.config.headers?.length || 0;
+        if (!this._askedUnchecked || !n) return;
+        this._askedUnchecked = false;
+        if (isColumnOrder(this._askedOrder, n)) return;
+        console.warn('[DataTable] columnOrder is not an order of the columns; ignored.');
+        if (this._order === this._askedOrder) this._order = null;
+        this._askedOrder = null;
+    }
+
+    /** The order in force, or null for the natural one. One rule, whether the
+     *  headers were known when an order came or not: the first of the live
+     *  order (dragged, moved or restored) and `columnOrder` that is an order
+     *  of today's columns — so a saved order of the wrong length never
+     *  displaces `columnOrder`. */
+    _columnOrder() {
+        const n = this.config.headers?.length || 0;
+        for (const o of [this._order, this._askedOrder]) {
+            if (o && isColumnOrder(o, n)) return o;
+        }
+        return null;
+    }
+
+    /**
+     * Every data column's index, hidden ones included, in the order drawn.
+     * @returns {number[]}
+     */
+    getColumnOrder() {
+        return (this._columnOrder() || naturalOrder(this.config.headers?.length || 0)).slice();
+    }
+
+    /**
+     * Move the column at position `from` of `getColumnOrder()` to position
+     * `to`, the others closing up behind it: from the natural order,
+     * `moveColumn(3, 1)` draws 0, 3, 1, 2. The widths stay with their columns.
+     * Saved under `persistKey`, and `onColumnsChange` is told.
+     *
+     * @param {number} from
+     * @param {number} to
+     * @returns {boolean} whether the order changed
+     */
+    moveColumn(from, to) {
+        const order = this.getColumnOrder();
+        const n = order.length;
+        if (![from, to].every((i) => Number.isInteger(i) && i >= 0 && i < n) || from === to) return false;
+        this._applyOrder(moveInOrder(order, from, to));
+        return true;
+    }
+
+    /** Swap in a new order (a permutation, or null), widths carried, and
+     *  tell whoever listens. */
+    _applyOrder(next) {
+        const before = this.getColumnOrder().join();
+        this._orderTouched = true;
+        this._carryWidths(() => this._setOrder(next));
+        if (this.getColumnOrder().join() === before) return;
+        this._savePersisted();
+        if (this._wrapperEl) this.render();
+        this._columnsChanged();
+    }
+
+    /** `columnChooser`'s items: one checkable item a column. */
+    _columnChooserItems() {
         const headers = this.config.headers || [];
         const lastShown = headers.length - this._hidden.size <= 1;
-        const items = headers.map((h, c) => {
+        return headers.map((h, c) => {
             const shown = !this._isHidden(c);
             return {
                 label: String(h ?? ''),
@@ -910,7 +1172,69 @@ export class DataTable {
                 onChoose: () => this.setColumnVisible(c, !shown),
             };
         });
-        this._showContextMenu(clientX, clientY, { ctx: null, items, copy: false });
+    }
+
+    /**
+     * STORY-0003. The header's right-click menu for a press on `target`: the
+     * consumer's `headerMenu` items for the data column under it, then — with
+     * `columnChooser` — the chooser's items behind a separator. Empty when
+     * there is nothing to show.
+     */
+    _headerMenuItems(target) {
+        const items = [];
+        const hook = this.config.headerMenu;
+        const colIdx = this._headerColumnAt(target);
+        if (typeof hook === 'function' && colIdx !== null) {
+            let asked = null;
+            try {
+                asked = hook(colIdx, {
+                    colIdx,
+                    header: this.config.headers?.[colIdx],
+                    hiddenColumns: this.getHiddenColumns(),
+                    table: this,
+                });
+            } catch (err) {
+                console.error('[DataTable] headerMenu threw', err);
+            }
+            for (const item of Array.isArray(asked) ? asked.filter(Boolean) : []) {
+                if (item.separator) { items.push({ separator: true }); continue; }
+                items.push({
+                    ...item,
+                    onChoose: () => {
+                        try { this.config.onHeaderMenuAction?.(item.action, colIdx); } catch (err) {
+                            console.error('[DataTable] onHeaderMenuAction threw', err);
+                        }
+                    },
+                });
+            }
+        }
+        // STORY-0086. Move left / Move right, for the data column under it.
+        if (this._reorder && colIdx !== null) {
+            const moves = this._reorder.menuItems(colIdx);
+            if (moves.length && items.length) items.push({ separator: true });
+            items.push(...moves);
+        }
+        // STORY-0066. Rename, delete, add a row.
+        const structural = this._structure()?.headerItems(colIdx) || [];
+        if (structural.length) {
+            if (items.length) items.push({ separator: true });
+            items.push(...structural);
+        }
+        if (this.config.columnChooser) {
+            if (items.length) items.push({ separator: true });
+            items.push(...this._columnChooserItems());
+        }
+        return items;
+    }
+
+    /** The data column of a header cell (the header row, or the filter row
+     *  under it), or null off one — the row number, the select column. */
+    _headerColumnAt(target) {
+        const cell = target?.closest?.('th, td');
+        const tr = cell?.parentNode;
+        if (!tr || tr.parentNode?.tagName !== 'THEAD') return null;
+        if (tr.children.length !== this._domColCount()) return null;
+        return this._dataIdxOfDom(Array.prototype.indexOf.call(tr.children, cell));
     }
 
     /** STORY-0010 `persistPage`: the client page changed, so save it. */
@@ -964,18 +1288,31 @@ export class DataTable {
             this._setHidden(updates.hiddenColumns);
             if (this.getHiddenColumns().join() !== before) {
                 this._savePersisted();
-                try { this.config.onColumnsChange?.(this.getHiddenColumns()); } catch (err) {
-                    console.error('[DataTable] onColumnsChange threw', err);
-                }
+                this._columnsChanged();
             }
         } else if (updates.headers && this._hidden.size) {
             this._setHidden([...this._hidden]);
         }
+        // STORY-0086. A new order asked for applies at once (refused, with a
+        // warning, when it is no order of the columns); new headers keep the
+        // order while it still fits them.
+        if (Object.prototype.hasOwnProperty.call(updates, 'columnOrder')) {
+            const before = this.getColumnOrder().join();
+            if (!this._setOrder(updates.columnOrder, true)) {
+                console.warn('[DataTable] columnOrder is not an order of the columns; ignored.');
+            } else if (this.getColumnOrder().join() !== before) {
+                this._savePersisted();
+                this._columnsChanged();
+            }
+        } else if (updates.headers) {
+            this._checkAskedOrder();
+        }
 
         // Reset state if rows changed
         if (updates.rows) {
             this._state.selected.clear();
             this._state.anchorIndex = null;
+            this._cellGrid?.newRows();
             if (this._state.offset >= updates.rows.length) {
                 this._state.offset = 0;
             }
@@ -1061,6 +1398,12 @@ export class DataTable {
      * @param {number[]} indices - Row indices to select
      */
     setSelection(indices) {
+        // STORY-0003. In cell mode, the cells of those rows: one range from the
+        // first of them to the last, as shown, across every column shown.
+        if (this._cellGrid) {
+            this._cellGrid.selectRows(indices);
+            return;
+        }
         this._state.selected.clear();
         for (const idx of indices) {
             if (idx >= 0 && idx < this.config.rows.length) {
@@ -1151,17 +1494,127 @@ export class DataTable {
      * Clear selection
      */
     clearSelection() {
+        if (this._cellGrid) {
+            this._cellGrid.clear();
+            return;
+        }
         this._state.selected.clear();
         this._state.anchorIndex = null;
         this._updateRowSelection();
         this._notifySelectionChange();
     }
 
+    // ─────────────────────────────────────────────────────────────────
+    // STORY-0003 — cell mode (`selectionMode: 'cells'`), see cell_grid.js
+    // ─────────────────────────────────────────────────────────────────
+
+    /**
+     * The cell selection: `{anchor, focus, range}`. `anchor` and `focus` (the
+     * cursor) are `{row, col, rowIdx}` — `row` the position in the order
+     * shown, `col` the data column, `rowIdx` the original row index — and
+     * `range` is `{top, bottom, left, right, rows, columns}`: positions,
+     * data columns at its edges, and the original row indices and data
+     * columns it covers. All null with nothing selected. Null outside cell
+     * mode.
+     */
+    getCellSelection() {
+        return this._cellGrid ? this._cellGrid.get() : null;
+    }
+
+    /**
+     * Put the cursor on a cell (`row` a position in the order shown, `col` a
+     * data column) — with `anchor`, select the range from there. `null`
+     * clears. The row is brought into view. A no-op outside cell mode.
+     *
+     * @param {{row:number, col:number}|null} focus
+     * @param {{row:number, col:number}} [anchor]
+     */
+    setCellSelection(focus, anchor = null) {
+        this._cellGrid?.set(focus, anchor);
+    }
+
+    /** Open the editor on a cell (position, data column), as F2 would.
+     *  Returns whether one opened. */
+    editCell(row, col) {
+        return !!this._cellGrid?.open(row, col);
+    }
+
+    /** Whether a cell editor is open. */
+    isEditing() {
+        return !!this._cellGrid?.isEditing();
+    }
+
+    // ── STORY-0088 `staged` ──────────────────────────────────────────────
+
+    /**
+     * Send every staged cell to `onCommit({edits})`, in one call. Resolves
+     * `{ok: true, committed}` (the staged cells and the undo ring are
+     * cleared), or `{ok: false, errors}` (the cells refused are marked and
+     * every staged value stays). An open editor's value is staged first.
+     * Without `staged`, resolves `{ok: false, errors: []}`.
+     *
+     * @returns {Promise<{ok: boolean, committed?: number, errors?: Array<{rowIdx:number, colIdx:number, error:string}>}>}
+     */
+    commit() {
+        const st = this._cellGrid?.staged;
+        return st ? st.commit() : Promise.resolve({ ok: false, errors: [] });
+    }
+
+    /** Drop every staged cell, its marks and the undo ring. Returns whether
+     *  there was anything to drop. */
+    discard() {
+        return !!this._cellGrid?.staged?.discard();
+    }
+
+    /** Take the last staged edit back (Ctrl+Z). Returns whether it moved. */
+    undo() {
+        return !!this._cellGrid?.staged?.undo();
+    }
+
+    /** Put the last edit taken back back again (Ctrl+Y). */
+    redo() {
+        return !!this._cellGrid?.staged?.redo();
+    }
+
+    /** Every staged cell, `{rowIdx, colIdx, value, previous}`, by row then
+     *  column. Empty without `staged`. */
+    getStagedEdits() {
+        return this._cellGrid?.staged ? this._cellGrid.staged.edits() : [];
+    }
+
+    /**
+     * STORY-0089. Fill from the cell range to the cell `to` (`{row, col}`:
+     * position in the order shown, data column), as dragging the fill handle
+     * there does: staged as ONE undo entry, Ctrl's repeat as `forceCopy`.
+     * Returns `{direction, count, staged, skipped}` —
+     * `staged` the NUMBER of cells that changed, `skipped` the cells `editable` refused
+     * (`{row, col, rowIdx}`) — or null when nothing was filled (no
+     * `fillHandle`, no range, `to` inside it, an editor open, a commit out).
+     */
+    fill(to, { forceCopy = false } = {}) {
+        return this._cellGrid?.fill ? this._cellGrid.fill.fill(to, { forceCopy }) : null;
+    }
+
+    /** Why sort, filters and pages are held — a staged edit — or null; with
+     *  a reason, `what` is refused out loud. */
+    _stagedRefusal(what) {
+        const why = this._cellGrid?.staged?.freezeReason() || null;
+        if (why) console.warn(`[DataTable] ${what} refused: ${why}`);
+        return why;
+    }
+
+    /** STORY-0066. Open the inline renamer on a data column's header (needs
+     *  `onColumnRename`). Returns whether it opened. */
+    renameColumn(colIdx) {
+        return !!this._structure()?.rename(colIdx);
+    }
+
     /**
      * Go to specific page
      * @param {number} page - Page number (0-indexed)
      */
     goToPage(page) {
+        if (this._stagedRefusal('goToPage')) return;
         // 0.7.0 `dataSource`: the page is the SOURCE's — asked for, and drawn
         // when it answers (the promise). Past a known total, the last page.
         // (The release review: this set an offset nothing under a data source
@@ -1185,6 +1638,7 @@ export class DataTable {
      * @param {number} rowIndex - Row index
      */
     goToRow(rowIndex) {
+        if (this._stagedRefusal('goToRow')) return;
         // 0.7.0 `dataSource`: the page that holds the row, from the source.
         if (this.config.dataSource) {
             const size = this._sourcePageSize();
@@ -1203,6 +1657,7 @@ export class DataTable {
      * @param {boolean} [ascending] - Sort direction (toggles if same column)
      */
     sortBy(colIndex, ascending) {
+        if (this._stagedRefusal('sortBy')) return;
         if (this._state.sortColumn === colIndex && ascending === undefined) {
             this._state.sortAscending = !this._state.sortAscending;
         } else {
@@ -1245,6 +1700,7 @@ export class DataTable {
      * Clear all column filters
      */
     clearFilters() {
+        if (this._stagedRefusal('clearFilters')) return;
         this._state.filters.clear();
         this._processedRows = null;
         this._processedIndexMap = null;
@@ -1310,6 +1766,12 @@ export class DataTable {
      * Render the table
      */
     render() {
+        // STORY-0003. An open cell editor is not torn down by a redraw: the
+        // render waits for its commit or cancel, and runs then.
+        if (this._cellGrid?.isEditing()) {
+            this._cellGrid.renderWaiting = true;
+            return;
+        }
         // Capture active filter input before re-render
         const activeFilterColIdx = this._getActiveFilterColIdx();
         // KEYBOARD FOCUS SURVIVES A RE-RENDER. Rendering replaces the table
@@ -1433,7 +1895,9 @@ export class DataTable {
         // empty one must keep the filter row — or a filter that matched nothing
         // could never be cleared. It goes through `_createTable` and gets its
         // empty row there.
-        const keepFilterRow = rows.length === 0 && !!this.config.dataSource && this.config.filterable;
+        // STORY-0091: a crosstab keeps its header rows and its corner too.
+        const keepFilterRow = rows.length === 0
+            && ((!!this.config.dataSource && this.config.filterable) || !!this._crosstab());
         if (rows.length === 0 && !keepFilterRow) {
             // Empty state — render the same chrome as the data table
             // (header row in its own non-scrolling wrap) followed by a
@@ -1456,13 +1920,12 @@ export class DataTable {
                 th.textContent = '#';
                 tr.appendChild(th);
             }
-            headers.forEach((h, colIdx) => {
-                if (this._isHidden(colIdx)) return;
+            for (const colIdx of this._shownColumns()) {
                 const th = document.createElement('th');
                 th.className = this._columnTypes[colIdx] || 'text';
-                th.textContent = h;
+                th.textContent = headers[colIdx];
                 tr.appendChild(th);
-            });
+            }
             thead.appendChild(tr);
             headerTable.appendChild(thead);
             headerWrap.appendChild(headerTable);
@@ -1489,7 +1952,15 @@ export class DataTable {
             this._tableEl = fullTable;
             // Extract thead → header table in its own non-scrolling
             // container. The body table keeps tbody only.
-            const thead = fullTable.querySelector('thead');
+            // STORY-0091. A crosstab keeps its `thead` in the body table: one
+            // table in one scroller, pinned by `position: sticky`.
+            const crosstab = this._crosstab();
+            const thead = crosstab ? null : fullTable.querySelector('thead');
+            if (crosstab) {
+                crosstab.decorate(fullTable);
+                this._headerTableEl = null;
+                this._headerWrapEl = null;
+            }
             if (thead) {
                 const headerWrap = document.createElement('div');
                 headerWrap.className = 'twm-preview-table-header-wrap';
@@ -1515,17 +1986,30 @@ export class DataTable {
         }
 
         this._tableWrapEl = tableWrap;
-        // STORY-0012 `columnChooser`: the header's right-click.
-        if (this.config.columnChooser && this._headerTableEl) {
+        // STORY-0012 `columnChooser` and STORY-0003 `headerMenu`: the header's
+        // right-click. With neither item to show, the page's own menu.
+        // STORY-0066: the groups' row and placeholder columns, the renamer's
+        // labels and the consumer's column actions, on the header just built.
+        this._colGroups()?.decorate(this._headerWrapEl, this._headerTableEl);
+        this._structure()?.decorate(this._headerTableEl);
+        if ((this.config.columnChooser || typeof this.config.headerMenu === 'function' || this._reorder
+             || this._structure()?.hasHeaderItems()) && this._headerTableEl) {
             const head = this._headerTableEl;
             const onHeadMenu = (ev) => {
+                const items = this._headerMenuItems(ev.target);
+                if (!items.length) return;
                 ev.preventDefault();
                 ev.stopPropagation();
-                setTimeout(() => this._showColumnChooser(ev.clientX, ev.clientY), 0);
+                setTimeout(() => this._showContextMenu(ev.clientX, ev.clientY,
+                                                       { ctx: null, items, copy: false }), 0);
             };
             head.addEventListener('contextmenu', onHeadMenu);
             this._disposers.push(() => head.removeEventListener('contextmenu', onHeadMenu));
         }
+        // STORY-0086 `reorderable`: the header's drag.
+        if (this._reorder && this._headerTableEl) {
+            this._reorder.install(this._headerTableEl.querySelector('thead > tr'));
+        }
         // 0.7.0 `pagerPosition: 'bottom'`: under the rows.
         if (this._paginationEl && this.config.pagerPosition === 'bottom') {
             this._paginationEl.classList.add('twm-pagination-controls--bottom');
@@ -1541,6 +2025,8 @@ export class DataTable {
             if (this._pagingEl) this._wrapperEl.appendChild(this._pagingEl);
         }
         this.container.appendChild(this._wrapperEl);
+        // STORY-0091. The crosstab's offsets, measured now the table is in.
+        this._crosstab()?.install();
         // 0.6.1 `scrollLock`: THIS render's body box joins the group, and leaves
         // it with the next render's cleanup or the dispose.
         if (this.config.scrollLock && typeof this.config.scrollLock.attach === 'function') {
@@ -1618,7 +2104,8 @@ export class DataTable {
         if (rows.length > 0 && (this.config.selectable || this.config.copyable || !this.config.readonly
                                 || typeof this.config.onRowActivate === 'function'
                                 || typeof this.config.rowDetail === 'function'
-                                || typeof this.config.onRowKeyDown === 'function')) {
+                                || typeof this.config.onRowKeyDown === 'function'
+                                || this._cellGrid)) {
             this._installInteractions();
         }
 
@@ -1669,14 +2156,14 @@ export class DataTable {
         }
 
         const { headers, rows } = this.config;
-        // STORY-0012. The columns shown — all of them, unless some are hidden.
-        const shown = (_, colIdx) => !this._isHidden(colIdx);
-        const matrix = [headers.filter(shown)];
+        // STORY-0012. The columns shown — all of them, unless some are hidden —
+        // and (STORY-0086) in the order shown.
+        const matrix = [this._rowColumns(headers.length).map((c) => headers[c])];
 
         for (const idx of indices) {
             const row = rows[idx];
             if (row) {
-                matrix.push(row.map((val, colIdx) => this._formatValue(val, colIdx)).filter(shown));
+                matrix.push(this._rowColumns(row.length).map((c) => this._formatValue(row[c], c)));
             }
         }
 
@@ -1715,12 +2202,11 @@ export class DataTable {
             return;
         }
 
-        const shown = (_, colIdx) => !this._isHidden(colIdx);
-        const lines = [headers.filter(shown).join(',')];
+        const lines = [this._rowColumns(headers.length).map((c) => headers[c]).join(',')];
         for (const row of rows) {
-            lines.push(row.map((val, colIdx) =>
-                this._csvEscape(this._formatValue(val, colIdx))
-            ).filter(shown).join(','));
+            lines.push(this._rowColumns(row.length).map((c) =>
+                this._csvEscape(this._formatValue(row[c], c))
+            ).join(','));
         }
 
         const csv = lines.join('\n');
@@ -1783,6 +2269,10 @@ export class DataTable {
     }
 
     _teardown(emptyHost) {
+        // STORY-0003. An open editor goes, committing nothing.
+        this._cellGrid?.dispose();
+        // STORY-0066. And an open column renamer.
+        this._tableStructure?.dispose();
         autoDisposeUnwatch(this);
         this._autoSeen = false;
         // 0.7.0. A grace still running, the follow timer, a request still out
@@ -2073,8 +2563,8 @@ export class DataTable {
             tr.appendChild(th);
         }
 
-        headers.forEach((header, colIdx) => {
-            if (this._isHidden(colIdx)) return;
+        this._shownColumns().forEach((colIdx) => {
+            const header = headers[colIdx];
             const th = document.createElement('th');
             th.className = 'data-table__filter-cell';
 
@@ -2450,6 +2940,7 @@ export class DataTable {
     }
 
     _onFilterInput(colIdx, value) {
+        if (this._stagedRefusal('A filter')) return;
         // 0.7.0. A filter value need not be text (a control's array, a range),
         // and an empty one of those is no filter. Text is judged as in 0.4.
         const empty = typeof value === 'string' ? !value : this._isEmptyFilterValue(value);
@@ -2653,6 +3144,7 @@ export class DataTable {
 
         // Page change handler - supports both client-side and server-side pagination
         const handlePageChange = (newOffset) => {
+            if (this._stagedRefusal('Turning the page')) return;
             if (isServerSide) {
                 // Auto-spinner if the consumer returns a Promise.
                 this._awaitWithSpinner(onPageChange(newOffset, pageSize));
@@ -2730,8 +3222,11 @@ export class DataTable {
     _createExportBtn() {
         const name = this.config.exportFilename;
         const filename = (typeof name === 'function' ? name(this) : name) || 'data.csv';
-        return this._createPaginationBtn('download', 'Download visible rows as CSV', false,
-                                         () => this.downloadCSV(filename));
+        const btn = this._createPaginationBtn('download', 'Download visible rows as CSV', false,
+                                              () => this.downloadCSV(filename));
+        // STORY-0088. Moves no rows, so a staged edit's freeze leaves it be.
+        btn.classList.add('twm-pagination-btn--export');
+        return btn;
     }
 
     /**
@@ -2871,6 +3366,7 @@ export class DataTable {
             this._wrapperEl.appendChild(next);
         }
         this._pagingEl = next;
+        this._cellGrid?.staged?.paintFreeze();   // STORY-0088
     }
 
     /**
@@ -2881,6 +3377,7 @@ export class DataTable {
      */
     _pagingCall(kind, fn, ...args) {
         if (typeof fn !== 'function' || this._pagingBusy) return;
+        if (this._stagedRefusal(`paging ${kind}`)) return;
         let result;
         try {
             result = fn(...args);
@@ -2912,6 +3409,9 @@ export class DataTable {
     _pagingMaybeLoadMore() {
         const p = this._pagingConfig();
         if (!p || !p.hasMore || this._pagingBusy) return;
+        // STORY-0088. Paging is held while cells are staged — quietly here:
+        // a scroll is not a click on a control that could say why.
+        if (this._cellGrid?.staged?.freezeReason()) return;
         // 0.7.0: not while the source is answering another question (a sort, a
         // filter, a refresh) — those rows are about to be replaced.
         if (this.config.dataSource && this._source?.inFlight) return;
@@ -3081,6 +3581,11 @@ export class DataTable {
         // hundred of a thousand.
         const pageRows = isServerSide || !this.config.pagination || this._pagingConfig()
             ? processedRows : processedRows.slice(offset, offset + pageSize);
+        // STORY-0003. Where the rows drawn stand in the order shown.
+        this._pageSpan = {
+            start: pageRows === processedRows ? 0 : offset,
+            count: pageRows.length,
+        };
 
         const table = document.createElement('table');
         table.className = this._tableClassName();
@@ -3098,8 +3603,8 @@ export class DataTable {
             headerRow.appendChild(th);
         }
 
-        headers.forEach((header, colIdx) => {
-            if (this._isHidden(colIdx)) return;
+        this._shownColumns().forEach((colIdx) => {
+            const header = headers[colIdx];
             const th = document.createElement('th');
             th.className = this._columnTypes[colIdx] || 'text';
 
@@ -3217,8 +3722,11 @@ export class DataTable {
         // 0.5.0. The row's place in the order shown (for 'position' numbers).
         tr.__position = (this._positionBase || 0) + localIdx;
         tr.className = 'data-preview-row';
+        // STORY-0003. The row's position in the order shown, for cell mode.
+        if (this._cellGrid) tr.__cellPos = (this._pageSpan?.start || 0) + localIdx;
 
-        if (this._state.selected.has(globalIdx)) {
+        // STORY-0003. In cell mode the CELLS are lit, not the rows.
+        if (this._state.selected.has(globalIdx) && !this._cellGrid) {
             tr.classList.add('selected');
         }
         // 0.5.0. The consumer's row classes and attributes, and the open mark.
@@ -3532,6 +4040,7 @@ export class DataTable {
         const wanted = new Set(want);
         for (const [i, tr] of v.map) {
             if (!wanted.has(i)) {
+                this._cellGrid?.rowLeaving(tr);   // STORY-0003: an open editor commits
                 tr.remove();
                 this._removeDetailPieces(tr);   // 0.7.0: its detail goes with it
                 v.map.delete(i);
@@ -3759,10 +4268,10 @@ export class DataTable {
         const changedCells = diff?.cells
             ? (diff.cells instanceof Set ? diff.cells : new Set(diff.cells))
             : null;
-        for (let colIdx = 0; colIdx < row.length; colIdx++) {
-            if (this._isHidden(colIdx)) continue;
+        for (const colIdx of this._rowColumns(row.length)) {
             const td = document.createElement('td');
             td.className = this._columnTypes[colIdx] || 'text';
+            if (this._cellGrid) td.__colIdx = colIdx;   // STORY-0003
 
             // Use custom cell renderer if provided
             const value = row[colIdx];
@@ -3813,6 +4322,12 @@ export class DataTable {
 
             tr.appendChild(td);
         }
+        // STORY-0066. An empty group's placeholder column.
+        this._colGroups()?.fillRow(tr);
+        // STORY-0091. The crosstab's pinned cells, and an empty axis's cell.
+        this._crosstab()?.fillRow(tr);
+        // STORY-0003. The selection, and a commit's pending or refused mark.
+        this._cellGrid?.decorateRow(tr);
     }
 
     /** Re-render ONE row in place, preserving everything around it.
@@ -3835,6 +4350,9 @@ export class DataTable {
      *   - keyboard focus, because the focused element's position is recorded
      *     before the replace and restored after.
      *
+     *  STORY-0003: on the row an open cell editor is in, the data is stored
+     *  now and the row is drawn when the editor closes (true is returned).
+     *
      *  @param {number} index   row index as tracked by `tr.__rowIndex`
      *  @param {any[]}  row     the new cell values
      *  @returns {boolean}      false when the row is not currently rendered
@@ -3867,6 +4385,9 @@ export class DataTable {
             this.config.rows[index] = row;
         }
         if (this._virt) this._virtSetRow(index, row);
+        // STORY-0003. The row holds an open cell editor: the rebuild would take
+        // it out of the document, so the row is drawn when the editor closes.
+        if (this._cellGrid?.holdRow(tr, index)) return true;
 
         // Record focus BEFORE the replace: `replaceChildren` detaches the
         // focused cell and the browser moves focus to <body>.
@@ -3913,7 +4434,7 @@ export class DataTable {
             });
         }
 
-        tr.classList.toggle('selected', this._state?.selected?.has(index) === true);
+        tr.classList.toggle('selected', this._state?.selected?.has(index) === true && !this._cellGrid);
         // 0.5.0. The row's data changed, so its classes, attributes, key and
         // open mark are asked again (a key paused, a delivery that died).
         this._decorateRow(tr, row, index);
@@ -4473,6 +4994,7 @@ export class DataTable {
 
     /** Go to the page at `offset` (paging back stops following). */
     _sourceGoTo(offset) {
+        if (this._stagedRefusal('Turning the page')) return undefined;
         const next = Math.max(0, offset | 0);
         // PAGING AWAY TURNS FOLLOWING OFF, and coming back does not turn it on
         // again by itself: a reader who left the tail to read an old page is
@@ -4764,6 +5286,7 @@ export class DataTable {
         const maxJump = Number.isFinite(c.maxJumpOffset) ? c.maxJumpOffset : null;
 
         const go = (newOffset) => {
+            if (this._stagedRefusal('Turning the page')) return;
             if (source) { this._sourceGoTo(newOffset); return; }
             if (server) { this._awaitWithSpinner(c.onPageChange(newOffset, pageSize)); return; }
             this._state.offset = newOffset;
@@ -4953,6 +5476,7 @@ export class DataTable {
      * value is whatever the column's control works in — text for the 0.4 box.
      */
     setFilter(colIdx, value) {
+        if (this._stagedRefusal('setFilter')) return;
         const textBox = !this._filterKindFor(colIdx, (this.config.headers || [])[colIdx]);
         const v = textBox && value != null && typeof value !== 'string' ? String(value) : value;
         if (textBox) {
@@ -5101,6 +5625,8 @@ export class DataTable {
         // STORY-0016. The select column, and whether the mode is on.
         if (this._gutter) names.push('twm-dt--select');
         if (this._selecting) names.push('twm-dt--selecting');
+        // STORY-0003.
+        if (this._cellGrid) names.push('twm-dt--cells');
         return names.join(' ');
     }
 
@@ -6056,6 +6582,9 @@ export class DataTable {
         headerWrap.scrollLeft = x;
         const residual = x - headerWrap.scrollLeft;
         headerTable.style.transform = residual ? `translateX(${-residual}px)` : '';
+        // STORY-0066. The group row follows the header: every width pass and
+        // drag ends here, and so does every sideways scroll.
+        this._colGroups()?.align();
     }
 
     /** Drag-to-resize: hang a thin grab handle off the right edge of
@@ -6261,11 +6790,17 @@ export class DataTable {
 
         const { selectable, copyable } = this.config;
         // STORY-0010. The consumer's own items install the menu by themselves.
-        const customMenu = this.config.contextMenuItems != null;
+        // STORY-0066: the structural row items make a menu of their own.
+        const customMenu = this.config.contextMenuItems != null || !!this._structure()?.hasRowItems();
         const tbody = this._tbodyEl;
         const table = this._tableEl;
 
-        if (selectable) {
+        // STORY-0003. Cell mode: the cells' own pointer and keys, bound before
+        // the activation, detail and copy listeners so a key it takes stops.
+        // The row click below is not cell mode's.
+        if (this._cellGrid) this._cellGrid.install(tbody, table);
+
+        if (selectable && !this._cellGrid) {
             const handleRowClick = (event) => {
                 const rowEl = event.target.closest('tr');
                 if (!rowEl || rowEl.__rowIndex === undefined) return;
@@ -6537,7 +7072,7 @@ export class DataTable {
             const idx = tr.__rowIndex;
             if (idx !== undefined) {
                 const on = this._state.selected.has(idx);
-                tr.classList.toggle('selected', on);
+                tr.classList.toggle('selected', on && !this._cellGrid);
                 // STORY-0016.
                 const box = this._gutter ? tr.querySelector(':scope > td.twm-dt-select-cell > input') : null;
                 if (box) box.checked = on;
@@ -6818,7 +7353,11 @@ export class DataTable {
                 items = null;
             }
         }
-        return Array.isArray(items) ? items.filter(Boolean) : [];
+        const list = Array.isArray(items) ? items.filter(Boolean) : [];
+        // STORY-0066. Insert and delete a row, after the consumer's items.
+        const structural = this._structure()?.rowItems(ctx.rowIdx) || [];
+        if (structural.length && list.length) list.push({ separator: true });
+        return list.concat(structural);
     }
 
     /**