@ai-matrx/design-system 0.28.0 → 0.31.0

package/dist/data-table/spreadsheet.d.ts

@@ -33,6 +33,46 @@ import { CellPatch } from './fill.js';
 
 /** What a set of cell patches was for, so a consumer can label its own toast. */
 type SpreadsheetIntent = "paste" | "fill" | "fill-down" | "undo" | "redo" | "clear";
+/** One cell a paste did not write, with the sentence that says why. */
+interface PasteRefusal {
+    /** Null when the cell belongs to no row on the grid. */
+    rowId: string | null;
+    columnId: string;
+    reason: string;
+    /**
+     * WHAT WAS REFUSED, kept rather than dropped.
+     *
+     * Without it a consumer showing a person their fifty pasted rows can say a
+     * cell was skipped but not WHICH one or what was in it — measured on Rincon
+     * Plumbing's September billing run, 2026-09-21: every refusal on an existing
+     * record read "Row 0, amount_due" because the value never reached the code
+     * that knew the line and the column's name. A refusal nobody can locate is
+     * only half a refusal.
+     */
+    value?: unknown;
+}
+/**
+ * What a paste WOULD do, handed over before any of it happens.
+ *
+ * Addresses are (rowId, columnId) like everywhere else in the grid, never
+ * indices — a row filtered out between the copy and the paste is not a row.
+ */
+interface SpreadsheetPastePlan {
+    /** The cells that would be written, already screened by `validateCell`. */
+    accepted: CellPatch[];
+    /** Cells `validateCell` or `writableColumnIds` turned away, each with its sentence. */
+    refusals: PasteRefusal[];
+    /**
+     * Rows of the pasted block that fell past the last row of the grid, in the
+     * grid's current column order (so a hidden or reordered column is honoured).
+     * Each entry maps a columnId to the raw clipboard text for that cell.
+     */
+    overflow: Array<Record<string, string>>;
+    /** Cells that fell past the RIGHT edge — there is no column to hold them. */
+    pastRightEdge: number;
+    /** Write `accepted` through `onPatch`, exactly as an unconfirmed paste would. */
+    apply: () => Promise<void>;
+}
 interface SpreadsheetGridOptions {
     /** Row ids currently rendered, in visual order. */
     rowIds: readonly string[];
@@ -54,6 +94,11 @@ interface SpreadsheetGridOptions {
     paste?: boolean | undefined;
     /** Says what just happened, and why something did not. */
     notify?: ((message: string) => void) | undefined;
+    /**
+     * Hand the whole paste over instead of applying it. See
+     * `MatrxDataTableSpreadsheetConfig.onPastePlan` for why this exists.
+     */
+    onPastePlan?: ((plan: SpreadsheetPastePlan) => void) | undefined;
     /**
      * OPEN THE EDITOR on the focused cell. Return true when the editor actually
      * opened, so the keystroke is consumed; return false and the key is left to
@@ -150,4 +195,4 @@ interface SpreadsheetClipboardEvent {
 declare const NOTHING: CellPatch[];
 declare function useSpreadsheetGrid(options: SpreadsheetGridOptions | null): SpreadsheetGrid;
 
-export { NOTHING as NO_PATCHES, type SpreadsheetCellProps, type SpreadsheetClipboardEvent, type SpreadsheetGrid, type SpreadsheetGridOptions, type SpreadsheetIntent, type SpreadsheetKeyEvent, useSpreadsheetGrid };
+export { NOTHING as NO_PATCHES, type PasteRefusal, type SpreadsheetCellProps, type SpreadsheetClipboardEvent, type SpreadsheetGrid, type SpreadsheetGridOptions, type SpreadsheetIntent, type SpreadsheetKeyEvent, type SpreadsheetPastePlan, useSpreadsheetGrid };

package/dist/data-table/spreadsheet.js

@@ -657,7 +657,7 @@ function useSpreadsheetGrid(options) {
         } catch {
           reason = void 0;
         }
-        if (reason) refusals.push({ columnId: patch.columnId, reason });
+        if (reason) refusals.push({ rowId: patch.rowId, columnId: patch.columnId, reason, value: patch.value });
         else accepted.push(patch);
       }
       return { accepted, refusals };
@@ -736,6 +736,7 @@ function useSpreadsheetGrid(options) {
         if (rowId === void 0 || columnId === void 0) continue;
         if (!current.isColumnWritable(columnId)) {
           skipped.push({
+            rowId,
             columnId,
             reason: current.columnRefusal?.(columnId) ?? `${columnId} cannot be cleared.`
           });
@@ -899,18 +900,33 @@ function useSpreadsheetGrid(options) {
       if (startRow === -1 || startCol === -1) return;
       const patches = [];
       const skipped = [];
-      let outside = 0;
+      let pastRightEdge = 0;
+      const overflow = [];
       for (let r = 0; r < block.length; r += 1) {
         const line = block[r] ?? [];
+        const rowId = rowIds[startRow + r];
+        if (rowId === void 0) {
+          const beyond = {};
+          for (let c = 0; c < line.length; c += 1) {
+            const columnId = columnIds[startCol + c];
+            if (columnId === void 0) {
+              pastRightEdge += 1;
+              continue;
+            }
+            beyond[columnId] = line[c] ?? "";
+          }
+          overflow.push(beyond);
+          continue;
+        }
         for (let c = 0; c < line.length; c += 1) {
-          const rowId = rowIds[startRow + r];
           const columnId = columnIds[startCol + c];
-          if (rowId === void 0 || columnId === void 0) {
-            outside += 1;
+          if (columnId === void 0) {
+            pastRightEdge += 1;
             continue;
           }
           if (!current.isColumnWritable(columnId)) {
             skipped.push({
+              rowId,
               columnId,
               reason: current.columnRefusal?.(columnId) ?? `${columnId} cannot take a pasted value.`
             });
@@ -920,9 +936,24 @@ function useSpreadsheetGrid(options) {
         }
       }
       const screened = screenPatches(patches);
+      const refusals = [...skipped, ...screened.refusals];
+      if (current.onPastePlan) {
+        const accepted = screened.accepted;
+        current.onPastePlan({
+          accepted,
+          refusals,
+          overflow,
+          pastRightEdge,
+          apply: async () => {
+            await applyPatches(accepted, "paste", "Pasted");
+          }
+        });
+        return;
+      }
       void applyPatches(screened.accepted, "paste", "Pasted");
+      const outside = pastRightEdge + overflow.reduce((n, row) => n + Object.keys(row).length, 0);
       const tail = outside > 0 ? ` ${outside} landed past the edge of the table and were ignored.` : "";
-      announceSkips([...skipped, ...screened.refusals], `Pasted ${screened.accepted.length} cells.${tail}`);
+      announceSkips(refusals, `Pasted ${screened.accepted.length} cells.${tail}`);
     },
     [range, rowIds, columnIds, applyPatches, announceSkips, screenPatches]
   );