@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/hooks/use-on-filter-table.js

@@ -0,0 +1,341 @@
+import { BLANK_LABEL, checkFilterRule, getStringifiedColor, ICON_SET_GLYPHS, pickIconBucket, resolveThreshold, } from "@rowsncolumns/spreadsheet";
+import { cellToAddress, isNil } from "@rowsncolumns/utils";
+import { produceWithPatches } from "immer";
+import set from "lodash/set";
+import { useCallback } from "react";
+import { buildDataValidationExpression, isDataValidationFormulaRule, } from "../api/data-validation";
+import { createFilterSpecs, createFilterSpecsByColumnIndex, } from "../api/filter";
+import { formulaToRelativeReference } from "../api/formula";
+import { useShowError } from "../atoms/error-state.atom";
+import { SHEET_PROTECTION_ERROR_TITLE, useCanEditSheet, useCanPerformSheetAction, } from "./use-can-edit-cellrange";
+/**
+ * Sorts a column
+ * @param param0
+ * @returns
+ */
+export const useOnFilterTable = ({ createHistory, onChangeTables, onChangeSheets, getEffectiveValue, getFormattedValue, getEffectiveFormat, conditionalFormats, getActiveCell, onRequestCalculate, getSheetName, locale, theme, onCommand, onRowVisibilityChange, }) => {
+    const canEditSheet = useCanEditSheet();
+    const canPerformSheetAction = useCanPerformSheetAction();
+    const showError = useShowError();
+    const onFilterTable = useCallback(async (sheetId, filter, 
+    // This is the relative columnIndex to the table
+    // and not relative to grid
+    columnIndex, conditionType, conditionValue, visibleValues, extras = {}) => {
+        // Protection — filter doesn't rewrite cell values but it does
+        // hide rows. The sheet's `<sheetProtection autoFilter>` flag is
+        // consulted first; the host's `isSheetProtected` policy via
+        // `canEditSheet` still gets a veto.
+        if (!canPerformSheetAction(sheetId, "autoFilter")) {
+            showError({
+                title: SHEET_PROTECTION_ERROR_TITLE,
+                message: "You can't change filters on a protected sheet.",
+            });
+            return;
+        }
+        if (!canEditSheet(sheetId)) {
+            console.debug("This sheet is protected, users cannot change table filters.");
+            return;
+        }
+        // History
+        const saveHistory = createHistory();
+        // Specs
+        const filterSpecs = createFilterSpecs(filter.filterSpecs ?? undefined, columnIndex, conditionType, conditionValue, visibleValues, extras);
+        const hiddenRows = await getHiddenRowsFromFilterSpecs(sheetId, filter, filterSpecs, onRequestCalculate, getEffectiveValue, getFormattedValue, getSheetName, theme, locale, getEffectiveFormat, conditionalFormats, extras.getCellConditionalFormat);
+        const { range } = filter;
+        // Change sheets
+        onChangeSheets?.((prevSheets) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheets, (draft) => {
+                const sheet = draft.find((sheet) => sheet.sheetId === sheetId);
+                if (sheet) {
+                    if (!sheet.rowMetadata) {
+                        sheet.rowMetadata = [];
+                    }
+                    for (let rowIndex = range.startRowIndex; rowIndex <= range.endRowIndex; rowIndex++) {
+                        sheet.rowMetadata[rowIndex] = {
+                            ...sheet.rowMetadata[rowIndex],
+                            hiddenByFilter: hiddenRows.has(rowIndex) ? true : false,
+                        };
+                    }
+                }
+                // Update filter specs
+                if (sheet?.basicFilter?.id === filter.id) {
+                    set(sheet, "basicFilter.filterSpecs", filterSpecs);
+                }
+            });
+            // Save history
+            saveHistory({
+                sheets: { patches, inversePatches },
+                activeCell: { undo: getActiveCell(), redo: getActiveCell() },
+            });
+            return nextState;
+        });
+        // Update table sort specs
+        onChangeTables?.((prevTables) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevTables, (draft) => {
+                const table = draft.find((table) => table.id === filter.id);
+                if (table) {
+                    table.filterSpecs = filterSpecs;
+                }
+            });
+            // Save history
+            saveHistory({
+                tables: { patches, inversePatches },
+            });
+            return nextState;
+        });
+        // Filtering changed which rows are visible — recalc SUBTOTALs
+        onRowVisibilityChange?.();
+        onCommand?.({
+            command: "filter-table",
+            sheetId,
+            filter,
+            columnIndex,
+            conditionType,
+            conditionValue,
+            visibleValues,
+            colorFilter: extras.colorFilter,
+            iconFilter: extras.iconFilter,
+        });
+    }, [
+        createHistory,
+        onChangeTables,
+        onChangeSheets,
+        getEffectiveValue,
+        getFormattedValue,
+        getEffectiveFormat,
+        conditionalFormats,
+        getActiveCell,
+        onRequestCalculate,
+        getSheetName,
+        locale,
+        onCommand,
+        canEditSheet,
+        canPerformSheetAction,
+        showError,
+        onRowVisibilityChange,
+    ]);
+    const onDeleteFilter = useCallback(async (sheetId, filter, columnIndex) => {
+        const result = await onFilterTable?.(sheetId, filter, columnIndex, undefined, undefined, []);
+        onCommand?.({
+            command: "delete-filter",
+            sheetId,
+            filter,
+            columnIndex,
+        });
+        return result;
+    }, [onFilterTable, onCommand]);
+    return [onFilterTable, onDeleteFilter];
+};
+/**
+ * Does the cell's rendered color match the colorFilter criterion?
+ * The CF overlay wins over the effective format — mirroring the
+ * renderer's precedence — because CF-painted fills/font colors never
+ * appear on the effective format. Returns true when no relevant color is
+ * set on the cell — Excel hides such rows when a color filter is active.
+ */
+const matchesCellColor = (colorFilter, format, conditionalFormat, theme) => {
+    const target = getStringifiedColor(colorFilter.color, theme);
+    if (!target)
+        return true;
+    const cellColor = colorFilter.mode === "cellColor"
+        ? conditionalFormat?.backgroundColor ?? format?.backgroundColor
+        : conditionalFormat?.textFormat?.color ?? format?.textFormat?.color;
+    const actual = getStringifiedColor(cellColor, theme);
+    if (!actual)
+        return false;
+    // Case-insensitive: hex casing differs between user-entered fills,
+    // theme palettes, and interpolated gradient colors.
+    return actual.toLowerCase() === target.toLowerCase();
+};
+/**
+ * Walk `conditionalFormats` once and build an iconSet evaluation context
+ * keyed by absolute columnIndex for every column that has an active
+ * `iconFilter`. Computing range min/max here (instead of per-row) keeps
+ * the filter cost O(rule range size) regardless of how many rows the
+ * filter scans.
+ */
+const buildIconEvalByColumn = (sheetId, filterRange, filterSpecs, conditionalFormats, getEffectiveValue) => {
+    const byColumn = new Map();
+    if (!conditionalFormats?.length)
+        return byColumn;
+    for (const spec of filterSpecs) {
+        const iconFilter = spec.filterCriteria?.iconFilter;
+        if (!iconFilter)
+            continue;
+        const absoluteColumnIndex = filterRange.startColumnIndex + spec.columnIndex;
+        for (const rule of conditionalFormats) {
+            if (rule.enabled === false)
+                continue;
+            const iconSetRule = rule.iconSetRule;
+            if (!iconSetRule || iconSetRule.iconSet !== iconFilter.iconSet)
+                continue;
+            const coveringRanges = rule.ranges.filter((r) => r.sheetId === sheetId &&
+                r.startColumnIndex <= absoluteColumnIndex &&
+                r.endColumnIndex >= absoluteColumnIndex);
+            if (coveringRanges.length === 0)
+                continue;
+            let rangeMin = Infinity;
+            let rangeMax = -Infinity;
+            for (const r of coveringRanges) {
+                for (let rr = r.startRowIndex; rr <= r.endRowIndex; rr++) {
+                    for (let cc = r.startColumnIndex; cc <= r.endColumnIndex; cc++) {
+                        const v = getEffectiveValue(sheetId, rr, cc);
+                        if (isNil(v))
+                            continue;
+                        const num = Number(v);
+                        if (!Number.isFinite(num))
+                            continue;
+                        if (num < rangeMin)
+                            rangeMin = num;
+                        if (num > rangeMax)
+                            rangeMax = num;
+                    }
+                }
+            }
+            if (!Number.isFinite(rangeMin))
+                continue;
+            const sortedThresholds = iconSetRule.thresholds
+                .map((t) => resolveThreshold(t, rangeMin, rangeMax))
+                .filter((n) => Number.isFinite(n))
+                .sort((a, b) => a - b);
+            byColumn.set(absoluteColumnIndex, {
+                iconSet: iconFilter.iconSet,
+                sortedThresholds,
+                ranges: coveringRanges,
+                glyphCount: ICON_SET_GLYPHS[iconFilter.iconSet]?.length ?? 0,
+            });
+            break;
+        }
+    }
+    return byColumn;
+};
+/**
+ * Does this cell's CF iconSet rule produce the icon the user filtered on?
+ * Returns false when the cell isn't in the rule's range or has no numeric
+ * value (Excel hides both cases when an icon filter is active).
+ */
+const matchesCellIcon = (iconFilter, ctx, sheetId, rowIndex, columnIndex, getEffectiveValue) => {
+    const inRange = ctx.ranges.some((r) => rowIndex >= r.startRowIndex &&
+        rowIndex <= r.endRowIndex &&
+        columnIndex >= r.startColumnIndex &&
+        columnIndex <= r.endColumnIndex);
+    if (!inRange)
+        return false;
+    const v = getEffectiveValue(sheetId, rowIndex, columnIndex);
+    if (isNil(v))
+        return false;
+    const num = Number(v);
+    if (!Number.isFinite(num))
+        return false;
+    const bucket = pickIconBucket(num, ctx.sortedThresholds);
+    const glyphIndex = Math.min(bucket, Math.max(0, ctx.glyphCount - 1));
+    return glyphIndex === iconFilter.iconId;
+};
+/**
+ * Get hidden rows from a filter
+ * @param filterSpecs
+ */
+export const getHiddenRowsFromFilterSpecs = async (sheetId, filterView, filterSpecs, onRequestCalculate, getEffectiveValue, getFormattedValue, getSheetName, theme, locale, 
+// Optional — only required when a column filter uses `colorFilter`.
+// Receives the cell's effective format so we can match cell or font color.
+getEffectiveFormat, 
+// Optional — required for `iconFilter` to work. See the prop docs on
+// `UseOnFilterTableProps.conditionalFormats` for the migration plan.
+conditionalFormats, 
+// Optional — reader for the rendered CF overlay (injected per-call via
+// `FilterTableExtras`). Lets `colorFilter` match CF-painted fills/font
+// colors, which the effective format doesn't carry.
+getCellConditionalFormat) => {
+    const activeSheetName = getSheetName(sheetId);
+    // Hidden rows
+    const hiddenRows = new Set();
+    // By columnIndex
+    const filterSpecByColumnIndex = createFilterSpecsByColumnIndex(filterSpecs);
+    // Gather hidden rows
+    const { range } = filterView;
+    // Build per-column iconSet evaluation contexts once (computing range
+    // min/max for every filtered row would be quadratic).
+    const iconEvalByColumn = buildIconEvalByColumn(sheetId, range, filterSpecs, conditionalFormats, getEffectiveValue);
+    const headerRow = filterView.headerRow ?? true;
+    const totalRow = filterView.totalRow;
+    const startRowIndex = range.startRowIndex + (headerRow ? 1 : 0);
+    const endRowIndex = range.endRowIndex - (totalRow ? 1 : 0);
+    for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+        for (let columnIndex = range.startColumnIndex; columnIndex <= range.endColumnIndex; columnIndex++) {
+            const dimensionIndex = columnIndex - range.startColumnIndex;
+            const columnFilter = filterSpecByColumnIndex[dimensionIndex];
+            const filterApplied = Boolean(columnFilter?.filterCriteria.condition?.type ||
+                columnFilter?.filterCriteria.visibleValues?.length ||
+                columnFilter?.filterCriteria.colorFilter ||
+                columnFilter?.filterCriteria.iconFilter);
+            if (!columnFilter || !filterApplied) {
+                continue;
+            }
+            const formulaRule = columnFilter?.filterCriteria.condition
+                ? {
+                    condition: columnFilter.filterCriteria.condition,
+                }
+                : undefined;
+            const isFormulaRule = isDataValidationFormulaRule(formulaRule);
+            const baseCellRef = cellToAddress({ rowIndex: startRowIndex, columnIndex }) ?? "A1";
+            const baseFormula = isFormulaRule
+                ? buildDataValidationExpression(formulaRule, baseCellRef, locale)
+                : undefined;
+            const formulaValue = baseFormula
+                ? formulaToRelativeReference(baseFormula, { rowIndex: startRowIndex, columnIndex }, { rowIndex, columnIndex }, activeSheetName, { ignoreCircular: true })
+                : undefined;
+            const currentVisibleValues = columnFilter?.filterCriteria.visibleValues;
+            const visibleValuesSet = currentVisibleValues
+                ? new Set(currentVisibleValues)
+                : undefined;
+            const showBlanks = visibleValuesSet?.has(BLANK_LABEL) ?? false;
+            const effectiveValue = getEffectiveValue(sheetId, rowIndex, columnIndex);
+            const formattedValue = getFormattedValue(sheetId, rowIndex, columnIndex);
+            const validationResult = columnFilter.filterCriteria.condition?.type
+                ? formulaValue
+                    ? await onRequestCalculate(formulaValue, sheetId, rowIndex, columnIndex)
+                    : checkFilterRule(columnFilter.filterCriteria, effectiveValue)
+                : true;
+            const isBlanksVisible = showBlanks
+                ? isNil(formattedValue) || formattedValue === ""
+                : false;
+            const isRowVisible = currentVisibleValues
+                ? isBlanksVisible ||
+                    (formattedValue && visibleValuesSet?.has(formattedValue))
+                : true;
+            // Color filter: hide rows whose cell/font color doesn't match.
+            // No-op when `getEffectiveFormat` isn't supplied — callers that
+            // don't need color filtering can skip the extra wiring.
+            const colorFilter = columnFilter.filterCriteria.colorFilter;
+            const iconFilter = columnFilter.filterCriteria.iconFilter;
+            const effectiveFormat = colorFilter && getEffectiveFormat
+                ? getEffectiveFormat(sheetId, rowIndex, columnIndex)
+                : undefined;
+            const cellConditionalFormat = colorFilter && getCellConditionalFormat
+                ? getCellConditionalFormat(sheetId, rowIndex, columnIndex)
+                : undefined;
+            const matchesColorFilter = !colorFilter || (!getEffectiveFormat && !getCellConditionalFormat)
+                ? true
+                : matchesCellColor(colorFilter, effectiveFormat, cellConditionalFormat, theme);
+            // Icon filter consults the precomputed iconSet context for this
+            // column (see `buildIconEvalByColumn` above). If no matching CF
+            // rule exists, the row is hidden — matches Excel's behavior.
+            const iconCtx = iconFilter
+                ? iconEvalByColumn.get(columnIndex)
+                : undefined;
+            const matchesIconFilter = !iconFilter
+                ? true
+                : !iconCtx
+                    ? false
+                    : matchesCellIcon(iconFilter, iconCtx, sheetId, rowIndex, columnIndex, getEffectiveValue);
+            const isHidden = !isRowVisible ||
+                validationResult === false ||
+                !matchesColorFilter ||
+                !matchesIconFilter;
+            if (isHidden) {
+                hiddenRows.add(rowIndex);
+            }
+        }
+    }
+    return hiddenRows;
+};

