refactor(datagrid): name-based identifiers + native sort indicators

CHANGELOG.md

@@ -23,6 +23,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Data grid column identifiers are now the column name (with positional fallback for duplicate names), so saved widths follow the column across schema changes that shift its position. Identifier resolution moved from static `DataGridView` helpers to a `ColumnIdentitySchema` value type owned by the coordinator.
+- `ColumnLayoutStorage` singleton replaced by a `ColumnLayoutPersisting` protocol with an injectable `FileColumnLayoutPersister` default. The coordinator depends on the protocol, not the concrete class, so tests can substitute a fake.
+- Column layout save/restore on table-switch (`saveColumnLayoutForTable` / `restoreColumnLayoutForTable`) folded into the data grid coordinator's lifecycle (load on column build, persist on resize/move/dismantle). The standalone `MainContentCoordinator+ColumnLayout` extension is gone; only the visibility orchestration remains. Removes the redundant `hasUserResizedColumns` flag and the external save trigger from the binding setter.
+- Data grid header sort indicators are `NSImageView` overlays drawn on a custom `NSTableHeaderView`, replacing Unicode arrows that were embedded in the column title string. The primary sorted column also gets the system header tint via `highlightedTableColumn`. VoiceOver announces the column name and sort direction separately.
+- Data grid column layout persistence routes through a coordinator callback fired from outside SwiftUI's update cycle, removing the `Task`-based `@Binding` mutation inside `updateNSView` and the `isWritingColumnLayout` re-entry guard.
+- Data grid cell reuse resets foreign-key arrow and dropdown chevron button context (target, action, row, column) when the button hides, preventing a stale handler from firing the wrong row if the column toggles between FK-eligible and not.
+- `applyColumnOrder` scans only the unsettled tail of the column array per move, halving the constant cost on reorders with many columns.
 - Replaced RowBuffer / InMemoryRowProvider / RowDataStore with TableRows / TableRowsStore / TableRowsController. Mutations emit Delta events; the controller drives NSTableView via insertRows / removeRows / reloadData(forRowIndexes:). Sort and the display cache moved off the row provider into the data grid coordinator, keyed by Row.id.
 - Routed every TableRows mutation through `mutateActiveTableRows` on MainContentCoordinator so the active ResultSet's snapshot stays in sync with the store. The snapshot now refreshes only when the user switches result sets (saving the outgoing tab, loading the incoming one), so each insert / undo / paste no longer triggers an `@Observable` re-render of the whole editor. Fixes empty cells on Load More and CPU spikes when adding or undoing rows.
 - Undo of a cell edit clears the modified-cell highlight: `DataChangeManager.applyDataUndo` now bumps `reloadVersion` so the data grid rebuilds its visual state cache.

TablePro/Core/Storage/ColumnLayoutStorage.swift → TablePro/Core/Storage/ColumnLayoutPersister.swift

@@ -1,16 +1,14 @@
 //
-//  ColumnLayoutStorage.swift
+//  ColumnLayoutPersister.swift
 //  TablePro
 //
 
 import Foundation
 import os
 
 @MainActor
