@ai-matrx/design-system 0.22.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # Changelog
 
+## 0.25.0 — 2026-09-20
+
+**Five defects a real browser found that jsdom could not, and the table's own
+stress page so the next one is found the same way.**
+
+Every clause in the component suite was green while all five of these were
+live. They are claims about SCROLLING, about a POINTER, and about what a person
+READS — none of which jsdom has. `demo/` is now where a real browser does that
+work: a hundred thousand rows with grouping, the spreadsheet gestures, the
+coverage sentence and the horizontal window on at once.
+
+- **The fill handle dragged and filled nothing.** Two `mouseup` listeners on
+  `window`; the one that only cleared the drag flag was registered first, so by
+  the time the one that commits the fill ran, there was no drag in progress.
+  One handler now reads the flag and then clears it. Proven by a real pointer:
+  four cells filled, `"Filled 4 cells down 1 column."`
+- **The scroll re-rendered the whole table on every event.** The window was
+  derived from a scroll offset held in state, so a four-thousand-line component
+  ran on every scroll whether or not one different row would be drawn: 38ms a
+  frame while scrolling EIGHT PIXELS, against the 16.7ms floor the same browser
+  hits on a static forty-row table. The scroll handler computes the window off
+  the DOM and sets state only when the rendered range actually moves.
+- **The first paint drew every row**, because the window settled in an effect
+  and an effect runs after the first render. Render now derives a window when
+  state has none, and when a stale one no longer fits the row count.
+- **`bodyEntries` built the whole list before windowing it**, allocating a
+  hundred thousand objects per scroll to render forty rows. It slices first.
+- **`cellProps` used `indexOf` per cell** — O(rows) per cell, twenty-four
+  million comparisons a frame at 100,000 rows. Index maps.
+- **The sticky header sat UNDER the frozen column.** A frozen body cell is
+  `z-20` so it can slide under the columns to its right; the header was `z-10`,
+  so the frozen column's cells scrolled over the header they belong to and the
+  top data row printed through the column names. Only a table long enough to
+  scroll shows it.
+- **`rowHeight` did nothing unless virtualization was engaged** — so a view that
+  remembered a row height was ignored on every table short enough to read. It
+  applies on its own now, with a clause that pins it.
+- **A group header said its subtotals twice** — once in the label line and again
+  in each column's cell — and the cell version was left-aligned under a
+  right-aligned money column. The label carries the count; the columns carry
+  the subtotals, each aligned with the numbers it totals.
+
+Measured on the production demo build, 1440x900 headless Chromium, 100,000 rows:
+**19 of the 40 rendered rows in the document, a 3.3-million-pixel scroll height,
+18.6ms median frame and 23.6ms at the 95th percentile**, zero console errors.
+
+## 0.24.0 — 2026-09-20
+
+**The window goes sideways too.**
+
+0.23.0 windowed the rows. A table can also be forty rows and three hundred
+columns, and that one put every column in the document. `virtualize.columns`
+closes it: the frozen leading run is ALWAYS drawn — a frozen identity column
+that scrolled out of the DOM would leave the table blank exactly when somebody
+scrolled far enough to need it — and a spacer cell on either side of the window
+carries the width of what was left out, in the header, every body row, every
+group header and the footer, so the table is as wide as it says it is.
+
+- It engages only past **30** non-frozen columns and only when the consumer
+  asks for it, so nothing in the product changes shape today.
+- A windowed column takes a FIXED width, and that is not a style choice: if the
+  drawn columns sized themselves to their content while the spacers claimed a
+  declared width, the horizontal scroll position would stop agreeing with the
+  window index and a person scrolling to column 80 would be shown column 74.
+- Every `colSpan` in the body now counts what is RENDERED, not what is
+  declared — a full-width row spanning the declared count would push itself
+  wider than its own header.
+
+Guard: three clauses in `MatrxDataTable.gaps.test.tsx`, including
+`padStart + drawn + padEnd === the rest of the table`; the red twin fails
+12/12 without the props.
+
+## 0.23.1 — 2026-09-20
+
+**Ticking a row no longer moves the row under your cursor.**
+
+Defect N11, the thirteenth cold walk of the Masterwork pipeline (blocking). Measured on a
+catalogued media Library at 1440x900: before the first click the header checkbox sat at `y 580`
+and rows 1-3 at `y 606 / 647 / 688`; the instant a row's checkbox was ticked the selection bar was
+inserted into the flow ABOVE the table and everything moved down **86px** — two full row heights,
+header checkbox to `y 666`, rows 1-3 to `y 692 / 733 / 774`. The cursor had not moved and was now
+resting on the SELECT-ALL box, so a second click at the same point selected 25 of 2,981 rows. The
+walker hit it twice before he thought to measure it, which is how we know a real person hits it.
+Picking three rows out of a long list meant re-measuring the table between every click.
+
+- **The selection bar is now the last child of the body region** — under the rows and under the
+  pagination, instead of wedged between the toolbar and the first row. The rows live in a `flex-1`
+  box; a flex child appended after `flex-1` can only take height from the bottom of that box and
+  cannot change where it STARTS, so no row can move down. It is also where the best in the world
+  put it: Gmail, Linear and Airtable all keep the selection bar at the bottom of the list.
+- **The bar carries `data-matrx-table-bulk-bar`**, so a test or a host can address it by what it
+  is rather than by where it happens to fall in a flat DOM query.
+- Guard: `MatrxDataTable.selection-never-shifts-rows.test.tsx`, five cases, three of which go red
+  the moment the block is moved back above `data-matrx-table-body-region`.
+
+**Consumer action:** none. No API changed. Every surface that hands `MatrxDataTable` a `selection`
+inherits the fix. One caveat for test authors: a test that reached the selection bar's copy menu
+as `getAllByRole("button", { name: /Copy, transform or export/ })[1]` was relying on the bar
+rendering above the rows; address it through `[data-matrx-table-bulk-bar]` instead (this
+package's own `default-copy-regressions.test.tsx` was updated the same way).
+
+## 0.23.0 — 2026-09-20
+
+**The three gaps are closed in the primitive, and the spreadsheet half of `/data` now lives here.**
+
+The owner's read of the `/data` grid named three things it could not do that Airtable, Google
+Sheets and Notion all can — and named the third one a lie on screen. All three are answered in
+the shared table, so every surface in the product inherits them instead of the one route that
+asked.
+
+- **`grouping`** — "group these rows by Status" with collapsible sections, a count, and a
+  per-column subtotal ON its own column, not crammed into a banner. Controlled for the two pieces
+  of state a person expects to survive (which column groups, which sections are shut), so a saved
+  view carries them like any other reading of the table. A blank value is its own named section
+  and sorts last: a section of unanswered rows is not the first thing a person wants to read. The
+  model is `./grouping.ts` — pure, with eleven aggregate kinds, every one of which LABELS itself
+  ("Sum 4,812.5", "12 filled") and says `Sum —` rather than `0` when it has nothing to add up.
+- **`virtualize`** — render the rows a person can see. Off by default; on, it engages only past
+  its own threshold (150 rows), so short tables behave exactly as they did. Two spacer rows stand
+  in for the height of what the window left out, and the invariant `padStart + rendered + padEnd
+  === total` is asserted over a spread of inputs, because a scrollbar that describes the slice
+  instead of the table is its own lie. `./virtual-window.ts` also has the variable-height and
+  scroll-to-index math, prefix-summed and binary-searched: O(log n) per scroll, not O(n).
+- **`coverage`** — THE HONEST COUNT. Declare what the current answer actually covers and the
+  table says so, in plain English, above the rows: *"This filter searched the first 5,000 rows
+  only. 84,312 rows in this table; the rest were not looked at."* A complete answer says nothing.
+  A partial count is never presented as exact. The sentences are asserted to contain none of
+  "cap", "limit", "fetch", "query", "client" or "source" — a person reading a screen is not
+  reading our vocabulary.
+- **`MatrxDataTableProps.rowHeight`** — an explicit body row height, for a view that remembers one.
+
+New entry points carrying the rest of the `/data` grid's reusable half, each pure and tested:
+
+- **`@ai-matrx/design-system/formulas`** — the 28-function expression language for computed
+  columns, moved out of the app verbatim. No `eval`, nothing throws, every failure is an
+  `ok: false` with a sentence.
+- **`@ai-matrx/design-system/data-table/grid-selection`** and **`/grid-clipboard`** — the range
+  model (shift-click, drag, keyboard, row/column/all) and real Excel/Sheets TSV.
+- **`@ai-matrx/design-system/data-table/fill`** — fill-down and the drag fill handle, with series
+  detection: `1, 2` continues to `3, 4, 5`, a single value copies, an inconsistent run copies. A
+  column that cannot take a write produces a skip with a sentence, never a silent drop.
+- **`@ai-matrx/design-system/data-table/cell-undo`** — the bounded, PURE undo/redo stack behind
+  cell edits.
+- **`@ai-matrx/design-system/data-table/validation`** — the column validation model, so a refusal
+  is the same sentence everywhere.
+
+One defect this work turned up and fixed in passing: an optional config field named `valueOf` is
+never absent, because every object in JavaScript already has one — `config.valueOf ? … : …` called
+`Object.prototype.valueOf` and grouped every row under the config object itself. The field is
+`readCell` now, in both the config and the model.
+
 ## 0.22.0 — 2026-09-20
 
 **The data table can paint, format and freeze — so every table in the product can.**

package/dist/data-table/cell-undo.cjs

@@ -0,0 +1,98 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/data-table/cell-undo.ts
+var cell_undo_exports = {};
+__export(cell_undo_exports, {
+  DEFAULT_UNDO_DEPTH: () => DEFAULT_UNDO_DEPTH,
+  canRedo: () => canRedo,
+  canUndo: () => canUndo,
+  createUndoStack: () => createUndoStack,
+  popRedo: () => popRedo,
+  popUndo: () => popUndo,
+  pushUndo: () => pushUndo,
+  undoEntryFor: () => undoEntryFor
+});
+module.exports = __toCommonJS(cell_undo_exports);
+var DEFAULT_UNDO_DEPTH = 100;
+function createUndoStack(depth = DEFAULT_UNDO_DEPTH) {
+  const bounded = Number.isFinite(depth) && depth > 0 ? Math.floor(depth) : 0;
+  return { past: [], future: [], depth: bounded };
+}
+function pushUndo(stack, entry) {
+  if (stack.depth <= 0) {
+    return { past: [], future: [], depth: stack.depth };
+  }
+  const past = [...stack.past, entry];
+  while (past.length > stack.depth) past.shift();
+  return { past, future: [], depth: stack.depth };
+}
+function popUndo(stack) {
+  const entry = stack.past[stack.past.length - 1];
+  if (entry === void 0) return { stack, entry: null };
+  return {
+    stack: {
+      past: stack.past.slice(0, -1),
+      future: [...stack.future, entry],
+      depth: stack.depth
+    },
+    entry
+  };
+}
+function popRedo(stack) {
+  const entry = stack.future[stack.future.length - 1];
+  if (entry === void 0) return { stack, entry: null };
+  const past = [...stack.past, entry];
+  while (past.length > stack.depth) past.shift();
+  return {
+    stack: { past, future: stack.future.slice(0, -1), depth: stack.depth },
+    entry
+  };
+}
+function keyOf(patch) {
+  return JSON.stringify([patch.rowId, patch.columnId]);
+}
+function undoEntryFor(before, after, label) {
+  const priors = /* @__PURE__ */ new Map();
+  for (const patch of before) priors.set(keyOf(patch), patch);
+  const undo = after.map((patch) => {
+    const prior = priors.get(keyOf(patch));
+    return {
+      rowId: patch.rowId,
+      columnId: patch.columnId,
+      value: prior ? prior.value : null
+    };
+  });
+  return {
+    label,
+    undo,
+    redo: after.map((patch) => ({
+      rowId: patch.rowId,
+      columnId: patch.columnId,
+      value: patch.value
+    }))
+  };
+}
+function canUndo(stack) {
+  return stack.depth > 0 && stack.past.length > 0;
+}
+function canRedo(stack) {
+  return stack.depth > 0 && stack.future.length > 0;
+}
+//# sourceMappingURL=cell-undo.cjs.map

package/dist/data-table/cell-undo.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/cell-undo.ts"],"sourcesContent":["/**\n * THE CELL UNDO STACK — the model behind Cmd-Z in a grid.\n *\n * WHY IT SHIPS WITH EASY EDITING, NOT AFTER IT. Lowering the friction to change\n * data raises the rate of accidental change: a click toggles a boolean, a bare\n * keystroke starts an edit, Delete empties a cell, and one drag of the fill\n * handle rewrites a column. Every one of those is a good affordance ONLY if the\n * floor underneath it is recoverable.\n *\n * WHAT THIS FILE IS. A bounded, PURE stack of reversible edits: no React, no\n * network, no toasts. The app's `useCellUndo` hook owned all three plus the\n * stack, which meant the stack's rules — depth, the redo contract, what an undo\n * of an added row means — could only be exercised by mounting a component and\n * mocking a database. Those rules are spreadsheet law, not app trivia, so they\n * belong in a module anyone can test in a millisecond and any client can reuse.\n *\n * WHY IT IS PATCHES, NOT CELL COORDINATES. An entry carries the patches that\n * undo it and the patches that redo it, captured BEFORE the write and never\n * derived after it: re-reading a cell later to discover what to restore races\n * with realtime and with agent writes, and would happily \"undo\" to a value\n * somebody else just set. Patches also make the entry shape indifferent to WHAT\n * changed — one cell, a filled column, or the cells of a row that was added or\n * deleted — which is how row and column operations join the same Cmd-Z the user\n * already trusts instead of living outside it.\n *\n * PURITY IS THE POINT. Every function returns a NEW stack and never mutates the\n * one it was handed, so the stack can live in React state, in a store, or in a\n * ref without the \"my undo history changed under me\" class of bug.\n */\n\nimport type { CellPatch } from \"./fill\";\n\nexport type { CellPatch };\n\nexport interface UndoEntry {\n  /** What the user did, in plain English, for the toast: \"Undid the change to Day rate.\" */\n  label: string;\n  /** The patches that UNDO it. */\n  undo: CellPatch[];\n  /** The patches that REDO it. */\n  redo: CellPatch[];\n}\n\nexport interface UndoStack {\n  past: UndoEntry[];\n  future: UndoEntry[];\n  depth: number;\n}\n\n/**\n * How many steps back we remember. Deliberately generous — the cost is a few\n * kilobytes of session memory, and the failure mode of a too-short stack is a\n * user discovering their mistake is unrecoverable.\n */\nexport const DEFAULT_UNDO_DEPTH = 100;\n\nexport function createUndoStack(depth: number = DEFAULT_UNDO_DEPTH): UndoStack {\n  const bounded = Number.isFinite(depth) && depth > 0 ? Math.floor(depth) : 0;\n  return { past: [], future: [], depth: bounded };\n}\n\n/**\n * Record an edit that already happened.\n *\n * Pushing CLEARS the redo future — the standard editor contract: you cannot\n * redo into a future you have just diverged from. Past `depth`, the OLDEST\n * entry is dropped, so the stack is bounded memory rather than a leak.\n */\nexport function pushUndo(stack: UndoStack, entry: UndoEntry): UndoStack {\n  if (stack.depth <= 0) {\n    // Undo is off. Pushing keeps the stack empty rather than silently growing\n    // a history nothing will ever read.\n    return { past: [], future: [], depth: stack.depth };\n  }\n  const past = [...stack.past, entry];\n  while (past.length > stack.depth) past.shift();\n  return { past, future: [], depth: stack.depth };\n}\n\nexport function popUndo(stack: UndoStack): { stack: UndoStack; entry: UndoEntry | null } {\n  const entry = stack.past[stack.past.length - 1];\n  if (entry === undefined) return { stack, entry: null };\n  return {\n    stack: {\n      past: stack.past.slice(0, -1),\n      future: [...stack.future, entry],\n      depth: stack.depth,\n    },\n    entry,\n  };\n}\n\nexport function popRedo(stack: UndoStack): { stack: UndoStack; entry: UndoEntry | null } {\n  const entry = stack.future[stack.future.length - 1];\n  if (entry === undefined) return { stack, entry: null };\n  const past = [...stack.past, entry];\n  while (past.length > stack.depth) past.shift();\n  return {\n    stack: { past, future: stack.future.slice(0, -1), depth: stack.depth },\n    entry,\n  };\n}\n\nfunction keyOf(patch: CellPatch): string {\n  // JSON, not a separator character: a row id or column id containing whatever\n  // separator we picked would collide two different cells into one key, and the\n  // undo would restore the wrong one.\n  return JSON.stringify([patch.rowId, patch.columnId]);\n}\n\n/**\n * Build an entry from a before/after pair, so a caller never assembles one by\n * hand — hand-assembled inverses are how an undo ends up restoring the wrong\n * cell.\n *\n * An after-patch with NO matching before is still undoable: its undo sets the\n * value back to `null`. That is the added-row case — a cell that did not exist\n * before the change has no prior value, and \"undo\" for it means empty, not\n * \"leave whatever is there\".\n */\nexport function undoEntryFor(\n  before: CellPatch[],\n  after: CellPatch[],\n  label: string,\n): UndoEntry {\n  const priors = new Map<string, CellPatch>();\n  for (const patch of before) priors.set(keyOf(patch), patch);\n\n  const undo: CellPatch[] = after.map((patch) => {\n    const prior = priors.get(keyOf(patch));\n    return {\n      rowId: patch.rowId,\n      columnId: patch.columnId,\n      value: prior ? prior.value : null,\n    };\n  });\n\n  return {\n    label,\n    undo,\n    redo: after.map((patch) => ({\n      rowId: patch.rowId,\n      columnId: patch.columnId,\n      value: patch.value,\n    })),\n  };\n}\n\n/** True when there is a step to take back. */\nexport function canUndo(stack: UndoStack): boolean {\n  return stack.depth > 0 && stack.past.length > 0;\n}\n\n/** True when there is a step to reapply. */\nexport function canRedo(stack: UndoStack): boolean {\n  return stack.depth > 0 && stack.future.length > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsDO,IAAM,qBAAqB;AAE3B,SAAS,gBAAgB,QAAgB,oBAA+B;AAC7E,QAAM,UAAU,OAAO,SAAS,KAAK,KAAK,QAAQ,IAAI,KAAK,MAAM,KAAK,IAAI;AAC1E,SAAO,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,OAAO,QAAQ;AAChD;AASO,SAAS,SAAS,OAAkB,OAA6B;AACtE,MAAI,MAAM,SAAS,GAAG;AAGpB,WAAO,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,OAAO,MAAM,MAAM;AAAA,EACpD;AACA,QAAM,OAAO,CAAC,GAAG,MAAM,MAAM,KAAK;AAClC,SAAO,KAAK,SAAS,MAAM,MAAO,MAAK,MAAM;AAC7C,SAAO,EAAE,MAAM,QAAQ,CAAC,GAAG,OAAO,MAAM,MAAM;AAChD;AAEO,SAAS,QAAQ,OAAiE;AACvF,QAAM,QAAQ,MAAM,KAAK,MAAM,KAAK,SAAS,CAAC;AAC9C,MAAI,UAAU,OAAW,QAAO,EAAE,OAAO,OAAO,KAAK;AACrD,SAAO;AAAA,IACL,OAAO;AAAA,MACL,MAAM,MAAM,KAAK,MAAM,GAAG,EAAE;AAAA,MAC5B,QAAQ,CAAC,GAAG,MAAM,QAAQ,KAAK;AAAA,MAC/B,OAAO,MAAM;AAAA,IACf;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,QAAQ,OAAiE;AACvF,QAAM,QAAQ,MAAM,OAAO,MAAM,OAAO,SAAS,CAAC;AAClD,MAAI,UAAU,OAAW,QAAO,EAAE,OAAO,OAAO,KAAK;AACrD,QAAM,OAAO,CAAC,GAAG,MAAM,MAAM,KAAK;AAClC,SAAO,KAAK,SAAS,MAAM,MAAO,MAAK,MAAM;AAC7C,SAAO;AAAA,IACL,OAAO,EAAE,MAAM,QAAQ,MAAM,OAAO,MAAM,GAAG,EAAE,GAAG,OAAO,MAAM,MAAM;AAAA,IACrE;AAAA,EACF;AACF;AAEA,SAAS,MAAM,OAA0B;AAIvC,SAAO,KAAK,UAAU,CAAC,MAAM,OAAO,MAAM,QAAQ,CAAC;AACrD;AAYO,SAAS,aACd,QACA,OACA,OACW;AACX,QAAM,SAAS,oBAAI,IAAuB;AAC1C,aAAW,SAAS,OAAQ,QAAO,IAAI,MAAM,KAAK,GAAG,KAAK;AAE1D,QAAM,OAAoB,MAAM,IAAI,CAAC,UAAU;AAC7C,UAAM,QAAQ,OAAO,IAAI,MAAM,KAAK,CAAC;AACrC,WAAO;AAAA,MACL,OAAO,MAAM;AAAA,MACb,UAAU,MAAM;AAAA,MAChB,OAAO,QAAQ,MAAM,QAAQ;AAAA,IAC/B;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,MAAM,MAAM,IAAI,CAAC,WAAW;AAAA,MAC1B,OAAO,MAAM;AAAA,MACb,UAAU,MAAM;AAAA,MAChB,OAAO,MAAM;AAAA,IACf,EAAE;AAAA,EACJ;AACF;AAGO,SAAS,QAAQ,OAA2B;AACjD,SAAO,MAAM,QAAQ,KAAK,MAAM,KAAK,SAAS;AAChD;AAGO,SAAS,QAAQ,OAA2B;AACjD,SAAO,MAAM,QAAQ,KAAK,MAAM,OAAO,SAAS;AAClD;","names":[]}

