@rowsncolumns/spreadsheet-state 28.0.66

package/dist/cjs/hooks/use-on-sort-range.js

@@ -0,0 +1,252 @@
+import { __assign, __read, __values } from "tslib";
+import { isStaticNode } from "@rowsncolumns/dag";
+import { isCellWithinBounds } from "@rowsncolumns/grid";
+import { getCellUserEnteredValue, getExtendedValueFormula, getStringifiedColor, } from "@rowsncolumns/spreadsheet";
+import { produceWithPatches } from "immer";
+import { useCallback } from "react";
+import { createSheetCellIdentifier } from "../api/formula";
+import { createSheetDraft } from "../api/immer-utils";
+import { useShowError } from "../atoms/error-state.atom";
+import { SHEET_PROTECTION_ERROR_TITLE, useCanEditCellRange, useCanPerformSheetAction, } from "./use-can-edit-cellrange";
+import { SheetCell } from "../sheet-cell";
+import { sortRowEntriesByFrozenState, } from "./utils/sort-rows";
+/**
+ * Sorts a column range.
+ * This does not expand the selection
+ * @param param0
+ * @returns
+ */
+export var useOnSortRange = function (_a) {
+    var locale = _a.locale, sharedStringRegistry = _a.sharedStringRegistry, createHistory = _a.createHistory, enqueueStructureChange = _a.enqueueStructureChange, enqueueGraphOperation = _a.enqueueGraphOperation, enqueueCalculation = _a.enqueueCalculation, onChangeSheetData = _a.onChangeSheetData, getDependents = _a.getDependents, isHiddenRow = _a.isHiddenRow, getFrozenRowCount = _a.getFrozenRowCount, getSheetName = _a.getSheetName, getEffectiveFormat = _a.getEffectiveFormat, theme = _a.theme, onCommand = _a.onCommand;
+    var canEditCellRange = useCanEditCellRange();
+    var canPerformSheetAction = useCanPerformSheetAction();
+    var showError = useShowError();
+    return useCallback(function (sheetId, selections, sortOrder, 
+    /**
+     * Optional per-column sort specifications, one per column in
+     * selection order (column 0 = `selection.range.startColumnIndex`).
+     * The array is consumed as multi-level "then by" specs by the row
+     * sorter (spec[0] primary, spec[1] tiebreaker, …). When omitted the
+     * legacy uniform-direction behavior is preserved exactly.
+     */
+    specs) {
+        var activeSheetName = getSheetName(sheetId);
+        // We need to track this for history. Precedent cells
+        var recalcCells = new Map();
+        // History
+        var saveHistory = createHistory();
+        var selection = selections[0];
+        if (!(selection === null || selection === void 0 ? void 0 : selection.range)) {
+            return;
+        }
+        // Protection — sort rewrites every cell in the range. The sheet's
+        // `<sheetProtection sort>` flag is consulted first; then any locked
+        // cell (host `canEditCell` / `isSheetProtected` policy via
+        // useCanEditCellRange) vetoes the sort.
+        if (!canPerformSheetAction(sheetId, "sort")) {
+            showError({
+                title: SHEET_PROTECTION_ERROR_TITLE,
+                message: "You can't sort a range on a protected sheet.",
+            });
+            return;
+        }
+        if (!canEditCellRange(sheetId, selection.range)) {
+            console.debug("This range is protected, users cannot sort this cell range.");
+            return;
+        }
+        enqueueStructureChange === null || enqueueStructureChange === void 0 ? void 0 : enqueueStructureChange({
+            kind: "invalidate-range",
+            sheetId: sheetId,
+            startRowIndex: selection.range.startRowIndex,
+            endRowIndex: selection.range.endRowIndex,
+            startColumnIndex: selection.range.startColumnIndex,
+            endColumnIndex: selection.range.endColumnIndex,
+        });
+        // Update sheet data
+        onChangeSheetData === null || onChangeSheetData === void 0 ? void 0 : onChangeSheetData(function (prevSheetData) {
+            var _a = __read(produceWithPatches(prevSheetData, function (draft) {
+                var e_1, _a;
+                var _b, _c, _d, _e, _f, _g, _h, _j, _k;
+                var sheet = createSheetDraft(draft, sheetId);
+                var startRowIndex = selection.range.startRowIndex;
+                var endRowIndex = selection.range.endRowIndex;
+                var startColumnIndex = selection.range.startColumnIndex;
+                var endColumnIndex = selection.range.endColumnIndex;
+                var rowEntries = [];
+                var rowSnapshots = new Map();
+                var frozenRowCount = getFrozenRowCount(sheetId);
+                for (var rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        continue;
+                    }
+                    var rowValue = sheet[rowIndex];
+                    var sortValues = [];
+                    for (var columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                        var cellData = (_b = rowValue === null || rowValue === void 0 ? void 0 : rowValue.values) === null || _b === void 0 ? void 0 : _b[columnIndex];
+                        var sheetCell = new SheetCell(sheetId, { rowIndex: rowIndex, columnIndex: columnIndex }, cellData, { locale: locale, sharedStringRegistry: sharedStringRegistry });
+                        var fallbackValue = (_c = sheetCell.getEffectiveValue()) !== null && _c !== void 0 ? _c : sheetCell.formattedValue;
+                        // When the per-column spec sorts by color/icon, swap the
+                        // value for the matching attribute from the cell's
+                        // effective format so sort-rows.ts can compare it.
+                        var spec = specs === null || specs === void 0 ? void 0 : specs[columnIndex - startColumnIndex];
+                        var sortBy = (_d = spec === null || spec === void 0 ? void 0 : spec.sortBy) !== null && _d !== void 0 ? _d : "value";
+                        var fmt = sortBy === "cellColor" ||
+                            sortBy === "fontColor" ||
+                            sortBy === "icon"
+                            ? getEffectiveFormat === null || getEffectiveFormat === void 0 ? void 0 : getEffectiveFormat(sheetId, rowIndex, columnIndex)
+                            : undefined;
+                        var sortValue = sortBy === "cellColor"
+                            ? getStringifiedColor(fmt === null || fmt === void 0 ? void 0 : fmt.backgroundColor, theme)
+                            : sortBy === "fontColor"
+                                ? getStringifiedColor((_e = fmt === null || fmt === void 0 ? void 0 : fmt.textFormat) === null || _e === void 0 ? void 0 : _e.color, theme)
+                                : sortBy === "icon"
+                                    ? (fmt === null || fmt === void 0 ? void 0 : fmt.conditionalIcon)
+                                        ? {
+                                            iconSet: fmt.conditionalIcon.iconSet,
+                                            iconId: fmt.conditionalIcon.iconId,
+                                        }
+                                        : undefined
+                                    : fallbackValue;
+                        sortValues.push(sortValue);
+                    }
+                    rowSnapshots.set(rowIndex, ((_f = rowValue === null || rowValue === void 0 ? void 0 : rowValue.values) !== null && _f !== void 0 ? _f : []).slice());
+                    rowEntries.push({ rowIndex: rowIndex, sortValues: sortValues });
+                }
+                // Sort each column. When per-column specs are provided, use
+                // them as multi-level "then by" specs (pre-resolving any
+                // target colors so sort-rows.ts can compare strings). Otherwise
+                // fall back to the legacy uniform-direction behavior.
+                var sortSpecs = specs
+                    ? specs.map(function (spec) { return (__assign(__assign({}, spec), { sortColor: getStringifiedColor(spec.sortColor, theme) })); })
+                    : new Array((_h = (_g = rowEntries[0]) === null || _g === void 0 ? void 0 : _g.sortValues.length) !== null && _h !== void 0 ? _h : 0).fill(sortOrder);
+                var sortedEntries = sortRowEntriesByFrozenState(rowEntries, frozenRowCount, sortSpecs);
+                // Counter for how many rows we have skipped
+                var skippedRow = 0;
+                for (var rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        skippedRow++;
+                        continue;
+                    }
+                    var sourceRow = sortedEntries[rowIndex - skippedRow - startRowIndex];
+                    if (!sourceRow) {
+                        continue;
+                    }
+                    if (sourceRow.rowIndex === rowIndex) {
+                        continue;
+                    }
+                    var sourceRowValues = (_j = rowSnapshots.get(sourceRow.rowIndex)) !== null && _j !== void 0 ? _j : [];
+                    var currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+                    for (var columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                        var sourceCellData = sourceRowValues[columnIndex];
+                        var hasFormula = !!getExtendedValueFormula(getCellUserEnteredValue(sourceCellData));
+                        var sheetCell = void 0;
+                        if (sourceCellData && hasFormula) {
+                            sheetCell = new SheetCell(sheetId, { rowIndex: sourceRow.rowIndex, columnIndex: columnIndex }, sourceCellData, { locale: locale, sharedStringRegistry: sharedStringRegistry });
+                        }
+                        var coords = (_k = sheetCell === null || sheetCell === void 0 ? void 0 : sheetCell.coords) !== null && _k !== void 0 ? _k : {
+                            rowIndex: sourceRow.rowIndex,
+                            columnIndex: columnIndex,
+                        };
+                        // get dependents of original cell
+                        var dependents = getDependents(__assign({ sheetId: sheetId }, coords));
+                        // Move formula
+                        if (sheetCell === null || sheetCell === void 0 ? void 0 : sheetCell.isFormula()) {
+                            sheetCell.moveFormula(sheetCell.coords, {
+                                rowIndex: rowIndex,
+                                columnIndex: columnIndex,
+                            }, activeSheetName, {
+                                preserveAbsolutes: true, // keep absolute refs fixed during sort
+                            });
+                        }
+                        // Add new formula
+                        if (hasFormula) {
+                            enqueueGraphOperation({
+                                type: "add",
+                                position: {
+                                    sheetId: sheetId,
+                                    rowIndex: rowIndex,
+                                    columnIndex: columnIndex,
+                                },
+                                previousPosition: __assign({ sheetId: sheetId }, coords),
+                            });
+                            recalcCells.set(createSheetCellIdentifier(sheetId, rowIndex, columnIndex), {
+                                sheetId: sheetId,
+                                rowIndex: rowIndex,
+                                columnIndex: columnIndex,
+                            });
+                        }
+                        try {
+                            for (var dependents_1 = (e_1 = void 0, __values(dependents)), dependents_1_1 = dependents_1.next(); !dependents_1_1.done; dependents_1_1 = dependents_1.next()) {
+                                var dependent = dependents_1_1.value;
+                                if (isStaticNode(dependent)) {
+                                    continue;
+                                }
+                                if (isCellWithinBounds(dependent.position, selection.range)) {
+                                    enqueueGraphOperation({
+                                        type: "add",
+                                        position: dependent.position,
+                                    });
+                                }
+                                else {
+                                    enqueueCalculation({
+                                        type: "dirty",
+                                        position: dependent.position,
+                                    });
+                                }
+                                recalcCells.set(createSheetCellIdentifier(dependent.position.sheetId, dependent.position.rowIndex, dependent.position.columnIndex), dependent.position);
+                            }
+                        }
+                        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                        finally {
+                            try {
+                                if (dependents_1_1 && !dependents_1_1.done && (_a = dependents_1.return)) _a.call(dependents_1);
+                            }
+                            finally { if (e_1) throw e_1.error; }
+                        }
+                        // Update
+                        if (sheetCell) {
+                            currentSheet[rowIndex].values[columnIndex] =
+                                sheetCell === null || sheetCell === void 0 ? void 0 : sheetCell.getCellData();
+                        }
+                        else {
+                            currentSheet[rowIndex].values[columnIndex] =
+                                sourceCellData;
+                        }
+                    }
+                }
+            }), 3), nextState = _a[0], patches = _a[1], inversePatches = _a[2];
+            // Save history
+            saveHistory({
+                sheetData: { patches: patches, inversePatches: inversePatches },
+                recalcCells: { undo: recalcCells, redo: recalcCells },
+                selections: { undo: selections, redo: selections },
+            });
+            return nextState;
+        });
+        onCommand === null || onCommand === void 0 ? void 0 : onCommand({
+            command: "sort-range",
+            sheetId: sheetId,
+            selections: selections,
+            sortOrder: sortOrder,
+        });
+    }, [
+        locale,
+        createHistory,
+        enqueueStructureChange,
+        getDependents,
+        enqueueGraphOperation,
+        enqueueCalculation,
+        onChangeSheetData,
+        isHiddenRow,
+        getFrozenRowCount,
+        getSheetName,
+        getEffectiveFormat,
+        theme,
+        onCommand,
+        canEditCellRange,
+        canPerformSheetAction,
+        showError,
+    ]);
+};