package/dist/esm/hooks/use-on-find-replace.d.ts

@@ -0,0 +1,19 @@
+import type { CellData, Sheet, SheetRange } from "@rowsncolumns/spreadsheet";
+import type { useCalculation } from "./use-calculation";
+import type { SearchOptions } from "./use-search";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SharedStringRegistry } from "./use-ss-registry";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+import type { OnCommand } from "../commands";
+type UseOnFindReplaceProps<T extends CellData, S extends Sheet> = {
+    locale?: string;
+    createHistory: () => (patches: SpreadsheetPatch) => void;
+    enqueueCalculation: ReturnType<typeof useCalculation>["enqueueCalculation"];
+    enqueueStructureChange?: ReturnType<typeof useCalculation>["enqueueStructureChange"];
+    onChangeSheetData: UseSpreadsheetProps<T, S>["onChangeSheetData"];
+    sharedStringRegistry?: SharedStringRegistry;
+    onCommand?: OnCommand;
+};
+export declare const useOnFindReplace: <T extends CellData, S extends Sheet>({ locale, createHistory, onChangeSheetData, enqueueCalculation, enqueueStructureChange, sharedStringRegistry, onCommand, }: UseOnFindReplaceProps<T, S>) => (lookupRanges: SheetRange[], searchStr: string, replaceWith: string | undefined, options?: SearchOptions) => void;
+export {};
+//# sourceMappingURL=use-on-find-replace.d.ts.map

