refactor(datagrid): sort moves to controller keyed by Row.id

Author: datlechin

CHANGELOG.md

@@ -22,7 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Introduced TableRows, Row, and Delta value types in TablePro/Models/Query/ as the foundation for the data grid row model rewrite. NSTableView delegate reads cell values and row count from TableRows; sidebar, JSON view, and exports now read from TableRows. Cell edits route through TableRows.edit and apply NSTableView updates via the Delta-driven TableRowsController. Row operations (add, duplicate, delete, paste, undo) mutate TableRows and apply the returned Delta through TableViewCoordinator.applyDelta. RowBuffer still backs sorting and the display cache pending later phases (Phase C.2 of the DataGrid refactor).
+- Introduced TableRows, Row, and Delta value types in TablePro/Models/Query/ as the foundation for the data grid row model rewrite. NSTableView delegate reads cell values and row count from TableRows; sidebar, JSON view, and exports now read from TableRows. Cell edits route through TableRows.edit and apply NSTableView updates via the Delta-driven TableRowsController. Row operations (add, duplicate, delete, paste, undo) mutate TableRows and apply the returned Delta through TableViewCoordinator.applyDelta. Sort state moved from InMemoryRowProvider's positional sortIndices to a TableViewCoordinator.sortedIDs permutation keyed by Row.id, so cell edits under sort hit the correct storage row and inserted rows survive at the end of the sorted view without re-sorting. RowBuffer still backs the display cache pending later phases (Phase C.2 of the DataGrid refactor).
 - DataChangeManager extracted a PendingChanges value type that owns cross-collection invariants for cell edits, row insertions, and deletions. DataChangeManager kept undo/redo registration, plugin SQL generation, and the `@Observable` boundary, dropping from ~960 to ~190 lines. The serialization DTO `TabPendingChanges` is renamed to `TabChangeSnapshot` to distinguish it from the live tracker.
 - AnyChangeManager uses ChangeManaging protocol instead of closure-based type erasure, removing all runtime `[Any]` downcasts
 - Row selection state moved from MainContentView @State to GridSelectionState @Observable class, preventing full view tree invalidation on every row click

TablePro/Models/Query/TableRows.swift

@@ -39,6 +39,18 @@ struct TableRows: Sendable {
         return rows[row][column]
     }
 
