@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/hooks/use-can-edit-cellrange.d.ts

@@ -0,0 +1,31 @@
+import type { CellInterface, GridRange } from "@rowsncolumns/common-types";
+import { type SheetProtectionAction } from "@rowsncolumns/spreadsheet";
+/** Error-state title shown when worksheet protection blocks an interaction. */
+export declare const SHEET_PROTECTION_ERROR_TITLE = "This sheet is protected";
+export declare const useCanEditSheet: () => (sheetId: number) => boolean;
+/**
+ * Workbook-level structural protection gate. Mirrors Excel's
+ * `workbookProtection lockStructure="1"`: when set, sheet-structural
+ * operations (add / delete / rename / move / duplicate / hide / show /
+ * tab color) are refused regardless of per-sheet protection.
+ *
+ * Cell-level edits are independently gated by `useCanEditCellRange` /
+ * `useCanEditSheet` — workbook protection only governs structure.
+ */
+export declare const useCanEditWorkbook: () => () => boolean;
+/**
+ * Granular worksheet-protection gate (`<sheetProtection>` action flags).
+ * Returns `(sheetId, action) => boolean` — `false` when the sheet's
+ * protection is active and prohibits the structural action (a flag set
+ * `true` prohibits, `false` allows, absent falls back to the OOXML default
+ * of prohibited; `mergeCells` is always prohibited while protected).
+ * Always `true` when the host supplies no protection lookup or the sheet is
+ * unprotected — so unprotected sheets behave exactly as before.
+ *
+ * Single-purpose: consult this ALONGSIDE `useCanEditSheet` /
+ * `useCanEditCellRange` (which cover whole-sheet protection and locked
+ * cells), not instead of them.
+ */
+export declare const useCanPerformSheetAction: () => (sheetId: number, action: SheetProtectionAction) => boolean;
+export declare const useCanEditCellRange: () => (sheetId: number, rangeOrCell: GridRange | CellInterface) => boolean;
+//# sourceMappingURL=use-can-edit-cellrange.d.ts.map

package/dist/esm/hooks/use-can-edit-cellrange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-can-edit-cellrange.d.ts","sourceRoot":"","sources":["../../../hooks/use-can-edit-cellrange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAEL,KAAK,qBAAqB,EAK3B,MAAM,2BAA2B,CAAC;AAMnC,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAEtE,eAAO,MAAM,eAAe,kBAGd,MAAM,YASnB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,qBAS9B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,kBAGvB,MAAM,UAAU,qBAAqB,YAIlD,CAAC;AAEF,eAAO,MAAM,mBAAmB,kBAIlB,MAAM,eAAe,SAAS,GAAG,aAAa,YAkB3D,CAAC"}

package/dist/esm/hooks/use-can-edit-cellrange.js