package/dist/data-table/cell-undo.d.cts

@@ -0,0 +1,85 @@
+import { CellPatch } from './fill.cjs';
+
+/**
+ * THE CELL UNDO STACK — the model behind Cmd-Z in a grid.
+ *
+ * WHY IT SHIPS WITH EASY EDITING, NOT AFTER IT. Lowering the friction to change
+ * data raises the rate of accidental change: a click toggles a boolean, a bare
+ * keystroke starts an edit, Delete empties a cell, and one drag of the fill
+ * handle rewrites a column. Every one of those is a good affordance ONLY if the
+ * floor underneath it is recoverable.
+ *
+ * WHAT THIS FILE IS. A bounded, PURE stack of reversible edits: no React, no
+ * network, no toasts. The app's `useCellUndo` hook owned all three plus the
+ * stack, which meant the stack's rules — depth, the redo contract, what an undo
+ * of an added row means — could only be exercised by mounting a component and
+ * mocking a database. Those rules are spreadsheet law, not app trivia, so they
+ * belong in a module anyone can test in a millisecond and any client can reuse.
+ *
+ * WHY IT IS PATCHES, NOT CELL COORDINATES. An entry carries the patches that
+ * undo it and the patches that redo it, captured BEFORE the write and never
+ * derived after it: re-reading a cell later to discover what to restore races
+ * with realtime and with agent writes, and would happily "undo" to a value
+ * somebody else just set. Patches also make the entry shape indifferent to WHAT
+ * changed — one cell, a filled column, or the cells of a row that was added or
+ * deleted — which is how row and column operations join the same Cmd-Z the user
+ * already trusts instead of living outside it.
+ *
+ * PURITY IS THE POINT. Every function returns a NEW stack and never mutates the
+ * one it was handed, so the stack can live in React state, in a store, or in a
+ * ref without the "my undo history changed under me" class of bug.
+ */
+
+interface UndoEntry {
+    /** What the user did, in plain English, for the toast: "Undid the change to Day rate." */
+    label: string;
+    /** The patches that UNDO it. */
+    undo: CellPatch[];
+    /** The patches that REDO it. */
+    redo: CellPatch[];
+}
+interface UndoStack {
+    past: UndoEntry[];
+    future: UndoEntry[];
+    depth: number;
+}
+/**
+ * How many steps back we remember. Deliberately generous — the cost is a few
+ * kilobytes of session memory, and the failure mode of a too-short stack is a
+ * user discovering their mistake is unrecoverable.
+ */
+declare const DEFAULT_UNDO_DEPTH = 100;
+declare function createUndoStack(depth?: number): UndoStack;
+/**
+ * Record an edit that already happened.
+ *
+ * Pushing CLEARS the redo future — the standard editor contract: you cannot
+ * redo into a future you have just diverged from. Past `depth`, the OLDEST
+ * entry is dropped, so the stack is bounded memory rather than a leak.
+ */
+declare function pushUndo(stack: UndoStack, entry: UndoEntry): UndoStack;
+declare function popUndo(stack: UndoStack): {
+    stack: UndoStack;
+    entry: UndoEntry | null;
+};
+declare function popRedo(stack: UndoStack): {
+    stack: UndoStack;
+    entry: UndoEntry | null;
+};
+/**
+ * Build an entry from a before/after pair, so a caller never assembles one by
+ * hand — hand-assembled inverses are how an undo ends up restoring the wrong
+ * cell.
+ *
+ * An after-patch with NO matching before is still undoable: its undo sets the
+ * value back to `null`. That is the added-row case — a cell that did not exist
+ * before the change has no prior value, and "undo" for it means empty, not
+ * "leave whatever is there".
+ */
+declare function undoEntryFor(before: CellPatch[], after: CellPatch[], label: string): UndoEntry;
+/** True when there is a step to take back. */
+declare function canUndo(stack: UndoStack): boolean;
+/** True when there is a step to reapply. */
+declare function canRedo(stack: UndoStack): boolean;
+
+export { CellPatch, DEFAULT_UNDO_DEPTH, type UndoEntry, type UndoStack, canRedo, canUndo, createUndoStack, popRedo, popUndo, pushUndo, undoEntryFor };

