Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .claude/rules/data-grid.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ Three layers, knowledge pointing one way: an owner's adapter, then `DataGridMode

- **Two tables, one grid.** The main pane's `DataGridTableView` holds every column, the row numbers first. The frozen pane is a second table laid over the main pane's leading edge, showing the row numbers and the frozen columns. Keys, find, copy and VoiceOver work on the main table.
- **The main table is the only first responder.** The frozen table refuses it and hands its presses to the controller. `DataGridContainerView.gridHasFocus` is the one focus flag: both panes' row views take `isEmphasized` from it, and so does the active-cell border.
- **Row height, row count, reloads, inserts and removes reach both panes in one call**, so their document heights never differ.
- **Vertical scroll stays in step through bounds-change notifications**: each pane's clip moves the other with `clipView.scroll(to:)` and `reflectScrolledClipView`, only when its y differs. Anywhere else scroll with `NSView.scroll(_:)`: moving a clip's x that way leaves the header behind.
- **Row height, row count, reloads, inserts, removes and height notes reach both panes in one call**, so their document heights never differ while rows are one pitch. A grid that wraps is the exception: AppKit estimates the height of rows it has not asked about, each table by its own sample, so the two documents differ.
- **Vertical scroll stays in step through bounds-change notifications**: each pane's clip moves the other with `clipView.scroll(to:)` and `reflectScrolledClipView`, only when its y differs. A grid that wraps matches the first visible row and its offset instead of y, in both directions, in `DataGridContainerView.syncVertical`, the one place the panes are aligned. Anywhere else scroll with `NSView.scroll(_:)`: moving a clip's x that way leaves the header behind.
- **The frozen pane forwards every wheel event to the main scroll view**, so one momentum engine moves both.
- **A `fitsRows` grid is as tall as its rows and scrolls only sideways.** It publishes `model.fittingHeight` for its host to size it, hands a vertical gesture to the enclosing scroll view (the axis is decided once per gesture), and reveals a row by scrolling that page. The Structure tab's sections use it.
- **Frozen columns take at most two thirds of the grid** (`DataGridMetrics.maximumFrozenShare`). Columns past that scroll, and Freeze Up to This Column is refused in the menu.
Expand All @@ -39,6 +39,9 @@ Three layers, knowledge pointing one way: an owner's adapter, then `DataGridMode

- **Cells are drawn, not mounted.** `DataGridRowView` draws its pane's cells through `DataGridCellRenderer`. `tableView(_:viewFor:row:)` returns nil except for the cell being edited and the accessibility stand-ins: a view per cell costs 45 ms a frame at 1,000 rows by 200 columns against 1.5 ms drawn.
- **A change repaints, it never reloads.** It reaches pixels as `needsDisplay` on the row views it names. `reloadData(forRowIndexes:columnIndexes:)` only mounts or unmounts a cell view, since reloading an edited row ends the edit. A full `reloadData()` drops the table selection without telling anyone, so the controller writes it back.
- **Wrap Text is per grid, and off is the fixed-pitch table.** `model.wrapsText` is the store's flag on a grid that offers `.wrapText`. The controller answers `tableView(_:heightOfRow:)` only while it is on (`responds(to:)`, then the delegates are assigned again and the tables reloaded), so a grid that never wraps runs none of this. `tableView.rowHeight` stays the one-line height in both modes.
- **A wrapped row's height comes from `display.lineCounts`**, a line count per `RowID` over every column, capped at `DataGridWrapLayout.maximumLines`. It clears with the display cache and whenever `DataGridWrapGeometry` moves (a width, the column set, a font, the Row height, Show Invisible Characters). A row with no count is one line. Rows AppKit shows or holds ready are measured on the main actor as the viewport moves, the prewarm fills the rest, and every count that changes an answer is followed by `noteHeightOfRows` on both panes inside a kept place, never by a reload.
- **In a tall row everything but the value sits on the first line**: the row number, the accessory, the checkbox, a placeholder and the edit field. `DataGridWrapLayout` breaks the value and the renderer draws it, from the text the formatter left with every line break as one LF.
- **Every column stays attached.** Never hide an off-screen column with `NSTableColumn.isHidden`: each write costs O(attached columns). Columns come from each pane's pool, keyed by `DataGridColumnID`, so a re-run of the same result does not flicker (#951).
- **Resolve a table column through `DataGridPane.slot(atTableIndex:columns:)` and `tableIndex(forDisplayPosition:columns:)`**, never a fixed index into `tableColumns`: the row-number column sits first and the frozen pane holds a subset.
- **`gridStyleMask` stays empty.** AppKit's vertical grid lines keep a subview per column (518 ms a layout at 500 columns). `DataGridBodyChrome` draws the separators in each row, and the stripes and separators past the last row.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
//
// SpecialCharacterText.swift
// TableProTextEngine
//

