@rowsncolumns/spreadsheet-state 28.0.66

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

@@ -0,0 +1,247 @@
+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 const useOnSortRange = ({ locale, sharedStringRegistry, createHistory, enqueueStructureChange, enqueueGraphOperation, enqueueCalculation, onChangeSheetData, getDependents, isHiddenRow, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, onCommand, }) => {
+    const canEditCellRange = useCanEditCellRange();
+    const canPerformSheetAction = useCanPerformSheetAction();
+    const showError = useShowError();
+    return useCallback((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) => {
+        const activeSheetName = getSheetName(sheetId);
+        // We need to track this for history. Precedent cells
+        const recalcCells = new Map();
+        // History
+        const saveHistory = createHistory();
+        const selection = selections[0];
+        if (!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?.({
+            kind: "invalidate-range",
+            sheetId,
+            startRowIndex: selection.range.startRowIndex,
+            endRowIndex: selection.range.endRowIndex,
+            startColumnIndex: selection.range.startColumnIndex,
+            endColumnIndex: selection.range.endColumnIndex,
+        });
+        // Update sheet data
+        onChangeSheetData?.((prevSheetData) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
+                const sheet = createSheetDraft(draft, sheetId);
+                const startRowIndex = selection.range.startRowIndex;
+                const endRowIndex = selection.range.endRowIndex;
+                const startColumnIndex = selection.range.startColumnIndex;
+                const endColumnIndex = selection.range.endColumnIndex;
+                const rowEntries = [];
+                const rowSnapshots = new Map();
+                const frozenRowCount = getFrozenRowCount(sheetId);
+                for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        continue;
+                    }
+                    const rowValue = sheet[rowIndex];
+                    const sortValues = [];
+                    for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                        const cellData = rowValue?.values?.[columnIndex];
+                        const sheetCell = new SheetCell(sheetId, { rowIndex, columnIndex }, cellData, { locale, sharedStringRegistry });
+                        const fallbackValue = sheetCell.getEffectiveValue() ?? 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.
+                        const spec = specs?.[columnIndex - startColumnIndex];
+                        const sortBy = spec?.sortBy ?? "value";
+                        const fmt = sortBy === "cellColor" ||
+                            sortBy === "fontColor" ||
+                            sortBy === "icon"
+                            ? getEffectiveFormat?.(sheetId, rowIndex, columnIndex)
+                            : undefined;
+                        const sortValue = sortBy === "cellColor"
+                            ? getStringifiedColor(fmt?.backgroundColor, theme)
+                            : sortBy === "fontColor"
+                                ? getStringifiedColor(fmt?.textFormat?.color, theme)
+                                : sortBy === "icon"
+                                    ? fmt?.conditionalIcon
+                                        ? {
+                                            iconSet: fmt.conditionalIcon.iconSet,
+                                            iconId: fmt.conditionalIcon.iconId,
+                                        }
+                                        : undefined
+                                    : fallbackValue;
+                        sortValues.push(sortValue);
+                    }
+                    rowSnapshots.set(rowIndex, (rowValue?.values ?? []).slice());
+                    rowEntries.push({ rowIndex, 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.
+                const sortSpecs = specs
+                    ? specs.map((spec) => ({
+                        ...spec,
+                        sortColor: getStringifiedColor(spec.sortColor, theme),
+                    }))
+                    : new Array(rowEntries[0]?.sortValues.length ?? 0).fill(sortOrder);
+                const sortedEntries = sortRowEntriesByFrozenState(rowEntries, frozenRowCount, sortSpecs);
+                // Counter for how many rows we have skipped
+                let skippedRow = 0;
+                for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        skippedRow++;
+                        continue;
+                    }
+                    const sourceRow = sortedEntries[rowIndex - skippedRow - startRowIndex];
+                    if (!sourceRow) {
+                        continue;
+                    }
+                    if (sourceRow.rowIndex === rowIndex) {
+                        continue;
+                    }
+                    const sourceRowValues = rowSnapshots.get(sourceRow.rowIndex) ?? [];
+                    const currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+                    for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                        const sourceCellData = sourceRowValues[columnIndex];
+                        const hasFormula = !!getExtendedValueFormula(getCellUserEnteredValue(sourceCellData));
+                        let sheetCell;
+                        if (sourceCellData && hasFormula) {
+                            sheetCell = new SheetCell(sheetId, { rowIndex: sourceRow.rowIndex, columnIndex }, sourceCellData, { locale, sharedStringRegistry });
+                        }
+                        const coords = sheetCell?.coords ?? {
+                            rowIndex: sourceRow.rowIndex,
+                            columnIndex,
+                        };
+                        // get dependents of original cell
+                        const dependents = getDependents({
+                            sheetId,
+                            ...coords,
+                        });
+                        // Move formula
+                        if (sheetCell?.isFormula()) {
+                            sheetCell.moveFormula(sheetCell.coords, {
+                                rowIndex,
+                                columnIndex,
+                            }, activeSheetName, {
+                                preserveAbsolutes: true, // keep absolute refs fixed during sort
+                            });
+                        }
+                        // Add new formula
+                        if (hasFormula) {
+                            enqueueGraphOperation({
+                                type: "add",
+                                position: {
+                                    sheetId,
+                                    rowIndex,
+                                    columnIndex,
+                                },
+                                previousPosition: {
+                                    sheetId,
+                                    ...coords,
+                                },
+                            });
+                            recalcCells.set(createSheetCellIdentifier(sheetId, rowIndex, columnIndex), {
+                                sheetId,
+                                rowIndex,
+                                columnIndex,
+                            });
+                        }
+                        for (const dependent of dependents) {
+                            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);
+                        }
+                        // Update
+                        if (sheetCell) {
+                            currentSheet[rowIndex].values[columnIndex] =
+                                sheetCell?.getCellData();
+                        }
+                        else {
+                            currentSheet[rowIndex].values[columnIndex] =
+                                sourceCellData;
+                        }
+                    }
+                }
+            });
+            // Save history
+            saveHistory({
+                sheetData: { patches, inversePatches },
+                recalcCells: { undo: recalcCells, redo: recalcCells },
+                selections: { undo: selections, redo: selections },
+            });
+            return nextState;
+        });
+        onCommand?.({
+            command: "sort-range",
+            sheetId,
+            selections,
+            sortOrder,
+        });
+    }, [
+        locale,
+        createHistory,
+        enqueueStructureChange,
+        getDependents,
+        enqueueGraphOperation,
+        enqueueCalculation,
+        onChangeSheetData,
+        isHiddenRow,
+        getFrozenRowCount,
+        getSheetName,
+        getEffectiveFormat,
+        theme,
+        onCommand,
+        canEditCellRange,
+        canPerformSheetAction,
+        showError,
+    ]);
+};

