From b8178b6a8c864b5b0aa1ff7469e7b42bb8556f2e Mon Sep 17 00:00:00 2001
From: Ngo Quoc Dat <datlechin@gmail.com>
Date: Mon, 13 Jul 2026 19:06:44 +0700
Subject: [PATCH] fix(datagrid): show column comments in headers on first load
 (#1861)

---
 CHANGELOG.md                                  |  1 +
 .../Views/Results/DataGridColumnPool.swift    | 18 +++-
 .../Results/DataGridUpdateSnapshot.swift      |  2 +-
 TablePro/Views/Results/DataGridView.swift     | 37 +++++---
 .../Views/Results/SortableHeaderCell.swift    | 12 ++-
 .../Views/Results/SortableHeaderView.swift    | 23 ++---
 .../Results/DataGridColumnPoolTests.swift     | 89 ++++++++++++++++++-
 .../Results/DataGridUpdateSnapshotTests.swift | 19 +++-
 .../Results/SortableHeaderViewTests.swift     | 83 +++++++++++++++++
 9 files changed, 242 insertions(+), 42 deletions(-)
 create mode 100644 TableProTests/Views/Results/SortableHeaderViewTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9751d9fdb..595497639 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Column comments now show in the data grid header as soon as the table opens, instead of only after the query was run again. The header also grows to fit the comment line, so it is no longer cut off until a column is resized. (#1861)
 - **Size to Fit** and **Size All Columns to Fit** no longer stretch a column with long text far past the window. A fitted column now stops at half the visible grid, and every column has a maximum width, so a column left oversized before is brought back in range the next time you open the table.
 - The username is now optional. Leaving it empty, or importing a connection URL that has no user in it, no longer fills in `root`. An empty username lets the database use its own default, the same as `psql` and `mysql` do: your Mac login name on MySQL/MariaDB and PostgreSQL, and `default` on ClickHouse. The `~/.pgpass` lookup now matches on that same user.
 - A failed or cancelled connection that uses a Cloudflare tunnel no longer leaves the `cloudflared` process running in the background.
diff --git a/TablePro/Views/Results/DataGridColumnPool.swift b/TablePro/Views/Results/DataGridColumnPool.swift
index 08bcf3e88..9da21d528 100644
--- a/TablePro/Views/Results/DataGridColumnPool.swift
+++ b/TablePro/Views/Results/DataGridColumnPool.swift
@@ -41,6 +41,7 @@ final class DataGridColumnPool {
 
         let willRestoreWidths = !(savedLayout?.columnWidths.isEmpty ?? true)
         let hiddenFromLayout = savedLayout?.hiddenColumns ?? []
+        var commentsChanged = false
 
         for slot in 0..<pooledColumns.count {
             let column = pooledColumns[slot]
@@ -49,14 +50,16 @@ final class DataGridColumnPool {
                 let resolvedWidth = willRestoreWidths
                     ? (savedLayout?.columnWidths[columnName] ?? widthCalculator(columnName, slot))
                     : widthCalculator(columnName, slot)
-                configureColumn(
+                if configureColumn(
                     column,
                     name: columnName,
                     columnType: slot < columnTypes.count ? columnTypes[slot] : nil,
                     comment: columnComments[columnName],
                     width: resolvedWidth,
                     isEditable: isEditable
-                )
+                ) {
+                    commentsChanged = true
+                }
                 let hidden = hiddenFromLayout.contains(columnName) || hiddenColumnNames.contains(columnName)
                 if column.isHidden != hidden {
                     column.isHidden = hidden
@@ -66,6 +69,9 @@ final class DataGridColumnPool {
             }
         }
         updateHeaderHeight(in: tableView, showsComments: hasVisibleComments(visibleCount: visibleCount))
+        if commentsChanged {
+            tableView.headerView?.needsDisplay = true
+        }
 
         let targetOrder = computeTargetOrder(
             visibleCount: visibleCount,
@@ -184,15 +190,17 @@ final class DataGridColumnPool {
         comment: String?,
         width: CGFloat,
         isEditable: Bool
-    ) {
+    ) -> Bool {
         if !(column.headerCell is SortableHeaderCell) || column.headerCell.stringValue != name {
             let cell = SortableHeaderCell(textCell: name)
             cell.font = column.headerCell.font
             cell.alignment = column.headerCell.alignment
             column.headerCell = cell
         }
-        if let headerCell = column.headerCell as? SortableHeaderCell {
+        var commentChanged = false
+        if let headerCell = column.headerCell as? SortableHeaderCell, headerCell.headerComment != comment {
             headerCell.headerComment = comment
+            commentChanged = true
         }
 
         var tooltip: String
@@ -222,6 +230,8 @@ final class DataGridColumnPool {
         if column.sortDescriptorPrototype?.key != name {
             column.sortDescriptorPrototype = NSSortDescriptor(key: name, ascending: true)
         }
+
+        return commentChanged
     }
 
     private func hasVisibleComments(visibleCount: Int) -> Bool {
diff --git a/TablePro/Views/Results/DataGridUpdateSnapshot.swift b/TablePro/Views/Results/DataGridUpdateSnapshot.swift
index 41e496328..5102f644e 100644
--- a/TablePro/Views/Results/DataGridUpdateSnapshot.swift
+++ b/TablePro/Views/Results/DataGridUpdateSnapshot.swift
@@ -21,5 +21,5 @@ struct DataGridUpdateSnapshot: Equatable {
     let alternatingRows: Bool
     let reloadVersion: Int
     let contentRevision: Int
-    let showObjectComments: Bool
+    let columnComments: [String: String]
 }
diff --git a/TablePro/Views/Results/DataGridView.swift b/TablePro/Views/Results/DataGridView.swift
index abe41984b..9910ddf92 100644
--- a/TablePro/Views/Results/DataGridView.swift
+++ b/TablePro/Views/Results/DataGridView.swift
@@ -80,6 +80,15 @@ struct DataGridView: NSViewRepresentable {
         tableView.addTableColumn(rowNumberColumn)
         rowNumberColumn.isHidden = !configuration.showRowNumbers
 
+        let sortableHeader = SortableHeaderView(frame: tableView.headerView?.frame ?? .zero)
+        sortableHeader.coordinator = context.coordinator
+        let headerMenu = NSMenu()
+        headerMenu.delegate = context.coordinator
+        sortableHeader.menu = headerMenu
+        tableView.headerView = sortableHeader
+
+        scrollView.documentView = tableView
+
         let initialRows = tableRowsProvider()
         context.coordinator.rebuildColumnMetadataCache(from: initialRows)
 
@@ -89,24 +98,17 @@ struct DataGridView: NSViewRepresentable {
             tableView: tableView,
             coordinator: context.coordinator,
             tableRows: initialRows,
+            columnComments: Self.effectiveColumnComments(for: initialRows),
             savedLayout: initialLayout
         )
         context.coordinator.isRebuildingColumns = false
 
-        let sortableHeader = SortableHeaderView(frame: tableView.headerView?.frame ?? .zero)
-        sortableHeader.coordinator = context.coordinator
-        let headerMenu = NSMenu()
-        headerMenu.delegate = context.coordinator
-        sortableHeader.menu = headerMenu
-        tableView.headerView = sortableHeader
-
         let hasMoveRow = delegate != nil
         if hasMoveRow {
             tableView.registerForDraggedTypes([NSPasteboard.PasteboardType("com.TablePro.rowDrag")])
             tableView.draggingDestinationFeedbackStyle = .gap
         }
 
-        scrollView.documentView = tableView
         context.coordinator.tableView = tableView
         installSelectionOverlay(tableView: tableView, coordinator: context.coordinator)
         context.coordinator.attachScrollObservers(scrollView: scrollView)
@@ -156,6 +158,7 @@ struct DataGridView: NSViewRepresentable {
         let settings = AppSettingsManager.shared.dataGrid
         let rowHeight = CGFloat(settings.rowHeight.rawValue)
         let alternatingRows = settings.showAlternateRows
+        let columnComments = Self.effectiveColumnComments(for: latestRows)
 
         let snapshot = DataGridUpdateSnapshot(
             rowDisplayCount: rowDisplayCount,
@@ -171,7 +174,7 @@ struct DataGridView: NSViewRepresentable {
             alternatingRows: alternatingRows,
             reloadVersion: changeManager.reloadVersion,
             contentRevision: contentRevision,
-            showObjectComments: AppSettingsManager.shared.general.showObjectComments
+            columnComments: columnComments
         )
 
         if snapshot != coordinator.lastUpdateSnapshot {
@@ -186,7 +189,8 @@ struct DataGridView: NSViewRepresentable {
                 rowHeight: rowHeight,
                 alternatingRows: alternatingRows,
                 hasMoveDelegate: snapshot.hasMoveDelegate,
-                contentChanged: contentChanged
+                contentChanged: contentChanged,
+                columnComments: columnComments
             )
             coordinator.lastUpdateSnapshot = snapshot
         }
@@ -204,7 +208,8 @@ struct DataGridView: NSViewRepresentable {
         rowHeight: CGFloat,
         alternatingRows: Bool,
         hasMoveDelegate: Bool,
-        contentChanged: Bool
+        contentChanged: Bool,
+        columnComments: [String: String]
     ) {
         if let rowNumCol = tableView.tableColumns.first(where: { $0.identifier == ColumnIdentitySchema.rowNumberIdentifier }) {
             let shouldHide = !configuration.showRowNumbers
@@ -286,6 +291,7 @@ struct DataGridView: NSViewRepresentable {
                 tableView: tableView,
                 coordinator: coordinator,
                 tableRows: latestRows,
+                columnComments: columnComments,
                 savedLayout: savedLayout
             )
             coordinator.isRebuildingColumns = false
@@ -314,15 +320,18 @@ struct DataGridView: NSViewRepresentable {
         coordinator.isApplyingProgrammaticRowSelection = false
     }
 
+    private static func effectiveColumnComments(for tableRows: TableRows) -> [String: String] {
+        guard AppSettingsManager.shared.general.showObjectComments else { return [:] }
+        return tableRows.columnComments
+    }
+
     private func reconcileColumnPool(
         tableView: NSTableView,
         coordinator: TableViewCoordinator,
         tableRows: TableRows,
+        columnComments: [String: String],
         savedLayout: ColumnLayoutState?
     ) {
-        let columnComments = AppSettingsManager.shared.general.showObjectComments
-            ? tableRows.columnComments
-            : [:]
         coordinator.columnPool.reconcile(
             tableView: tableView,
             schema: coordinator.identitySchema,
diff --git a/TablePro/Views/Results/SortableHeaderCell.swift b/TablePro/Views/Results/SortableHeaderCell.swift
index 8850d981b..3856236a2 100644
--- a/TablePro/Views/Results/SortableHeaderCell.swift
+++ b/TablePro/Views/Results/SortableHeaderCell.swift
@@ -24,6 +24,16 @@ final class SortableHeaderCell: NSTableHeaderCell {
     private static let funnelSize = NSSize(width: 13, height: 13)
     private static let funnelPointSize: CGFloat = 11
 
+    private static let commentFont = NSFont.systemFont(ofSize: commentFontSize)
+
+    static let commentLineHeight: CGFloat = {
+        let lineHeight = NSAttributedString(
+            string: "X",
+            attributes: [.font: commentFont]
+        ).size().height
+        return (lineHeight + commentLineSpacing).rounded(.up)
+    }()
+
     override init(textCell string: String) {
         super.init(textCell: string)
         lineBreakMode = .byTruncatingTail
@@ -202,7 +212,7 @@ final class SortableHeaderCell: NSTableHeaderCell {
         }
 
         let commentAttributes: [NSAttributedString.Key: Any] = [
-            .font: NSFont.systemFont(ofSize: Self.commentFontSize),
+            .font: Self.commentFont,
             .foregroundColor: commentColor,
             .paragraphStyle: paragraph
         ]
diff --git a/TablePro/Views/Results/SortableHeaderView.swift b/TablePro/Views/Results/SortableHeaderView.swift
index 0dc900f73..a713ad274 100644
--- a/TablePro/Views/Results/SortableHeaderView.swift
+++ b/TablePro/Views/Results/SortableHeaderView.swift
@@ -63,7 +63,6 @@ enum HeaderSortCycle {
 final class SortableHeaderView: NSTableHeaderView {
     weak var coordinator: TableViewCoordinator?
 
-    static let commentHeaderHeight: CGFloat = 40
     private static let clickDragThreshold: CGFloat = 4
     private static let resizeZoneWidth: CGFloat = 4
     private static let fallbackHeight: CGFloat = 28
@@ -73,14 +72,12 @@ final class SortableHeaderView: NSTableHeaderView {
     private var mouseMovedTrackingArea: NSTrackingArea?
     private var hoveredColumnIndex: Int?
 
-    /// Header height when no visible column carries a comment. Captured from the
-    /// height AppKit gave the header at creation so the compact layout keeps the
-    /// platform default instead of a hardcoded value.
     private let naturalHeight: CGFloat
 
-    /// Grows the header to `commentHeaderHeight` so each cell can draw its comment
-    /// on a second line. Enforced through `setFrameSize` so `NSScrollView.tile()`
-    /// cannot shrink it back on scroll, live resize, or column drag.
+    var commentHeaderHeight: CGFloat {
+        naturalHeight + SortableHeaderCell.commentLineHeight
+    }
+
     var showsComments = false {
         didSet {
             guard showsComments != oldValue else { return }
@@ -98,20 +95,12 @@ final class SortableHeaderView: NSTableHeaderView {
         super.init(coder: coder)
     }
 
-    override func setFrameSize(_ newSize: NSSize) {
-        var size = newSize
-        if showsComments {
-            size.height = Self.commentHeaderHeight
-        }
-        super.setFrameSize(size)
-    }
-
     private func applyHeaderHeight() {
-        let targetHeight = showsComments ? Self.commentHeaderHeight : naturalHeight
+        let targetHeight = showsComments ? commentHeaderHeight : naturalHeight
         if frame.height != targetHeight {
             setFrameSize(NSSize(width: frame.width, height: targetHeight))
         }
-        enclosingScrollView?.tile()
+        tableView?.enclosingScrollView?.tile()
         needsDisplay = true
     }
 
diff --git a/TableProTests/Views/Results/DataGridColumnPoolTests.swift b/TableProTests/Views/Results/DataGridColumnPoolTests.swift
index a72af268b..8d0aef66c 100644
--- a/TableProTests/Views/Results/DataGridColumnPoolTests.swift
+++ b/TableProTests/Views/Results/DataGridColumnPoolTests.swift
@@ -413,9 +413,10 @@ struct DataGridColumnPoolTests {
         let pool = DataGridColumnPool()
         let tableView = makeTableView()
         let naturalHeight: CGFloat = 28
-        tableView.headerView = SortableHeaderView(
+        let headerView = SortableHeaderView(
             frame: NSRect(x: 0, y: 0, width: 200, height: naturalHeight)
         )
+        tableView.headerView = headerView
         let schema = ColumnIdentitySchema(columns: ["id", "email"])
 
         pool.reconcile(
@@ -429,7 +430,8 @@ struct DataGridColumnPoolTests {
             widthCalculator: defaultWidthCalculator
         )
 
-        #expect(tableView.headerView?.frame.height == SortableHeaderView.commentHeaderHeight)
+        #expect(headerView.commentHeaderHeight > naturalHeight)
+        #expect(headerView.frame.height == headerView.commentHeaderHeight)
 
         pool.reconcile(
             tableView: tableView,
@@ -442,7 +444,88 @@ struct DataGridColumnPoolTests {
             widthCalculator: defaultWidthCalculator
         )
 
-        #expect(tableView.headerView?.frame.height == naturalHeight)
+        #expect(headerView.frame.height == naturalHeight)
+    }
+
+    @Test("comments arriving after the first reconcile grow the header and repaint it")
+    func reconcile_appliesCommentsArrivingAfterFirstLoad() throws {
+        let pool = DataGridColumnPool()
+        let tableView = makeTableView()
+        let naturalHeight: CGFloat = 28
+        let headerView = SortableHeaderView(
+            frame: NSRect(x: 0, y: 0, width: 200, height: naturalHeight)
+        )
+        tableView.headerView = headerView
+        let schema = ColumnIdentitySchema(columns: ["id", "email"])
+
+        pool.reconcile(
+            tableView: tableView,
+            schema: schema,
+            columnTypes: makeColumnTypes(count: 2),
+            columnComments: [:],
+            savedLayout: nil,
+            isEditable: true,
+            hiddenColumnNames: [],
+            widthCalculator: defaultWidthCalculator
+        )
+
+        #expect(headerView.frame.height == naturalHeight)
+
+        headerView.needsDisplay = false
+        pool.reconcile(
+            tableView: tableView,
+            schema: schema,
+            columnTypes: makeColumnTypes(count: 2),
+            columnComments: ["email": "Primary contact address"],
+            savedLayout: nil,
+            isEditable: true,
+            hiddenColumnNames: [],
+            widthCalculator: defaultWidthCalculator
+        )
+
+        let emailColumn = try #require(dataColumns(in: tableView).first { $0.headerCell.stringValue == "email" })
+        let headerCell = try #require(emailColumn.headerCell as? SortableHeaderCell)
+        #expect(headerCell.headerComment == "Primary contact address")
+        #expect(headerView.frame.height == headerView.commentHeaderHeight)
+    }
+
+    @Test("an edited comment reaches the header cell without changing the header height")
+    func reconcile_appliesEditedCommentAtUnchangedHeaderHeight() throws {
+        let pool = DataGridColumnPool()
+        let tableView = makeTableView()
+        let headerView = SortableHeaderView(frame: NSRect(x: 0, y: 0, width: 200, height: 28))
+        tableView.headerView = headerView
+        let schema = ColumnIdentitySchema(columns: ["id", "email"])
+
+        pool.reconcile(
+            tableView: tableView,
+            schema: schema,
+            columnTypes: makeColumnTypes(count: 2),
+            columnComments: ["email": "Primary contact address"],
+            savedLayout: nil,
+            isEditable: true,
+            hiddenColumnNames: [],
+            widthCalculator: defaultWidthCalculator
+        )
+
+        let heightAfterFirstReconcile = headerView.frame.height
+
+        pool.reconcile(
+            tableView: tableView,
+            schema: schema,
+            columnTypes: makeColumnTypes(count: 2),
+            columnComments: ["email": "Work address"],
+            savedLayout: nil,
+            isEditable: true,
+            hiddenColumnNames: [],
+            widthCalculator: defaultWidthCalculator
+        )
+
+        let emailColumn = try #require(dataColumns(in: tableView).first { $0.headerCell.stringValue == "email" })
+        let headerCell = try #require(emailColumn.headerCell as? SortableHeaderCell)
+        #expect(headerCell.headerComment == "Work address")
+        #expect(emailColumn.headerToolTip == "email (Text)\nWork address")
+        #expect(headerView.frame.height == heightAfterFirstReconcile)
     }
 
     @Test("reconcile is idempotent for equivalent inputs")
diff --git a/TableProTests/Views/Results/DataGridUpdateSnapshotTests.swift b/TableProTests/Views/Results/DataGridUpdateSnapshotTests.swift
index 0bc7a4678..57e4320a7 100644
--- a/TableProTests/Views/Results/DataGridUpdateSnapshotTests.swift
+++ b/TableProTests/Views/Results/DataGridUpdateSnapshotTests.swift
@@ -14,7 +14,8 @@ struct DataGridUpdateSnapshotTests {
         rowDisplayCount: Int = 3,
         columns: [String] = ["name", "type"],
         reloadVersion: Int = 0,
-        contentRevision: Int = 0
+        contentRevision: Int = 0,
+        columnComments: [String: String] = [:]
     ) -> DataGridUpdateSnapshot {
         DataGridUpdateSnapshot(
             rowDisplayCount: rowDisplayCount,
@@ -30,7 +31,7 @@ struct DataGridUpdateSnapshotTests {
             alternatingRows: true,
             reloadVersion: reloadVersion,
             contentRevision: contentRevision,
-            showObjectComments: false
+            columnComments: columnComments
         )
     }
 
@@ -55,4 +56,18 @@ struct DataGridUpdateSnapshotTests {
         #expect(base != makeSnapshot(rowDisplayCount: 6, reloadVersion: 2, contentRevision: 4))
         #expect(base != makeSnapshot(rowDisplayCount: 5, reloadVersion: 3, contentRevision: 4))
     }
+
+    @Test("Column comments arriving after the rows still change the snapshot")
+    func columnCommentsArrivingLaterChangeSnapshot() {
+        let beforeMetadata = makeSnapshot(columnComments: [:])
+        let afterMetadata = makeSnapshot(columnComments: ["name": "Display name"])
+        #expect(beforeMetadata != afterMetadata)
+    }
+
+    @Test("An edited column comment changes the snapshot at the same row and column count")
+    func editedColumnCommentChangesSnapshot() {
+        let before = makeSnapshot(columnComments: ["name": "Display name"])
+        let after = makeSnapshot(columnComments: ["name": "Full name"])
+        #expect(before != after)
+    }
 }
diff --git a/TableProTests/Views/Results/SortableHeaderViewTests.swift b/TableProTests/Views/Results/SortableHeaderViewTests.swift
new file mode 100644
index 000000000..70c59f4c3
--- /dev/null
+++ b/TableProTests/Views/Results/SortableHeaderViewTests.swift
@@ -0,0 +1,83 @@
+//
+//  SortableHeaderViewTests.swift
+//  TableProTests
+//
+
+import AppKit
+import Testing
+
+@testable import TablePro
+
+@Suite("SortableHeaderView comment height")
+@MainActor
+struct SortableHeaderViewTests {
+    private struct Grid {
+        let scrollView: NSScrollView
+        let tableView: NSTableView
+        let headerView: SortableHeaderView
+
+        var headerClipHeight: CGFloat? {
+            scrollView.subviews
+                .compactMap { $0 as? NSClipView }
+                .first { $0 !== scrollView.contentView }?
+                .frame.height
+        }
+    }
+
+    private func makeGrid() -> Grid {
+        let scrollView = NSScrollView(frame: NSRect(x: 0, y: 0, width: 400, height: 300))
+        let tableView = NSTableView(frame: scrollView.bounds)
+        tableView.addTableColumn(NSTableColumn(identifier: NSUserInterfaceItemIdentifier("id")))
+        let headerView = SortableHeaderView(frame: tableView.headerView?.frame ?? .zero)
+        tableView.headerView = headerView
+        scrollView.documentView = tableView
+        scrollView.layoutSubtreeIfNeeded()
+        return Grid(scrollView: scrollView, tableView: tableView, headerView: headerView)
+    }
+
+    @Test("Showing comments grows the scroll view's header area, not just the header frame")
+    func showingCommentsGrowsHeaderClip() {
+        let grid = makeGrid()
+        let naturalHeight = grid.headerView.frame.height
+
+        grid.headerView.showsComments = true
+
+        #expect(grid.headerView.commentHeaderHeight > naturalHeight)
+        #expect(grid.headerView.frame.height == grid.headerView.commentHeaderHeight)
+        #expect(grid.headerClipHeight == grid.headerView.commentHeaderHeight)
+    }
+
+    @Test("Hiding comments restores the platform header height")
+    func hidingCommentsRestoresNaturalHeight() {
+        let grid = makeGrid()
+        let naturalHeight = grid.headerView.frame.height
+
+        grid.headerView.showsComments = true
+        grid.headerView.showsComments = false
+
+        #expect(grid.headerView.frame.height == naturalHeight)
+        #expect(grid.headerClipHeight == naturalHeight)
+    }
+
+    @Test("The comment header reserves room for the comment line under the column name")
+    func commentHeaderHeightFitsCommentLine() {
+        let grid = makeGrid()
+        let naturalHeight = grid.headerView.frame.height
+
+        #expect(grid.headerView.commentHeaderHeight == naturalHeight + SortableHeaderCell.commentLineHeight)
+    }
+
+    @Test("Resizing and reloading the grid keeps the grown header")
+    func laterLayoutKeepsGrownHeader() {
+        let grid = makeGrid()
+        grid.headerView.showsComments = true
+
+        grid.scrollView.setFrameSize(NSSize(width: 320, height: 240))
+        grid.scrollView.tile()
+        grid.tableView.reloadData()
+        grid.scrollView.layoutSubtreeIfNeeded()
+
+        #expect(grid.headerView.frame.height == grid.headerView.commentHeaderHeight)
+        #expect(grid.headerClipHeight == grid.headerView.commentHeaderHeight)
+    }
+}