package/dist/esm/hooks/use-on-find-replace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-on-find-replace.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-find-replace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAU7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,KAAK,qBAAqB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD,kBAAkB,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC5E,sBAAsB,CAAC,EAAE,UAAU,CACjC,OAAO,cAAc,CACtB,CAAC,wBAAwB,CAAC,CAAC;IAC5B,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAClE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,4HAQnE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,oBAGV,UAAU,EAAE,aACf,MAAM,eACJ,MAAM,GAAG,SAAS,YACrB,aAAa,SAgJ5B,CAAC"}

package/dist/esm/hooks/use-on-find-replace.js

@@ -0,0 +1,115 @@
+import { isNil, iterateCellsInRange } from "@rowsncolumns/utils";
+import { produceWithPatches } from "immer";
+import { useCallback } from "react";
+import { createSheetCellIdentifier } from "../api/formula";
+import { createSheetDraft } from "../api/immer-utils";
+import { SheetCell } from "../sheet-cell";
+import { buildSearchRegex } from "./use-search";
+export const useOnFindReplace = ({ locale, createHistory, onChangeSheetData, enqueueCalculation, enqueueStructureChange, sharedStringRegistry, onCommand, }) => {
+    return useCallback((lookupRanges, searchStr, replaceWith, options) => {
+        // Build the matcher once with the same helper `useSearch` uses, so
+        // case-insensitivity / whole-word / user-regex stay in sync between
+        // find and replace. Bail early on a compile failure (regex mode
+        // with a malformed pattern) — matches `useSearch`'s zero-matches
+        // behaviour.
+        const regex = buildSearchRegex(searchStr, options);
+        if (!regex)
+            return;
+        // Find-replace scans the WHOLE scope — which a windowed UI doesn't hold. Stream the INTENT to
+        // an engine consumer (the Rust model has the complete document) and let it do the find+replace
+        // and recompute, streaming back the changed cells. The local pass below is the legacy
+        // non-engine path (the UI holds all data only when no engine is attached).
+        onCommand?.({
+            command: "find-replace",
+            ranges: lookupRanges,
+            find: searchStr,
+            replace: replaceWith ?? "",
+            matchCase: options?.matchCase,
+            wholeWord: options?.wholeWord,
+            useRegex: options?.useRegex,
+        });
+        const sheetCell = new SheetCell();
+        const saveHistory = createHistory();
+        // We need to track this for history. Precedent cells
+        const recalcCells = new Map();
+        // Replace writes through `onChangeSheetData` directly. Conservatively
+        // invalidate each entire lookup range — every match is within it,
+        // and tracking individual hits would mean a second pass to bound them.
+        if (!isNil(replaceWith)) {
+            for (const range of lookupRanges) {
+                enqueueStructureChange?.({
+                    kind: "invalidate-range",
+                    sheetId: range.sheetId,
+                    startRowIndex: range.startRowIndex,
+                    endRowIndex: range.endRowIndex,
+                    startColumnIndex: range.startColumnIndex,
+                    endColumnIndex: range.endColumnIndex,
+                });
+            }
+        }
+        // Callback
+        onChangeSheetData?.((prevSheetData) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
+                for (const range of lookupRanges) {
+                    for (const [rowIndex, columnIndex] of iterateCellsInRange(range)) {
+                        const currentSheet = createSheetDraft(draft, range.sheetId, rowIndex);
+                        const cellData = draft[range.sheetId]?.[rowIndex]?.values?.[columnIndex];
+                        sheetCell.assign(range.sheetId, { rowIndex, columnIndex }, cellData, { locale });
+                        // Match AND replace against the formatted value — what
+                        // the user sees and what `useSearch` matched. The
+                        // user-entered value can be a number / formula whose
+                        // display form ("$100.00") doesn't contain the literal
+                        // search string ("100"), so trying to replace in `sv`
+                        // alone misses those cells. Writing the replaced
+                        // formatted text back as the new user-entered value
+                        // mirrors Excel / Google Sheets — a cell that was
+                        // numeric with a currency format becomes the plain
+                        // string the user typed in the Replace box.
+                        const formattedValue = sheetCell.formattedValue;
+                        if (isNil(formattedValue))
+                            continue;
+                        // `g` flag is set by `buildSearchRegex`; reset lastIndex
+                        // before .test so a stateful regex doesn't skip the
+                        // first character on a re-run.
+                        regex.lastIndex = 0;
+                        if (!regex.test(formattedValue))
+                            continue;
+                        regex.lastIndex = 0;
+                        const next = formattedValue.replace(regex, replaceWith ?? "");
+                        sheetCell.setUserEnteredValue(next);
+                        sharedStringRegistry?.registerCell(sheetCell);
+                        currentSheet[rowIndex].values[columnIndex] =
+                            sheetCell.getCellData();
+                        enqueueCalculation({
+                            type: "add",
+                            position: {
+                                rowIndex,
+                                columnIndex,
+                                sheetId: range.sheetId,
+                            },
+                        });
+                        recalcCells.set(createSheetCellIdentifier(range.sheetId, rowIndex, columnIndex), {
+                            columnIndex,
+                            rowIndex,
+                            sheetId: range.sheetId,
+                        });
+                    }
+                }
+            });
+            saveHistory({
+                sheetData: { patches, inversePatches },
+                recalcCells: { undo: recalcCells, redo: recalcCells },
+            });
+            return nextState;
+        });
+        sharedStringRegistry?.getPatches(saveHistory);
+    }, [
+        createHistory,
+        locale,
+        enqueueCalculation,
+        enqueueStructureChange,
+        onChangeSheetData,
+        sharedStringRegistry,
+        onCommand,
+    ]);
+};