+    func index(of id: RowID) -> Int? {
+        for (index, row) in rows.enumerated() where row.id == id {
+            return index
+        }
+        return nil
+    }
+
+    func row(withID id: RowID) -> Row? {
+        guard let index = index(of: id) else { return nil }
+        return rows[index]
+    }
+
     @discardableResult
     mutating func edit(row: Int, column: Int, value: String?) -> Delta {
         guard row >= 0, row < rows.count else { return .none }

TablePro/Views/Main/Child/MainEditorContentView.swift

@@ -10,9 +10,11 @@ import AppKit
 import CodeEditSourceEditor
 import SwiftUI
 
-/// Cache for sorted query result rows to avoid re-sorting on every SwiftUI body evaluation
+/// Cache for sorted query result rows to avoid re-sorting on every SwiftUI body evaluation.
+/// Stores a permutation of `RowID` so the grid keeps the same display order even after
+/// inserts and deletes mutate the underlying TableRows storage.
 private struct SortedRowsCache {
-    let sortedIndices: [Int]
+    let sortedIDs: [RowID]
     let columnIndex: Int
     let direction: SortDirection
     let schemaVersion: Int
@@ -578,6 +580,7 @@ struct MainEditorContentView: View {
                 showRowNumbers: AppSettingsManager.shared.dataGrid.showRowNumbers,
                 hiddenColumns: columnVisibilityManager.hiddenColumns
             ),
+            sortedIDs: sortedIDsForTab(tab),
             delegate: dataTabDelegate,
             selectedRowIndices: Binding(
                 get: { selectionState.indices },
@@ -633,7 +636,6 @@ struct MainEditorContentView: View {
         if let rs = tab.display.activeResultSet, !rs.resultColumns.isEmpty {
             provider = InMemoryRowProvider(
                 rowBuffer: rs.rowBuffer,
-                sortIndices: sortIndicesForTab(tab),
                 columns: rs.resultColumns,
                 columnDefaults: rs.columnDefaults,
                 columnTypes: rs.columnTypes,
@@ -645,7 +647,6 @@ struct MainEditorContentView: View {
             let buffer = coordinator.rowDataStore.buffer(for: tab.id)
             provider = InMemoryRowProvider(
                 rowBuffer: buffer,
-                sortIndices: sortIndicesForTab(tab),
                 columns: buffer.columns,
                 columnDefaults: buffer.columnDefaults,
                 columnTypes: buffer.columnTypes,
@@ -715,73 +716,66 @@ struct MainEditorContentView: View {
         }
     }
 
-    /// Returns sort index permutation for a tab, or nil if no sorting is needed.
+    /// Returns the display order as a permutation of `RowID`, or nil when no sort applies.
     /// For table tabs, sorting is handled server-side via SQL ORDER BY.
-    private func sortIndicesForTab(_ tab: QueryTab) -> [Int]? {
-        // Resolve data source: active ResultSet or tab-level fallback
+    private func sortedIDsForTab(_ tab: QueryTab) -> [RowID]? {
         let rowBuffer: RowBuffer
-        let rows: [[String?]]
         let colTypes: [ColumnType]
         if let rs = tab.display.activeResultSet, !rs.resultColumns.isEmpty {
             rowBuffer = rs.rowBuffer
-            rows = rs.resultRows
             colTypes = rs.columnTypes
         } else {
             let buffer = coordinator.rowDataStore.buffer(for: tab.id)
             rowBuffer = buffer
-            rows = buffer.rows
             colTypes = buffer.columnTypes
         }
 
         guard !rowBuffer.isEvicted else { return nil }
 
-        // Table tabs: no client-side sorting
         if tab.tabType == .table {
             return nil
         }
 
-        // Query tabs: apply client-side sorting
         guard tab.sortState.isSorting else {
             return nil
         }
 
-        // Check coordinator's async sort cache (for large datasets sorted on background thread)
+        guard let tableRows = coordinator.tableRowsStore.existingTableRows(for: tab.id),
+              !tableRows.rows.isEmpty else {
+            return nil
+        }
+
         if let cached = coordinator.querySortCache[tab.id],
             cached.columnIndex == (tab.sortState.columnIndex ?? -1),
             cached.direction == tab.sortState.direction,
             cached.schemaVersion == tab.schemaVersion
         {
-            return cached.sortedIndices
+            return cached.sortedIDs
         }
 
-        // For datasets sorted async, return nil (unsorted) until cache is ready
-        if rows.count > 1_000 {
+        if tableRows.rows.count > 1_000 {
             return nil
         }
 
-        // Small dataset: sort synchronously with view-level cache
         if let cached = sortCache[tab.id],
             cached.columnIndex == (tab.sortState.columnIndex ?? -1),
             cached.direction == tab.sortState.direction,
             cached.schemaVersion == tab.schemaVersion
         {
-            return cached.sortedIndices
+            return cached.sortedIDs
         }
 
         let sortColumns = tab.sortState.columns
-        let indices = Array(rows.indices)
-        let sortedIndices = indices.sorted { idx1, idx2 in
-            let row1 = rows[idx1]
-            let row2 = rows[idx2]
+        let storageRows = tableRows.rows
+        let sortedIndices = Array(storageRows.indices).sorted { idx1, idx2 in
+            let row1 = storageRows[idx1].values
+            let row2 = storageRows[idx2].values
             for sortCol in sortColumns {
-                let val1 =
-                    sortCol.columnIndex < row1.count
+                let val1 = sortCol.columnIndex < row1.count
                     ? (row1[sortCol.columnIndex] ?? "") : ""
-                let val2 =
-                    sortCol.columnIndex < row2.count
+                let val2 = sortCol.columnIndex < row2.count
                     ? (row2[sortCol.columnIndex] ?? "") : ""
-                let colType =
-                    sortCol.columnIndex < colTypes.count
+                let colType = sortCol.columnIndex < colTypes.count
                     ? colTypes[sortCol.columnIndex] : nil
                 let result = RowSortComparator.compare(val1, val2, columnType: colType)
                 if result == .orderedSame { continue }
@@ -791,16 +785,16 @@ struct MainEditorContentView: View {
             }
             return false
         }
+        let sortedIDs = sortedIndices.map { storageRows[$0].id }
 
-        // Cache the result
         sortCache[tab.id] = SortedRowsCache(
-            sortedIndices: sortedIndices,
+            sortedIDs: sortedIDs,
             columnIndex: tab.sortState.columnIndex ?? -1,
             direction: tab.sortState.direction,
             schemaVersion: tab.schemaVersion
         )
 
-        return sortedIndices
+        return sortedIDs
     }
 
     private func sortStateBinding(for tab: QueryTab) -> Binding<SortState> {

TablePro/Views/Main/MainContentCoordinator.swift

@@ -21,9 +21,11 @@ enum DiscardAction {
     case filter
 }
 
-/// Cache entry for async-sorted query tab rows (stores index permutation, not row copies)
+/// Cache entry for async-sorted query tab rows. Stores a permutation of `RowID` so the
+/// sort survives mutations: inserted rows append to the end of the sorted view, and
+/// removed rows are dropped from the permutation without re-sorting.
 struct QuerySortCacheEntry {
-    let sortedIndices: [Int]
+    let sortedIDs: [RowID]
     let columnIndex: Int
     let direction: SortDirection
     let schemaVersion: Int
@@ -1357,13 +1359,14 @@ final class MainContentCoordinator {
             tabManager.tabs[tabIndex].sortState = currentSort
             tabManager.tabs[tabIndex].hasUserInteraction = true
             tabManager.tabs[tabIndex].pagination.reset()
-            let rows = buffer.rows
             let tabId = tab.id
             let schemaVersion = tab.schemaVersion
             let sortColumns = currentSort.columns
             let colTypes = buffer.columnTypes
+            let storageRows = tableRowsStore.existingTableRows(for: tabId)?.rows ?? []
+            let snapshotRows: [(id: RowID, values: [String?])] = storageRows.map { ($0.id, $0.values) }
 
-            if rows.count > 1_000 {
+            if storageRows.count > 1_000 {
                 // Sort on background thread to avoid UI freeze
                 activeSortTasks[tabId]?.cancel()
                 activeSortTasks.removeValue(forKey: tabId)
@@ -1373,8 +1376,8 @@ final class MainContentCoordinator {
 
                 let sortStartTime = Date()
                 let task = Task.detached { [weak self] in
-                    let sortedIndices = Self.multiColumnSortIndices(
-                        rows: rows,
+                    let sortedIDs = Self.multiColumnSortedIDs(
+                        rows: snapshotRows,
                         sortColumns: sortColumns,
                         columnTypes: colTypes
                     )
@@ -1388,7 +1391,7 @@ final class MainContentCoordinator {
                             return
                         }
                         self.querySortCache[tabId] = QuerySortCacheEntry(
-                            sortedIndices: sortedIndices,
+                            sortedIDs: sortedIDs,
                             columnIndex: sortColumns.first?.columnIndex ?? 0,
                             direction: sortColumns.first?.direction ?? .ascending,
                             schemaVersion: schemaVersion
@@ -1430,13 +1433,12 @@ final class MainContentCoordinator {
         }
     }
 
-    /// Multi-column sort returning index permutation (nonisolated for background thread).
-    /// Returns an array of indices into the original `rows` array, sorted by the given columns.
-    nonisolated private static func multiColumnSortIndices(
-        rows: [[String?]],
+    /// Multi-column sort returning a permutation of `RowID` (nonisolated for background thread).
+    nonisolated private static func multiColumnSortedIDs(
+        rows: [(id: RowID, values: [String?])],
         sortColumns: [SortColumn],
         columnTypes: [ColumnType] = []
-    ) -> [Int] {
+    ) -> [RowID] {
         // Fast path: single-column sort avoids intermediate key array allocation
         if sortColumns.count == 1 {
             let col = sortColumns[0]
@@ -1445,18 +1447,20 @@ final class MainContentCoordinator {
             let colType = colIndex < columnTypes.count ? columnTypes[colIndex] : nil
             var indices = Array(0..<rows.count)
             indices.sort { i1, i2 in
-                let v1 = colIndex < rows[i1].count ? (rows[i1][colIndex] ?? "") : ""
-                let v2 = colIndex < rows[i2].count ? (rows[i2][colIndex] ?? "") : ""
+                let row1 = rows[i1].values
+                let row2 = rows[i2].values
+                let v1 = colIndex < row1.count ? (row1[colIndex] ?? "") : ""
+                let v2 = colIndex < row2.count ? (row2[colIndex] ?? "") : ""
                 let cmp = RowSortComparator.compare(v1, v2, columnType: colType)
                 return ascending ? cmp == .orderedAscending : cmp == .orderedDescending
             }
-            return indices
+            return indices.map { rows[$0].id }
         }
 
         var indices = Array(0..<rows.count)
         indices.sort { i1, i2 in
-            let row1 = rows[i1]
-            let row2 = rows[i2]
+            let row1 = rows[i1].values
+            let row2 = rows[i2].values
             for sortCol in sortColumns {
                 let v1 = sortCol.columnIndex < row1.count ? (row1[sortCol.columnIndex] ?? "") : ""
                 let v2 = sortCol.columnIndex < row2.count ? (row2[sortCol.columnIndex] ?? "") : ""
@@ -1470,6 +1474,6 @@ final class MainContentCoordinator {
             }
             return false
         }
-        return indices
+        return indices.map { rows[$0].id }
     }
 }

TablePro/Views/Results/DataGridCoordinator.swift

@@ -20,6 +20,7 @@ final class TableViewCoordinator: NSObject, NSTableViewDelegate, NSTableViewData
     var tableRowsMutator: @MainActor (@MainActor (inout TableRows) -> Void) -> Void = { _ in }
     var changeManager: AnyChangeManager
     var isEditable: Bool
+    var sortedIDs: [RowID]?
     weak var delegate: (any DataGridViewDelegate)?
     weak var activeFKPreviewPopover: NSPopover?
     var dropdownColumns: Set<Int>?
@@ -201,6 +202,7 @@ final class TableViewCoordinator: NSObject, NSTableViewDelegate, NSTableViewData
         rowVisualStateCache.removeAll()
         cachedRowCount = 0
         cachedColumnCount = 0
+        sortedIDs = nil
         // Remove columns and reload to release cell views
         if let tableView {
             while let col = tableView.tableColumns.last {
@@ -259,6 +261,26 @@ final class TableViewCoordinator: NSObject, NSTableViewDelegate, NSTableViewData
         lastIdentity = nil
     }
 
+    func displayRow(at displayIndex: Int) -> Row? {
+        let tableRows = tableRowsProvider()
+        if let sorted = sortedIDs {
+            guard displayIndex >= 0, displayIndex < sorted.count else { return nil }
+            return tableRows.row(withID: sorted[displayIndex])
+        }
+        guard displayIndex >= 0, displayIndex < tableRows.count else { return nil }
+        return tableRows.rows[displayIndex]
+    }
+
+    func tableRowsIndex(forDisplayRow displayIndex: Int) -> Int? {
+        if let sorted = sortedIDs {
+            guard displayIndex >= 0, displayIndex < sorted.count else { return nil }
+            return tableRowsProvider().index(of: sorted[displayIndex])
+        }
+        let count = tableRowsProvider().count
+        guard displayIndex >= 0, displayIndex < count else { return nil }
+        return displayIndex
+    }
+
     func applyDelta(_ delta: Delta) {
         switch delta {
         case .cellChanged(let row, let column):
@@ -287,15 +309,37 @@ final class TableViewCoordinator: NSObject, NSTableViewDelegate, NSTableViewData
             tableView.reloadData(forRowIndexes: rowSet, columnIndexes: colSet)
         case .rowsInserted(let indices):
             guard !indices.isEmpty else { return }
+            appendInsertedIDsToSortedIDs(at: indices)
             applyInsertedRows(indices)
         case .rowsRemoved(let indices):
             guard !indices.isEmpty else { return }
+            removeMissingIDsFromSortedIDs()
             applyRemovedRows(indices)
         case .columnsReplaced, .fullReplace:
+            sortedIDs = nil
             applyFullReplace()
         }
     }
 
+    private func appendInsertedIDsToSortedIDs(at indices: IndexSet) {
+        guard sortedIDs != nil else { return }
+        let tableRows = tableRowsProvider()
+        for index in indices where index >= 0 && index < tableRows.count {
+            sortedIDs?.append(tableRows.rows[index].id)
+        }
+    }
+
+    private func removeMissingIDsFromSortedIDs() {
+        guard sortedIDs != nil else { return }
+        let tableRows = tableRowsProvider()
+        var survivingIDs = Set<RowID>()
+        survivingIDs.reserveCapacity(tableRows.count)
+        for row in tableRows.rows {
+            survivingIDs.insert(row.id)
+        }
+        sortedIDs?.removeAll { !survivingIDs.contains($0) }
+    }
+
     func invalidateCachesForUndoRedo() {
         rowProvider.invalidateDisplayCache()
         rebuildVisualStateCache()
@@ -369,8 +413,14 @@ final class TableViewCoordinator: NSObject, NSTableViewDelegate, NSTableViewData
 
         let tableRows = tableRowsProvider()
         var insertedRowIndices = Set<Int>()
-        for (index, row) in tableRows.rows.enumerated() where row.id.isInserted {
-            insertedRowIndices.insert(index)
+        if let sorted = sortedIDs {
+            for (displayIndex, id) in sorted.enumerated() where id.isInserted {
+                insertedRowIndices.insert(displayIndex)
+            }
+        } else {
+            for (index, row) in tableRows.rows.enumerated() where row.id.isInserted {
+                insertedRowIndices.insert(index)
+            }
         }
 
         if !changeManager.hasChanges && insertedRowIndices.isEmpty {
@@ -413,6 +463,6 @@ final class TableViewCoordinator: NSObject, NSTableViewDelegate, NSTableViewData
     // MARK: - NSTableViewDataSource
 
     func numberOfRows(in tableView: NSTableView) -> Int {
-        tableRowsProvider().count
+        sortedIDs?.count ?? tableRowsProvider().count
     }
 }