diff --git a/QUICK_TEST_GUIDE.md b/QUICK_TEST_GUIDE.md new file mode 100644 index 0000000..97d8283 --- /dev/null +++ b/QUICK_TEST_GUIDE.md @@ -0,0 +1,321 @@ +# 🧪 Guide de Test Rapide - Système de Théming + +## Démarrage rapide + +```bash +# 1. Installer les dépendances (si nécessaire) +npm install + +# 2. Lancer l'application en mode dev +npm run dev + +# 3. Ouvrir dans le navigateur +# http://localhost:4200 +``` + +## Test manuel des thèmes + +### Accéder aux paramètres + +1. Ouvrir l'application +2. Naviguer vers **Parameters** / **Paramètres** +3. Section **Apparence** / **Appearance** + +### Tester les modes + +**Mode System** : +- Sélectionner "System" +- Changer le mode de votre OS (light/dark) +- L'application doit suivre automatiquement + +**Mode Light** : +- Sélectionner "Light" +- Toute l'interface doit être en mode clair + +**Mode Dark** : +- Sélectionner "Dark" +- Toute l'interface doit être en mode sombre + +### Tester les thèmes + +Pour chaque thème, vérifier en mode Light ET Dark (si applicable) : + +#### 1. **Light** (thème par défaut clair) +- Mode : Light uniquement +- Palette : Blanc, gris, bleus + +#### 2. **Dark** (thème par défaut sombre) +- Mode : Dark uniquement +- Palette : Bleu-gris foncé, texte clair + +#### 3. **Obsidian** +- Mode Light : Beige chaud, texte anthracite +- Mode Dark : Gris très foncé, accents beiges + +#### 4. **Nord** +- Mode Light : Blanc neigeux, palette nordique pastel +- Mode Dark : Bleu-gris arctique, palette nordique + +#### 5. **Notion** +- Mode Light : Blanc pur, minimaliste +- Mode Dark : Noir profond, contraste élevé + +#### 6. **GitHub** +- Mode Light : Style GitHub classique +- Mode Dark : GitHub Dimmed Dark + +#### 7. **Discord** +- Mode Light : Gris très clair, violet Discord +- Mode Dark : Gris Discord, violet Discord + +#### 8. **Monokai** +- Mode Light : Crème, accents atténués +- Mode Dark : Vert-gris foncé, palette Monokai + +## Checklist de vérification + +Pour chaque combinaison thème/mode, vérifier : + +### 🏠 Page d'accueil / Liste + +- [ ] **Sidebar gauche** + - Fond cohérent + - Items hover visibles + - Item actif distinct + - Badges de compteurs lisibles + - Séparateurs visibles + +- [ ] **Topbar** + - Fond cohérent + - Barre de recherche lisible + - Placeholder visible + - Focus ring visible + - Icônes visibles + +- [ ] **Liste des notes** + - Items lisibles + - Hover distinct + - Selected visible + - Path muted lisible + - Séparateurs visibles + +### 📄 Page de détail + +- [ ] **Contenu markdown** + - Titres (H1-H6) lisibles + - Paragraphes lisibles + - Liens visibles et hover + - Listes (ul, ol) lisibles + - Blockquotes distincts + - Code inline lisible + - Code blocks (fences) lisibles + - Tables lisibles (headers, zebra) + - HR visibles + +- [ ] **Panneaux latéraux** + - TOC lisible + - Propriétés lisibles + - Tags lisibles et hover + +### ✏️ Mode édition + +- [ ] **Éditeur** + - Fond CodeMirror cohérent + - Texte lisible + - Sélection visible + - Gutters lisibles + - Cursor visible + - Coloration syntaxique cohérente + +- [ ] **Toolbar** + - Boutons lisibles + - Hover visible + - Active visible + +### 🎨 Composants UI + +- [ ] **Modales** + - Fond cohérent + - Overlay visible + - Bordures visibles + - Boutons lisibles + +- [ ] **Menus contextuels** + - Fond cohérent + - Items hover visibles + - Séparateurs visibles + +- [ ] **Toasts** + - Fond cohérent + - Texte lisible + - Bordure visible + - Barre de progression visible + +- [ ] **Chips/Tags** + - Fond cohérent + - Texte lisible + - Hover visible + - Selected distinct + +- [ ] **Inputs** + - Fond cohérent + - Texte lisible + - Placeholder visible + - Focus ring visible + - Border visible + +- [ ] **Buttons** + - Fond cohérent + - Texte lisible + - Hover visible + - Active visible + - Disabled visible + +### 📱 Mobile + +- [ ] **Bottom navigation** + - Fond cohérent + - Icônes visibles + - Active visible + +- [ ] **Drawers/Sheets** + - Fond cohérent + - Overlay visible + +### 🎯 Graphes (si applicable) + +- [ ] **Graph view** + - Nœuds visibles + - Liens visibles + - Labels lisibles + - Légende lisible + +## Tests de contraste + +### Outils recommandés + +1. **Chrome DevTools** + - F12 → Lighthouse → Accessibility + - Vérifier les contrastes automatiquement + +2. **WebAIM Contrast Checker** + - https://webaim.org/resources/contrastchecker/ + - Tester manuellement les combinaisons critiques + +### Combinaisons à tester + +Pour chaque thème : +- [ ] Texte principal / Fond principal (ratio ≥ 4.5:1) +- [ ] Texte muted / Fond principal (ratio ≥ 4.5:1) +- [ ] Liens / Fond principal (ratio ≥ 4.5:1) +- [ ] Boutons / Fond bouton (ratio ≥ 4.5:1) + +## Tests de persistance + +1. **Sélectionner un thème** (ex: Obsidian Dark) +2. **Recharger la page** (F5) + - ✅ Le thème doit être conservé + - ✅ Pas de flash de contenu (anti-FOUC) + +3. **Fermer et rouvrir le navigateur** + - ✅ Le thème doit être conservé + +4. **Tester en navigation privée** + - ✅ Thème par défaut (Light) + - ✅ Changement de thème fonctionne + - ⚠️ Non persisté après fermeture (comportement attendu) + +## Tests de réactivité + +1. **Ouvrir la page Parameters** +2. **Changer le mode** (Light → Dark) + - ✅ Changement immédiat sur toute la page + - ✅ Pas de rechargement nécessaire + +3. **Changer le thème** (Obsidian → Nord) + - ✅ Changement immédiat sur toute la page + - ✅ Pas de rechargement nécessaire + +4. **Ouvrir plusieurs onglets** + - ✅ Changement dans un onglet se reflète dans les autres (après focus) + +## Debugging + +### Vérifier le thème actif + +Ouvrir la console (F12) et taper : + +```javascript +// Vérifier la classe dark +document.documentElement.classList.contains('dark') + +// Vérifier le thème +document.documentElement.getAttribute('data-theme') + +// Vérifier les préférences stockées +JSON.parse(localStorage.getItem('obsiviewer.preferences.v1')) +``` + +### Forcer un thème manuellement + +```javascript +// Forcer dark mode +document.documentElement.classList.add('dark') + +// Forcer un thème +document.documentElement.setAttribute('data-theme', 'nord') + +// Recharger pour restaurer les préférences +location.reload() +``` + +### Inspecter les tokens CSS + +```javascript +// Obtenir la valeur d'un token +getComputedStyle(document.documentElement).getPropertyValue('--bg-main') + +// Lister tous les tokens +Array.from(document.styleSheets) + .flatMap(sheet => Array.from(sheet.cssRules)) + .filter(rule => rule.style?.getPropertyValue('--bg')) +``` + +## Rapport de bugs + +Si vous trouvez un problème : + +1. **Capturer** : + - Screenshot du problème + - Thème actif (nom + mode) + - Navigateur + version + - Résolution d'écran + +2. **Reproduire** : + - Étapes pour reproduire + - Comportement attendu + - Comportement observé + +3. **Vérifier** : + - Console (erreurs JS ?) + - Network (ressources manquantes ?) + - Computed styles (tokens appliqués ?) + +## Checklist finale + +Avant de valider le système de théming : + +- [ ] Les 14 combinaisons sont testées +- [ ] Tous les composants UI sont cohérents +- [ ] Les contrastes respectent WCAG AA +- [ ] La persistance fonctionne +- [ ] Pas de flash au chargement (anti-FOUC) +- [ ] Les transitions sont fluides +- [ ] Le mode System fonctionne +- [ ] Mobile est testé +- [ ] Aucune couleur hardcodée visible +- [ ] Documentation à jour + +--- + +**Bon test ! 🎨** diff --git a/THEMING_STATUS.md b/THEMING_STATUS.md new file mode 100644 index 0000000..0eab650 --- /dev/null +++ b/THEMING_STATUS.md @@ -0,0 +1,233 @@ +# 🎨 État du Système de Théming - ObsiViewer + +**Date** : 20 octobre 2025 +**Statut** : 🟢 Infrastructure complète - Refactoring en cours + +--- + +## ✅ Complété + +### 1. Architecture de base (100%) + +- ✅ **themes.css** : 14 variantes (7 thèmes × 2 modes) avec tokens CSS complets + - Light, Dark, Obsidian, Nord, Notion, GitHub, Discord, Monokai + - Chaque thème a une version light ET dark + - Tokens : backgrounds, text, borders, brand, status, UI, editor, shadows + +- ✅ **tailwind.config.js** : Configuration complète + - Mapping de tous les tokens CSS vers classes Tailwind + - 40+ tokens mappés (bg, fg, surface1/2, primary, accent, etc.) + - Support des variantes (hover, focus, dark) + +- ✅ **ThemeService** : Service Angular fonctionnel + - Gestion mode (system/light/dark) + thème + - Persistance localStorage + - Observable pour réactivité + - Application sur `` (classe `.dark` + `data-theme`) + +- ✅ **codemirror-themes.ts** : 14 variantes CodeMirror 6 + - Fonction `cm6ThemeFor(themeId, mode)` complète + - Chaque thème a sa palette de coloration syntaxique + - Cohérence avec les tokens CSS + +- ✅ **Anti-FOUC** : Script inline dans `index.html` + - Lecture des préférences avant Angular + - Application immédiate du thème + - Pas de flash de contenu non stylé + +### 2. Refactoring automatisé (68%) + +- ✅ **Script `refactor-colors.mjs`** créé +- ✅ **66 fichiers** mis à jour automatiquement +- ✅ **232 occurrences** de couleurs hardcodées remplacées + - `bg-slate-*` → `bg-surface1/2` + - `text-gray-*` → `text-main/muted` + - `border-slate-*` → `border-border` + - Variantes dark:, hover:, focus: gérées + +### 3. Documentation + +- ✅ **THEMING_IMPLEMENTATION.md** : Documentation technique complète +- ✅ **THEMING_STATUS.md** : Ce fichier (état du projet) + +--- + +## 🔄 En cours + +### Refactoring manuel (109 occurrences restantes) + +**Fichiers prioritaires** (14+ matches) : +1. `app-sidebar-drawer.component.ts` (14 matches) +2. `graph-options-panel.component.ts` (11 matches) +3. `app-shell-nimbus.component.ts` (9 matches) + +**Fichiers moyens** (4-8 matches) : +- `quick-links.component.ts` (8) +- `nimbus-sidebar.component.ts` (8) +- `markdown-playground.component.ts` (6) +- `add-bookmark-modal.component.html` (6) +- `search-query-assistant.component.ts` (5) +- `filters-section.component.ts` (4) + +**Fichiers mineurs** (1-3 matches) : +- 23 fichiers avec 1-3 occurrences chacun + +**Types de cas restants** : +- Styles conditionnels complexes +- Classes dynamiques avec logique métier +- Variantes rares (active:, disabled:, group-hover:) +- Couleurs dans des contextes spécifiques (graphes, visualisations) + +--- + +## ⏳ À faire + +### 1. Refactoring manuel (Priorité : Haute) + +**Approche recommandée** : +1. Traiter les 3 fichiers prioritaires (34 matches) +2. Traiter les 7 fichiers moyens (47 matches) +3. Traiter les 23 fichiers mineurs (28 matches) + +**Commande pour identifier** : +```bash +grep -rn "bg-slate-\|bg-gray-\|text-slate-\|text-gray-" src/ | wc -l +``` + +### 2. Tests de la matrice complète (Priorité : Haute) + +**14 combinaisons à tester** : + +| Thème | Light | Dark | +|-----------|-------|------| +| Light | ✅ | N/A | +| Dark | N/A | ✅ | +| Obsidian | ⏳ | ⏳ | +| Nord | ⏳ | ⏳ | +| Notion | ⏳ | ⏳ | +| GitHub | ⏳ | ⏳ | +| Discord | ⏳ | ⏳ | +| Monokai | ⏳ | ⏳ | + +**Checklist par combinaison** : +- [ ] Sidebar (fond, hover, actif, badges) +- [ ] Topbar + search (input, focus, placeholder) +- [ ] Liste notes (items, hover, selected) +- [ ] Page détail (titres, liens, code, tables) +- [ ] Mode édition (inputs, buttons, CodeMirror) +- [ ] Panneaux (TOC, propriétés, tags) +- [ ] Modales (fond, overlay, bordure) +- [ ] Menus contextuels +- [ ] Toasts +- [ ] Tables (headers, zebra, hover) +- [ ] Chips/Tags (fond, hover, selected) +- [ ] Scrollbars +- [ ] Page Parameters +- [ ] Mobile (bottom nav, drawers) + +### 3. Validation contrastes (Priorité : Moyenne) + +**Outils** : +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) +- Chrome DevTools (Lighthouse) + +**Critères WCAG AA** : +- Texte normal : ratio ≥ 4.5:1 +- Texte large : ratio ≥ 3:1 +- Éléments UI : ratio ≥ 3:1 + +**À vérifier pour chaque thème** : +- [ ] Texte principal / fond +- [ ] Texte muted / fond +- [ ] Liens / fond +- [ ] Boutons / fond +- [ ] Bordures / fond + +### 4. Vérification finale (Priorité : Basse) + +- [ ] Aucune couleur hardcodée restante (grep complet) +- [ ] Tous les composants utilisent les tokens +- [ ] Documentation à jour +- [ ] Screenshots comparatifs (avant/après) +- [ ] Guide utilisateur pour la page Parameters + +--- + +## 📊 Métriques + +### Progression globale + +``` +Infrastructure : ████████████████████ 100% (5/5) +Refactoring : █████████████░░░░░░░ 68% (232/341) +Tests : ░░░░░░░░░░░░░░░░░░░░ 0% (0/14) +Documentation : ████████████████████ 100% (2/2) +--- +TOTAL : ████████████░░░░░░░░ 67% +``` + +### Détails refactoring + +| Catégorie | Avant | Après | Restant | +|--------------------|-------|-------|---------| +| Couleurs hardcodées| 341 | 109 | 109 | +| Fichiers touchés | 0 | 66 | ~32 | +| Tokens créés | 0 | 40+ | - | +| Thèmes complets | 2 | 14 | - | + +--- + +## 🚀 Commandes rapides + +```bash +# Refactoring automatique (réexécuter si besoin) +node scripts/refactor-colors.mjs + +# Rechercher couleurs hardcodées +grep -rn "bg-slate-\|bg-gray-\|text-slate-\|text-gray-" src/ + +# Lancer l'application +npm run dev + +# Tests E2E +npm run test:e2e + +# Build production +npm run build +``` + +--- + +## 🎯 Objectif final + +**Application entièrement thémable** : +- ✅ 7 thèmes × 2 modes = 14 combinaisons +- ✅ Aucune couleur hardcodée +- ✅ Cohérence visuelle totale +- ✅ Accessibilité WCAG AA +- ✅ Performance optimale (CSS variables) +- ✅ Expérience utilisateur fluide (anti-FOUC) + +--- + +## 📝 Notes + +### Points d'attention + +1. **CodeMirror 6** : Les thèmes sont appliqués dynamiquement via `ThemeService.getCodeMirrorExtensions()` +2. **Persistance** : Clé localStorage `obsiviewer.preferences.v1` +3. **Réactivité** : Tous les composants doivent s'abonner à `ThemeService.onPrefs$` si nécessaire +4. **Mobile** : Vérifier les overlays et bottom sheets dans chaque thème +5. **Graphes** : Les visualisations D3/Canvas peuvent nécessiter un traitement spécial + +### Améliorations futures + +- [ ] Thème personnalisé (éditeur de couleurs) +- [ ] Import/export de thèmes +- [ ] Prévisualisation live dans Parameters +- [ ] Thèmes communautaires +- [ ] Mode haute contraste dédié + +--- + +**Dernière mise à jour** : 20 octobre 2025, 17:05 UTC-04:00 diff --git a/angular.json b/angular.json index 8fb256d..ff35252 100644 --- a/angular.json +++ b/angular.json @@ -25,6 +25,7 @@ "node_modules/angular-calendar/css/angular-calendar.css", "src/styles/tokens.css", "src/styles/components.css", + "src/styles/syntax.css", "src/styles.css" ], "assets": [ diff --git a/docs/THEMING_IMPLEMENTATION.md b/docs/THEMING_IMPLEMENTATION.md new file mode 100644 index 0000000..b04b3cc --- /dev/null +++ b/docs/THEMING_IMPLEMENTATION.md @@ -0,0 +1,239 @@ +# Système de Théming ObsiViewer - Documentation + +## Vue d'ensemble + +Système de théming double dimension : **7 thèmes × 2 modes = 14 combinaisons** + +- **Modes** : Light, Dark +- **Thèmes** : Light (default), Dark (default), Obsidian, Nord, Notion, GitHub, Discord, Monokai + +## Architecture + +### 1. Tokens CSS (`src/styles/themes.css`) + +Tous les thèmes définissent un ensemble cohérent de tokens CSS : + +```css +/* Backgrounds */ +--bg, --bg-main, --bg-muted +--card, --card-bg, --elevated +--sidebar-bg, --surface-1, --surface-2 + +/* Text */ +--fg, --text-main, --text-muted, --muted + +/* Borders */ +--border + +/* Brand & Accents */ +--primary, --brand, --brand-700, --brand-800 +--secondary, --accent + +/* Status */ +--success, --warning, --danger, --info + +/* UI Elements */ +--chip-bg, --link, --link-hover, --ring + +/* Editor (CodeMirror 6) */ +--editor-bg, --editor-fg, --editor-selection +--editor-gutter-bg, --editor-gutter-fg, --editor-cursor + +/* Shadows */ +--shadow-color, --scrollbar-thumb +``` + +### 2. Configuration Tailwind (`tailwind.config.js`) + +Tous les tokens sont mappés dans Tailwind : + +```javascript +colors: { + bg: 'var(--bg)', + 'bg-main': 'var(--bg-main)', + fg: 'var(--fg)', + surface1: 'var(--surface-1)', + primary: 'var(--primary)', + // ... etc +} +``` + +### 3. ThemeService (`src/app/core/services/theme.service.ts`) + +Service central qui gère : +- Mode : `'system' | 'light' | 'dark'` +- Thème : `'light' | 'dark' | 'obsidian' | 'nord' | 'notion' | 'github' | 'discord' | 'monokai'` +- Application sur `` : classe `.dark` + attribut `data-theme` +- Persistance dans localStorage +- Observable `onPrefs$` pour réactivité + +### 4. CodeMirror 6 (`src/app/core/codemirror-themes.ts`) + +Fonction `cm6ThemeFor(themeId, mode)` qui retourne les extensions CM6 appropriées pour chaque combinaison thème/mode. + +### 5. Anti-FOUC (`index.html`) + +Script inline qui lit les préférences et applique le thème avant le chargement d'Angular : + +```javascript +(function () { + const prefs = JSON.parse(localStorage.getItem('obsiviewer.preferences.v1') || '{}'); + const isDark = prefs.mode === 'dark' || (prefs.mode === 'system' && prefersDark); + html.classList.toggle('dark', isDark); + html.setAttribute('data-theme', prefs.theme || 'light'); +})(); +``` + +## Matrice des Thèmes + +### Light (Default) +- **Light mode** : Blanc pur, texte gris foncé, accents bleus +- **Dark mode** : N/A (thème light uniquement) + +### Dark (Default) +- **Light mode** : N/A (thème dark uniquement) +- **Dark mode** : Fond bleu-gris foncé, texte clair, accents bleus clairs + +### Obsidian +- **Light mode** : Beige chaud (#fafaf8), texte anthracite, accents terre +- **Dark mode** : Gris très foncé (#1e1e1e), texte clair, accents beiges + +### Nord +- **Light mode** : Blanc neigeux (#eceff4), texte bleu-gris, palette nordique pastel +- **Dark mode** : Bleu-gris arctique (#2e3440), texte givré, palette nordique + +### Notion +- **Light mode** : Blanc pur, texte charbon, minimaliste +- **Dark mode** : Noir profond (#171717), texte ivoire, contraste élevé + +### GitHub +- **Light mode** : Blanc, texte GitHub (#24292f), palette GitHub +- **Dark mode** : Dimmed dark (#0d1117), palette GitHub dark + +### Discord +- **Light mode** : Gris très clair (#f6f7f9), texte foncé, violet Discord +- **Dark mode** : Gris Discord (#2b2d31), texte clair, violet Discord + +### Monokai +- **Light mode** : Crème (#fbfbf7), texte foncé, accents verts/oranges atténués +- **Dark mode** : Vert-gris foncé (#272822), texte clair, palette Monokai classique + +## Utilisation dans les Composants + +### Classes Tailwind recommandées + +```html + +
Carte
+
Surface niveau 1
+
Surface niveau 2
+ + +