@@ -0,0 +1,72 @@
+import { isActionBlockedBySheetProtection, useCanEditCell, useGetSheetProtection, useIsSheetProtected, useIsWorkbookProtected, } from "@rowsncolumns/spreadsheet";
+import { convertCellToRange, iterateCellsInRange } from "@rowsncolumns/utils";
+import { useCallback } from "react";
+import { isSelectionRange } from "../api/range";
+/** Error-state title shown when worksheet protection blocks an interaction. */
+export const SHEET_PROTECTION_ERROR_TITLE = "This sheet is protected";
+export const useCanEditSheet = () => {
+    const isSheetProtected = useIsSheetProtected();
+    return useCallback((sheetId) => {
+        const isProtected = isSheetProtected?.(sheetId);
+        if (isProtected) {
+            return false;
+        }
+        return true;
+    }, [isSheetProtected]);
+};
+/**
+ * Workbook-level structural protection gate. Mirrors Excel's
+ * `workbookProtection lockStructure="1"`: when set, sheet-structural
+ * operations (add / delete / rename / move / duplicate / hide / show /
+ * tab color) are refused regardless of per-sheet protection.
+ *
+ * Cell-level edits are independently gated by `useCanEditCellRange` /
+ * `useCanEditSheet` — workbook protection only governs structure.
+ */
+export const useCanEditWorkbook = () => {
+    const isWorkbookProtected = useIsWorkbookProtected();
+    return useCallback(() => {
+        const isProtected = isWorkbookProtected?.();
+        if (isProtected) {
+            return false;
+        }
+        return true;
+    }, [isWorkbookProtected]);
+};
+/**
+ * Granular worksheet-protection gate (`<sheetProtection>` action flags).
+ * Returns `(sheetId, action) => boolean` — `false` when the sheet's
+ * protection is active and prohibits the structural action (a flag set
+ * `true` prohibits, `false` allows, absent falls back to the OOXML default
+ * of prohibited; `mergeCells` is always prohibited while protected).
+ * Always `true` when the host supplies no protection lookup or the sheet is
+ * unprotected — so unprotected sheets behave exactly as before.
+ *
+ * Single-purpose: consult this ALONGSIDE `useCanEditSheet` /
+ * `useCanEditCellRange` (which cover whole-sheet protection and locked
+ * cells), not instead of them.
+ */
+export const useCanPerformSheetAction = () => {
+    const getSheetProtection = useGetSheetProtection();
+    return useCallback((sheetId, action) => !isActionBlockedBySheetProtection(getSheetProtection?.(sheetId), action), [getSheetProtection]);
+};
+export const useCanEditCellRange = () => {
+    const canEditCell = useCanEditCell();
+    const canEditSheet = useCanEditSheet();
+    return useCallback((sheetId, rangeOrCell) => {
+        // If user cannot edit the sheet, early return
+        if (canEditSheet && !canEditSheet(sheetId)) {
+            return false;
+        }
+        // Check if to range is protected
+        const range = isSelectionRange(rangeOrCell)
+            ? rangeOrCell
+            : convertCellToRange(rangeOrCell);
+        for (const [rowIndex, columnIndex] of iterateCellsInRange(range)) {
+            if (canEditCell && !canEditCell?.(sheetId, { rowIndex, columnIndex })) {
+                return false;
+            }
+        }
+        return true;
+    }, [canEditCell, canEditSheet]);
+};

package/dist/esm/hooks/use-cellxfs-registry.d.ts

@@ -0,0 +1,6 @@
+import { type Dispatch, type SetStateAction } from "react";
+import { CellXfsRegistry } from "../cellxfs-registry";
+import type { CellXfs } from "../types";
+export { CellXfsRegistry } from "../cellxfs-registry";
+export declare const useCellXfsRegistry: (cellXfs: CellXfs | undefined | null, onChangeCellXfs?: Dispatch<SetStateAction<CellXfs | undefined | null>>) => CellXfsRegistry;
+//# sourceMappingURL=use-cellxfs-registry.d.ts.map

package/dist/esm/hooks/use-cellxfs-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cellxfs-registry.d.ts","sourceRoot":"","sources":["../../../hooks/use-cellxfs-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EAGpB,MAAM,OAAO,CAAC;AAEf,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,eAAO,MAAM,kBAAkB,GAC7B,SAAS,OAAO,GAAG,SAAS,GAAG,IAAI,EACnC,kBAAkB,QAAQ,CAAC,cAAc,CAAC,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC,oBAwBvE,CAAC"}

package/dist/esm/hooks/use-cellxfs-registry.js

@@ -0,0 +1,22 @@
+import { useCallback, useRef, } from "react";
+import { CellXfsRegistry } from "../cellxfs-registry";
+export { CellXfsRegistry } from "../cellxfs-registry";
+export const useCellXfsRegistry = (cellXfs, onChangeCellXfs) => {
+    const cellXfsRegistryRef = useRef(undefined);
+    const getCellXfsRegistry = useCallback(() => {
+        if (!cellXfsRegistryRef.current) {
+            cellXfsRegistryRef.current = new CellXfsRegistry(cellXfs, onChangeCellXfs);
+        }
+        return cellXfsRegistryRef.current;
+    }, []);
+    const cellXfsRegistry = getCellXfsRegistry();
+    // Sync the registry's internal `cellXfs` synchronously during render, NOT
+    // in a layout effect. The renderer calls `getDerivedFormat` during the
+    // grid's `cells` useMemo (render phase) which resolves `uf.sid` through
+    // the registry — a layout-effect sync would leave the registry pointing
+    // at the previous `cellXfs` for that lookup, so newly-registered styles
+    // would resolve to `undefined` and a formula cell's derived format would
+    // be stuck stale until the next render.
+    cellXfsRegistry.setCellXfs(cellXfs);
+    return cellXfsRegistry;
+};