package/dist/esm/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/esm/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/esm/hooks/use-on-sort-table.js

@@ -0,0 +1,332 @@
+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 const useOnSortTable = ({ locale, sharedStringRegistry, createHistory, enqueueCalculation, enqueueStructureChange, enqueueGraphOperation, onChangeSheetData, onChangeTables, onChangeSheets, getDependents, isHiddenRow, getActiveCell, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, enableSortTimingLogs, onCommand, }) => {
+    const canEditCellRange = useCanEditCellRange();
+    const canPerformSheetAction = useCanPerformSheetAction();
+    const showError = useShowError();
+    const callback = useCallback((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;
+        }
+        const now = typeof performance !== "undefined" &&
+            typeof performance.now === "function"
+            ? performance.now.bind(performance)
+            : Date.now;
+        const activeSheetName = getSheetName(sheetId);
+        // We need to track this for history. Precedent cells
+        const recalcCells = new Map();
+        // History
+        const 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).
+        const sortSpecs = Array.isArray(dimensionIndexOrSpecs)
+            ? dimensionIndexOrSpecs
+            : [
+                {
+                    dimensionIndex: dimensionIndexOrSpecs,
+                    sortOrder: sortOrder ?? "ASCENDING",
+                    ...(options?.sortBy ? { sortBy: options.sortBy } : {}),
+                    ...(options?.sortColor ? { sortColor: options.sortColor } : {}),
+                    ...(options?.sortIcon ? { sortIcon: options.sortIcon } : {}),
+                    ...(options?.customList
+                        ? { customList: options.customList }
+                        : {}),
+                },
+            ];
+        // Primary spec drives `onCommand` reporting and timing logs.
+        const primarySpec = sortSpecs[0];
+        if (!primarySpec) {
+            return;
+        }
+        enqueueStructureChange?.({
+            kind: "invalidate-range",
+            sheetId,
+            startRowIndex: filter.range.startRowIndex,
+            endRowIndex: filter.range.endRowIndex,
+            startColumnIndex: filter.range.startColumnIndex,
+            endColumnIndex: filter.range.endColumnIndex,
+        });
+        // Update table sort specs
+        onChangeTables?.((prevTables) => {
+            const exists = prevTables.find((table) => table.id === filter.id);
+            if (exists) {
+                const [nextState, patches, inversePatches] = produceWithPatches(prevTables, (draft) => {
+                    const table = draft.find((table) => table.id === filter.id);
+                    if (table) {
+                        table.sortSpecs = sortSpecs;
+                    }
+                });
+                // Save history
+                saveHistory({
+                    tables: { patches, inversePatches },
+                });
+                return nextState;
+            }
+            else {
+                return prevTables;
+            }
+        });
+        // Update basic filter sort specs if exists
+        onChangeSheets?.((prevSheets) => {
+            const sheet = prevSheets.find((sheet) => sheet.sheetId === sheetId);
+            if (sheet && sheet.basicFilter?.id === filter.id) {
+                const [nextState, patches, inversePatches] = produceWithPatches(prevSheets, (draft) => {
+                    const sheet = draft.find((sheet) => sheet.sheetId === sheetId);
+                    if (sheet) {
+                        set(sheet, "basicFilter.sortSpecs", sortSpecs);
+                    }
+                });
+                saveHistory({
+                    sheets: {
+                        patches,
+                        inversePatches,
+                    },
+                });
+                return nextState;
+            }
+            return prevSheets;
+        });
+        // Update sheet data
+        onChangeSheetData?.((prevSheetData) => {
+            const overallStart = now();
+            let buildMs = 0;
+            let sortMs = 0;
+            let applyMs = 0;
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheetData, (draft) => {
+                const sheet = draft[sheetId];
+                const { range, headerRow = true, totalRow } = filter;
+                const startRowIndex = range.startRowIndex + (headerRow ? 1 : 0);
+                const endRowIndex = range.endRowIndex - (totalRow ? 1 : 0);
+                const rowEntries = [];
+                const rowSnapshots = new Map();
+                const frozenRowCount = getFrozenRowCount(sheetId);
+                // Gather row data
+                const buildStart = now();
+                for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        continue;
+                    }
+                    const rowValue = sheet[rowIndex];
+                    rowSnapshots.set(rowIndex, (rowValue?.values ?? []).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`.
+                    const sortValues = sortSpecs.map((spec) => {
+                        const specColumnIndex = range.startColumnIndex + spec.dimensionIndex;
+                        const sortCellData = rowValue?.values?.[specColumnIndex];
+                        const sortCell = new SheetCell(sheetId, { rowIndex, columnIndex: specColumnIndex }, sortCellData, { locale, sharedStringRegistry });
+                        const fallbackValue = sortCell.getEffectiveValue() ?? sortCell.formattedValue;
+                        // For color/icon sort modes, replace the value with the
+                        // matching attribute from the cell's effective format.
+                        const sortBy = spec.sortBy ?? "value";
+                        const fmt = sortBy === "cellColor" ||
+                            sortBy === "fontColor" ||
+                            sortBy === "icon"
+                            ? 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?.backgroundColor, theme)
+                            : sortBy === "fontColor"
+                                ? getStringifiedColor(fmt?.textFormat?.color, theme)
+                                : sortBy === "icon"
+                                    ? fmt?.conditionalIcon
+                                        ? {
+                                            iconSet: fmt.conditionalIcon.iconSet,
+                                            iconId: fmt.conditionalIcon.iconId,
+                                        }
+                                        : undefined
+                                    : fallbackValue;
+                    });
+                    rowEntries.push({ rowIndex, sortValues });
+                }
+                buildMs = now() - buildStart;
+                // Sort data — one engine spec per SortSpecs entry, in order.
+                const sortStart = now();
+                const sortedEntries = sortRowEntriesByFrozenState(rowEntries, frozenRowCount, sortSpecs.map((spec) => ({
+                    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
+                let skippedRow = 0;
+                // Save
+                const applyStart = now();
+                for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+                    // Ignore hidden rows
+                    if (isHiddenRow(sheetId, rowIndex)) {
+                        skippedRow++;
+                        continue;
+                    }
+                    const sourceRow = sortedEntries[rowIndex - skippedRow - startRowIndex];
+                    if (!sourceRow) {
+                        continue;
+                    }
+                    if (sourceRow.rowIndex === rowIndex) {
+                        continue;
+                    }
+                    const sourceRowValues = rowSnapshots.get(sourceRow.rowIndex) ?? [];
+                    const currentSheet = createSheetDraft(draft, sheetId, rowIndex);
+                    const reusableSheetCell = new SheetCell();
+                    const rangeWidth = range.endColumnIndex - range.startColumnIndex + 1;
+                    const rangeValues = sourceRowValues.slice(range.startColumnIndex, range.endColumnIndex + 1);
+                    if (!currentSheet[rowIndex].values) {
+                        currentSheet[rowIndex].values = [];
+                    }
+                    currentSheet[rowIndex].values.splice(range.startColumnIndex, rangeWidth, ...rangeValues);
+                    for (let columnIndex = range.startColumnIndex; columnIndex <= range.endColumnIndex; columnIndex++) {
+                        const sourceCellData = sourceRowValues[columnIndex];
+                        const hasFormula = !!getExtendedValueFormula(getCellUserEnteredValue(sourceCellData));
+                        let sheetCell;
+                        if (sourceCellData && hasFormula) {
+                            sheetCell = reusableSheetCell.assign(sheetId, { rowIndex: sourceRow.rowIndex, columnIndex }, sourceCellData, { locale, sharedStringRegistry });
+                            sheetCell.moveFormula(sheetCell.coords, {
+                                rowIndex,
+                                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,
+                                    rowIndex,
+                                    columnIndex,
+                                },
+                                previousPosition: {
+                                    sheetId,
+                                    rowIndex: sourceRow.rowIndex,
+                                    columnIndex,
+                                },
+                            });
+                            recalcCells.set(createSheetCellIdentifier(sheetId, rowIndex, columnIndex), {
+                                sheetId,
+                                rowIndex,
+                                columnIndex,
+                            });
+                        }
+                        if (sheetCell) {
+                            currentSheet[rowIndex].values[columnIndex] =
+                                sheetCell.getCellData();
+                        }
+                        // Dependents
+                        const dependents = getDependents({
+                            sheetId,
+                            rowIndex,
+                            columnIndex,
+                        });
+                        // Check if this cell has any dependents
+                        for (const dependent of dependents) {
+                            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);
+                        }
+                    }
+                }
+                applyMs = now() - applyStart;
+            });
+            const overallMs = now() - overallStart;
+            if (enableSortTimingLogs) {
+                console.debug("sort-table timings", {
+                    sheetId,
+                    sortOrder: primarySpec.sortOrder,
+                    range: filter.range,
+                    buildMs,
+                    sortMs,
+                    applyMs,
+                    overallMs,
+                });
+            }
+            // Save history
+            saveHistory({
+                sheetData: { patches, inversePatches },
+                recalcCells: { undo: recalcCells, redo: recalcCells },
+                activeCell: { undo: getActiveCell(), redo: getActiveCell() },
+            });
+            return nextState;
+        });
+        onCommand?.({
+            command: "sort-table",
+            sheetId,
+            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;
+};