package/dist/cjs/hooks/use-on-sort-table.d.ts

@@ -0,0 +1,59 @@
+import type { CellInterface } from "@rowsncolumns/common-types";
+import type { CellData, FilterView, Sheet, SortOrder, SortSpecs, TableView } from "@rowsncolumns/spreadsheet";
+import type { SpreadsheetTheme } from "@rowsncolumns/spreadsheet";
+import type { OnCommand } from "../commands";
+import type { useCalculation } from "./use-calculation";
+import type { UseSpreadsheetProps } from "./use-spreadsheet-state";
+import type { SharedStringRegistry } from "./use-ss-registry";
+import type { SpreadsheetPatch } from "./use-undo-redo";
+import { type DimensionSortSpec } from "./utils/sort-rows";
+import type { useSheetProperties } from "./use-sheet-properties";
+export type SortTableOptions = Pick<DimensionSortSpec, "sortBy" | "sortColor" | "sortIcon" | "customList">;
+/**
+ * The sort callback supports two call forms:
+ *  - Single-dimension (filter-box A→Z / Z→A buttons):
+ *    `(sheetId, filter, dimensionIndex, sortOrder, options?)`.
+ *  - Multi-dimension (custom sort dialog):
+ *    `(sheetId, filter, specs)` where `specs` is the full ordered list
+ *    of `SortSpecs` (primary first, then tiebreakers). The full array is
+ *    persisted to `table.sortSpecs` / `basicFilter.sortSpecs`.
+ */
+export type OnSortTable = {
+    (sheetId: number, filter: FilterView | TableView, dimensionIndex: number, sortOrder: SortOrder, options?: SortTableOptions): void;
+    (sheetId: number, filter: FilterView | TableView, specs: SortSpecs[]): void;
+};
+type UseOnSortTableProps<T extends CellData, S extends Sheet> = {
+    locale?: string;
+    sharedStringRegistry?: SharedStringRegistry;
+    createHistory(): (patches: SpreadsheetPatch) => void;
+    enqueueCalculation: ReturnType<typeof useCalculation>["enqueueCalculation"];
+    enqueueStructureChange?: ReturnType<typeof useCalculation>["enqueueStructureChange"];
+    enqueueGraphOperation: ReturnType<typeof useCalculation>["enqueueGraphOperation"];
+    onChangeSheetData: UseSpreadsheetProps<T, S>["onChangeSheetData"];
+    onChangeTables: UseSpreadsheetProps<T, S>["onChangeTables"];
+    onChangeSheets: UseSpreadsheetProps<T, S>["onChangeSheets"];
+    isHiddenRow(sheetId: number, rowIndex: number): boolean;
+    getDependents: ReturnType<typeof useCalculation>["getDependents"];
+    getActiveCell: () => CellInterface;
+    getFrozenRowCount(sheetId: number): number;
+    getSheetName(sheetId: number): string;
+    /**
+     * Optional — needed for `sortBy: "cellColor" | "fontColor" | "icon"`.
+     */
+    getEffectiveFormat?: ReturnType<typeof useSheetProperties>["getEffectiveFormat"];
+    /**
+     * Required for color sort modes — used to resolve theme-indexed colors
+     * to the same hex the renderer paints before comparison.
+     */
+    theme: SpreadsheetTheme;
+    enableSortTimingLogs?: boolean;
+    onCommand?: OnCommand;
+};
+/**
+ * Sorts a column
+ * @param param0
+ * @returns
+ */
+export declare const useOnSortTable: <T extends CellData, S extends Sheet>({ locale, sharedStringRegistry, createHistory, enqueueCalculation, enqueueStructureChange, enqueueGraphOperation, onChangeSheetData, onChangeTables, onChangeSheets, getDependents, isHiddenRow, getActiveCell, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, enableSortTimingLogs, onCommand, }: UseOnSortTableProps<T, S>) => OnSortTable;
+export {};
+//# sourceMappingURL=use-on-sort-table.d.ts.map