package/dist/data-table/cell-undo.d.ts

@@ -0,0 +1,85 @@
+import { CellPatch } from './fill.js';
+
+/**
+ * THE CELL UNDO STACK — the model behind Cmd-Z in a grid.
+ *
+ * WHY IT SHIPS WITH EASY EDITING, NOT AFTER IT. Lowering the friction to change
+ * data raises the rate of accidental change: a click toggles a boolean, a bare
+ * keystroke starts an edit, Delete empties a cell, and one drag of the fill
+ * handle rewrites a column. Every one of those is a good affordance ONLY if the
+ * floor underneath it is recoverable.
+ *
+ * WHAT THIS FILE IS. A bounded, PURE stack of reversible edits: no React, no
+ * network, no toasts. The app's `useCellUndo` hook owned all three plus the
+ * stack, which meant the stack's rules — depth, the redo contract, what an undo
+ * of an added row means — could only be exercised by mounting a component and
+ * mocking a database. Those rules are spreadsheet law, not app trivia, so they
+ * belong in a module anyone can test in a millisecond and any client can reuse.
+ *
+ * WHY IT IS PATCHES, NOT CELL COORDINATES. An entry carries the patches that
+ * undo it and the patches that redo it, captured BEFORE the write and never
+ * derived after it: re-reading a cell later to discover what to restore races
+ * with realtime and with agent writes, and would happily "undo" to a value
+ * somebody else just set. Patches also make the entry shape indifferent to WHAT
+ * changed — one cell, a filled column, or the cells of a row that was added or
+ * deleted — which is how row and column operations join the same Cmd-Z the user
+ * already trusts instead of living outside it.
+ *
+ * PURITY IS THE POINT. Every function returns a NEW stack and never mutates the
+ * one it was handed, so the stack can live in React state, in a store, or in a
+ * ref without the "my undo history changed under me" class of bug.
+ */
+
+interface UndoEntry {
+    /** What the user did, in plain English, for the toast: "Undid the change to Day rate." */
+    label: string;
+    /** The patches that UNDO it. */
+    undo: CellPatch[];
+    /** The patches that REDO it. */
+    redo: CellPatch[];
+}
+interface UndoStack {
+    past: UndoEntry[];
+    future: UndoEntry[];
+    depth: number;
+}
+/**
+ * How many steps back we remember. Deliberately generous — the cost is a few
+ * kilobytes of session memory, and the failure mode of a too-short stack is a
+ * user discovering their mistake is unrecoverable.
+ */
+declare const DEFAULT_UNDO_DEPTH = 100;
+declare function createUndoStack(depth?: number): UndoStack;
+/**
+ * Record an edit that already happened.
+ *
+ * Pushing CLEARS the redo future — the standard editor contract: you cannot
+ * redo into a future you have just diverged from. Past `depth`, the OLDEST
+ * entry is dropped, so the stack is bounded memory rather than a leak.
+ */
+declare function pushUndo(stack: UndoStack, entry: UndoEntry): UndoStack;
+declare function popUndo(stack: UndoStack): {
+    stack: UndoStack;
+    entry: UndoEntry | null;
+};
+declare function popRedo(stack: UndoStack): {
+    stack: UndoStack;
+    entry: UndoEntry | null;
+};
+/**
+ * Build an entry from a before/after pair, so a caller never assembles one by
+ * hand — hand-assembled inverses are how an undo ends up restoring the wrong
+ * cell.
+ *
+ * An after-patch with NO matching before is still undoable: its undo sets the
+ * value back to `null`. That is the added-row case — a cell that did not exist
+ * before the change has no prior value, and "undo" for it means empty, not
+ * "leave whatever is there".
+ */
+declare function undoEntryFor(before: CellPatch[], after: CellPatch[], label: string): UndoEntry;
+/** True when there is a step to take back. */
+declare function canUndo(stack: UndoStack): boolean;
+/** True when there is a step to reapply. */
+declare function canRedo(stack: UndoStack): boolean;
+
+export { CellPatch, DEFAULT_UNDO_DEPTH, type UndoEntry, type UndoStack, canRedo, canUndo, createUndoStack, popRedo, popUndo, pushUndo, undoEntryFor };