package/dist/esm/hooks/use-on-freeze.d.ts

@@ -0,0 +1,13 @@
+import { type CellData, type Sheet } from "@rowsncolumns/spreadsheet";
+import type { OnCommand } from "../commands";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+export type UseOnFreezeProps<T extends CellData, S extends Sheet> = {
+    createHistory(): (patches: SpreadsheetPatch) => void;
+    onChangeSheets: UseSpreadsheetProps<T, S>["onChangeSheets"];
+    onChangeEmbeds?: UseSpreadsheetProps<T, S>["onChangeEmbeds"];
+    onChangeCharts?: UseSpreadsheetProps<T, S>["onChangeCharts"];
+    onCommand?: OnCommand;
+};
+export declare const useOnFreeze: <T extends CellData, S extends Sheet>({ createHistory, onChangeSheets, onChangeEmbeds, onChangeCharts, onCommand, }: UseOnFreezeProps<T, S>) => readonly [(sheetId: number, rowIndex: number) => void, (sheetId: number, columnIndex: number) => void];
+//# sourceMappingURL=use-on-freeze.d.ts.map

package/dist/esm/hooks/use-on-freeze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-on-freeze.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-freeze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAGtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IAClE,aAAa,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACrD,cAAc,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC5D,cAAc,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC7D,cAAc,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,+EAM9D,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,yBAGX,MAAM,YAAY,MAAM,qBA8BxB,MAAM,eAAe,MAAM,UA8BxC,CAAC"}

