@ai-matrx/design-system 0.41.0 → 0.42.1

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

@@ -84,8 +84,23 @@ interface SpreadsheetGridOptions {
     isColumnWritable: (columnId: string) => boolean;
     /** Why a column refuses, as a sentence. Used in the skip list. */
     columnRefusal?: ((columnId: string) => string | undefined) | undefined;
-    /** Applies a batch of writes. The consumer owns the door. */
-    onPatch: (patches: CellPatch[], intent: SpreadsheetIntent) => void | Promise<void>;
+    /**
+     * Applies a batch of writes. The consumer owns the door. Optional only for a
+     * `readOnly` grid, which never writes; a writable grid without it refuses
+     * every write out loud rather than dropping it.
+     */
+    onPatch?: ((patches: CellPatch[], intent: SpreadsheetIntent) => void | Promise<void>) | undefined;
+    /**
+     * SELECT AND COPY, NEVER CHANGE. A reader gets the whole range cursor — click,
+     * drag, shift-click, arrows, select-all, Cmd-C — and no gesture that writes:
+     * no fill handle, and cut, paste, clear, fill-down, undo and redo each say
+     * `readOnlyReason` instead of doing anything. Separate from editing on
+     * purpose: whether a person may CHANGE a table is not whether they may COPY
+     * a range out of it.
+     */
+    readOnly?: boolean | undefined;
+    /** The sentence a refused write says on a read-only grid. */
+    readOnlyReason?: string | undefined;
     /** 0 turns undo off. */
     undoDepth?: number | undefined;
     /** The little square at the corner of a selection. */
@@ -198,6 +213,8 @@ interface SpreadsheetClipboardEvent {
     preventDefault: () => void;
 }
 declare const NOTHING: CellPatch[];
+/** What a refused write says on a read-only grid when the consumer names nothing better. */
+declare const READ_ONLY_REASON = "This table is view-only \u2014 you can select and copy, but not change cells.";
 declare function useSpreadsheetGrid(options: SpreadsheetGridOptions | null): SpreadsheetGrid;
 
-export { NOTHING as NO_PATCHES, type PasteRefusal, type SpreadsheetCellProps, type SpreadsheetClipboardEvent, type SpreadsheetGrid, type SpreadsheetGridOptions, type SpreadsheetIntent, type SpreadsheetKeyEvent, type SpreadsheetPastePlan, useSpreadsheetGrid };
+export { NOTHING as NO_PATCHES, type PasteRefusal, READ_ONLY_REASON, type SpreadsheetCellProps, type SpreadsheetClipboardEvent, type SpreadsheetGrid, type SpreadsheetGridOptions, type SpreadsheetIntent, type SpreadsheetKeyEvent, type SpreadsheetPastePlan, useSpreadsheetGrid };

package/dist/data-table/spreadsheet.js

@@ -624,6 +624,7 @@ function camePastAPortalIntoTheContainer(target) {
   return element.closest('[data-matrx-table-spreadsheet="true"]') === null;
 }
 var NOTHING = [];
+var READ_ONLY_REASON = "This table is view-only \u2014 you can select and copy, but not change cells.";
 function useSpreadsheetGrid(options) {
   const [range, setRange] = useState(null);
   const [fillTarget, setFillTarget] = useState(null);
@@ -690,10 +691,18 @@ function useSpreadsheetGrid(options) {
         }));
         setStack((previous) => pushUndo(previous, undoEntryFor(before, patches, label)));
       }
+      if (!current.onPatch) return;
       await current.onPatch(patches, intent);
     },
     []
   );
