Projets/ObsiViewer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ObsiViewer/docs/NIMBUS_EDITOR_README.md
Bruno Charest ee3085ce38 feat: add Nimbus Editor with Unsplash integration 
- 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
2025-11-11 11:38:27 -05:00

9.2 KiB
Raw Blame History

🧠 É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 (

    ,

    ,
      , 
      )

    • 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
    • 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

    🐛 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