package/dist/esm/hooks/use-on-freeze.js

@@ -0,0 +1,55 @@
+import { useCallback } from "react";
+import { freezeColumn, freezeRow } from "../interface/freeze";
+import { useCanEditSheet } from "./use-can-edit-cellrange";
+export const useOnFreeze = ({ createHistory, onChangeSheets, onChangeEmbeds, onChangeCharts, onCommand, }) => {
+    const canEditSheet = useCanEditSheet();
+    const onFreezeRow = useCallback((sheetId, rowIndex) => {
+        if (!canEditSheet(sheetId)) {
+            console.debug("This range is protected, users cannot edit this cell range.");
+            return;
+        }
+        freezeRow({
+            createHistory,
+            onChangeSheets,
+            onChangeEmbeds,
+            onChangeCharts,
+        })(sheetId, rowIndex);
+        onCommand?.({
+            command: "freeze-row",
+            sheetId,
+            rowIndex,
+        });
+    }, [
+        canEditSheet,
+        createHistory,
+        onChangeSheets,
+        onChangeEmbeds,
+        onChangeCharts,
+        onCommand,
+    ]);
+    const onFreezeColumn = useCallback((sheetId, columnIndex) => {
+        if (!canEditSheet?.(sheetId)) {
+            console.debug("This range is protected, users cannot edit this cell range.");
+            return;
+        }
+        freezeColumn({
+            createHistory,
+            onChangeSheets,
+            onChangeEmbeds,
+            onChangeCharts,
+        })(sheetId, columnIndex);
+        onCommand?.({
+            command: "freeze-column",
+            sheetId,
+            columnIndex,
+        });
+    }, [
+        canEditSheet,
+        createHistory,
+        onChangeSheets,
+        onChangeEmbeds,
+        onChangeCharts,
+        onCommand,
+    ]);
+    return [onFreezeRow, onFreezeColumn];
+};