Texte principal

+

Texte secondaire

+ + +
Bordure
+ + + + + +Lien +``` + +### ⚠️ À ÉVITER + +```html + +
...
+
...
+ + +
...
+``` + +## Tests + +### Checklist de validation + +Pour chaque combinaison (14 au total) : + +- [ ] **Sidebar** : Fond, hover, items actifs, badges +- [ ] **Topbar** : Barre de recherche, focus, placeholder +- [ ] **Liste des notes** : Items, hover, selected, path muted +- [ ] **Page détail** : Titres, liens, listes, blockquotes, code, tables +- [ ] **Mode édition** : Inputs, buttons, toolbars, CodeMirror +- [ ] **Panneaux** : TOC, propriétés, tags +- [ ] **Modales** : Fond, bordure, overlay +- [ ] **Menus contextuels** : Dropdown, tooltips +- [ ] **Toasts** : Fond, bordure, barre de progression +- [ ] **Tables** : Headers, zebra, hover +- [ ] **Chips/Tags** : Fond, texte, bordure, hover, selected +- [ ] **Scrollbars** : Thumb, track +- [ ] **Page Parameters** : Contrôles mode/thème +- [ ] **Mobile** : Bottom nav, sheets, drawers + +### Contraste + +Tous les thèmes doivent respecter WCAG AA : +- Texte normal : ratio ≥ 4.5:1 +- Texte large : ratio ≥ 3:1 + +## Refactoring effectué + +### Automatisé (script `refactor-colors.mjs`) + +- ✅ 66 fichiers mis à jour automatiquement +- ✅ Remplacement de 232+ occurrences de couleurs hardcodées +- ✅ Gestion des variantes : hover, focus, dark + +### Restant (109 occurrences) + +Cas complexes nécessitant révision manuelle : +- Composants avec logique conditionnelle +- Styles inline dynamiques +- Cas spécifiques métier + +## Commandes utiles + +```bash +# Lancer le refactoring automatique +node scripts/refactor-colors.mjs + +# Rechercher les couleurs hardcodées restantes +grep -r "bg-slate-\|bg-gray-\|text-slate-\|text-gray-" src/ + +# Lancer l'application en mode dev +npm run dev + +# Tests E2E +npm run test:e2e +``` + +## Prochaines étapes + +1. ✅ Créer themes.css avec 14 variantes +2. ✅ Configurer Tailwind +3. ✅ Mettre à jour codemirror-themes.ts +4. ✅ Refactoring automatisé (68% des couleurs) +5. 🔄 Refactoring manuel des 109 occurrences restantes +6. ⏳ Tests matrice complète +7. ⏳ Validation contrastes +8. ⏳ Documentation utilisateur + +## Notes techniques + +- **Persistance** : `localStorage` clé `obsiviewer.preferences.v1` +- **Réactivité** : Observable `ThemeService.onPrefs$` +- **SSR-safe** : Vérifications `typeof window !== 'undefined'` +- **Performance** : Transitions CSS 150ms +- **Accessibilité** : `color-scheme` CSS pour scrollbars natives + +## Ressources + +- [Tailwind CSS Variables](https://tailwindcss.com/docs/customizing-colors#using-css-variables) +- [CodeMirror 6 Theming](https://codemirror.net/docs/ref/#view.EditorView^theme) +- [WCAG Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) diff --git a/docs/ui-theming.md b/docs/ui-theming.md new file mode 100644 index 0000000..968ad35 --- /dev/null +++ b/docs/ui-theming.md @@ -0,0 +1,95 @@ +# UI Theming and CM6 Highlight + +## Theme Variables + +- **Global tokens** (in `src/styles.css`): + - `--color-accent` main accent color (per-theme override via `[data-theme]`). + - `--cm-hl-bg` computed background for inline highlights (theme dependent). + - `--cm-hl-br` border radius for highlights (default 3px). +- **Button tokens**: + - `--btn-radius`, `--btn-padding-y`, `--btn-padding-x`, `--btn-font`, `--btn-shadow`, `--btn-ring`, `--btn-speed`. + - `--btn-bg`, `--btn-fg`, `--btn-bg-hover`, `--btn-bg-active`, `--btn-outline`. + +### Defaults + +```css +:root { + --color-accent: #3b82f6; + --cm-hl-bg: color-mix(in srgb, var(--color-accent) 28%, transparent); + --cm-hl-br: 3px; +} +[data-theme="dark"], .dark { + --cm-hl-bg: color-mix(in srgb, var(--color-accent) 22%, transparent); +} +[data-theme="nimbus"] { --color-accent: #7c3aed; } +[data-theme="emerald"] { --color-accent: #10b981; } +``` + +## CodeMirror 6 Highlight Extensions + +Files in `src/app/shared/editor/extensions/`: +- `highlight-occurrences.extension.ts` – inline dynamic occurrences via regex. +- `ranged-highlights.extension.ts` – ranged highlights via `StateEffect`/`StateField`. +- `markdown-theme-highlight.extension.ts` – composes ranged + Markdown `HighlightStyle` and facet-driven CSS variable. + +### CSS class + +- `.cm-md-highlight { background: var(--cm-hl-bg); border-radius: var(--cm-hl-br, 3px); transition: background var(--btn-speed) ease; }` + +## Angular Integration + +Service: `EditorHighlightService` (`src/app/shared/editor/editor-highlight.service.ts`) + +- `extensions: Extension[]` – base markdown theme highlight extensions to add at editor creation. +- `occurrencesExtension(pattern)` – build occurrences extension. +- `applyOccurrences(view, compartment, pattern)` – reconfigure a `Compartment` with occurrences. +- `setRanges(view, ranges)` / `clearRanges(view)` – ranged highlights via effects. +- `facet()` – access the facet to optionally override `--cm-hl-bg` per-view. + +Example inside editor component: + +```ts +// compartments +occurrencesCompartment = new Compartment(); +highlightFacetCompartment = new Compartment(); + +// in EditorState.create extensions +...highlightService.extensions, +occurrencesCompartment.of([]), +highlightFacetCompartment.of([]), + +// API usage +highlightOccurrences("TODO"); +setHighlights([{ from: 10, to: 24 }]); +clearHighlights(); +// optional color override +view.dispatch({ effects: highlightFacetCompartment.reconfigure([ highlightService.facet().of('color-mix(in srgb, var(--color-accent) 40%, transparent)') ])}); +``` + +Live theme changes are applied by reconfiguring the theme compartment and calling `EditorView.requestMeasure(...)` to refresh decorations that rely on CSS variables. + +## Button Utilities + +Classes in `src/styles.css`: +- Base: `btn` +- Variants: `btn-solid`, `btn-outline`, `btn-ghost` +- Sizes: `btn-sm`, `btn-md`, `btn-lg` + +Example: + +```html + + + +``` + +## Accessibility + +- Buttons use focus ring via `--btn-outline`. +- Ensure icon-only buttons have `aria-label`. + +## Performance Notes + +- Occurrence highlights compute decorations only over visible ranges; cost is O(visibleText) per viewport update. +- Ranged highlights use a `StateField` and `tr.changes.mapPos` to keep ranges aligned after edits; updates are incremental. +- For large docs (≥5k lines), prefer ranged highlights for bulk operations; occurrences are fine for quick regex patterns like `TODO`. diff --git a/index.html b/index.html index 7cb6691..ea0bfe7 100644 --- a/index.html +++ b/index.html @@ -1,9 +1,33 @@ - + - ObsiWatcher - Obsidian Vault Viewer + ObsiViewer - Obsidian Vault Viewer +