+  const refuseWrite = useCallback(() => {
+    const current = optionsRef.current;
+    if (!current) return true;
+    if (!current.readOnly && current.onPatch) return false;
+    current.notify?.(current.readOnlyReason ?? READ_ONLY_REASON);
+    return true;
+  }, []);
   const readValueAt = useCallback((rowIndex, columnIndex) => {
     const current = optionsRef.current;
     const rowId = current?.rowIds[rowIndex];
@@ -727,6 +736,7 @@ function useSpreadsheetGrid(options) {
     []
   );
   const doFillDown = useCallback(async () => {
+    if (refuseWrite()) return;
     const base = fillRequestBase();
     if (!base || !bounds) return;
     const result = fillDown({
@@ -736,8 +746,9 @@ function useSpreadsheetGrid(options) {
     const screened = screenPatches(result.patches);
     await applyPatches(screened.accepted, "fill-down", "Filled down");
     announceSkips([...result.skipped, ...screened.refusals], result.summary);
-  }, [fillRequestBase, bounds, applyPatches, announceSkips, screenPatches]);
+  }, [fillRequestBase, bounds, applyPatches, announceSkips, screenPatches, refuseWrite]);
   const doClear = useCallback(async () => {
+    if (refuseWrite()) return;
     const current = optionsRef.current;
     if (!current || !bounds) return;
     const patches = [];
@@ -764,20 +775,22 @@ function useSpreadsheetGrid(options) {
       [...skipped, ...screened.refusals],
       `Cleared ${screened.accepted.length} cells.`
     );
-  }, [bounds, applyPatches, announceSkips, screenPatches]);
+  }, [bounds, applyPatches, announceSkips, screenPatches, refuseWrite]);
   const doUndo = useCallback(async () => {
+    if (refuseWrite()) return;
     const taken = popUndo(stack);
     if (!taken.entry) return;
     setStack(taken.stack);
     await applyPatches(taken.entry.undo, "undo", taken.entry.label);
     optionsRef.current?.notify?.(taken.entry.label);
-  }, [stack, applyPatches]);
+  }, [stack, applyPatches, refuseWrite]);
   const doRedo = useCallback(async () => {
+    if (refuseWrite()) return;
     const taken = popRedo(stack);
     if (!taken.entry) return;
     setStack(taken.stack);
     await applyPatches(taken.entry.redo, "redo", taken.entry.label);
-  }, [stack, applyPatches]);
+  }, [stack, applyPatches, refuseWrite]);
   const move = useCallback(
     (direction, extend) => {
       setRange((previous) => {
@@ -853,7 +866,7 @@ function useSpreadsheetGrid(options) {
         case "edit":
         case "editSeeded": {
           const focused = range?.focus;
-          if (!focused || !current.onEditRequest) return;
+          if (!focused || !current.onEditRequest || current.readOnly) return;
           const seed = action.kind === "editSeeded" ? action.seed : null;
           if (current.onEditRequest(focused, seed)) event.preventDefault();
           return;
@@ -910,6 +923,7 @@ function useSpreadsheetGrid(options) {
       const text = event.clipboardData?.getData("text/plain") ?? "";
       if (!text) return;
       event.preventDefault();
+      if (refuseWrite()) return;
       const block = parseClipboardGrid(text);
       const start = range.focus;
       const startRow = rowIds.indexOf(start.rowId);
@@ -972,7 +986,7 @@ function useSpreadsheetGrid(options) {
       const tail = outside > 0 ? ` ${outside} landed past the edge of the table and were ignored.` : "";
       announceSkips(refusals, `Pasted ${screened.accepted.length} cells.${tail}`);
     },
-    [range, rowIds, columnIds, applyPatches, announceSkips, screenPatches]
+    [range, rowIds, columnIds, applyPatches, announceSkips, screenPatches, refuseWrite]
   );
   const cellProps = useCallback(
     (rowId, columnId) => {
@@ -1023,7 +1037,7 @@ function useSpreadsheetGrid(options) {
   const isFillHandleCell = useCallback(
     (rowId, columnId) => {
       const current = optionsRef.current;
-      if (!current || current.fillHandle === false || !bounds) return false;
+      if (!current || current.fillHandle === false || current.readOnly || !bounds) return false;
       return rowIds[bounds.r1] === rowId && columnIds[bounds.c1] === columnId;
     },
     [bounds, rowIds, columnIds]
@@ -1050,6 +1064,7 @@ function useSpreadsheetGrid(options) {
       const source = boundsRef.current;
       setFillTarget(null);
       if (!target || !source) return;
+      if (refuseWrite()) return;
       const base = fillRequestBase();
       if (!base) return;
       const result = fillRange({
@@ -1063,7 +1078,7 @@ function useSpreadsheetGrid(options) {
     };
     window.addEventListener("mouseup", commit);
     return () => window.removeEventListener("mouseup", commit);
-  }, [options, fillRequestBase, applyPatches, announceSkips, screenPatches]);
+  }, [options, fillRequestBase, applyPatches, announceSkips, screenPatches, refuseWrite]);
   return {
     range,
     bounds,
@@ -1086,6 +1101,7 @@ function useSpreadsheetGrid(options) {
 }
 export {
   NOTHING as NO_PATCHES,
+  READ_ONLY_REASON,
   useSpreadsheetGrid
 };
 //# sourceMappingURL=spreadsheet.js.map