package/dist/esm/hooks/use-on-group-columns.d.ts

@@ -0,0 +1,11 @@
+import type { CellData, Sheet } from "@rowsncolumns/spreadsheet";
+import type { OnCommand } from "../commands";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+export type UseOnGroupColumnsProps<T extends CellData, S extends Sheet> = {
+    createHistory(): (patches: SpreadsheetPatch) => void;
+    onChangeSheets: UseSpreadsheetProps<T, S>["onChangeSheets"];
+    onCommand?: OnCommand;
+};
+export declare const useOnGroupColumns: <T extends CellData, S extends Sheet>({ createHistory, onChangeSheets, onCommand, }: UseOnGroupColumnsProps<T, S>) => (sheetId: number, columnIndexes: number[]) => void;
+//# sourceMappingURL=use-on-group-columns.d.ts.map

package/dist/esm/hooks/use-on-group-columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-on-group-columns.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-group-columns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAER,KAAK,EACN,MAAM,2BAA2B,CAAC;AAMnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IACxE,aAAa,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACrD,cAAc,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,+CAIpE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,eAGjB,MAAM,iBAAiB,MAAM,EAAE,SAkC5C,CAAC"}

package/dist/esm/hooks/use-on-group-columns.js

@@ -0,0 +1,35 @@
+import { produceWithPatches } from "immer";
+import { useCallback } from "react";
+import { clampOutlineLevel, contiguousSpans } from "../api/outline";
+import { useCanEditSheet } from "./use-can-edit-cellrange";
+export const useOnGroupColumns = ({ createHistory, onChangeSheets, onCommand, }) => {
+    const canEditSheet = useCanEditSheet();
+    return useCallback((sheetId, columnIndexes) => {
+        if (!canEditSheet(sheetId) || columnIndexes.length === 0)
+            return;
+        const saveHistory = createHistory();
+        const sorted = [...columnIndexes].sort((a, b) => a - b);
+        const spans = contiguousSpans(sorted);
+        onChangeSheets?.((prevSheets) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheets, (draft) => {
+                const sheet = draft.find((s) => s.sheetId === sheetId);
+                if (!sheet)
+                    return;
+                if (!sheet.columnMetadata)
+                    sheet.columnMetadata = [];
+                for (const { start, end } of spans) {
+                    for (let c = start; c <= end; c++) {
+                        if (!sheet.columnMetadata[c]) {
+                            sheet.columnMetadata[c] = {};
+                        }
+                        const meta = sheet.columnMetadata[c];
+                        meta.outlineLevel = clampOutlineLevel((meta.outlineLevel ?? 0) + 1);
+                    }
+                }
+            });
+            saveHistory({ sheets: { patches, inversePatches } });
+            return nextState;
+        });
+        onCommand?.({ command: "group-columns", sheetId, columnIndexes });
+    }, [canEditSheet, createHistory, onChangeSheets, onCommand]);
+};

