feat(datagrid): show column comment as a persistent header subtitle (#1789)

[datlechin]

Closes #1789. Supersedes #1790.

Problem

When View > Show Object Comments is on, a column's comment was only added to the header's hover tooltip. It was never visible without hovering. #1789 asks for the comment to show persistently in the column header.

Change

The comment now renders as a second line under the column name when the setting is on. The tooltip stays as the full-text fallback for truncated comments. With the setting off, or for columns without a comment, the header is the single line it is today.

• SortableHeaderCell splits the cell into a name band (top, sized to the single-line height) and a comment band (bottom). Title, sort chevron, priority badge, and filter funnel all align to the name band, so indicators never overlap the subtitle. Comment uses secondaryLabelColor and a smaller font, truncates with an ellipsis, and is appended to the VoiceOver label.
• SortableHeaderView captures AppKit's natural single-line header height and enforces the taller height in setFrameSize, so it survives AppKit re-tiling on column and window resize.
• DataGridColumnPool decides the two-line state from the visible columns that have a comment and drives both the cells and the header view.
• DataGridView keeps the row-number header aligned and adds a comments signature to the update snapshot so comments that load after the columns first appear still refresh.

Scoped to comments only, which is what #1789 asks. #1790 also showed the column type under the same toggle; that is left out here.

Tests

• SortableHeaderCellTests: name-band/comment-band split, indicator alignment to the name band, single-line fallback.
• DataGridColumnPoolTests: cells get the comment and two-line flag, single line when no comment, hidden columns excluded.

Notes

• No new user-facing strings (reuses the existing toggle).
• CHANGELOG and the MySQL/PostgreSQL docs updated.

https://claude.ai/code/session_0198faM6VCrViRU4XwRoS1DC

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77be9dfec7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Redraw headers when subtitle text changes

When object comments are already visible and at least one visible column still has a comment, a later metadata refresh can change headerCell.comment without changing requiresCommentLine; showsCommentLine therefore remains true and its didSet does not invalidate the header. Because this is just a custom stored property on the cell, AppKit will keep painting the old subtitle until some unrelated redraw such as a resize or hover occurs. Please mark the affected header rect, or the header view, as needing display when the comment value changes.

Useful? React with 👍 / 👎.

[datlechin]

Superseded: the same implementation is now pushed directly to #1790.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
TablePro	🔴 Failed	–	Jun 30, 2026, 11:23 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.