package/dist/esm/hooks/use-citations.d.ts

@@ -0,0 +1,19 @@
+import type { Citation } from "@rowsncolumns/common-types";
+import type { CellData, Sheet } from "@rowsncolumns/spreadsheet";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+type UseCitationsProps<T extends CellData, S extends Sheet> = {
+    locale?: string;
+    onChangeSheetData: UseSpreadsheetProps<T, S>["onChangeSheetData"];
+    onChangeCitations: UseSpreadsheetProps<T, S>["onChangeCitations"];
+    createHistory: () => (patches: SpreadsheetPatch) => void;
+};
+export declare const useCitations: <T extends CellData, S extends Sheet>({ locale, onChangeSheetData, onChangeCitations, createHistory, }: UseCitationsProps<T, S>) => {
+    onCreateCitation: (sheetId: number, rowIndex: number, columnIndex: number, citation: Citation) => void;
+    onCreateBatchCitations: (citations: Citation[]) => void;
+    onUpdateCitation: (citationId: string, updates: Partial<Omit<Citation, "id">>) => void;
+    onRemoveCitationFromCell: (sheetId: number, rowIndex: number, columnIndex: number) => void;
+    onDeleteCitation: (citationId: string) => void;
+};
+export {};
+//# sourceMappingURL=use-citations.d.ts.map

package/dist/esm/hooks/use-citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-citations.d.ts","sourceRoot":"","sources":["../../../hooks/use-citations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAUjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,KAAK,iBAAiB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAClE,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAClE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,kEAK/D,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;gCAMX,MAAM,YACL,MAAM,eACH,MAAM,YACT,QAAQ;wCAiBR,QAAQ,EAAE;mCAaT,MAAM,WAAW,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;wCAajD,MAAM,YAAY,MAAM,eAAe,MAAM;mCAc1C,MAAM;CAgBtB,CAAC"}

package/dist/esm/hooks/use-citations.js

@@ -0,0 +1,61 @@
+import { useCallback } from "react";
+import { createBatchCitations, createCitation, deleteCitation, removeCitationFromCell, updateCitation, } from "../interface/citations";
+export const useCitations = ({ locale, onChangeSheetData, onChangeCitations, createHistory, }) => {
+    /**
+     * Create a new citation and attach it to a cell
+     */
+    const onCreateCitation = useCallback((sheetId, rowIndex, columnIndex, citation) => {
+        if (!createHistory)
+            return;
+        createCitation({
+            locale,
+            onChangeSheetData,
+            onChangeCitations,
+            createHistory,
+        })(sheetId, rowIndex, columnIndex, citation);
+    }, [locale, onChangeSheetData, onChangeCitations, createHistory]);
+    /**
+     * Create multiple citations in a batch (adds to citations array only)
+     */
+    const onCreateBatchCitations = useCallback((citations) => {
+        createBatchCitations({
+            onChangeCitations,
+            createHistory,
+        })(citations);
+    }, [onChangeCitations, createHistory]);
+    /**
+     * Update an existing citation
+     */
+    const onUpdateCitation = useCallback((citationId, updates) => {
+        updateCitation({
+            onChangeCitations,
+            createHistory,
+        })(citationId, updates);
+    }, [onChangeCitations, createHistory]);
+    /**
+     * Remove a citation from a cell
+     */
+    const onRemoveCitationFromCell = useCallback((sheetId, rowIndex, columnIndex) => {
+        removeCitationFromCell({
+            locale,
+            onChangeSheetData,
+            createHistory,
+        })(sheetId, rowIndex, columnIndex);
+    }, [locale, onChangeSheetData, createHistory]);
+    /**
+     * Delete a citation completely (removes from array and from all cells)
+     */
+    const onDeleteCitation = useCallback((citationId) => {
+        deleteCitation({
+            onChangeCitations,
+            createHistory,
+        })(citationId);
+    }, [onChangeCitations, createHistory]);
+    return {
+        onCreateCitation,
+        onCreateBatchCitations,
+        onUpdateCitation,
+        onRemoveCitationFromCell,
+        onDeleteCitation,
+    };
+};

