feat: add SQL favorites with keyword expansion and sidebar UI

Author: datlechin

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- SQL Favorites: save and organize frequently used queries with optional keyword bindings for autocomplete expansion
 - Copy selected rows as JSON from context menu and Edit menu
 - iCloud Sync (Pro): sync connections, groups, tags, settings, and query history across Macs via CloudKit
 - Pro feature gating system with license-aware UI overlay for Pro-only features

TablePro/Core/Autocomplete/CompletionEngine.swift

@@ -46,6 +46,11 @@ final class CompletionEngine {
 
     // MARK: - Public API
 
+    /// Update favorite keywords for autocomplete expansion
+    func updateFavoriteKeywords(_ keywords: [String: (name: String, query: String)]) {
+        provider.updateFavoriteKeywords(keywords)
+    }
+
     /// Get completions for the given text and cursor position
     /// This is a pure function - no side effects
     func getCompletions(

TablePro/Core/Autocomplete/SQLCompletionItem.swift

@@ -18,6 +18,7 @@ enum SQLCompletionKind: String, CaseIterable {
     case schema     // Database/schema names
     case alias      // Table aliases
     case `operator` // Operators (=, <>, LIKE, etc.)
+    case favorite   // Saved SQL favorite (keyword expansion)
 
     /// SF Symbol for display
     var iconName: String {
@@ -30,6 +31,7 @@ enum SQLCompletionKind: String, CaseIterable {
         case .schema: return "s.circle.fill"
         case .alias: return "a.circle.fill"
         case .operator: return "equal.circle.fill"
+        case .favorite: return "star.circle.fill"
         }
     }
 
@@ -44,12 +46,14 @@ enum SQLCompletionKind: String, CaseIterable {
         case .schema: return .systemGreen
         case .alias: return .systemGray
         case .operator: return .systemIndigo
+        case .favorite: return .systemYellow
         }
     }
 
     /// Base sort priority (lower = higher priority in same context)
     var basePriority: Int {
         switch self {
+        case .favorite: return 50
         case .column: return 100
         case .table: return 200
         case .view: return 210
@@ -259,4 +263,15 @@ extension SQLCompletionItem {
             documentation: documentation
         )
     }
+
+    /// Create a favorite keyword expansion item
+    static func favorite(keyword: String, name: String, query: String) -> SQLCompletionItem {
+        SQLCompletionItem(
+            label: keyword,
+            kind: .favorite,
+            insertText: query,
+            detail: name,
+            documentation: String(query.prefix(200))
+        )
+    }
 }

TablePro/Core/Autocomplete/SQLCompletionProvider.swift

@@ -17,6 +17,7 @@ final class SQLCompletionProvider {
     private var databaseType: DatabaseType?
     private var cachedDialect: SQLDialectDescriptor?
     private var cachedStatementCompletions: [CompletionEntry] = []
+    private var favoriteKeywords: [String: (name: String, query: String)] = [:]
 
     /// Minimum prefix length to trigger suggestions
     private let minPrefixLength = 1
@@ -41,6 +42,11 @@ final class SQLCompletionProvider {
         self.cachedStatementCompletions = statementCompletions
     }
 
+    /// Update cached favorite keywords for autocomplete expansion
+    func updateFavoriteKeywords(_ keywords: [String: (name: String, query: String)]) {
+        self.favoriteKeywords = keywords
+    }
+
     // MARK: - Public API
 
     /// Get completion suggestions for the current cursor position
@@ -81,6 +87,14 @@ final class SQLCompletionProvider {
     ) async -> [SQLCompletionItem] {
         var items: [SQLCompletionItem] = []
 
+        // Check for favorite keyword matches first (highest priority)
+        if !favoriteKeywords.isEmpty && !context.prefix.isEmpty {
+            let lowerPrefix = context.prefix.lowercased()
+            for (keyword, value) in favoriteKeywords where keyword.lowercased().hasPrefix(lowerPrefix) {
+                items.append(.favorite(keyword: keyword, name: value.name, query: value.query))
+            }
+        }
+
         // If we have a dot prefix, we're looking for columns of a specific table
         if let dotPrefix = context.dotPrefix {
             // Resolve the table name from alias or direct reference

TablePro/Core/Services/Infrastructure/AppNotifications.swift

@@ -18,4 +18,8 @@ extension Notification.Name {
 
     static let connectionUpdated = Notification.Name("connectionUpdated")
     static let databaseDidConnect = Notification.Name("databaseDidConnect")
+
+    // MARK: - SQL Favorites
+
+    static let sqlFavoritesDidUpdate = Notification.Name("sqlFavoritesDidUpdate")
 }

TablePro/Core/Storage/SQLFavoriteManager.swift

@@ -0,0 +1,116 @@
+//
+//  SQLFavoriteManager.swift
+//  TablePro
+//
+
+import Foundation
+import os
+
+/// Manages SQL favorites with notifications and sync tracking
+final class SQLFavoriteManager {
+    static let shared = SQLFavoriteManager()
+    private static let logger = Logger(subsystem: "com.TablePro", category: "SQLFavoriteManager")
+
+    private let storage: SQLFavoriteStorage
+
+    /// Creates an isolated manager with its own storage. For testing only.
+    init(isolatedStorage: SQLFavoriteStorage) {
+        self.storage = isolatedStorage
+    }
+
+    private init() {
+        self.storage = SQLFavoriteStorage.shared
+    }
+
+    // MARK: - Favorites
+
+    func addFavorite(_ favorite: SQLFavorite) async -> Bool {
+        let result = await storage.addFavorite(favorite)
+        if result {
+            SyncChangeTracker.shared.markDirty(.favorite, id: favorite.id.uuidString)
+            postUpdateNotification()
+        }
+        return result
+    }
+
+    func updateFavorite(_ favorite: SQLFavorite) async -> Bool {
+        let result = await storage.updateFavorite(favorite)
+        if result {
+            SyncChangeTracker.shared.markDirty(.favorite, id: favorite.id.uuidString)
+            postUpdateNotification()
+        }
+        return result
+    }
+
+    func deleteFavorite(id: UUID) async -> Bool {
+        let result = await storage.deleteFavorite(id: id)
+        if result {
+            SyncChangeTracker.shared.markDeleted(.favorite, id: id.uuidString)
+            postUpdateNotification()
+        }
+        return result
+    }
+
+    func fetchFavorites(
+        connectionId: UUID? = nil,
+        folderId: UUID? = nil,
+        searchText: String? = nil
+    ) async -> [SQLFavorite] {
+        await storage.fetchFavorites(connectionId: connectionId, folderId: folderId, searchText: searchText)
+    }
+
+    // MARK: - Folders
+
+    func addFolder(_ folder: SQLFavoriteFolder) async -> Bool {
+        let result = await storage.addFolder(folder)
+        if result {
+            SyncChangeTracker.shared.markDirty(.favoriteFolder, id: folder.id.uuidString)
+            postUpdateNotification()
+        }
+        return result
+    }
+
+    func updateFolder(_ folder: SQLFavoriteFolder) async -> Bool {
+        let result = await storage.updateFolder(folder)
+        if result {
+            SyncChangeTracker.shared.markDirty(.favoriteFolder, id: folder.id.uuidString)
+            postUpdateNotification()
+        }
+        return result
+    }
+
+    func deleteFolder(id: UUID) async -> Bool {
+        let result = await storage.deleteFolder(id: id)
+        if result {
+            SyncChangeTracker.shared.markDeleted(.favoriteFolder, id: id.uuidString)
+            postUpdateNotification()
+        }
+        return result
+    }
+
+    func fetchFolders(connectionId: UUID? = nil) async -> [SQLFavoriteFolder] {
+        await storage.fetchFolders(connectionId: connectionId)
+    }
+
+    // MARK: - Keyword Support
+
+    func fetchKeywordMap(connectionId: UUID? = nil) async -> [String: (name: String, query: String)] {
+        await storage.fetchKeywordMap(connectionId: connectionId)
+    }
+
+    func isKeywordAvailable(
+        _ keyword: String,
+        connectionId: UUID?,
+        excludingFavoriteId: UUID? = nil
+    ) async -> Bool {
+        await storage.isKeywordAvailable(keyword, connectionId: connectionId, excludingFavoriteId: excludingFavoriteId)
+    }
+
+    // MARK: - Notifications
+
+    private func postUpdateNotification() {
+        DispatchQueue.main.async {
+            NotificationCenter.default.post(name: .sqlFavoritesDidUpdate, object: nil)
+        }
+    }
+}