-internal final class ColumnLayoutStorage {
-    static let shared = ColumnLayoutStorage()
-
-    private static let logger = Logger(subsystem: "com.TablePro", category: "ColumnLayoutStorage")
+final class FileColumnLayoutPersister: ColumnLayoutPersisting {
+    private static let logger = Logger(subsystem: "com.TablePro", category: "ColumnLayoutPersister")
     private static let legacyKeyPrefix = "com.TablePro.columns.layout."
     private static let migrationCompleteKey = "com.TablePro.columnLayoutMigrationComplete"
 
@@ -25,19 +23,19 @@ internal final class ColumnLayoutStorage {
 
     private var cache: [UUID: [String: PersistedColumnLayout]] = [:]
 
-    private init() {
-        storageDirectory = Self.resolvedStorageDirectory()
+    init(storageDirectory: URL? = nil) {
+        self.storageDirectory = storageDirectory ?? Self.resolvedStorageDirectory()
 
         do {
             try FileManager.default.createDirectory(
-                at: storageDirectory,
+                at: self.storageDirectory,
                 withIntermediateDirectories: true
             )
         } catch {
             Self.logger.error("Failed to create storage directory: \(error.localizedDescription)")
         }
 
-        Self.performMigrationIfNeeded(storageDirectory: storageDirectory)
+        Self.performMigrationIfNeeded(storageDirectory: self.storageDirectory)
     }
 
     func save(_ layout: ColumnLayoutState, for tableName: String, connectionId: UUID) {

TablePro/Core/Storage/ColumnLayoutPersisting.swift

@@ -0,0 +1,13 @@
+//
+//  ColumnLayoutPersisting.swift
+//  TablePro
+//
+
+import Foundation
+
+@MainActor
+protocol ColumnLayoutPersisting: AnyObject {
+    func load(for tableName: String, connectionId: UUID) -> ColumnLayoutState?
+    func save(_ layout: ColumnLayoutState, for tableName: String, connectionId: UUID)
+    func clear(for tableName: String, connectionId: UUID)
+}

TablePro/Core/Storage/ValueDisplayFormatStorage.swift

@@ -2,9 +2,6 @@
 //  ValueDisplayFormatStorage.swift
 //  TablePro
 //
-//  Persists per-column display format overrides to UserDefaults.
-//  Follows the same pattern as ColumnLayoutStorage.
-//
 
 import Foundation
 

TablePro/Models/Query/QueryTabState.swift

@@ -59,18 +59,10 @@ struct TabChangeSnapshot: Equatable {
     }
 }
 
-/// Sort direction for column sorting
 enum SortDirection: Equatable {
     case ascending
     case descending
 
-    var indicator: String {
-        switch self {
-        case .ascending: return "▲"
-        case .descending: return "▼"
-        }
-    }
-
     mutating func toggle() {
         self = self == .ascending ? .descending : .ascending
     }

TablePro/Models/UI/ColumnIdentitySchema.swift

@@ -0,0 +1,47 @@
+//
+//  ColumnIdentitySchema.swift
+//  TablePro
+//
+
+import AppKit
+
+struct ColumnIdentitySchema: Equatable {
+    static let rowNumberIdentifier = NSUserInterfaceItemIdentifier("__rowNumber__")
+
+    let identifiers: [NSUserInterfaceItemIdentifier]
+    let isNameBased: Bool
+    private let indexByRawIdentifier: [String: Int]
+
+    init(columns: [String]) {
+        let canUseNames = Set(columns).count == columns.count
+            && !columns.contains(Self.rowNumberIdentifier.rawValue)
+
+        if canUseNames {
+            self.identifiers = columns.map { NSUserInterfaceItemIdentifier($0) }
+            self.isNameBased = true
+        } else {
+            self.identifiers = columns.indices.map {
+                NSUserInterfaceItemIdentifier("col_\($0)")
+            }
+            self.isNameBased = false
+        }
+
+        var map: [String: Int] = [:]
+        map.reserveCapacity(self.identifiers.count)
+        for (index, identifier) in self.identifiers.enumerated() {
+            map[identifier.rawValue] = index
+        }
+        self.indexByRawIdentifier = map
+    }
+
+    static let empty = ColumnIdentitySchema(columns: [])
+
+    func identifier(for dataIndex: Int) -> NSUserInterfaceItemIdentifier? {
+        guard dataIndex >= 0, dataIndex < identifiers.count else { return nil }
+        return identifiers[dataIndex]
+    }
+
+    func dataIndex(from identifier: NSUserInterfaceItemIdentifier) -> Int? {
+        indexByRawIdentifier[identifier.rawValue]
+    }
+}

TablePro/Resources/Localizable.xcstrings

@@ -14085,6 +14085,9 @@
           }
         }
       }
+    },
+    "Don't Sort" : {
+
     },
     "Done" : {
 

TablePro/Views/Main/Child/DataTabGridDelegate.swift

@@ -17,6 +17,7 @@ final class DataTabGridDelegate: DataGridViewDelegate {
 
     var onCellEdit: ((Int, Int, String?) -> Void)?
     var onSort: ((Int, Bool, Bool) -> Void)?
+    var onClearSort: (() -> Void)?
     var onAddRow: (() -> Void)?
     var onUndoInsert: ((Int) -> Void)?
     var onFilterColumn: ((String) -> Void)?
@@ -32,6 +33,10 @@ final class DataTabGridDelegate: DataGridViewDelegate {
         onSort?(column, ascending, isMultiSort)
     }
 
+    func dataGridClearSort() {
+        onClearSort?()
+    }
+
     func dataGridAddRow() {
         onAddRow?()
     }

TablePro/Views/Main/Child/MainEditorContentView.swift

@@ -30,6 +30,7 @@ struct MainEditorContentView: View {
 
     let onCellEdit: (Int, Int, String?) -> Void
     let onSort: (Int, Bool, Bool) -> Void
+    let onClearSort: () -> Void
     let onAddRow: () -> Void
     let onUndoInsert: (Int) -> Void
     let onSelectionChange: (Set<Int>) -> Void
@@ -145,6 +146,7 @@ struct MainEditorContentView: View {
         dataTabDelegate.selectionState = selectionState
         dataTabDelegate.onCellEdit = onCellEdit
         dataTabDelegate.onSort = onSort
+        dataTabDelegate.onClearSort = onClearSort
         dataTabDelegate.onUndoInsert = onUndoInsert
         dataTabDelegate.onFilterColumn = onFilterColumn
         dataTabDelegate.onRefresh = onRefresh
@@ -663,7 +665,6 @@ struct MainEditorContentView: View {
                 }
                 Task { @MainActor in
                     coordinator.isUpdatingColumnLayout = false
-                    coordinator.saveColumnLayoutForTable()
                 }
             }
         )

TablePro/Views/Main/Extensions/MainContentCoordinator+ColumnVisibility.swift

@@ -22,6 +22,14 @@ extension MainContentCoordinator {
         columnVisibilityManager.restoreLastHiddenColumns(for: tableName, connectionId: connectionId)
     }
 
+    func saveColumnVisibilityForActiveTable() {
+        guard let tab = tabManager.selectedTab,
+              tab.tabType == .table,
+              let tableName = tab.tableContext.tableName,
+              !tableName.isEmpty else { return }
+        columnVisibilityManager.saveLastHiddenColumns(for: tableName, connectionId: connectionId)
+    }
+
     /// Prune hidden columns that no longer exist in the current result set
     func pruneHiddenColumns(currentColumns: [String]) {
         columnVisibilityManager.pruneStaleColumns(currentColumns)

TablePro/Views/Main/Extensions/MainContentCoordinator+Navigation.swift

@@ -100,7 +100,7 @@ extension MainContentCoordinator {
             }
             // In-place navigation needs selectRedisDatabaseAndQuery to ensure the correct
             // database is SELECTed and session state is updated before querying.
-            restoreColumnLayoutForTable(tableName)
+            restoreLastHiddenColumnsForTable(tableName)
             restoreFiltersForTable(tableName)
             if navigationModel == .inPlace, let dbIndex = Int(currentDatabase) {
                 selectRedisDatabaseAndQuery(dbIndex)
@@ -128,7 +128,7 @@ extension MainContentCoordinator {
                     tabManager.tabs[tabIndex].pagination.reset()
                     toolbarState.isTableTab = true
                 }
-                restoreColumnLayoutForTable(tableName)
+                restoreLastHiddenColumnsForTable(tableName)
                 restoreFiltersForTable(tableName)
                 if let dbIndex = Int(currentDatabase) {
                     selectRedisDatabaseAndQuery(dbIndex)
@@ -212,7 +212,7 @@ extension MainContentCoordinator {
                     previewCoordinator.toolbarState.isTableTab = true
                 }
                 preview.window.makeKeyAndOrderFront(nil)
-                previewCoordinator.restoreColumnLayoutForTable(tableName)
+                previewCoordinator.restoreLastHiddenColumnsForTable(tableName)
                 previewCoordinator.restoreFiltersForTable(tableName)
                 previewCoordinator.runQuery()
                 return
@@ -282,7 +282,7 @@ extension MainContentCoordinator {
                 tabManager.tabs[tabIndex].pagination.reset()
                 toolbarState.isTableTab = true
             }
-            restoreColumnLayoutForTable(tableName)
+            restoreLastHiddenColumnsForTable(tableName)
             restoreFiltersForTable(tableName)
             runQuery()
             return

TablePro/Views/Main/Extensions/MainContentCoordinator+TabSwitch.swift

@@ -40,7 +40,7 @@ extension MainContentCoordinator {
                 filterStateManager.saveLastFilters(for: tableName)
             }
             saveColumnVisibilityToTab()
-            saveColumnLayoutForTable()
+            saveColumnVisibilityForActiveTable()
         }
         let saveMs = Int(Date().timeIntervalSince(saveStart) * 1_000)
 

TablePro/Views/Main/Extensions/MainContentView+Setup.swift

@@ -70,7 +70,7 @@ extension MainContentView {
                             tabManager.tabs[tabIndex].content.query = filteredQuery
                         }
                         if let tableName = selectedTab.tableContext.tableName {
-                            coordinator.restoreColumnLayoutForTable(tableName)
+                            coordinator.restoreLastHiddenColumnsForTable(tableName)
                         }
                         coordinator.executeTableTabQueryDirectly()
                     }
@@ -161,7 +161,7 @@ extension MainContentView {
                         Task { await coordinator.switchDatabase(to: firstTab.tableContext.databaseName) }
                     } else {
                         if let tableName = firstTab.tableContext.tableName {
-                            coordinator.restoreColumnLayoutForTable(tableName)
+                            coordinator.restoreLastHiddenColumnsForTable(tableName)
                         }
                         coordinator.executeTableTabQueryDirectly()
                     }

TablePro/Views/Main/MainContentCoordinator.swift

@@ -1422,6 +1422,33 @@ final class MainContentCoordinator {
         }
     }
 
+    func clearSort() {
+        guard let (tab, tabIndex) = tabManager.selectedTabAndIndex else { return }
+        guard tab.sortState.isSorting else { return }
+
+        let emptySort = SortState()
+
+        if tab.tabType == .query {
+            tabManager.tabs[tabIndex].sortState = emptySort
+            tabManager.tabs[tabIndex].hasUserInteraction = true
+            querySortCache.removeValue(forKey: tab.id)
+            dataTabDelegate?.dataGridDidReplaceAllRows()
+            return
+        }
+
+        let tabId = tab.id
+        let capturedQuery = tab.content.query
+        confirmDiscardChangesIfNeeded(action: .sort) { [weak self] confirmed in
+            guard let self, confirmed,
+                  let idx = self.tabManager.tabs.firstIndex(where: { $0.id == tabId }) else { return }
+            self.tabManager.tabs[idx].sortState = emptySort
+            self.tabManager.tabs[idx].hasUserInteraction = true
+            self.tabManager.tabs[idx].pagination.reset()
+            self.tabManager.tabs[idx].content.query = Self.stripTrailingOrderBy(from: capturedQuery)
+            self.runQuery()
+        }
+    }
+
     /// Multi-column sort returning a permutation of `RowID` (nonisolated for background thread).
     nonisolated private static func multiColumnSortedIDs(
         rows: [(id: RowID, values: [String?])],

TablePro/Views/Main/MainContentView.swift

@@ -410,6 +410,9 @@ struct MainContentView: View {
                     columnIndex: columnIndex, ascending: ascending,
                     isMultiSort: isMultiSort)
             },
+            onClearSort: {
+                coordinator.clearSort()
+            },
             onAddRow: {
                 coordinator.addNewRow()
             },