package/dist/esm/hooks/use-comments.d.ts

@@ -0,0 +1,14 @@
+import type { CellData, Sheet } from "@rowsncolumns/spreadsheet";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+type UseCommentsProps<T extends CellData, S extends Sheet> = {
+    locale?: string;
+    onChangeSheetData: UseSpreadsheetProps<T, S>["onChangeSheetData"];
+    createHistory?: () => (patches: SpreadsheetPatch) => void;
+};
+export declare const useComments: <T extends CellData, S extends Sheet>({ locale, onChangeSheetData, createHistory, }: UseCommentsProps<T, S>) => {
+    onInsertComment: (sheetId: number, rowIndex: number, columnIndex: number, commentThreadId: string | number | undefined) => void;
+    onRemoveComment: (sheetId: number, rowIndex: number, columnIndex: number) => void;
+};
+export {};
+//# sourceMappingURL=use-comments.d.ts.map

package/dist/esm/hooks/use-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-comments.d.ts","sourceRoot":"","sources":["../../../hooks/use-comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAMjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,KAAK,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC3D,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,+CAI9D,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC;+BAGV,MAAM,YACL,MAAM,eACH,MAAM,mBACF,MAAM,GAAG,MAAM,GAAG,SAAS;+BA8BpC,MAAM,YAAY,MAAM,eAAe,MAAM;CA6B1D,CAAC"}

package/dist/esm/hooks/use-comments.js

@@ -0,0 +1,45 @@
+import { produceWithPatches } from "immer";
+import { useCallback } from "react";
+import { createSheetDraft } from "../api/immer-utils";
+import { SheetCell } from "../sheet-cell";
+export const useComments = ({ locale, onChangeSheetData, createHistory, }) => {
+    const onInsertComment = useCallback((sheetId, rowIndex, columnIndex, commentThreadId) => {
+        const saveHistory = createHistory?.();
+        const sheetCell = new SheetCell();
+        onChangeSheetData?.((prevSheetData) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
+                const currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+                const cellData = currentSheet[rowIndex].values?.[columnIndex];
+                sheetCell.assign(sheetId, { rowIndex, columnIndex }, cellData, {
+                    locale,
+                });
+                sheetCell.updateCommentThreadId(commentThreadId);
+                currentSheet[rowIndex].values[columnIndex] = sheetCell.getCellData();
+            });
+            saveHistory?.({
+                sheetData: { patches, inversePatches },
+            });
+            return nextState;
+        });
+    }, [locale, onChangeSheetData, createHistory]);
+    const onRemoveComment = useCallback((sheetId, rowIndex, columnIndex) => {
+        const saveHistory = createHistory?.();
+        const sheetCell = new SheetCell();
+        onChangeSheetData?.((prevSheetData) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
+                const currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+                const cellData = currentSheet[rowIndex].values?.[columnIndex];
+                sheetCell.assign(sheetId, { rowIndex, columnIndex }, cellData, {
+                    locale,
+                });
+                sheetCell.clearCommentThreadId();
+                currentSheet[rowIndex].values[columnIndex] = sheetCell.getCellData();
+            });
+            saveHistory?.({
+                sheetData: { patches, inversePatches },
+            });
+            return nextState;
+        });
+    }, [locale, onChangeSheetData, createHistory]);
+    return { onInsertComment, onRemoveComment };
+};