package/dist/cjs/hooks/use-on-sort-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-on-sort-table.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-sort-table.ts"],"names":[],"mappings":"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"}

package/dist/cjs/hooks/use-on-sort-table.js

@@ -0,0 +1,345 @@
+import { __assign, __read, __spreadArray, __values } from "tslib";
+import { isStaticNode } from "@rowsncolumns/dag";
+import { isCellWithinBounds } from "@rowsncolumns/grid";
+import { getCellUserEnteredValue, getExtendedValueFormula, getStringifiedColor, } from "@rowsncolumns/spreadsheet";
+import { produceWithPatches } from "immer";
+import set from "lodash/set";
+import { useCallback } from "react";
+import { createSheetCellIdentifier } from "../api/formula";
+import { createSheetDraft } from "../api/immer-utils";
+import { SheetCell } from "../sheet-cell";
+import { useShowError } from "../atoms/error-state.atom";
+import { SHEET_PROTECTION_ERROR_TITLE, useCanEditCellRange, useCanPerformSheetAction, } from "./use-can-edit-cellrange";
+import { sortRowEntriesByFrozenState, } from "./utils/sort-rows";
+/**
+ * Sorts a column
+ * @param param0
+ * @returns
+ */
+export var useOnSortTable = function (_a) {
+    var locale = _a.locale, sharedStringRegistry = _a.sharedStringRegistry, createHistory = _a.createHistory, enqueueCalculation = _a.enqueueCalculation, enqueueStructureChange = _a.enqueueStructureChange, enqueueGraphOperation = _a.enqueueGraphOperation, onChangeSheetData = _a.onChangeSheetData, onChangeTables = _a.onChangeTables, onChangeSheets = _a.onChangeSheets, getDependents = _a.getDependents, isHiddenRow = _a.isHiddenRow, getActiveCell = _a.getActiveCell, getFrozenRowCount = _a.getFrozenRowCount, getSheetName = _a.getSheetName, getEffectiveFormat = _a.getEffectiveFormat, theme = _a.theme, enableSortTimingLogs = _a.enableSortTimingLogs, onCommand = _a.onCommand;
+    var canEditCellRange = useCanEditCellRange();
+    var canPerformSheetAction = useCanPerformSheetAction();
+    var showError = useShowError();
+    var callback = useCallback(function (sheetId, filter, dimensionIndexOrSpecs, sortOrder, options) {
+        // Protection — sorting a table rewrites every row in the table's
+        // data range. Block if any cell in that range is locked on a
+        // protected sheet.
+        if (!canPerformSheetAction(sheetId, "sort")) {
+            showError({
+                title: SHEET_PROTECTION_ERROR_TITLE,
+                message: "You can't sort a table on a protected sheet.",
+            });
+            return;
+        }
+        if (!canEditCellRange(sheetId, filter.range)) {
+            console.debug("This table is on a protected range, users cannot sort it.");
+            return;
+        }
+        var now = typeof performance !== "undefined" &&
+            typeof performance.now === "function"
+            ? performance.now.bind(performance)
+            : Date.now;
+        var activeSheetName = getSheetName(sheetId);
+        // We need to track this for history. Precedent cells
+        var recalcCells = new Map();
+        // History
+        var saveHistory = createHistory();
+        // Normalize the two call forms into a single ordered SortSpecs[].
+        // The multi-dimension form passes the full array directly; the
+        // single-dimension form builds a one-element array (preserving the
+        // exact shape the filter-box buttons produced previously).
+        var sortSpecs = Array.isArray(dimensionIndexOrSpecs)
+            ? dimensionIndexOrSpecs
+            : [
+                __assign(__assign(__assign(__assign({ dimensionIndex: dimensionIndexOrSpecs, sortOrder: sortOrder !== null && sortOrder !== void 0 ? sortOrder : "ASCENDING" }, ((options === null || options === void 0 ? void 0 : options.sortBy) ? { sortBy: options.sortBy } : {})), ((options === null || options === void 0 ? void 0 : options.sortColor) ? { sortColor: options.sortColor } : {})), ((options === null || options === void 0 ? void 0 : options.sortIcon) ? { sortIcon: options.sortIcon } : {})), ((options === null || options === void 0 ? void 0 : options.customList)
+                    ? { customList: options.customList }
+                    : {})),
+            ];
+        // Primary spec drives `onCommand` reporting and timing logs.
+        var primarySpec = sortSpecs[0];
+        if (!primarySpec) {
+            return;
+        }
+        enqueueStructureChange === null || enqueueStructureChange === void 0 ? void 0 : enqueueStructureChange({
+            kind: "invalidate-range",
+            sheetId: sheetId,
+            startRowIndex: filter.range.startRowIndex,
+            endRowIndex: filter.range.endRowIndex,
+            startColumnIndex: filter.range.startColumnIndex,
+            endColumnIndex: filter.range.endColumnIndex,
+        });
+        // Update table sort specs
+        onChangeTables === null || onChangeTables === void 0 ? void 0 : onChangeTables(function (prevTables) {
+            var exists = prevTables.find(function (table) { return table.id === filter.id; });
+            if (exists) {
+                var _a = __read(produceWithPatches(prevTables, function (draft) {
+                    var table = draft.find(function (table) { return table.id === filter.id; });
+                    if (table) {
+                        table.sortSpecs = sortSpecs;
+                    }
+                }), 3), nextState = _a[0], patches = _a[1], inversePatches = _a[2];
+                // Save history
+                saveHistory({
+                    tables: { patches: patches, inversePatches: inversePatches },
+                });
+                return nextState;
+            }
+            else {
+                return prevTables;
+            }
+        });
+        // Update basic filter sort specs if exists
+        onChangeSheets === null || onChangeSheets === void 0 ? void 0 : onChangeSheets(function (prevSheets) {
+            var _a;
+            var sheet = prevSheets.find(function (sheet) { return sheet.sheetId === sheetId; });
+            if (sheet && ((_a = sheet.basicFilter) === null || _a === void 0 ? void 0 : _a.id) === filter.id) {
+                var _b = __read(produceWithPatches(prevSheets, function (draft) {
+                    var sheet = draft.find(function (sheet) { return sheet.sheetId === sheetId; });
+                    if (sheet) {
+                        set(sheet, "basicFilter.sortSpecs", sortSpecs);
+                    }
+                }), 3), nextState = _b[0], patches = _b[1], inversePatches = _b[2];
+                saveHistory({
+                    sheets: {
+                        patches: patches,
+                        inversePatches: inversePatches,
+                    },
+                });
+                return nextState;
+            }
+            return prevSheets;
+        });
+        // Update sheet data
+        onChangeSheetData === null || onChangeSheetData === void 0 ? void 0 : onChangeSheetData(function (prevSheetData) {
+            var overallStart = now();
+            var buildMs = 0;
+            var sortMs = 0;
+            var applyMs = 0;
+            var _a = __read(produceWithPatches(prevSheetData, function (draft) {
+                var _a, e_1, _b;
+                var _c, _d;
+                var sheet = draft[sheetId];
+                var _e = filter, range = _e.range, _f = _e.headerRow, headerRow = _f === void 0 ? true : _f, totalRow = _e.totalRow;
+                var startRowIndex = range.startRowIndex + (headerRow ? 1 : 0);
+                var endRowIndex = range.endRowIndex - (totalRow ? 1 : 0);
+                var rowEntries = [];
+                var rowSnapshots = new Map();
+                var frozenRowCount = getFrozenRowCount(sheetId);
+                // Gather row data
+                var buildStart = now();
+                var _loop_1 = function (rowIndex) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        return "continue";
+                    }
+                    var rowValue = sheet[rowIndex];
+                    rowSnapshots.set(rowIndex, ((_c = rowValue === null || rowValue === void 0 ? void 0 : rowValue.values) !== null && _c !== void 0 ? _c : []).slice());
+                    // One sort value per spec, in spec order, so the comparator
+                    // can apply each spec as a "then by" tiebreaker. Each spec's
+                    // column is `range.startColumnIndex + spec.dimensionIndex`.
+                    var sortValues = sortSpecs.map(function (spec) {
+                        var _a, _b, _c, _d;
+                        var specColumnIndex = range.startColumnIndex + spec.dimensionIndex;
+                        var sortCellData = (_a = rowValue === null || rowValue === void 0 ? void 0 : rowValue.values) === null || _a === void 0 ? void 0 : _a[specColumnIndex];
+                        var sortCell = new SheetCell(sheetId, { rowIndex: rowIndex, columnIndex: specColumnIndex }, sortCellData, { locale: locale, sharedStringRegistry: sharedStringRegistry });
+                        var fallbackValue = (_b = sortCell.getEffectiveValue()) !== null && _b !== void 0 ? _b : sortCell.formattedValue;
+                        // For color/icon sort modes, replace the value with the
+                        // matching attribute from the cell's effective format.
+                        var sortBy = (_c = spec.sortBy) !== null && _c !== void 0 ? _c : "value";
+                        var fmt = sortBy === "cellColor" ||
+                            sortBy === "fontColor" ||
+                            sortBy === "icon"
+                            ? getEffectiveFormat === null || getEffectiveFormat === void 0 ? void 0 : getEffectiveFormat(sheetId, rowIndex, specColumnIndex)
+                            : undefined;
+                        // Resolve theme-indexed colors to their painted hex so
+                        // sort-rows.ts can compare via plain string equality.
+                        return sortBy === "cellColor"
+                            ? getStringifiedColor(fmt === null || fmt === void 0 ? void 0 : fmt.backgroundColor, theme)
+                            : sortBy === "fontColor"
+                                ? getStringifiedColor((_d = fmt === null || fmt === void 0 ? void 0 : fmt.textFormat) === null || _d === void 0 ? void 0 : _d.color, theme)
+                                : sortBy === "icon"
+                                    ? (fmt === null || fmt === void 0 ? void 0 : fmt.conditionalIcon)
+                                        ? {
+                                            iconSet: fmt.conditionalIcon.iconSet,
+                                            iconId: fmt.conditionalIcon.iconId,
+                                        }
+                                        : undefined
+                                    : fallbackValue;
+                    });
+                    rowEntries.push({ rowIndex: rowIndex, sortValues: sortValues });
+                };
+                for (var rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    _loop_1(rowIndex);
+                }
+                buildMs = now() - buildStart;
+                // Sort data — one engine spec per SortSpecs entry, in order.
+                var sortStart = now();
+                var sortedEntries = sortRowEntriesByFrozenState(rowEntries, frozenRowCount, sortSpecs.map(function (spec) { return ({
+                    sortOrder: spec.sortOrder,
+                    sortBy: spec.sortBy,
+                    // Pre-resolve so the comparator can use string equality.
+                    sortColor: getStringifiedColor(spec.sortColor, theme),
+                    sortIcon: spec.sortIcon,
+                    customList: spec.customList,
+                }); }));
+                sortMs = now() - sortStart;
+                // Counter for how many rows we have skipped
+                var skippedRow = 0;
+                // Save
+                var applyStart = now();
+                for (var rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        skippedRow++;
+                        continue;
+                    }
+                    var sourceRow = sortedEntries[rowIndex - skippedRow - startRowIndex];
+                    if (!sourceRow) {
+                        continue;
+                    }
+                    if (sourceRow.rowIndex === rowIndex) {
+                        continue;
+                    }
+                    var sourceRowValues = (_d = rowSnapshots.get(sourceRow.rowIndex)) !== null && _d !== void 0 ? _d : [];
+                    var currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+                    var reusableSheetCell = new SheetCell();
+                    var rangeWidth = range.endColumnIndex - range.startColumnIndex + 1;
+                    var rangeValues = sourceRowValues.slice(range.startColumnIndex, range.endColumnIndex + 1);
+                    if (!currentSheet[rowIndex].values) {
+                        currentSheet[rowIndex].values = [];
+                    }
+                    (_a = currentSheet[rowIndex].values).splice.apply(_a, __spreadArray([range.startColumnIndex,
+                        rangeWidth], __read(rangeValues), false));
+                    for (var columnIndex = range.startColumnIndex; columnIndex <= range.endColumnIndex; columnIndex++) {
+                        var sourceCellData = sourceRowValues[columnIndex];
+                        var hasFormula = !!getExtendedValueFormula(getCellUserEnteredValue(sourceCellData));
+                        var sheetCell = void 0;
+                        if (sourceCellData && hasFormula) {
+                            sheetCell = reusableSheetCell.assign(sheetId, { rowIndex: sourceRow.rowIndex, columnIndex: columnIndex }, sourceCellData, { locale: locale, sharedStringRegistry: sharedStringRegistry });
+                            sheetCell.moveFormula(sheetCell.coords, {
+                                rowIndex: rowIndex,
+                                columnIndex: columnIndex,
+                            }, activeSheetName, {
+                                preserveAbsolutes: true, // keep absolute refs fixed during sort to avoid #REF errors
+                            });
+                        }
+                        // Todo @vinay
+                        // sheetCell.clearConditionalFormatResults();
+                        if (hasFormula) {
+                            enqueueGraphOperation({
+                                type: "add",
+                                position: {
+                                    sheetId: sheetId,
+                                    rowIndex: rowIndex,
+                                    columnIndex: columnIndex,
+                                },
+                                previousPosition: {
+                                    sheetId: sheetId,
+                                    rowIndex: sourceRow.rowIndex,
+                                    columnIndex: columnIndex,
+                                },
+                            });
+                            recalcCells.set(createSheetCellIdentifier(sheetId, rowIndex, columnIndex), {
+                                sheetId: sheetId,
+                                rowIndex: rowIndex,
+                                columnIndex: columnIndex,
+                            });
+                        }
+                        if (sheetCell) {
+                            currentSheet[rowIndex].values[columnIndex] =
+                                sheetCell.getCellData();
+                        }
+                        // Dependents
+                        var dependents = getDependents({
+                            sheetId: sheetId,
+                            rowIndex: rowIndex,
+                            columnIndex: columnIndex,
+                        });
+                        try {
+                            // Check if this cell has any dependents
+                            for (var dependents_1 = (e_1 = void 0, __values(dependents)), dependents_1_1 = dependents_1.next(); !dependents_1_1.done; dependents_1_1 = dependents_1.next()) {
+                                var dependent = dependents_1_1.value;
+                                if (isStaticNode(dependent)) {
+                                    continue;
+                                }
+                                if (isCellWithinBounds(dependent.position, filter.range)) {
+                                    enqueueGraphOperation({
+                                        type: "add",
+                                        position: dependent.position,
+                                    });
+                                }
+                                else {
+                                    enqueueCalculation({
+                                        type: "dirty",
+                                        position: dependent.position,
+                                    });
+                                }
+                                recalcCells.set(createSheetCellIdentifier(dependent.position.sheetId, dependent.position.rowIndex, dependent.position.columnIndex), dependent.position);
+                            }
+                        }
+                        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                        finally {
+                            try {
+                                if (dependents_1_1 && !dependents_1_1.done && (_b = dependents_1.return)) _b.call(dependents_1);
+                            }
+                            finally { if (e_1) throw e_1.error; }
+                        }
+                    }
+                }
+                applyMs = now() - applyStart;
+            }), 3), nextState = _a[0], patches = _a[1], inversePatches = _a[2];
+            var overallMs = now() - overallStart;
+            if (enableSortTimingLogs) {
+                console.debug("sort-table timings", {
+                    sheetId: sheetId,
+                    sortOrder: primarySpec.sortOrder,
+                    range: filter.range,
+                    buildMs: buildMs,
+                    sortMs: sortMs,
+                    applyMs: applyMs,
+                    overallMs: overallMs,
+                });
+            }
+            // Save history
+            saveHistory({
+                sheetData: { patches: patches, inversePatches: inversePatches },
+                recalcCells: { undo: recalcCells, redo: recalcCells },
+                activeCell: { undo: getActiveCell(), redo: getActiveCell() },
+            });
+            return nextState;
+        });
+        onCommand === null || onCommand === void 0 ? void 0 : onCommand({
+            command: "sort-table",
+            sheetId: sheetId,
+            filter: filter,
+            dimensionIndex: primarySpec.dimensionIndex,
+            sortOrder: primarySpec.sortOrder,
+        });
+    }, [
+        locale,
+        sharedStringRegistry,
+        createHistory,
+        enqueueCalculation,
+        enqueueStructureChange,
+        enqueueGraphOperation,
+        onChangeSheets,
+        onChangeSheetData,
+        onChangeTables,
+        getActiveCell,
+        getDependents,
+        isHiddenRow,
+        getFrozenRowCount,
+        getSheetName,
+        getEffectiveFormat,
+        enableSortTimingLogs,
+        onCommand,
+        canEditCellRange,
+        canPerformSheetAction,
+        showError,
+        theme,
+    ]);
+    // Expose the overloaded signature (single-dimension + multi-dimension)
+    // while keeping the single normalized implementation above.
+    return callback;
+};