From 34de2125eb452368a5d1456b4d8a375087bb1405 Mon Sep 17 00:00:00 2001 From: ZhuchkaTriplesix Date: Thu, 28 May 2026 11:31:04 +0300 Subject: [PATCH] docs(theme): add theme system guide and README link (#55) Document workbench vs editor architecture, VS Code import, overrides, tokenColors pipeline, and testing pointers. --- README.md | 1 + docs/roadmap.md | 5 ++ docs/theme.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 170 insertions(+) create mode 100644 docs/theme.md diff --git a/README.md b/README.md index f807d0a3..e8d34c75 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,7 @@ flutter build macos ## More documentation - [Security / local data](docs/security.md) +- [Theme system](docs/theme.md) - [User guide](docs/user-guide.md) - [Releases](docs/tags-and-releases.md) - [Release checklist](docs/release-checklist.md) diff --git a/docs/roadmap.md b/docs/roadmap.md index 46731e04..1f2a3973 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -2,6 +2,11 @@ Living document for planned work. Not a commitment order; adjust as priorities change. +## Theme system + +- **Done:** runtime themes, VS Code `colors` import, `tokenColors` syntax highlighting — see [theme.md](theme.md). +- **Later:** animated theme transitions ([#57](https://github.com/QueryaHub/Querya-Desktop/issues/57)), advanced editor (LSP / `code_forge` spike). + ## Query history and favorites - **Done:** `sql_query_history` in SQLite + record/list APIs; **History** in PostgreSQL / MySQL toolbars; **Preferences → Query history limit** ([`AppSettings.getSqlHistoryMaxEntries`](lib/core/storage/app_settings.dart)). diff --git a/docs/theme.md b/docs/theme.md new file mode 100644 index 00000000..f542f248 --- /dev/null +++ b/docs/theme.md @@ -0,0 +1,164 @@ +# Querya theme system + +Querya Desktop uses a VS Code–inspired theme pipeline: workbench chrome colors, +editor syntax tokens, and optional import of community `.json` / `.jsonc` themes. + +## Architecture + +```mermaid +flowchart TB + subgraph input [Input] + VSCode["VS Code theme file\n(colors + tokenColors)"] + Prefs["Preferences overrides"] + end + + subgraph parse [Parser] + JSONC["stripJsonc"] + Manifest["VsCodeThemeManifest"] + Map["vscode_color_map"] + Tokens["TokenStyleResolver"] + end + + subgraph models [Runtime models] + WB["QueryaWorkbenchTheme"] + ED["QueryaEditorTheme"] + QT["QueryaTheme"] + end + + subgraph ui [UI] + Scope["QueryaThemeScope"] + Shadcn["ShadcnApp ColorScheme"] + Editor["QueryaCodeEditor\nsyntax_highlight"] + end + + VSCode --> JSONC --> Manifest + Manifest --> Map --> WB + Manifest --> Map --> ED + Manifest --> Tokens --> ED + Prefs --> Map + WB --> QT + ED --> QT + QT --> Scope + QT --> Shadcn + QT --> Editor +``` + +| Layer | Purpose | +|-------|---------| +| **Workbench** | Sidebar, tabs, canvas, accents, git decoration | +| **Editor** | SQL/JSON editor surface, selection, line numbers, syntax token hues | +| **ColorScheme** | shadcn/Material widgets (buttons, inputs, dialogs) | + +`ThemeController` merges layers, persists settings in `AppSettings`, and drives +`QueryaApp` via `ListenableBuilder`. + +## Built-in presets + +- **Querya Dark** — default (`QueryaThemePreset.queryaDark`) +- **Querya Light** — light UI (`QueryaThemePreset.queryaLight`) +- **Imported** — after a VS Code file is imported (`QueryaThemePreset.imported`) + +Access tokens in widgets: + +```dart +final workbench = context.workbench; +final editor = context.editorTheme; +final scheme = Theme.of(context).colorScheme; +``` + +Requires `QueryaThemeScope` above the widget (provided by `QueryaApp`). + +## VS Code `colors` (workbench subset) + +Supported keys are listed in [theme-import.md](theme-import.md) and defined in +`lib/core/theme/parser/vscode_color_map.dart`. + +Merge order for the active theme: + +``` +effectiveColors = merge(importedTheme.colors, userOverrides) +``` + +Built-in preset values apply for keys not present in the merged map. + +### User override example + +Stored in `theme_overrides_json` as VS Code key → hex: + +```json +{ + "sideBar.background": "#1a1a2e", + "editor.background": "#16161e", + "focusBorder": "#89b4fa" +} +``` + +API: + +```dart +await ThemeController.instance.setWorkbenchColor('sideBar.background', color); +await ThemeController.instance.clearColorOverrides(); +``` + +## VS Code `tokenColors` (syntax highlighting) + +`tokenColors` entries map TextMate scopes to foreground/background/fontStyle. +`TokenStyleResolver` resolves scopes by longest prefix (`keyword.control.sql` → +`keyword.control` → `keyword`). + +Imported rules are: + +1. Persisted in the copied theme file under app data +2. Applied to `QueryaEditorTheme` token fields (comment, keyword, string, …) +3. Converted to `syntax_highlight` `HighlighterTheme` for `QueryaCodeEditor` + +Buffers ≥ 8KB are highlighted in a background isolate to keep typing responsive. + +## Importing a theme + +1. Open **Preferences → Appearance** +2. Choose **Theme mode** (Dark / Light / System) +3. Click **Import theme…** and select a VS Code `.json` or `.jsonc` file +4. Select the imported preset from **Color preset** + +The file must include a `colors` object (required for import). `tokenColors` are +optional but recommended for editor highlighting. + +See also: [theme-import.md](theme-import.md). + +## Adding a new workbench token + +1. Add a field to `QueryaWorkbenchTheme` (or reuse an existing one) +2. Map a VS Code key in `kVsCodeColorMap` / `kSupportedVsCodeColorKeys` +3. Handle the field in `_applyWorkbenchField` in `querya_theme_from_vscode.dart` +4. Migrate UI surfaces to `context.workbench.` instead of hardcoded colors +5. Add a fixture + unit test under `test/core/theme/` + +## Testing + +| Area | Location | +|------|----------| +| JSONC / manifest | `test/core/theme/parser/` | +| Color merge | `test/core/theme/parser/vscode_colors_merge_test.dart` | +| Fixtures | `test/fixtures/themes/` | +| ThemeController | `test/core/theme/theme_controller_test.dart` | +| Editor highlighting | `test/core/editor/` | + +Run: `flutter test test/core/theme/` + +## Roadmap (Phase 2+) + +| Topic | Status | +|-------|--------| +| Workbench `colors` import | Done | +| Preferences UI | Done | +| SQL/JSON syntax highlighting | Done | +| `tokenColors` → highlighter | Done | +| Theme transition animation | [#57](https://github.com/QueryaHub/Querya-Desktop/issues/57) | +| `code_forge` / LSP editor | [#52](https://github.com/QueryaHub/Querya-Desktop/issues/52) | + +## Related docs + +- [theme-import.md](theme-import.md) — supported `colors` keys and merge behavior +- [research_theme.md](research_theme.md) — background research (RU) +- [editor-spike-report.md](editor-spike-report.md) — code editor package evaluation