package/dist/esm/hooks/use-conditional-formatting-rules.d.ts

@@ -0,0 +1,22 @@
+import type { ConditionalFormatRule } from "@rowsncolumns/spreadsheet";
+import type { useCalculation } from "./use-calculation";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+export type UseConditionalFormattingRulesProps = {
+    enqueueCalculation: ReturnType<typeof useCalculation>["enqueueCalculation"];
+    /**
+     * Create a new history
+     * @returns
+     */
+    createHistory: () => (patches: SpreadsheetPatch) => void;
+    /**
+     * Callback to update conditional formatting
+     */
+    onChangeConditionalFormats?: React.Dispatch<React.SetStateAction<ConditionalFormatRule[]>>;
+};
+export declare const useConditionalFormattingRules: ({ enqueueCalculation, createHistory, onChangeConditionalFormats, }: UseConditionalFormattingRulesProps) => {
+    onCreateConditionalFormattingRule: (rule: ConditionalFormatRule) => void;
+    onUpdateConditionalFormattingRule: (updatedRule: ConditionalFormatRule, previousRule: ConditionalFormatRule) => void;
+    onDeleteConditionalFormattingRule: (rule: ConditionalFormatRule) => void;
+    onPreviewConditionalFormattingRule: (rule: ConditionalFormatRule) => void;
+};
+//# sourceMappingURL=use-conditional-formatting-rules.d.ts.map

package/dist/esm/hooks/use-conditional-formatting-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-conditional-formatting-rules.d.ts","sourceRoot":"","sources":["../../../hooks/use-conditional-formatting-rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAUvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAcxD,MAAM,MAAM,kCAAkC,GAAG;IAC/C,kBAAkB,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC5E;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD;;OAEG;IACH,0BAA0B,CAAC,EAAE,KAAK,CAAC,QAAQ,CACzC,KAAK,CAAC,cAAc,CAAC,qBAAqB,EAAE,CAAC,CAC9C,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAI,oEAI3C,kCAAkC;8CAK1B,qBAAqB;qDAwBb,qBAAqB,gBACpB,qBAAqB;8CA2B9B,qBAAqB;+CAuBrB,qBAAqB;CAgB/B,CAAC"}

package/dist/esm/hooks/use-conditional-formatting-rules.js

@@ -0,0 +1,81 @@
+import { useCallback } from "react";
+import { createConditionalFormattingRule, deleteConditionalFormattingRule, previewConditionalFormattingRule, updateConditionalFormattingRule, } from "../interface/conditional-formatting-rules";
+import { useCanEditSheet } from "./use-can-edit-cellrange";
+// CF rules carry one or more ranges; each range names a sheetId. A
+// rule is editable only if EVERY sheet it touches is editable.
+const ruleSheetsEditable = (rule, canEditSheet) => {
+    for (const range of rule.ranges ?? []) {
+        if (!canEditSheet(range.sheetId))
+            return false;
+    }
+    return true;
+};
+export const useConditionalFormattingRules = ({ enqueueCalculation, createHistory, onChangeConditionalFormats, }) => {
+    const canEditSheet = useCanEditSheet();
+    // Create new rule
+    const onCreateConditionalFormattingRule = useCallback((rule) => {
+        if (!ruleSheetsEditable(rule, canEditSheet)) {
+            console.debug("Cannot create conditional formatting rule — one of its ranges is on a protected sheet.");
+            return;
+        }
+        createConditionalFormattingRule({
+            enqueueCalculation,
+            createHistory,
+            onChangeConditionalFormats,
+        })(rule);
+    }, [
+        createHistory,
+        enqueueCalculation,
+        onChangeConditionalFormats,
+        canEditSheet,
+    ]);
+    // Update an existing rule
+    const onUpdateConditionalFormattingRule = useCallback((updatedRule, previousRule) => {
+        if (!ruleSheetsEditable(previousRule, canEditSheet) ||
+            !ruleSheetsEditable(updatedRule, canEditSheet)) {
+            console.debug("Cannot update conditional formatting rule — one of its ranges is on a protected sheet.");
+            return;
+        }
+        updateConditionalFormattingRule({
+            enqueueCalculation,
+            createHistory,
+            onChangeConditionalFormats,
+        })(updatedRule, previousRule);
+    }, [
+        createHistory,
+        onChangeConditionalFormats,
+        enqueueCalculation,
+        canEditSheet,
+    ]);
+    // Delete conditional formatting
+    const onDeleteConditionalFormattingRule = useCallback((rule) => {
+        if (!ruleSheetsEditable(rule, canEditSheet)) {
+            console.debug("Cannot delete conditional formatting rule — one of its ranges is on a protected sheet.");
+            return;
+        }
+        deleteConditionalFormattingRule({
+            enqueueCalculation,
+            createHistory,
+            onChangeConditionalFormats,
+        })(rule);
+    }, [
+        enqueueCalculation,
+        onChangeConditionalFormats,
+        createHistory,
+        canEditSheet,
+    ]);
+    // on Preview conditional formatting — non-destructive, no gate
+    const onPreviewConditionalFormattingRule = useCallback((rule) => {
+        previewConditionalFormattingRule({
+            enqueueCalculation,
+            createHistory,
+            onChangeConditionalFormats,
+        })(rule);
+    }, [enqueueCalculation, createHistory, onChangeConditionalFormats]);
+    return {
+        onCreateConditionalFormattingRule,
+        onUpdateConditionalFormattingRule,
+        onDeleteConditionalFormattingRule,
+        onPreviewConditionalFormattingRule,
+    };
+};