import AppKit

// The editor's marks for a view that breaks a value into lines itself, such as a grid cell that wraps.
public struct SpecialCharacterText {
// As long as the source, unit for unit, so an offset into one is an offset into the other.
public let string: NSAttributedString
public let marks: [SpecialCharacterMark]

public init(_ string: NSAttributedString, style: SpecialCharacterStyle) {
let display = SpecialCharacterDisplay.make(from: string, style: style)
self.string = display.string
marks = display.marks
}

// `line` shows `string` from `start`: typeset from it there, or laid out from that part alone.
// `drawn` is `line` or an end truncation of it, which drops the marks the ellipsis replaced.
public func marks(from start: Int, in line: CTLine, drawnAs drawn: CTLine) -> [SpecialCharacterMark] {
guard !marks.isEmpty else { return [] }
let range = CTLineGetStringRange(line)
let lineEnd = range.location + range.length
var shownEnd = lineEnd
if drawn !== line {
let runs = CTLineGetGlyphRuns(drawn) as? [CTRun] ?? []
shownEnd = runs.map(CTRunGetStringRange)
.filter { $0.location + $0.length == lineEnd }
.map(\.location)
.min() ?? lineEnd
}
let end = start + shownEnd - range.location
let shown = marks
.filter { $0.offset >= start && $0.offset + $0.length <= end }
.map { $0.offset(by: -start) }
return SpecialCharacterGeometry.positioned(shown, in: drawn)
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import AppKit
@testable import TableProTextEngine
import Testing

@MainActor
struct SpecialCharacterTextTests {
private let font = NSFont.monospacedSystemFont(ofSize: 13, weight: .regular)

private func attributed(_ text: String) -> NSAttributedString {
NSAttributedString(string: text, attributes: [.font: font, .foregroundColor: NSColor.black])
}

@Test("The laid out text is as long as its source and leaves a line break unmarked")
func keepsLengthAndLineBreaks() {
let source = "a\u{200B}\nb\u{202E}c"
let text = SpecialCharacterText(attributed(source), style: SpecialCharacterStyle())

#expect(text.string.length == (source as NSString).length)
#expect(text.marks.map(\.offset) == [1, 4])
#expect((text.string.string as NSString).character(at: 2) == 0x0A)
}

@Test("A typeset line takes only its own marks, placed from the line's start")
func marksFollowTheirLine() throws {
let text = SpecialCharacterText(attributed("ab\u{200B}\ncd\u{200B}"), style: SpecialCharacterStyle())
let typesetter = CTTypesetterCreateWithAttributedString(text.string)
let first = CTTypesetterCreateLine(typesetter, CFRange(location: 0, length: 4))
let second = CTTypesetterCreateLine(typesetter, CFRange(location: 4, length: 3))

let firstMarks = text.marks(from: 0, in: first, drawnAs: first)
let secondMarks = text.marks(from: 4, in: second, drawnAs: second)
let prefix = CGFloat(CTLineGetTypographicBounds(CTLineCreateWithAttributedString(attributed("cd")), nil, nil, nil))

#expect(firstMarks.count == 1)
#expect(secondMarks.count == 1)
let mark = try #require(secondMarks.first)
#expect(abs(mark.minX - prefix) < 0.5)
#expect(mark.maxX - mark.minX > 10)
}

@Test("A line laid out from part of the text, then cut at its end, drops the marks the ellipsis replaced")
func truncatedPartDropsHiddenMarks() throws {
let source = "x\n\u{200B}" + String(repeating: "y", count: 40) + "\u{200B}"
let text = SpecialCharacterText(attributed(source), style: SpecialCharacterStyle())
let part = text.string.attributedSubstring(from: NSRange(location: 2, length: text.string.length - 2))
let line = CTLineCreateWithAttributedString(part)
let ellipsis = CTLineCreateWithAttributedString(attributed("\u{2026}"))
let cut = try #require(CTLineCreateTruncatedLine(line, 120, .end, ellipsis))

#expect(text.marks(from: 2, in: line, drawnAs: line).count == 2)
let shown = text.marks(from: 2, in: line, drawnAs: cut)
#expect(shown.count == 1)
#expect(shown.first?.minX == 0)
}
}
11 changes: 10 additions & 1 deletion apple/TablePro/Core/DataGrid/DataGridDisplayState.swift
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,15 @@ import Foundation
// Formatted text kept by the model, so a remount of the grid draws from it instead of formatting every row again (#2424).
@MainActor
final class DataGridDisplayState {
let cache = RowDisplayCache()
let lineCounts: RowLineCountStore
let cache: RowDisplayCache
var highlightRuleSetKey: HighlightRuleSet.Key?
// Whether the cached text kept its line breaks, which only a grid that wraps asks for.
var keepsLineBreaks = false

init() {
let lineCounts = RowLineCountStore()
self.lineCounts = lineCounts
cache = RowDisplayCache(lineCounts: lineCounts)
}
}
16 changes: 16 additions & 0 deletions apple/TablePro/Core/DataGrid/DataGridModel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -373,6 +373,22 @@ final class DataGridModel: ObservableObject {
refreshFind()
}

// MARK: - Wrap

// Only a grid that offers the command wraps, whatever its store holds.
var wrapsText: Bool {
configuration.commands.contains(.wrapText) && store.wrapsText
}

// The cached text is flattened or keeps its breaks by this flag, so it goes with the change, mounted or not.
func setWrapsText(_ wraps: Bool) {
guard configuration.commands.contains(.wrapText), wraps != store.wrapsText, commitEditing() else { return }
store.wrapsText = wraps
display.keepsLineBreaks = wraps
display.cache.removeAll()
mountedView?.configurationDidChange()
}

// MARK: - Schemas

private func observeSchemas() {
Expand Down
3 changes: 3 additions & 0 deletions apple/TablePro/Core/DataGrid/DataGridOwnerProtocols.swift
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ enum DataGridCommand: Hashable, CaseIterable {
case valueFilter
case copyAsSQL
case loadUnloadedValues
case wrapText
}

enum DataGridLayoutScope: Equatable {
Expand Down Expand Up @@ -161,6 +162,7 @@ protocol DataGridStateStore: AnyObject {
var displayFormats: [ValueDisplayFormat?] { get set }
var selectionSnapshot: GridSelectionSnapshot { get set }
var viewportAnchor: GridViewportPlacement? { get set }
var wrapsText: Bool { get set }
var layoutScope: DataGridLayoutScope { get }
}

Expand All @@ -172,6 +174,7 @@ final class InMemoryDataGridStateStore: DataGridStateStore {
var displayFormats: [ValueDisplayFormat?] = []
var selectionSnapshot = GridSelectionSnapshot.empty
var viewportAnchor: GridViewportPlacement?
var wrapsText = false
let layoutScope: DataGridLayoutScope = .ephemeral

init(columnLayout: ColumnLayoutState = ColumnLayoutState(), sortState: SortState = SortState()) {
Expand Down
52 changes: 47 additions & 5 deletions apple/TablePro/Core/DataGrid/DataGridPrewarmWindow.swift
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
// The slice of a result the data grid formats ahead of the viewport.
//

import Foundation
import AppKit
import TableProPluginKit

/// The rows the background prewarm may format, as a function of the rows on screen.
Expand All @@ -23,6 +23,45 @@ enum DataGridPrewarmWindow {
}
}

// What a wrapping grid's rows are measured against, copied out so a batch counts their lines where it formats them.
struct DataGridPrewarmWrap: Sendable {
struct Column: Sendable {
let dataIndex: Int
let width: CGFloat
let kind: DataGridCellKind
}

let columns: [Column]
let face: DataGridWrapLayout.Face
let isEditable: Bool
let marksEmptyText: Bool
let marksInvisibles: Bool
// Rows with a pending change or a value left on the server draw text the batch cannot see.
let measurableRows: Set<RowID>
let generation: Int

// Nil leaves the row to the main actor: a marked character is as wide as its marker, which is laid out there.
func lineCount(of row: Row, texts: ContiguousArray<String?>) -> Int? {
guard measurableRows.contains(row.id) else { return nil }
var lines = 1
for column in columns where column.dataIndex < row.values.count && column.dataIndex < texts.count {
let rawValue = row.values[column.dataIndex]
guard column.kind != .checkbox,
DataGridCellContent.placeholder(for: rawValue, marksEmptyText: marksEmptyText) == nil,
let text = texts[column.dataIndex] else { continue }
let accessory = DataGridCellAccessory.visible(for: column.kind, isEditable: isEditable, rawValue: rawValue.asText)
let width = accessory.availableTextWidth(in: NSRect(x: 0, y: 0, width: column.width, height: 0))
if marksInvisibles {
let shown = DataGridWrapLayout.bounded(text, width: width, pointSize: face.font.pointSize).text
guard !DataGridWrapLayout.holdsMarkableCharacter(shown) else { return nil }
}
lines = max(lines, DataGridWrapLayout.lineCount(of: text, width: width, face: face))
if lines >= DataGridWrapLayout.maximumLines { break }
}
return lines
}
}

// A few rows of the window, copied out so the formatting never holds the result's whole buffer: an edit made
// meanwhile would then copy every row.
struct DataGridPrewarmBatch: Sendable {
Expand All @@ -36,12 +75,14 @@ struct DataGridPrewarmBatch: Sendable {
let dateFormat: DateFormatOption
// What the display cache had dropped when the rows were copied; text formatted before a later drop is stale.
let invalidations: Int
var keepsLineBreaks = false
var wrap: DataGridPrewarmWrap?

// A renderer serves one thread, so each batch builds its own from the format.
@concurrent
nonisolated func formatted() async -> sending [(id: RowID, box: RowDisplayBox)] {
nonisolated func formatted() async -> sending [(id: RowID, box: RowDisplayBox, lineCount: Int?)] {
let dates = DateDisplayRenderer(format: dateFormat)
var formatted: [(id: RowID, box: RowDisplayBox)] = []
var formatted: [(id: RowID, box: RowDisplayBox, lineCount: Int?)] = []
formatted.reserveCapacity(rows.count)
for row in rows where !Task.isCancelled {
let box = RowDisplayBox(ContiguousArray<String?>(repeating: nil, count: columnCount))
Expand All @@ -51,11 +92,12 @@ struct DataGridPrewarmBatch: Sendable {
columnType: dataIndex < columnTypes.count ? columnTypes[dataIndex] : nil,
displayFormat: dataIndex < formats.count ? formats[dataIndex] : nil,
databaseType: databaseType,
dates: dates
dates: dates,
keepsLineBreaks: keepsLineBreaks
)
box.setText(display.text ?? row.values[dataIndex].asText ?? "", at: dataIndex, isFormatted: display.isFormatted)
}
formatted.append((row.id, box))
formatted.append((row.id, box, wrap?.lineCount(of: row, texts: box.values)))
}
return formatted
}
Expand Down
33 changes: 32 additions & 1 deletion apple/TablePro/Core/DataGrid/RowDisplayBox.swift
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,31 @@ final class RowDisplayBox {
}
}

// The lines each measured row needs while its grid wraps. A row with no entry has not been measured and stands one line tall.
@MainActor
final class RowLineCountStore {
private var counts: [RowID: Int] = [:]
// Rises whenever a count is dropped, so one measured off the main actor can tell it went stale on the way back.
private(set) var generation = 0

subscript(id: RowID) -> Int? {
get { counts[id] }
set { counts[id] = newValue }
}

var isEmpty: Bool { counts.isEmpty }

func remove(_ id: RowID) {
generation &+= 1
counts.removeValue(forKey: id)
}

func removeAll() {
generation &+= 1
counts.removeAll(keepingCapacity: true)
}
}

@MainActor
final class RowDisplayCache {
// Callers mutate a box in place, so only the cost recorded at insertion matches what was added to `totalCost`.
Expand All @@ -63,10 +88,13 @@ final class RowDisplayCache {
private(set) var invalidations = 0
private let countLimit: Int
private let costLimit: Int
// A row's line count follows from its text, so every call that drops text drops the count with it.
private let lineCounts: RowLineCountStore?

init(countLimit: Int = 50_000, costLimit: Int = 64 * 1_024 * 1_024) {
init(countLimit: Int = 50_000, costLimit: Int = 64 * 1_024 * 1_024, lineCounts: RowLineCountStore? = nil) {
self.countLimit = countLimit
self.costLimit = costLimit
self.lineCounts = lineCounts
}

func box(forID id: RowID) -> RowDisplayBox? {
Expand Down Expand Up @@ -106,6 +134,7 @@ final class RowDisplayCache {

func removeAll() {
invalidations &+= 1
lineCounts?.removeAll()
storage.removeAll(keepingCapacity: true)
highlights.removeAll(keepingCapacity: true)
insertionOrder.removeAll(keepingCapacity: true)
Expand All @@ -116,6 +145,7 @@ final class RowDisplayCache {
// Row ids are positional: a row edited in place keeps its id and would otherwise be served its pre-edit text.
func clearValues(forID id: RowID) {
invalidations &+= 1
lineCounts?.remove(id)
highlights.removeValue(forKey: id)
guard let existing = storage[id] else { return }
totalCost -= existing.cost
Expand All @@ -127,6 +157,7 @@ final class RowDisplayCache {
func clearValues(forDataIndexes dataIndexes: Set<Int>) {
guard !dataIndexes.isEmpty else { return }
invalidations &+= 1
lineCounts?.removeAll()
highlights.removeAll(keepingCapacity: true)
storage = storage.mapValues { entry in
for index in dataIndexes {
Expand Down
2 changes: 2 additions & 0 deletions apple/TablePro/Core/Menu/ViewMenuBuilder.swift
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ enum ViewMenuBuilder {
String(localized: "Highlight Rules…"),
action: #selector(MainSplitViewController.showHighlightRules(_:))
),
// A focused data grid answers this itself; the window answers for the selected tab's grid otherwise.
MenuItemFactory.item(String(localized: "Wrap Text"), action: #selector(MainSplitViewController.toggleWrapText(_:))),
MenuItemFactory.item(
String(localized: "Show Query History"),
action: #selector(MainSplitViewController.toggleQueryHistory(_:)),
Expand Down
Loading
Loading