package/dist/data-table/cell-undo.js

@@ -0,0 +1,78 @@
+
+// src/data-table/cell-undo.ts
+var DEFAULT_UNDO_DEPTH = 100;
+function createUndoStack(depth = DEFAULT_UNDO_DEPTH) {
+  const bounded = Number.isFinite(depth) && depth > 0 ? Math.floor(depth) : 0;
+  return { past: [], future: [], depth: bounded };
+}
+function pushUndo(stack, entry) {
+  if (stack.depth <= 0) {
+    return { past: [], future: [], depth: stack.depth };
+  }
+  const past = [...stack.past, entry];
+  while (past.length > stack.depth) past.shift();
+  return { past, future: [], depth: stack.depth };
+}
+function popUndo(stack) {
+  const entry = stack.past[stack.past.length - 1];
+  if (entry === void 0) return { stack, entry: null };
+  return {
+    stack: {
+      past: stack.past.slice(0, -1),
+      future: [...stack.future, entry],
+      depth: stack.depth
+    },
+    entry
+  };
+}
+function popRedo(stack) {
+  const entry = stack.future[stack.future.length - 1];
+  if (entry === void 0) return { stack, entry: null };
+  const past = [...stack.past, entry];
+  while (past.length > stack.depth) past.shift();
+  return {
+    stack: { past, future: stack.future.slice(0, -1), depth: stack.depth },
+    entry
+  };
+}
+function keyOf(patch) {
+  return JSON.stringify([patch.rowId, patch.columnId]);
+}
+function undoEntryFor(before, after, label) {
+  const priors = /* @__PURE__ */ new Map();
+  for (const patch of before) priors.set(keyOf(patch), patch);
+  const undo = after.map((patch) => {
+    const prior = priors.get(keyOf(patch));
+    return {
+      rowId: patch.rowId,
+      columnId: patch.columnId,
+      value: prior ? prior.value : null
+    };
+  });
+  return {
+    label,
+    undo,
+    redo: after.map((patch) => ({
+      rowId: patch.rowId,
+      columnId: patch.columnId,
+      value: patch.value
+    }))
+  };
+}
+function canUndo(stack) {
+  return stack.depth > 0 && stack.past.length > 0;
+}
+function canRedo(stack) {
+  return stack.depth > 0 && stack.future.length > 0;
+}
+export {
+  DEFAULT_UNDO_DEPTH,
+  canRedo,
+  canUndo,
+  createUndoStack,
+  popRedo,
+  popUndo,
+  pushUndo,
+  undoEntryFor
+};
+//# sourceMappingURL=cell-undo.js.map