package/dist/esm/hooks/use-data-validation-rules.d.ts

@@ -0,0 +1,54 @@
+import type { useGetEffectiveValuesFromRange } from "@rowsncolumns/spreadsheet";
+import { type CellData, type DataValidationRuleRecord, type Sheet } from "@rowsncolumns/spreadsheet";
+import type { CellXfsRegistry } from "../cellxfs-registry";
+import { type CreateDataValidationRuleOptions } from "../interface/data-validation-rules";
+import type { SharedStringRegistry } from "../shared-string-registry";
+import type { useCalculation } from "./use-calculation";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+export type UseDataValidationRuleProps<T extends CellData, S extends Sheet> = {
+    /**
+     * Current locale
+     */
+    locale?: string;
+    /**
+     * Queue up for calculation
+     */
+    enqueueCalculation: ReturnType<typeof useCalculation>["enqueueCalculation"];
+    /**
+     * Create a new history
+     * @returns
+     */
+    createHistory: () => (patches: SpreadsheetPatch) => void;
+    /**
+     * Callback to update conditional formatting
+     */
+    onChangeDataValidations?: React.Dispatch<React.SetStateAction<DataValidationRuleRecord[]>>;
+    /**
+     * Validation rules are attached to cells
+     */
+    onChangeSheetData: UseSpreadsheetProps<T, S>["onChangeSheetData"];
+    /**
+     * Get effective values from range
+     */
+    getEffectiveValuesFromRange?: ReturnType<typeof useGetEffectiveValuesFromRange>;
+    getSheetName(sheetId: number): string;
+    /**
+     * Style registry — required to round-trip `uf: { sid }` style references
+     * when stamping/clearing data validation on cells. Without it, the cell's
+     * `uf` is dropped on write.
+     */
+    cellXfsRegistry?: CellXfsRegistry;
+    /**
+     * Shared-string registry — paired with `cellXfsRegistry` for the same
+     * round-trip reason on `ss` rich-text references.
+     */
+    sharedStringRegistry?: SharedStringRegistry;
+};
+export declare const useDataValidationRules: <T extends CellData, S extends Sheet>({ locale, onChangeSheetData, onChangeDataValidations, createHistory, enqueueCalculation, getEffectiveValuesFromRange, getSheetName, cellXfsRegistry, sharedStringRegistry, }: UseDataValidationRuleProps<T, S>) => {
+    onCreateDataValidationRule: (rule: DataValidationRuleRecord, options?: CreateDataValidationRuleOptions) => void;
+    onUpdateDataValidationRule: (rule: DataValidationRuleRecord, previousRule: DataValidationRuleRecord) => void;
+    onDeleteDataValidationRule: (rule: DataValidationRuleRecord) => void;
+    onDeleteDataValidationRules: (rules: DataValidationRuleRecord[]) => void;
+};
+//# sourceMappingURL=use-data-validation-rules.d.ts.map

