feat(datagrid): filter a table by a cell's value from the cell context menu (#3101)

Signed-off-by: Ngô Quốc Đạt <datlechin@gmail.com>

Author: datlechin

CHANGELOG.md

@@ -49,6 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Tables from every schema in Open Quickly and the sidebar filter, and `schema.table` searches in both. (#3048)
 - Recent-tab switching on Control-Tab, with a list of the window's tabs while Control is held. (#2524)
 - **Extensions** for SQLite and local libSQL connections, loading sqlite-vec, SpatiaLite and other libraries on connect. (#2502)
+- **Filter** in a data grid cell's context menu, for narrowing a table to rows sharing that cell's value. (#3066)
 - Version history for saved queries, with **Restore This Version**. (#2505)
 - Git status letters, history and **Discard Changes…** for files in a linked SQL folder. (#2505)
 - Whether a materialized view can be refreshed concurrently, on its **Indexes** tab. (#2522)
@@ -182,6 +183,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A dropped database or schema leaving every one of its tables' saved settings behind.
 - Favorites rows left behind by a dropped table, schema or database.
 - Column and operator pull-downs in **Highlight Rules** snapping back to their previous value, leaving every rule on **equals** and on the column it was created with. (#3015)
+- Lines of a multi-line value run together in the cell menu's **Highlight** titles.
 - Favorite queries missing from the sidebar Favorites tab on the first switch to it. (#3016)
 - Favorites list silently dropping rows during a burst of iCloud favorites updates.
 - A favorite moved out of **Global** still listed, and its keyword still expanding, in every other connection.

TablePro/Core/Coordinators/FilterCoordinator.swift

@@ -541,12 +541,79 @@ final class FilterCoordinator: ObservableObject {
         applyCommit(.solo(filter.id))
     }
 
+    /// Whether the selected tab's rows can be filtered from the grid: a table tab showing its rows,
+    /// on an engine that filters by column rather than by a key pattern.
+    var canFilterRows: Bool {
+        guard let tab = parent.tabManager.selectedTab,
+              tab.tabType == .table,
+              tab.tableContext.tableName != nil,
+              tab.display.resultsViewMode.showsRowFilters else { return false }
+        return !usesBrowseSearch
+    }
+
+    /// Narrows what the grid shows by one more condition, which a cell's Filter menu offers.
+    func applyCellFilter(_ filter: TableFilter) {
+        guard canFilterRows, filter.isValid,
+              !Self.isRunning(filter, in: selectedTabFilterState) else { return }
+        applyTransition { state in
+            state = Self.cellFilterState(state, adding: filter)
+        }
+    }
+
+    /// Whether the rows on screen were already fetched with this condition, so adding it would
+    /// change nothing but the page.
+    static func isRunning(_ filter: TableFilter, in state: TabFilterState) -> Bool {
+        guard state.executedFilters.contains(where: { $0.hasSameCondition(as: filter) }) else { return false }
+        return state.filterLogicMode == .and || state.executedFilters.count == 1
+    }
+
+    /// The filter state that shows what the grid showed, and only rows matching `filter` too.
+    ///
+    /// What the grid showed is `executedFilters`, never `appliedFilters`: rows typed and never
+    /// applied, and rows left in the panel by Clear, resolve as applied under `.all` without having
+    /// run. So a row stays checked only when it is running, every other row is unchecked rather than
+    /// removed, and the commit becomes `.all` over exactly the checked rows, which is also what the
+    /// saved state restores. A row that already holds the condition is checked instead of repeated.
+    ///
+    /// Under Match any, a condition can only be added to one running row or none, where the two
+    /// modes agree and the mode becomes Match all. With two or more running rows the condition
+    /// cannot join them, so it runs alone.
+    static func cellFilterState(_ state: TabFilterState, adding filter: TableFilter) -> TabFilterState {
+        let executedIDs = Set(state.executedFilters.map(\.id))
+        let runningIDs = Set(state.filters.lazy.map(\.id).filter(executedIDs.contains))
+        let keepsRunningRows = state.filterLogicMode == .and || runningIDs.count <= 1
+        let keptIDs = keepsRunningRows ? runningIDs : []
+        let existingID = state.filters.first { $0.hasSameCondition(as: filter) }?.id
+
+        var next = state
+        next.filters = state.filters.map { row in
+            var row = row
+            row.isEnabled = keptIDs.contains(row.id) || row.id == existingID
+            return row
+        }
+        if existingID == nil {
+            var added = filter
+            added.isEnabled = true
+            next.filters.append(added)
+        }
+        if keepsRunningRows {
+            next.filterLogicMode = .and
+        }
+        next.commit = .all
+        next.isVisible = true
+        return next
+    }
+
     /// Writes the commit, persists it and re-queries, all behind the discard guard.
     ///
     /// Behind it, because `commit` is the record of what the rows on screen were fetched with.
     /// Setting it first and taking the guard afterwards left a declined apply reporting a filter
     /// the grid had never run, saved to disk, and re-run by the next page turn.
     private func applyCommit(_ commit: FilterCommit) {
+        applyTransition { $0.commit = commit }
+    }
+
+    private func applyTransition(_ transition: @escaping (inout TabFilterState) -> Void) {
         guard let (tab, tabIndex) = parent.tabManager.selectedTabAndIndex,
               let tableName = tab.tableContext.tableName else { return }
 
@@ -555,7 +622,7 @@ final class FilterCoordinator: ObservableObject {
         parent.confirmDiscardChangesIfNeeded(action: .filter) { [weak self] confirmed in
             guard let self, confirmed else { return }
             guard capturedTabIndex < parent.tabManager.tabs.count else { return }
-            parent.tabManager.mutate(at: capturedTabIndex) { $0.filterState.commit = commit }
+            mutateFilterState(at: capturedTabIndex, transition)
             commitFilters(
                 parent.tabManager.tabs[capturedTabIndex].filterState.appliedFilters,
                 logicMode: nil,

TablePro/Core/Utilities/SQL/ColumnTypeSQLQuoting.swift

@@ -41,17 +41,41 @@ internal enum ColumnTypeSQLQuoting {
     static func isCharacterType(_ type: ColumnType?) -> Bool {
         guard case let .text(rawType)? = type else { return false }
         guard let rawType else { return true }
-        let base = rawType.prefix { $0 != "(" }
-            .trimmingCharacters(in: .whitespaces)
-            .uppercased()
+        let base = baseName(of: rawType)
         if characterBaseNames.contains(base) { return true }
         return base.contains("CHAR") || base.hasSuffix("TEXT")
     }
 
+    /// Whether `column = 'literal'` is a valid comparison for the column's own type. Large objects
+    /// and XML have no equality operator on the engines that define them (Oracle ORA-00932, SQL
+    /// Server error 402, PostgreSQL `operator does not exist: xml = unknown`), and neither does
+    /// PostgreSQL's `json`.
+    static func hasEqualityOperator(_ type: ColumnType) -> Bool {
+        switch type {
+        case .text(let rawType):
+            guard let rawType else { return true }
+            return !typesWithoutEquality.contains(baseName(of: rawType))
+        case .integer, .decimal, .date, .timestamp, .datetime, .boolean, .enumType, .set:
+            return true
+        case .blob, .json, .spatial, .array:
+            return false
+        }
+    }
+
+    private static func baseName(of rawType: String) -> String {
+        rawType.prefix { $0 != "(" }
+            .trimmingCharacters(in: .whitespaces)
+            .uppercased()
+    }
+
     private static let characterBaseNames: Set<String> = [
         "STRING", "FIXEDSTRING", "CLOB", "NCLOB", "NAME", "CITEXT"
     ]
 
+    private static let typesWithoutEquality: Set<String> = [
+        "CLOB", "NCLOB", "NTEXT", "LONG", "XML", "XMLTYPE"
+    ]
+
     static func supportsEmptyStringComparison(_ type: ColumnType?) -> Bool {
         guard let type else { return true }
         return isKnownTextLike(type)

TablePro/Models/Database/TableFilter.swift

@@ -222,6 +222,17 @@ struct TableFilter: Identifiable, Equatable, Hashable, Codable {
 }
 
 extension TableFilter {
+    /// Whether both rows select the same rows, whatever their id, position or enabled flag.
+    func hasSameCondition(as other: TableFilter) -> Bool {
+        columnName == other.columnName
+            && filterOperator == other.filterOperator
+            && value == other.value
+            && secondValue == other.secondValue
+            && rawSQL == other.rawSQL
+            && isCaseSensitive == other.isCaseSensitive
+            && elementScope == other.elementScope
+    }
+
     /// The joined `value` stays as it was for drivers that still read a `BETWEEN` as one
     /// comma-separated string; `secondValue` carries the upper bound intact for those that don't,
     /// so a bound holding a comma is no longer mistaken for the separator.

TablePro/Models/Highlight/HighlightRuleDescription.swift

@@ -47,12 +47,14 @@ enum HighlightRuleDescription {
         )
     }
 
+    /// A limited value is shown on one line, so its line breaks become spaces: `NSMenu` lays a
+    /// title's line break out as nothing at all, which ran the two lines together.
     static func truncated(_ value: String, to limit: Int?) -> String {
         guard let limit, limit > 0 else { return value }
         let source = value as NSString
-        guard source.length > limit else { return value }
+        guard source.length > limit else { return value.sanitizedForCellDisplay }
         let cut = source.rangeOfComposedCharacterSequence(at: limit).location
-        return source.substring(to: cut) + "\u{2026}"
+        return source.substring(to: cut).sanitizedForCellDisplay + "\u{2026}"
     }
 
     private static func operatorText(_ filterOperator: FilterOperator) -> String {

TablePro/Views/Filter/CellFilterMenuBuilder.swift

@@ -0,0 +1,88 @@
+//
+//  CellFilterMenuBuilder.swift
+//  TablePro
+//
+
+import AppKit
+import TableProPluginKit
+
+@MainActor
+enum CellFilterMenuBuilder {
+    static let maxValueLength = 10_000
+
+    /// The conditions a cell can offer, each one matching the row it came from.
+    ///
+    /// The value goes into the same filter a reader could type, so it is offered only where that
+    /// filter matches it exactly. The SQL generators trim a value and read the word `NULL` as SQL
+    /// NULL outside text columns, a column whose type is unresolved has its literals guessed at,
+    /// and some types have no `=` at all, so any of those gets nothing rather than a filter that
+    /// would drop the row the reader clicked.
+    static func conditions(
+        columnName: String,
+        columnType: ColumnType?,
+        value: PluginCellValue
+    ) -> [TableFilter] {
+        switch value {
+        case .null:
+            return [.isNull, .isNotNull].map { filter(columnName, $0) }
+        case .text(let text) where text.isEmpty:
+            guard let columnType, ColumnTypeSQLQuoting.supportsEmptyStringComparison(columnType) else { return [] }
+            return [.isEmpty, .isNotEmpty].map { filter(columnName, $0) }
+        case .text(let text):
+            guard let columnType, matchesExactly(text, columnType: columnType) else { return [] }
+            return comparisonOperators(for: columnType).map { filter(columnName, $0, value: text) }
+        case .bytes:
+            return []
+        }
+    }
+
+    static func title(for filter: TableFilter) -> String {
+        HighlightRuleDescription.condition(
+            columnName: filter.columnName,
+            filterOperator: filter.filterOperator,
+            value: filter.value,
+            secondValue: filter.secondValue,
+            valueLimit: HighlightRuleDescription.menuValueLimit
+        )
+    }
+
+    static func menuItem(
+        columnName: String,
+        columnType: ColumnType?,
+        value: PluginCellValue,
+        apply: @escaping (TableFilter) -> Void
+    ) -> NSMenuItem? {
+        let filters = conditions(columnName: columnName, columnType: columnType, value: value)
+        guard !filters.isEmpty else { return nil }
+
+        let submenu = NSMenu()
+        for filter in filters {
+            submenu.addItem(ClosureMenuTarget.item(title: title(for: filter)) { apply(filter) })
+        }
+
+        let item = NSMenuItem(title: String(localized: "Filter"), action: nil, keyEquivalent: "")
+        item.image = NSImage(systemSymbolName: "line.3.horizontal.decrease.circle", accessibilityDescription: nil)
+        item.submenu = submenu
+        return item
+    }
+
+    private static func matchesExactly(_ text: String, columnType: ColumnType) -> Bool {
+        guard ColumnTypeSQLQuoting.hasEqualityOperator(columnType),
+              (text as NSString).length <= maxValueLength,
+              text == text.trimmingCharacters(in: .whitespaces) else { return false }
+        return !HighlightCondition.readsAsNullLiteral(text, columnType: columnType)
+    }
+
+    private static func comparisonOperators(for columnType: ColumnType) -> [FilterOperator] {
+        switch columnType {
+        case .integer, .decimal, .date, .timestamp, .datetime:
+            return [.equal, .notEqual, .greaterThan, .lessThan]
+        case .text, .boolean, .enumType, .set, .blob, .json, .spatial, .array:
+            return [.equal, .notEqual]
+        }
+    }
+
+    private static func filter(_ columnName: String, _ filterOperator: FilterOperator, value: String = "") -> TableFilter {
+        TableFilter(columnName: columnName, filterOperator: filterOperator, value: value)
+    }
+}

TablePro/Views/Main/Child/DataTabGridDelegate.swift

@@ -160,6 +160,29 @@ final class DataTabGridDelegate: DataGridViewDelegate {
         return HighlightMenuBuilder.menuItem(for: context, actions: actions)
     }
 
+    /// Offered only for a value the server holds: a row the reader inserted, or a cell they edited,
+    /// is not on the server yet, so a filter built from it cannot find the row it came from.
+    func dataGridFilterMenuItem(forRow displayRow: Int, dataColumn: Int) -> NSMenuItem? {
+        guard let coordinator, coordinator.canFilterRows,
+              let grid = tableViewCoordinator,
+              let tab = coordinator.tabManager.selectedTab,
+              let row = grid.displayRow(at: displayRow) else { return nil }
+        let visualState = grid.visualState(for: displayRow)
+        guard !visualState.isInserted, !visualState.isModified(columnIndex: dataColumn) else { return nil }
+        let tableRows = grid.tableRowsProvider()
+        let columns = tableRows.columns
+        guard columns.indices.contains(dataColumn), dataColumn < row.values.count else { return nil }
+
+        let tabId = tab.id
+        return CellFilterMenuBuilder.menuItem(
+            columnName: columns[dataColumn],
+            columnType: dataColumn < tableRows.columnTypes.count ? tableRows.columnTypes[dataColumn] : nil,
+            value: row.values[dataColumn]
+        ) { [weak coordinator] filter in
+            coordinator?.applyCellFilter(filter, forTab: tabId)
+        }
+    }
+
     func dataGridHighlightValuesMenuItem(forColumn dataColumnIndex: Int) -> NSMenuItem? {
         guard coordinator != nil, let grid = tableViewCoordinator else { return nil }
         let columns = grid.tableRowsProvider().columns

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

@@ -72,6 +72,15 @@ extension MainContentCoordinator {
         filterCoordinator.applySoloFilter(filter)
     }
 
+    var canFilterRows: Bool {
+        filterCoordinator.canFilterRows
+    }
+
+    func applyCellFilter(_ filter: TableFilter, forTab tabId: UUID) {
+        guard tabManager.selectedTab?.id == tabId else { return }
+        filterCoordinator.applyCellFilter(filter)
+    }
+
     func toggleFilterPanel() {
         filterCoordinator.toggleFilterPanel()
     }

TablePro/Views/Results/DataGridRowView.swift

@@ -516,13 +516,7 @@ class DataGridRowView: NSTableRowView {
             menu.addItem(jsonViewItem)
         }
 
-        if dataColumnIndex >= 0,
-           let highlightItem = coordinator.delegate?.dataGridHighlightMenuItem(
-               forRow: rowIndex,
-               dataColumn: dataColumnIndex
-           ) {
-            menu.addItem(highlightItem)
-        }
+        addCellValueMenuItems(to: menu, dataColumnIndex: dataColumnIndex, delegate: coordinator.delegate)
 
         let tableRows = coordinator.tableRowsProvider()
         addForeignKeyMenuItems(to: menu, dataColumnIndex: dataColumnIndex, tableRows: tableRows)
@@ -591,6 +585,20 @@ class DataGridRowView: NSTableRowView {
         return menu
     }
 
+    private func addCellValueMenuItems(
+        to menu: NSMenu,
+        dataColumnIndex: Int,
+        delegate: (any DataGridViewDelegate)?
+    ) {
+        guard dataColumnIndex >= 0, let delegate else { return }
+        if let filterItem = delegate.dataGridFilterMenuItem(forRow: rowIndex, dataColumn: dataColumnIndex) {
+            menu.addItem(filterItem)
+        }
+        if let highlightItem = delegate.dataGridHighlightMenuItem(forRow: rowIndex, dataColumn: dataColumnIndex) {
+            menu.addItem(highlightItem)
+        }
+    }
+
     private func buildSetValueMenu(dataColumnIndex: Int, tableRows: TableRows) -> NSMenu {
         let setValueMenu = NSMenu()
 

TablePro/Views/Results/DataGridViewDelegate.swift

@@ -32,6 +32,7 @@ protocol DataGridViewDelegate: AnyObject {
     func dataGridColumnStructureMenuItems(forColumn dataColumnIndex: Int) -> [NSMenuItem]
     func dataGridRowStructureMenuItems(forRow displayRow: Int) -> [NSMenuItem]
     func dataGridHighlightMenuItem(forRow displayRow: Int, dataColumn: Int) -> NSMenuItem?
+    func dataGridFilterMenuItem(forRow displayRow: Int, dataColumn: Int) -> NSMenuItem?
     func dataGridHighlightValuesMenuItem(forColumn dataColumnIndex: Int) -> NSMenuItem?
     func dataGridVisualState(forRow row: Int) -> RowVisualState?
     func dataGridRowView(for tableView: NSTableView, row: Int, coordinator: TableViewCoordinator) -> NSTableRowView?
@@ -83,6 +84,7 @@ extension DataGridViewDelegate {
     func dataGridColumnStructureMenuItems(forColumn dataColumnIndex: Int) -> [NSMenuItem] { [] }
     func dataGridRowStructureMenuItems(forRow displayRow: Int) -> [NSMenuItem] { [] }
     func dataGridHighlightMenuItem(forRow displayRow: Int, dataColumn: Int) -> NSMenuItem? { nil }
+    func dataGridFilterMenuItem(forRow displayRow: Int, dataColumn: Int) -> NSMenuItem? { nil }
     func dataGridHighlightValuesMenuItem(forColumn dataColumnIndex: Int) -> NSMenuItem? { nil }
     func dataGridVisualState(forRow row: Int) -> RowVisualState? { nil }
     func dataGridRowView(for tableView: NSTableView, row: Int, coordinator: TableViewCoordinator) -> NSTableRowView? { nil }