package/dist/data-table/cell-undo.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/cell-undo.ts"],"sourcesContent":["/**\n * THE CELL UNDO STACK — the model behind Cmd-Z in a grid.\n *\n * WHY IT SHIPS WITH EASY EDITING, NOT AFTER IT. Lowering the friction to change\n * data raises the rate of accidental change: a click toggles a boolean, a bare\n * keystroke starts an edit, Delete empties a cell, and one drag of the fill\n * handle rewrites a column. Every one of those is a good affordance ONLY if the\n * floor underneath it is recoverable.\n *\n * WHAT THIS FILE IS. A bounded, PURE stack of reversible edits: no React, no\n * network, no toasts. The app's `useCellUndo` hook owned all three plus the\n * stack, which meant the stack's rules — depth, the redo contract, what an undo\n * of an added row means — could only be exercised by mounting a component and\n * mocking a database. Those rules are spreadsheet law, not app trivia, so they\n * belong in a module anyone can test in a millisecond and any client can reuse.\n *\n * WHY IT IS PATCHES, NOT CELL COORDINATES. An entry carries the patches that\n * undo it and the patches that redo it, captured BEFORE the write and never\n * derived after it: re-reading a cell later to discover what to restore races\n * with realtime and with agent writes, and would happily \"undo\" to a value\n * somebody else just set. Patches also make the entry shape indifferent to WHAT\n * changed — one cell, a filled column, or the cells of a row that was added or\n * deleted — which is how row and column operations join the same Cmd-Z the user\n * already trusts instead of living outside it.\n *\n * PURITY IS THE POINT. Every function returns a NEW stack and never mutates the\n * one it was handed, so the stack can live in React state, in a store, or in a\n * ref without the \"my undo history changed under me\" class of bug.\n */\n\nimport type { CellPatch } from \"./fill\";\n\nexport type { CellPatch };\n\nexport interface UndoEntry {\n  /** What the user did, in plain English, for the toast: \"Undid the change to Day rate.\" */\n  label: string;\n  /** The patches that UNDO it. */\n  undo: CellPatch[];\n  /** The patches that REDO it. */\n  redo: CellPatch[];\n}\n\nexport interface UndoStack {\n  past: UndoEntry[];\n  future: UndoEntry[];\n  depth: number;\n}\n\n/**\n * How many steps back we remember. Deliberately generous — the cost is a few\n * kilobytes of session memory, and the failure mode of a too-short stack is a\n * user discovering their mistake is unrecoverable.\n */\nexport const DEFAULT_UNDO_DEPTH = 100;\n\nexport function createUndoStack(depth: number = DEFAULT_UNDO_DEPTH): UndoStack {\n  const bounded = Number.isFinite(depth) && depth > 0 ? Math.floor(depth) : 0;\n  return { past: [], future: [], depth: bounded };\n}\n\n/**\n * Record an edit that already happened.\n *\n * Pushing CLEARS the redo future — the standard editor contract: you cannot\n * redo into a future you have just diverged from. Past `depth`, the OLDEST\n * entry is dropped, so the stack is bounded memory rather than a leak.\n */\nexport function pushUndo(stack: UndoStack, entry: UndoEntry): UndoStack {\n  if (stack.depth <= 0) {\n    // Undo is off. Pushing keeps the stack empty rather than silently growing\n    // a history nothing will ever read.\n    return { past: [], future: [], depth: stack.depth };\n  }\n  const past = [...stack.past, entry];\n  while (past.length > stack.depth) past.shift();\n  return { past, future: [], depth: stack.depth };\n}\n\nexport function popUndo(stack: UndoStack): { stack: UndoStack; entry: UndoEntry | null } {\n  const entry = stack.past[stack.past.length - 1];\n  if (entry === undefined) return { stack, entry: null };\n  return {\n    stack: {\n      past: stack.past.slice(0, -1),\n      future: [...stack.future, entry],\n      depth: stack.depth,\n    },\n    entry,\n  };\n}\n\nexport function popRedo(stack: UndoStack): { stack: UndoStack; entry: UndoEntry | null } {\n  const entry = stack.future[stack.future.length - 1];\n  if (entry === undefined) return { stack, entry: null };\n  const past = [...stack.past, entry];\n  while (past.length > stack.depth) past.shift();\n  return {\n    stack: { past, future: stack.future.slice(0, -1), depth: stack.depth },\n    entry,\n  };\n}\n\nfunction keyOf(patch: CellPatch): string {\n  // JSON, not a separator character: a row id or column id containing whatever\n  // separator we picked would collide two different cells into one key, and the\n  // undo would restore the wrong one.\n  return JSON.stringify([patch.rowId, patch.columnId]);\n}\n\n/**\n * Build an entry from a before/after pair, so a caller never assembles one by\n * hand — hand-assembled inverses are how an undo ends up restoring the wrong\n * cell.\n *\n * An after-patch with NO matching before is still undoable: its undo sets the\n * value back to `null`. That is the added-row case — a cell that did not exist\n * before the change has no prior value, and \"undo\" for it means empty, not\n * \"leave whatever is there\".\n */\nexport function undoEntryFor(\n  before: CellPatch[],\n  after: CellPatch[],\n  label: string,\n): UndoEntry {\n  const priors = new Map<string, CellPatch>();\n  for (const patch of before) priors.set(keyOf(patch), patch);\n\n  const undo: CellPatch[] = after.map((patch) => {\n    const prior = priors.get(keyOf(patch));\n    return {\n      rowId: patch.rowId,\n      columnId: patch.columnId,\n      value: prior ? prior.value : null,\n    };\n  });\n\n  return {\n    label,\n    undo,\n    redo: after.map((patch) => ({\n      rowId: patch.rowId,\n      columnId: patch.columnId,\n      value: patch.value,\n    })),\n  };\n}\n\n/** True when there is a step to take back. */\nexport function canUndo(stack: UndoStack): boolean {\n  return stack.depth > 0 && stack.past.length > 0;\n}\n\n/** True when there is a step to reapply. */\nexport function canRedo(stack: UndoStack): boolean {\n  return stack.depth > 0 && stack.future.length > 0;\n}\n"],"mappings":";;AAsDO,IAAM,qBAAqB;AAE3B,SAAS,gBAAgB,QAAgB,oBAA+B;AAC7E,QAAM,UAAU,OAAO,SAAS,KAAK,KAAK,QAAQ,IAAI,KAAK,MAAM,KAAK,IAAI;AAC1E,SAAO,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,OAAO,QAAQ;AAChD;AASO,SAAS,SAAS,OAAkB,OAA6B;AACtE,MAAI,MAAM,SAAS,GAAG;AAGpB,WAAO,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,OAAO,MAAM,MAAM;AAAA,EACpD;AACA,QAAM,OAAO,CAAC,GAAG,MAAM,MAAM,KAAK;AAClC,SAAO,KAAK,SAAS,MAAM,MAAO,MAAK,MAAM;AAC7C,SAAO,EAAE,MAAM,QAAQ,CAAC,GAAG,OAAO,MAAM,MAAM;AAChD;AAEO,SAAS,QAAQ,OAAiE;AACvF,QAAM,QAAQ,MAAM,KAAK,MAAM,KAAK,SAAS,CAAC;AAC9C,MAAI,UAAU,OAAW,QAAO,EAAE,OAAO,OAAO,KAAK;AACrD,SAAO;AAAA,IACL,OAAO;AAAA,MACL,MAAM,MAAM,KAAK,MAAM,GAAG,EAAE;AAAA,MAC5B,QAAQ,CAAC,GAAG,MAAM,QAAQ,KAAK;AAAA,MAC/B,OAAO,MAAM;AAAA,IACf;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,QAAQ,OAAiE;AACvF,QAAM,QAAQ,MAAM,OAAO,MAAM,OAAO,SAAS,CAAC;AAClD,MAAI,UAAU,OAAW,QAAO,EAAE,OAAO,OAAO,KAAK;AACrD,QAAM,OAAO,CAAC,GAAG,MAAM,MAAM,KAAK;AAClC,SAAO,KAAK,SAAS,MAAM,MAAO,MAAK,MAAM;AAC7C,SAAO;AAAA,IACL,OAAO,EAAE,MAAM,QAAQ,MAAM,OAAO,MAAM,GAAG,EAAE,GAAG,OAAO,MAAM,MAAM;AAAA,IACrE;AAAA,EACF;AACF;AAEA,SAAS,MAAM,OAA0B;AAIvC,SAAO,KAAK,UAAU,CAAC,MAAM,OAAO,MAAM,QAAQ,CAAC;AACrD;AAYO,SAAS,aACd,QACA,OACA,OACW;AACX,QAAM,SAAS,oBAAI,IAAuB;AAC1C,aAAW,SAAS,OAAQ,QAAO,IAAI,MAAM,KAAK,GAAG,KAAK;AAE1D,QAAM,OAAoB,MAAM,IAAI,CAAC,UAAU;AAC7C,UAAM,QAAQ,OAAO,IAAI,MAAM,KAAK,CAAC;AACrC,WAAO;AAAA,MACL,OAAO,MAAM;AAAA,MACb,UAAU,MAAM;AAAA,MAChB,OAAO,QAAQ,MAAM,QAAQ;AAAA,IAC/B;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,MAAM,MAAM,IAAI,CAAC,WAAW;AAAA,MAC1B,OAAO,MAAM;AAAA,MACb,UAAU,MAAM;AAAA,MAChB,OAAO,MAAM;AAAA,IACf,EAAE;AAAA,EACJ;AACF;AAGO,SAAS,QAAQ,OAA2B;AACjD,SAAO,MAAM,QAAQ,KAAK,MAAM,KAAK,SAAS;AAChD;AAGO,SAAS,QAAQ,OAA2B;AACjD,SAAO,MAAM,QAAQ,KAAK,MAAM,OAAO,SAAS;AAClD;","names":[]}

package/dist/data-table/copy-helpers.d.cts

@@ -1,10 +1,14 @@
 import { AgentPayloadInput } from './copy-types.cjs';
-import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-Sn249eoy.cjs';
+import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-CmQrOz-T.cjs';
 import '../content-transfer.cjs';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.cjs';
-import '../types-BdbvlF9-.cjs';
+import '../types-CJWU1Gae.cjs';
+import './grouping.cjs';
+import './fill.cjs';
+import './spreadsheet.cjs';
+import './grid-selection.cjs';
 
 /**
  * Typed, declared-column capture for MatrxDataTable's built-in Alchemy source.

package/dist/data-table/copy-helpers.d.ts

@@ -1,10 +1,14 @@
 import { AgentPayloadInput } from './copy-types.js';
-import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-D-flTpK0.js';
+import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-nlLCMiqd.js';
 import '../content-transfer.js';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.js';
-import '../types-BdbvlF9-.js';
+import '../types-CJWU1Gae.js';
+import './grouping.js';
+import './fill.js';
+import './spreadsheet.js';
+import './grid-selection.js';
 
 /**
  * Typed, declared-column capture for MatrxDataTable's built-in Alchemy source.