package/dist/esm/hooks/use-data-validation-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-data-validation-rules.d.ts","sourceRoot":"","sources":["../../../hooks/use-data-validation-rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,wBAAwB,EAC7B,KAAK,KAAK,EACX,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,KAAK,+BAA+B,EAKrC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAexD,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IAC5E;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,kBAAkB,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC5E;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD;;OAEG;IACH,uBAAuB,CAAC,EAAE,KAAK,CAAC,QAAQ,CACtC,KAAK,CAAC,cAAc,CAAC,wBAAwB,EAAE,CAAC,CACjD,CAAC;IACF;;OAEG;IACH,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAClE;;OAEG;IACH,2BAA2B,CAAC,EAAE,UAAU,CACtC,OAAO,8BAA8B,CACtC,CAAC;IACF,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,8KAUzE,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC;uCAMvB,wBAAwB,YACpB,+BAA+B;uCAqCnC,wBAAwB,gBAChB,wBAAwB;uCA8EjC,wBAAwB;yCAvCvB,wBAAwB,EAAE;CAwErC,CAAC"}

package/dist/esm/hooks/use-data-validation-rules.js

@@ -0,0 +1,135 @@
+import { useCallback } from "react";
+import { createDataValidationRule, deleteDataValidationRule, deleteDataValidationRules, updateDataValidationRule, } from "../interface/data-validation-rules";
+import { useCanEditSheet } from "./use-can-edit-cellrange";
+// DV rules are anchored to one or more ranges; each range names a
+// sheetId. A rule is editable only if EVERY sheet it touches is
+// editable.
+const dvRuleSheetsEditable = (rule, canEditSheet) => {
+    for (const range of rule.ranges ?? []) {
+        if (!canEditSheet(range.sheetId))
+            return false;
+    }
+    return true;
+};
+export const useDataValidationRules = ({ locale, onChangeSheetData, onChangeDataValidations, createHistory, enqueueCalculation, getEffectiveValuesFromRange, getSheetName, cellXfsRegistry, sharedStringRegistry, }) => {
+    const canEditSheet = useCanEditSheet();
+    // Create new rule
+    const onCreateDataValidationRule = useCallback((rule, options) => {
+        if (!options?.importSource && !dvRuleSheetsEditable(rule, canEditSheet)) {
+            console.debug("Cannot create data validation rule — one of its ranges is on a protected sheet.");
+            return;
+        }
+        createDataValidationRule({
+            locale,
+            onChangeSheetData,
+            onChangeDataValidations,
+            createHistory,
+            enqueueCalculation,
+            getEffectiveValuesFromRange,
+            getSheetName,
+            cellXfsRegistry,
+            sharedStringRegistry,
+        })(rule, options);
+    }, [
+        locale,
+        getEffectiveValuesFromRange,
+        enqueueCalculation,
+        createHistory,
+        onChangeSheetData,
+        onChangeDataValidations,
+        getSheetName,
+        canEditSheet,
+        cellXfsRegistry,
+        sharedStringRegistry,
+    ]);
+    // Update existing rule
+    const onUpdateDataValidationRule = useCallback((rule, previousRule) => {
+        if (!dvRuleSheetsEditable(rule, canEditSheet) ||
+            !dvRuleSheetsEditable(previousRule, canEditSheet)) {
+            console.debug("Cannot update data validation rule — one of its ranges is on a protected sheet.");
+            return;
+        }
+        updateDataValidationRule({
+            locale,
+            onChangeSheetData,
+            onChangeDataValidations,
+            createHistory,
+            enqueueCalculation,
+            getEffectiveValuesFromRange,
+            getSheetName,
+            cellXfsRegistry,
+            sharedStringRegistry,
+        })(rule, previousRule);
+    }, [
+        locale,
+        getEffectiveValuesFromRange,
+        enqueueCalculation,
+        createHistory,
+        onChangeSheetData,
+        onChangeDataValidations,
+        getSheetName,
+        canEditSheet,
+        cellXfsRegistry,
+        sharedStringRegistry,
+    ]);
+    // Remove all rules
+    const onDeleteDataValidationRules = useCallback((rules) => {
+        // Filter out rules whose sheets are protected. Bulk delete
+        // skips them silently rather than aborting the whole call —
+        // that matches Excel, which only blocks the protected ones.
+        const allowed = rules.filter((r) => dvRuleSheetsEditable(r, canEditSheet));
+        if (allowed.length === 0) {
+            console.debug("Cannot delete data validation rules — all are on protected sheets.");
+            return;
+        }
+        deleteDataValidationRules({
+            locale,
+            onChangeSheetData,
+            onChangeDataValidations,
+            createHistory,
+            enqueueCalculation,
+            getSheetName,
+            cellXfsRegistry,
+            sharedStringRegistry,
+        })(allowed);
+    }, [
+        locale,
+        enqueueCalculation,
+        onChangeSheetData,
+        onChangeDataValidations,
+        createHistory,
+        getSheetName,
+        canEditSheet,
+        cellXfsRegistry,
+        sharedStringRegistry,
+    ]);
+    // Delete single rule
+    const onDeleteDataValidationRule = useCallback((rule) => {
+        if (!dvRuleSheetsEditable(rule, canEditSheet)) {
+            console.debug("Cannot delete data validation rule — one of its ranges is on a protected sheet.");
+            return;
+        }
+        deleteDataValidationRule({
+            locale,
+            onChangeSheetData,
+            onChangeDataValidations,
+            createHistory,
+            enqueueCalculation,
+            getSheetName,
+        })(rule);
+    }, [
+        locale,
+        enqueueCalculation,
+        onChangeSheetData,
+        onChangeDataValidations,
+        canEditSheet,
+        createHistory,
+        getSheetName,
+    ]);
+    return {
+        onCreateDataValidationRule,
+        onUpdateDataValidationRule,
+        onDeleteDataValidationRule,
+        onDeleteDataValidationRules,
+    };
+};