package/dist/esm/hooks/use-on-group-rows.d.ts

@@ -0,0 +1,17 @@
+import type { CellData, Sheet } from "@rowsncolumns/spreadsheet";
+import type { OnCommand } from "../commands";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+export type UseOnGroupRowsProps<T extends CellData, S extends Sheet> = {
+    createHistory(): (patches: SpreadsheetPatch) => void;
+    onChangeSheets: UseSpreadsheetProps<T, S>["onChangeSheets"];
+    onCommand?: OnCommand;
+};
+/**
+ * Group a contiguous run of rows. The selection is split into
+ * contiguous spans first (so non-adjacent rows form independent
+ * groups). Each span has its `outlineLevel` incremented by one, capped
+ * at 7. Matches Excel's Data → Group → Rows command.
+ */
+export declare const useOnGroupRows: <T extends CellData, S extends Sheet>({ createHistory, onChangeSheets, onCommand, }: UseOnGroupRowsProps<T, S>) => (sheetId: number, rowIndexes: number[]) => void;
+//# sourceMappingURL=use-on-group-rows.d.ts.map

package/dist/esm/hooks/use-on-group-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-on-group-rows.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-group-rows.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAER,KAAK,EACN,MAAM,2BAA2B,CAAC;AAMnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,IAAI;IACrE,aAAa,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACrD,cAAc,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,EAAE,+CAIjE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,eAGd,MAAM,cAAc,MAAM,EAAE,SAkCzC,CAAC"}