Bruno Charest
ee3085ce38
- Integrated Unsplash API for image search functionality with environment configuration - Added new Nimbus Editor page component with navigation from sidebar and mobile drawer - Enhanced TOC with highlight animation for editor heading navigation - Improved CDK overlay z-index hierarchy for proper menu layering - Removed obsolete logging validation script
351 lines
9.2 KiB
Markdown
351 lines
9.2 KiB
Markdown
# 🧠 Éditeur Nimbus - Documentation Complète
|
|
|
|
## Vue d'ensemble
|
|
|
|
L'**Éditeur Nimbus** est un éditeur de texte avancé à blocs, inspiré de Fusebase/Nimbus, intégré dans ObsiViewer. Il offre une expérience d'édition moderne et puissante avec support de 15+ types de blocs différents.
|
|
|
|
## 📍 Accès
|
|
|
|
- **URL**: `/tests/nimbus-editor`
|
|
- **Section**: Tests
|
|
- **Menu**: Section Tests → Éditeur Nimbus
|
|
|
|
## 🎯 Fonctionnalités Principales
|
|
|
|
### Types de Blocs Supportés
|
|
|
|
#### BASIC
|
|
- **Paragraph** - Texte simple
|
|
- **Heading 1/2/3** - Titres de section
|
|
- **Bullet List** - Liste à puces
|
|
- **Numbered List** - Liste numérotée
|
|
- **Checkbox List** - Liste de tâches
|
|
- **Toggle** - Contenu repliable
|
|
- **Table** - Tableau de données
|
|
- **Code** - Code avec coloration syntaxique
|
|
- **Quote** - Citation
|
|
- **Line** - Séparateur horizontal
|
|
- **File** - Pièce jointe
|
|
|
|
#### ADVANCED
|
|
- **Steps** - Étapes numérotées
|
|
- **Kanban Board** - Tableau Kanban
|
|
- **Hint** - Boîte de conseil (info/warning/success/note)
|
|
- **Progress** - Barre de progression
|
|
- **Dropdown** - Liste déroulante
|
|
- **Button** - Bouton interactif
|
|
- **Outline** - Table des matières automatique
|
|
|
|
#### MEDIA
|
|
- **Image** - Insertion d'images
|
|
- **Embed** - Intégration de contenu externe (YouTube, Google Drive, Maps)
|
|
|
|
## ⌨️ Raccourcis Clavier
|
|
|
|
### Commandes Générales
|
|
- `/` - Ouvrir la palette de commandes
|
|
- `Ctrl+/` - Ouvrir la palette de commandes
|
|
- `Escape` - Fermer un menu/overlay
|
|
- `Ctrl+S` - Sauvegarder (automatique)
|
|
|
|
### Titres
|
|
- `Ctrl+Alt+1` - Insérer Heading 1
|
|
- `Ctrl+Alt+2` - Insérer Heading 2
|
|
- `Ctrl+Alt+3` - Insérer Heading 3
|
|
|
|
### Listes
|
|
- `Ctrl+Shift+8` - Liste à puces
|
|
- `Ctrl+Shift+7` - Liste numérotée
|
|
- `Ctrl+Shift+C` - Liste de tâches
|
|
|
|
### Blocs
|
|
- `Ctrl+Alt+6` - Toggle block
|
|
- `Ctrl+Alt+C` - Code block
|
|
- `Ctrl+Alt+Y` - Quote
|
|
- `Ctrl+Alt+U` - Hint
|
|
- `Ctrl+Alt+5` - Button
|
|
|
|
### Formatage Texte
|
|
- `Ctrl+B` - Gras
|
|
- `Ctrl+I` - Italique
|
|
- `Ctrl+U` - Souligné
|
|
- `Ctrl+K` - Insérer lien
|
|
|
|
### Opérations sur Blocs
|
|
- `Ctrl+Backspace` - Supprimer bloc
|
|
- `Alt+↑` - Déplacer bloc vers le haut
|
|
- `Alt+↓` - Déplacer bloc vers le bas
|
|
- `Ctrl+D` - Dupliquer bloc
|
|
- `Tab` - Indenter (dans une liste)
|
|
- `Shift+Tab` - Dés-indenter (dans une liste)
|
|
|
|
## 🎨 Interface Utilisateur
|
|
|
|
### Topbar (Barre Supérieure)
|
|
- **Titre**: Éditeur Nimbus avec icône 🧠
|
|
- **Bouton Export**: Dropdown avec 3 formats
|
|
- 📄 Markdown (.md)
|
|
- 🌐 HTML (.html)
|
|
- 📦 JSON (.json)
|
|
- **Bouton Clear**: Effacer le document
|
|
|
|
### Zone d'Édition
|
|
- **Titre du document**: Éditable, taille XL
|
|
- **Compteur de blocs**: Affichage du nombre de blocs
|
|
- **Indicateur de sauvegarde**: ✓ Saved / ⋯ Saving / ✗ Error
|
|
- **Liste de blocs**: Affichage vertical des blocs
|
|
- **Bouton "Add block"**: Ouvrir la palette
|
|
|
|
### Footer
|
|
- Informations de navigation
|
|
- Raccourcis clavier principaux
|
|
|
|
### Palette "/" (Slash Menu)
|
|
- **Position**: Centrée à 30% du haut
|
|
- **Taille**: 560px de largeur
|
|
- **Recherche**: Temps réel avec filtrage
|
|
- **Navigation**: Flèches ↑/↓, Enter pour sélectionner
|
|
- **Catégories**: BASIC, ADVANCED, MEDIA, INTEGRATIONS
|
|
- **Aperçu**: Description + raccourci pour chaque item
|
|
|
|
## 💾 Persistance
|
|
|
|
### Auto-Save
|
|
- **Debounce**: 750ms
|
|
- **Stockage**: localStorage
|
|
- **Clé**: `nimbus-editor-doc`
|
|
- **Format**: JSON complet du document
|
|
|
|
### Chargement
|
|
- Au démarrage, l'éditeur tente de charger depuis localStorage
|
|
- Si aucune donnée, crée un nouveau document vide
|
|
- Bouton "Clear" pour effacer et recommencer
|
|
|
|
## 📤 Exportation
|
|
|
|
### Markdown (.md)
|
|
- Titres: `# ## ###`
|
|
- Listes: `- ` ou `1. ` ou `- [ ]`
|
|
- Code: triple backticks avec langage
|
|
- Quote: `> `
|
|
- Line: `---`
|
|
|
|
### HTML (.html)
|
|
- Document complet avec `<html><head><body>`
|
|
- Styles CSS intégrés
|
|
- Balises sémantiques (<p>, <h1>, <ul>, <pre>)
|
|
- Encodage HTML automatique
|
|
|
|
### JSON (.json)
|
|
- Sérialisation exacte du DocumentModel
|
|
- Structure complète avec métadonnées
|
|
- Indentation: 2 espaces
|
|
- Rechargeable dans l'éditeur
|
|
|
|
## 🏗️ Architecture Technique
|
|
|
|
### Structure de Dossiers
|
|
```
|
|
src/app/editor/
|
|
├── core/
|
|
│ ├── models/ # Block, Document models
|
|
│ ├── utils/ # ID generator
|
|
│ └── constants/ # Palette items, keyboard shortcuts
|
|
├── services/
|
|
│ ├── document.service.ts
|
|
│ ├── selection.service.ts
|
|
│ ├── palette.service.ts
|
|
│ ├── shortcuts.service.ts
|
|
│ └── export/
|
|
│ └── export.service.ts
|
|
├── components/
|
|
│ ├── editor-shell/
|
|
│ ├── block/
|
|
│ │ ├── block-host.component.ts
|
|
│ │ └── blocks/ # 18 block components
|
|
│ └── palette/
|
|
│ └── slash-palette.component.ts
|
|
└── features/tests/nimbus-editor/
|
|
└── nimbus-editor-page.component.ts
|
|
```
|
|
|
|
### Services Principaux
|
|
|
|
#### DocumentService
|
|
- Gestion de l'état du document (Angular Signals)
|
|
- CRUD sur les blocs (insert, update, delete, move, duplicate)
|
|
- Conversion entre types de blocs
|
|
- Génération automatique de l'outline
|
|
- Auto-save avec debounce
|
|
|
|
#### SelectionService
|
|
- Gestion du bloc actif
|
|
- Signal readonly pour éviter mutations externes
|
|
|
|
#### PaletteService
|
|
- État de la palette (ouvert/fermé)
|
|
- Recherche et filtrage des items
|
|
- Navigation clavier (↑/↓)
|
|
- Position dynamique
|
|
|
|
#### ShortcutsService
|
|
- Détection et exécution des raccourcis clavier
|
|
- Intégration avec DocumentService et PaletteService
|
|
- Prévention des conflits
|
|
|
|
#### ExportService
|
|
- Export vers Markdown, HTML, JSON
|
|
- Téléchargement automatique des fichiers
|
|
- Sanitization HTML
|
|
|
|
### Composants
|
|
|
|
#### EditorShellComponent
|
|
- Conteneur principal de l'éditeur
|
|
- Header avec titre éditable
|
|
- Zone de blocs avec BlockHost
|
|
- Gestion des événements clavier globaux
|
|
|
|
#### BlockHostComponent
|
|
- Router vers le composant de bloc approprié
|
|
- Gestion de la sélection
|
|
- Drag handle pour déplacement (visuel)
|
|
- Menu contextuel (clic droit)
|
|
|
|
#### SlashPaletteComponent
|
|
- Overlay modal avec recherche
|
|
- Liste filtrée des blocs disponibles
|
|
- Navigation clavier complète
|
|
- Fermeture sur clic extérieur ou ESC
|
|
|
|
#### Block Components (18 composants)
|
|
- Un composant par type de bloc
|
|
- Input: Block<Props>
|
|
- Output: Update événement
|
|
- Contenteditable pour édition inline
|
|
- Styles Tailwind intégrés
|
|
|
|
## 🧪 Tests & Validation
|
|
|
|
### Tests Manuels Recommandés
|
|
|
|
1. **Création de blocs**
|
|
- Tester tous les types via palette "/"
|
|
- Vérifier l'insertion correcte
|
|
|
|
2. **Édition**
|
|
- Modifier texte dans paragraph/heading
|
|
- Ajouter items dans listes
|
|
- Éditer code avec sélection de langage
|
|
|
|
3. **Conversion**
|
|
- Paragraph → Heading
|
|
- Bullet list → Checkbox list
|
|
- Quote → Paragraph
|
|
|
|
4. **Raccourcis**
|
|
- Ctrl+Alt+1/2/3 pour headings
|
|
- Ctrl+Shift+8/7/C pour listes
|
|
- Alt+↑/↓ pour déplacer blocs
|
|
|
|
5. **Exportation**
|
|
- Exporter en Markdown, vérifier formatage
|
|
- Exporter en HTML, ouvrir dans navigateur
|
|
- Exporter en JSON, réimporter
|
|
|
|
6. **Persistance**
|
|
- Créer document, recharger page
|
|
- Vérifier que le contenu est restauré
|
|
- Clear et vérifier nouveau document vide
|
|
|
|
### Points d'Attention
|
|
|
|
- **Performance**: Avec 100+ blocs, vérifier pas de lag
|
|
- **Mémoire**: Auto-save ne doit pas accumuler
|
|
- **Sécurité**: HTML sanitizé lors export
|
|
- **A11y**: Focus management, aria-labels
|
|
|
|
## 🚀 Déploiement
|
|
|
|
### Prérequis
|
|
- Angular 20+
|
|
- Tailwind CSS 3.4+
|
|
- Angular CDK (pour Drag & Drop Kanban)
|
|
|
|
### Installation
|
|
Toutes les dépendances sont déjà incluses dans le projet ObsiViewer.
|
|
|
|
### Accès en Production
|
|
Une fois déployé, accessible via:
|
|
```
|
|
https://votre-domaine.com/tests/nimbus-editor
|
|
```
|
|
|
|
## 🔮 Roadmap & Améliorations Futures
|
|
|
|
### MVP Actuel ✅
|
|
- 15+ types de blocs
|
|
- Palette "/"
|
|
- Raccourcis clavier
|
|
- Auto-save localStorage
|
|
- Export MD/HTML/JSON
|
|
|
|
### Améliorations Potentielles
|
|
- [ ] Menu "@" pour mentions (dates, people, folders)
|
|
- [ ] Context menu (clic droit) sur blocs
|
|
- [ ] PDF export côté serveur (Puppeteer)
|
|
- [ ] DOCX export (lib docx)
|
|
- [ ] Collaboration temps réel (WebSocket)
|
|
- [ ] Historique undo/redo (stack)
|
|
- [ ] Templates de documents
|
|
- [ ] Thèmes d'éditeur personnalisables
|
|
- [ ] Upload d'images drag & drop
|
|
- [ ] Embed enrichi (Unsplash, etc.)
|
|
|
|
## 📚 Ressources
|
|
|
|
### Documentation Technique
|
|
- Spécification complète dans le prompt initial
|
|
- Code commenté dans chaque fichier
|
|
|
|
### Références
|
|
- Fusebase: https://fusebase.com
|
|
- Nimbus Note: https://nimbusweb.me
|
|
- Notion API: https://developers.notion.com
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Document ne se sauvegarde pas
|
|
- Vérifier console pour erreurs localStorage
|
|
- Quota localStorage peut être atteint (5-10MB)
|
|
- Clear localStorage et recommencer
|
|
|
|
### Palette "/" ne s'ouvre pas
|
|
- Vérifier que le focus est dans l'éditeur
|
|
- Essayer Ctrl+/ au lieu de /
|
|
- Recharger la page
|
|
|
|
### Export ne fonctionne pas
|
|
- Vérifier que le document n'est pas vide
|
|
- Vérifier console pour erreurs
|
|
- Essayer un format différent (JSON toujours fonctionne)
|
|
|
|
### Blocs ne s'affichent pas correctement
|
|
- Vérifier classes Tailwind chargées
|
|
- Recharger page
|
|
- Clear cache navigateur
|
|
|
|
## 📞 Support
|
|
|
|
Pour tout problème ou suggestion d'amélioration:
|
|
1. Ouvrir une issue sur GitHub
|
|
2. Contacter l'équipe ObsiViewer
|
|
3. Consulter la documentation technique dans `/docs`
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Date**: 2025-01-04
|
|
**Auteurs**: ObsiViewer Team
|
|
**License**: Selon projet ObsiViewer
|