package/dist/esm/hooks/use-deferred-calculation-flush.d.ts

@@ -0,0 +1,14 @@
+import type { MutableRefObject } from "react";
+type DeferredMap<T> = Map<number, Map<string, T>>;
+type UseDeferredCalculationFlushOptions<T> = {
+    activeSheetId?: number;
+    deferredOperationsBySheetRef: MutableRefObject<DeferredMap<T>>;
+    enqueueOperation: (operation: T) => void;
+    onFlushComplete?: () => void;
+    onChunkComplete?: () => void | Promise<void>;
+    chunkSize?: number;
+    maxSliceMs?: number;
+};
+export declare const useDeferredCalculationFlush: <T>({ activeSheetId, deferredOperationsBySheetRef, enqueueOperation, onFlushComplete, onChunkComplete, chunkSize, maxSliceMs, }: UseDeferredCalculationFlushOptions<T>) => void;
+export {};
+//# sourceMappingURL=use-deferred-calculation-flush.d.ts.map

package/dist/esm/hooks/use-deferred-calculation-flush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-deferred-calculation-flush.d.ts","sourceRoot":"","sources":["../../../hooks/use-deferred-calculation-flush.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAK9C,KAAK,WAAW,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AAElD,KAAK,kCAAkC,CAAC,CAAC,IAAI;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4BAA4B,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,gBAAgB,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,IAAI,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,2BAA2B,GAAI,CAAC,EAAE,6HAQ5C,kCAAkC,CAAC,CAAC,CAAC,SAqFvC,CAAC"}