@rowsncolumns/spreadsheet-state 29.0.0 → 29.1.1

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

@@ -3,6 +3,7 @@ import { getCellUserEnteredValue, getExtendedValueFormula, getStringifiedColor,
 import { produceWithPatches } from "immer";
 import { useCallback } from "react";
 import { createSheetCellIdentifier } from "../api/formula";
+import { getCellSortValue } from "../api/sort";
 import { createSheetDraft } from "../api/immer-utils";
 import { SheetCell } from "../sheet-cell";
 import { useShowError } from "../atoms/error-state.atom";
@@ -32,7 +33,7 @@ const buildSortValue = (options, fallbackValue, getEffectiveFormat, theme, sheet
  * @param param0
  * @returns
  */
-export const useOnSortColumn = ({ rowCount, columnCount, locale, sharedStringRegistry, createHistory, enqueueCalculation, enqueueStructureChange, enqueueGraphOperation, onChangeSheetData, isHiddenRow, getDependents, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, enableSortTimingLogs, onCommand, }) => {
+export const useOnSortColumn = ({ rowCount, columnCount, locale, sharedStringRegistry, createHistory, enqueueCalculation, enqueueStructureChange, enqueueGraphOperation, onChangeSheetData, onChangeSheets, getCellData, getDataRowCount, isHiddenRow, isManuallyHiddenRow, getDependents, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, enableSortTimingLogs, onCommand, }) => {
     const canEditSheet = useCanEditSheet();
     const canPerformSheetAction = useCanPerformSheetAction();
     const showError = useShowError();
@@ -72,82 +73,114 @@ export const useOnSortColumn = ({ rowCount, columnCount, locale, sharedStringReg
             startColumnIndex: 1,
             endColumnIndex: columnCount,
         });
+        const startRowIndex = 1;
+        const startColumnIndex = 1;
+        const isPinnedRow = (rowIndex) => isManuallyHiddenRow
+            ? isManuallyHiddenRow(sheetId, rowIndex)
+            : isHiddenRow(sheetId, rowIndex);
+        const overallStart = now();
+        // Gather the sort keys from the committed cell data. Pinned rows
+        // contribute no entry and are never rewritten.
+        const buildStart = now();
+        const dataRowCount = getDataRowCount(sheetId) ?? 0;
+        const rowEntries = [];
+        for (let rowIndex = startRowIndex; rowIndex <= dataRowCount; rowIndex++) {
+            if (isPinnedRow(rowIndex)) {
+                continue;
+            }
+            // Build one sort value per level: the primary column first,
+            // then each "then by" column in order.
+            const buildLevelValue = (columnIndex, levelOptions) => {
+                const sortCell = new SheetCell(sheetId, { rowIndex, columnIndex }, getCellData(sheetId, rowIndex, columnIndex), { locale, sharedStringRegistry });
+                const fallbackValue = getCellSortValue(sortCell);
+                return buildSortValue(levelOptions, fallbackValue, getEffectiveFormat, theme, sheetId, rowIndex, columnIndex);
+            };
+            const sortValues = [
+                buildLevelValue(sortedColumnIndex, options),
+            ];
+            for (const level of additionalLevels ?? []) {
+                sortValues.push(buildLevelValue(level.columnIndex, level));
+            }
+            rowEntries.push({ rowIndex, sortValues });
+        }
+        const buildMs = now() - buildStart;
+        // The slots the sorted rows land on, ascending (the sort reorders
+        // `rowEntries` in place).
+        const destRows = rowEntries.map((entry) => entry.rowIndex);
+        // Sort data
+        const sortStart = now();
+        // Primary spec, then one spec per "then by" level. The order
+        // matches the sortValues built above so the comparator pairs
+        // each value with its spec. `sortedEntries[i]` is the row that
+        // lands on `destRows[i]`.
+        const specs = [
+            {
+                sortOrder,
+                sortBy: options?.sortBy ?? "value",
+                // Pre-resolve the target color the same way the cell sort
+                // values are resolved, so sort-rows.ts can compare strings.
+                sortColor: getStringifiedColor(options?.sortColor, theme),
+                sortIcon: options?.sortIcon,
+                customList: options?.customList,
+            },
+            ...(additionalLevels ?? []).map((level) => ({
+                sortOrder: level.sortOrder,
+                sortBy: level.sortBy ?? "value",
+                sortColor: getStringifiedColor(level.sortColor, theme),
+                sortIcon: level.sortIcon,
+                customList: level.customList,
+            })),
+        ];
+        const sortedEntries = sortRowEntriesByFrozenState(rowEntries, frozenRowCount, specs);
+        const sortMs = now() - sortStart;
+        // Carry each row's `hiddenByFilter` flag to the row's destination: a
+        // sort does not re-evaluate the filter, so the hidden set follows the
+        // rows.
+        onChangeSheets?.((prevSheets) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheets, (draft) => {
+                const sheet = draft.find((sheet) => sheet.sheetId === sheetId);
+                if (!sheet) {
+                    return;
+                }
+                const hiddenByFilterAt = (rowIndex) => Boolean(sheet.rowMetadata?.[rowIndex]?.hiddenByFilter);
+                // Read every source flag before writing any destination.
+                const carried = destRows.map((rowIndex, index) => hiddenByFilterAt(sortedEntries[index]?.rowIndex ?? rowIndex));
+                destRows.forEach((rowIndex, index) => {
+                    const hiddenByFilter = carried[index];
+                    if (hiddenByFilter === hiddenByFilterAt(rowIndex)) {
+                        return;
+                    }
+                    if (!sheet.rowMetadata) {
+                        sheet.rowMetadata = [];
+                    }
+                    sheet.rowMetadata[rowIndex] = {
+                        ...sheet.rowMetadata[rowIndex],
+                        hiddenByFilter,
+                    };
+                });
+            });
+            if (!patches.length) {
+                return prevSheets;
+            }
+            saveHistory({ sheets: { patches, inversePatches } });
+            return nextState;
+        });
         // 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 = createSheetDraft(draft, sheetId);
-                const startRowIndex = 1;
-                const startColumnIndex = 1;
-                const rowCount = sheet.length;
-                const rowEntries = [];
                 const rowSnapshots = new Map();
-                const buildStart = now();
                 let maxColumnCount = 0;
-                for (let rowIndex = startRowIndex; rowIndex <= rowCount; rowIndex++) {
-                    // Ignore hidden rows
-                    if (isHiddenRow(sheetId, rowIndex)) {
-                        continue;
-                    }
-                    const rowValue = sheet[rowIndex];
-                    const columnCount = rowValue?.values?.length ?? 0;
-                    maxColumnCount = Math.max(maxColumnCount, columnCount);
-                    rowSnapshots.set(rowIndex, (rowValue?.values ?? []).slice());
-                    // Build one sort value per level: the primary column first,
-                    // then each "then by" column in order.
-                    const buildLevelValue = (columnIndex, levelOptions) => {
-                        const sortCellData = rowValue?.values?.[columnIndex];
-                        const sortCell = new SheetCell(sheetId, { rowIndex, columnIndex }, sortCellData, { locale, sharedStringRegistry });
-                        const fallbackValue = sortCell.getEffectiveValue() ?? sortCell.formattedValue;
-                        return buildSortValue(levelOptions, fallbackValue, getEffectiveFormat, theme, sheetId, rowIndex, columnIndex);
-                    };
-                    const sortValues = [
-                        buildLevelValue(sortedColumnIndex, options),
-                    ];
-                    for (const level of additionalLevels ?? []) {
-                        sortValues.push(buildLevelValue(level.columnIndex, level));
-                    }
-                    rowEntries.push({ rowIndex, sortValues });
+                for (const rowIndex of destRows) {
+                    const rowValues = sheet[rowIndex]?.values ?? [];
+                    maxColumnCount = Math.max(maxColumnCount, rowValues.length);
+                    rowSnapshots.set(rowIndex, rowValues.slice());
                 }
-                buildMs = now() - buildStart;
-                // Sort data
-                const sortStart = now();
-                // Primary spec, then one spec per "then by" level. The order
-                // matches the sortValues built above so the comparator pairs
-                // each value with its spec.
-                const specs = [
-                    {
-                        sortOrder,
-                        sortBy: options?.sortBy ?? "value",
-                        // Pre-resolve the target color the same way the cell sort
-                        // values are resolved, so sort-rows.ts can compare strings.
-                        sortColor: getStringifiedColor(options?.sortColor, theme),
-                        sortIcon: options?.sortIcon,
-                        customList: options?.customList,
-                    },
-                    ...(additionalLevels ?? []).map((level) => ({
-                        sortOrder: level.sortOrder,
-                        sortBy: level.sortBy ?? "value",
-                        sortColor: getStringifiedColor(level.sortColor, theme),
-                        sortIcon: level.sortIcon,
-                        customList: level.customList,
-                    })),
-                ];
-                const sortedEntries = sortRowEntriesByFrozenState(rowEntries, frozenRowCount, specs);
-                sortMs = now() - sortStart;
-                // Counter for how many rows we have skipped
-                let skippedRow = 0;
                 const applyStart = now();
-                for (let rowIndex = startRowIndex; rowIndex <= sortedEntries.length; rowIndex++) {
-                    // Ignore hidden rows
-                    if (isHiddenRow(sheetId, rowIndex)) {
-                        skippedRow++;
-                        continue;
-                    }
-                    const sourceRow = sortedEntries[rowIndex - skippedRow - startRowIndex];
+                for (let index = 0; index < destRows.length; index++) {
+                    const rowIndex = destRows[index];
+                    const sourceRow = sortedEntries[index];
                     if (!sourceRow) {
                         continue;
                     }
@@ -254,7 +287,11 @@ export const useOnSortColumn = ({ rowCount, columnCount, locale, sharedStringReg
         enqueueStructureChange,
         enqueueGraphOperation,
         onChangeSheetData,
+        onChangeSheets,
+        getCellData,
+        getDataRowCount,
         isHiddenRow,
+        isManuallyHiddenRow,
         getDependents,
         getFrozenRowCount,
         canEditSheet,

package/dist/esm/hooks/use-on-sort-range.d.ts

@@ -1,5 +1,5 @@
 import type { SelectionArea } from "@rowsncolumns/common-types";
-import { type CellData, type SelectionAttributes, type SortOrder, type SpreadsheetTheme } from "@rowsncolumns/spreadsheet";
+import { type CellData, type Sheet, type SelectionAttributes, type SortOrder, type SpreadsheetTheme } from "@rowsncolumns/spreadsheet";
 import type { OnCommand } from "../commands";
 import type { useCalculation } from "./use-calculation";
 import type { useSheetProperties } from "./use-sheet-properties";
@@ -7,7 +7,7 @@ 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";
-export type UseOnSortRangeProps<T extends CellData> = {
+export type UseOnSortRangeProps<T extends CellData, S extends Sheet = Sheet> = {
     locale?: string;
     sharedStringRegistry?: SharedStringRegistry;
     createHistory(): (patches: SpreadsheetPatch) => void;
@@ -15,7 +15,30 @@ export type UseOnSortRangeProps<T extends CellData> = {
     enqueueGraphOperation: ReturnType<typeof useCalculation>["enqueueGraphOperation"];
     enqueueCalculation: ReturnType<typeof useCalculation>["enqueueCalculation"];
     onChangeSheetData: UseSpreadsheetProps<T>["onChangeSheetData"];
+    /**
+     * Receives each sorted row's `hiddenByFilter` flag at its destination,
+     * in the same undo step as the cell rewrite. Without it filter-hidden
+     * rows still sort, but the hidden set stays on the old row numbers.
+     */
+    onChangeSheets?: UseSpreadsheetProps<T, S>["onChangeSheets"];
+    /**
+     * Committed cell data — the sort keys are gathered from it before the
+     * state updaters run, so one row permutation drives both the sheet data
+     * rewrite and the row-metadata carry-over.
+     */
+    getCellData(sheetId: number, rowIndex: number, columnIndex: number): T | null | undefined;
+    /**
+     * Any hidden row (by the user, a filter, or a collapsed group). Used as
+     * the pin predicate only when `isManuallyHiddenRow` is not supplied.
+     */
     isHiddenRow(sheetId: number, rowIndex: number): boolean;
+    /**
+     * A row the user hid (`hiddenByUser` / a collapsed outline group). These
+     * rows are pinned in place; rows an AutoFilter hid sort along with the
+     * visible ones and keep their `hiddenByFilter` flag at their destination,
+     * like Excel.
+     */
+    isManuallyHiddenRow?(sheetId: number, rowIndex: number): boolean;
     getDependents: ReturnType<typeof useCalculation>["getDependents"];
     getFrozenRowCount(sheetId: number): number;
     getSheetName(sheetId: number): string;
@@ -38,5 +61,5 @@ export type UseOnSortRangeProps<T extends CellData> = {
  * @param param0
  * @returns
  */
-export declare const useOnSortRange: <T extends CellData>({ locale, sharedStringRegistry, createHistory, enqueueStructureChange, enqueueGraphOperation, enqueueCalculation, onChangeSheetData, getDependents, isHiddenRow, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, onCommand, }: UseOnSortRangeProps<T>) => (sheetId: number, selections: SelectionArea<SelectionAttributes>[], sortOrder: SortOrder, specs?: DimensionSortSpec[]) => void;
+export declare const useOnSortRange: <T extends CellData, S extends Sheet = Sheet>({ locale, sharedStringRegistry, createHistory, enqueueStructureChange, enqueueGraphOperation, enqueueCalculation, onChangeSheetData, onChangeSheets, getCellData, getDependents, isHiddenRow, isManuallyHiddenRow, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, onCommand, }: UseOnSortRangeProps<T, S>) => (sheetId: number, selections: SelectionArea<SelectionAttributes>[], sortOrder: SortOrder, specs?: DimensionSortSpec[]) => void;
 //# sourceMappingURL=use-on-sort-range.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-on-sort-range.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-sort-range.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE,OAAO,EACL,KAAK,QAAQ,EAIb,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAOnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,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,EACL,KAAK,iBAAiB,EAEvB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,QAAQ,IAAI;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,aAAa,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACrD,sBAAsB,CAAC,EAAE,UAAU,CACjC,OAAO,cAAc,CACtB,CAAC,wBAAwB,CAAC,CAAC;IAC5B,qBAAqB,EAAE,UAAU,CAC/B,OAAO,cAAc,CACtB,CAAC,uBAAuB,CAAC,CAAC;IAC3B,kBAAkB,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC5E,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAC/D,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxD,aAAa,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,eAAe,CAAC,CAAC;IAClE,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3C,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAC7B,OAAO,kBAAkB,CAC1B,CAAC,oBAAoB,CAAC,CAAC;IACxB;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,2OAehD,mBAAmB,CAAC,CAAC,CAAC,eAMV,MAAM,cACH,aAAa,CAAC,mBAAmB,CAAC,EAAE,aACrC,SAAS,UAQZ,iBAAiB,EAAE,SA8ShC,CAAC"}
+{"version":3,"file":"use-on-sort-range.d.ts","sourceRoot":"","sources":["../../../hooks/use-on-sort-range.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,KAAK,EAIV,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAQnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,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,EACL,KAAK,iBAAiB,EAEvB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,mBAAmB,CAC7B,CAAC,SAAS,QAAQ,EAClB,CAAC,SAAS,KAAK,GAAG,KAAK,IACrB;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,aAAa,IAAI,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACrD,sBAAsB,CAAC,EAAE,UAAU,CACjC,OAAO,cAAc,CACtB,CAAC,wBAAwB,CAAC,CAAC;IAC5B,qBAAqB,EAAE,UAAU,CAC/B,OAAO,cAAc,CACtB,CAAC,uBAAuB,CAAC,CAAC;IAC3B,kBAAkB,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC5E,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC7D;;;;OAIG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxD;;;;;OAKG;IACH,mBAAmB,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACjE,aAAa,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,eAAe,CAAC,CAAC;IAClE,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3C,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAC7B,OAAO,kBAAkB,CAC1B,CAAC,oBAAoB,CAAC,CAAC;IACxB;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,EAAE,6RAkBzE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,eAMb,MAAM,cACH,aAAa,CAAC,mBAAmB,CAAC,EAAE,aACrC,SAAS,UAQZ,iBAAiB,EAAE,SA2UhC,CAAC"}

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

@@ -4,6 +4,7 @@ import { getCellUserEnteredValue, getExtendedValueFormula, getStringifiedColor,
 import { produceWithPatches } from "immer";
 import { useCallback } from "react";
 import { createSheetCellIdentifier } from "../api/formula";
+import { getCellSortValue } from "../api/sort";
 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";
@@ -15,7 +16,7 @@ import { sortRowEntriesByFrozenState, } from "./utils/sort-rows";
  * @param param0
  * @returns
  */
-export const useOnSortRange = ({ locale, sharedStringRegistry, createHistory, enqueueStructureChange, enqueueGraphOperation, enqueueCalculation, onChangeSheetData, getDependents, isHiddenRow, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, onCommand, }) => {
+export const useOnSortRange = ({ locale, sharedStringRegistry, createHistory, enqueueStructureChange, enqueueGraphOperation, enqueueCalculation, onChangeSheetData, onChangeSheets, getCellData, getDependents, isHiddenRow, isManuallyHiddenRow, getFrozenRowCount, getSheetName, getEffectiveFormat, theme, onCommand, }) => {
     const canEditCellRange = useCanEditCellRange();
     const canPerformSheetAction = useCanPerformSheetAction();
     const showError = useShowError();
@@ -60,75 +61,107 @@ export const useOnSortRange = ({ locale, sharedStringRegistry, createHistory, en
             startColumnIndex: selection.range.startColumnIndex,
             endColumnIndex: selection.range.endColumnIndex,
         });
+        const startRowIndex = selection.range.startRowIndex;
+        const endRowIndex = selection.range.endRowIndex;
+        const startColumnIndex = selection.range.startColumnIndex;
+        const endColumnIndex = selection.range.endColumnIndex;
+        const frozenRowCount = getFrozenRowCount(sheetId);
+        const isPinnedRow = (rowIndex) => isManuallyHiddenRow
+            ? isManuallyHiddenRow(sheetId, rowIndex)
+            : isHiddenRow(sheetId, rowIndex);
+        // Gather the sort keys from the committed cell data. Pinned rows
+        // contribute no entry and are never rewritten.
+        const rowEntries = [];
+        for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+            if (isPinnedRow(rowIndex)) {
+                continue;
+            }
+            const sortValues = [];
+            for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                const sheetCell = new SheetCell(sheetId, { rowIndex, columnIndex }, getCellData(sheetId, rowIndex, columnIndex), { locale, sharedStringRegistry });
+                const fallbackValue = getCellSortValue(sheetCell);
+                // 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);
+            }
+            rowEntries.push({ rowIndex, sortValues });
+        }
+        // The slots the sorted rows land on, ascending (the sort reorders
+        // `rowEntries` in place).
+        const destRows = rowEntries.map((entry) => entry.rowIndex);
+        // 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.
+        // `sortedEntries[i]` is the row that lands on `destRows[i]`.
+        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);
+        // Carry each row's `hiddenByFilter` flag to the row's destination: a
+        // sort does not re-evaluate the filter, so the hidden set follows the
+        // rows.
+        onChangeSheets?.((prevSheets) => {
+            const [nextState, patches, inversePatches] = produceWithPatches(prevSheets, (draft) => {
+                const sheet = draft.find((sheet) => sheet.sheetId === sheetId);
+                if (!sheet) {
+                    return;
+                }
+                const hiddenByFilterAt = (rowIndex) => Boolean(sheet.rowMetadata?.[rowIndex]?.hiddenByFilter);
+                // Read every source flag before writing any destination.
+                const carried = destRows.map((rowIndex, index) => hiddenByFilterAt(sortedEntries[index]?.rowIndex ?? rowIndex));
+                destRows.forEach((rowIndex, index) => {
+                    const hiddenByFilter = carried[index];
+                    if (hiddenByFilter === hiddenByFilterAt(rowIndex)) {
+                        return;
+                    }
+                    if (!sheet.rowMetadata) {
+                        sheet.rowMetadata = [];
+                    }
+                    sheet.rowMetadata[rowIndex] = {
+                        ...sheet.rowMetadata[rowIndex],
+                        hiddenByFilter,
+                    };
+                });
+            });
+            if (!patches.length) {
+                return prevSheets;
+            }
+            saveHistory({ sheets: { patches, inversePatches } });
+            return nextState;
+        });
         // 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 });
+                for (const rowIndex of destRows) {
+                    rowSnapshots.set(rowIndex, (sheet[rowIndex]?.values ?? []).slice());
                 }
-                // 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];
+                for (let index = 0; index < destRows.length; index++) {
+                    const rowIndex = destRows[index];
+                    const sourceRow = sortedEntries[index];
                     if (!sourceRow) {
                         continue;
                     }
@@ -234,7 +267,10 @@ export const useOnSortRange = ({ locale, sharedStringRegistry, createHistory, en
         enqueueGraphOperation,
         enqueueCalculation,
         onChangeSheetData,
+        onChangeSheets,
+        getCellData,
         isHiddenRow,
+        isManuallyHiddenRow,
         getFrozenRowCount,
         getSheetName,
         getEffectiveFormat,

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

@@ -32,7 +32,24 @@ type UseOnSortTableProps<T extends CellData, S extends Sheet> = {
     onChangeSheetData: UseSpreadsheetProps<T, S>["onChangeSheetData"];
     onChangeTables: UseSpreadsheetProps<T, S>["onChangeTables"];
     onChangeSheets: UseSpreadsheetProps<T, S>["onChangeSheets"];
+    /**
+     * Committed cell data — the sort keys are gathered from it before the
+     * state updaters run, so one row permutation drives both the sheet data
+     * rewrite and the row-metadata carry-over.
+     */
+    getCellData(sheetId: number, rowIndex: number, columnIndex: number): T | null | undefined;
+    /**
+     * Any hidden row (by the user, a filter, or a collapsed group). Used as
+     * the pin predicate only when `isManuallyHiddenRow` is not supplied.
+     */
     isHiddenRow(sheetId: number, rowIndex: number): boolean;
+    /**
+     * A row the user hid (`hiddenByUser` / a collapsed outline group). These
+     * rows are pinned in place; rows an AutoFilter hid sort along with the
+     * visible ones and keep their `hiddenByFilter` flag at their destination,
+     * like Excel.
+     */
+    isManuallyHiddenRow?(sheetId: number, rowIndex: number): boolean;
     getDependents: ReturnType<typeof useCalculation>["getDependents"];
     getActiveCell: () => CellInterface;
     getFrozenRowCount(sheetId: number): number;
@@ -54,6 +71,6 @@ type UseOnSortTableProps<T extends CellData, S extends Sheet> = {
  * @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 declare const useOnSortTable: <T extends CellData, S extends Sheet>({ locale, sharedStringRegistry, createHistory, enqueueCalculation, enqueueStructureChange, enqueueGraphOperation, onChangeSheetData, onChangeTables, onChangeSheets, getCellData, getDependents, isHiddenRow, isManuallyHiddenRow, 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

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