docs: ajout analyse complète architecture toolbar multi-zone (5 zones: top bar, slash menu, bubble menu, quick insert, AI panel)

2026-06-05 19:53:05 -04:00
parent 0f1ae237a0
commit 0f400d72cd
1 changed files with 435 additions and 0 deletions
@@ -0,0 +1,435 @@
 # 🎯 Analyse : Architecture de Toolbar pour ObsiGate
 > **Date** : 2026-06-05
 > **Auteur** : Hermes-Claw (Agent IA)
 > **Contexte** : Recherche et recommandation du meilleur design de barre d'outils pour l'éditeur ObsiGate
 > **Fonctionnalités cibles** : Édition Markdown, Actions IA, Insertion PDF, Insertion Images
 ---
 ## 📋 Sources d'inspiration
 L'analyse repose sur l'étude des éditeurs leaders du marché :
 | Éditeur | Pattern clé | Pertinence pour ObsiGate |
 |---------|-------------|--------------------------|
 | **Notion** | Slash menu + Bubble menu + Quick insert `+` | ⭐⭐⭐⭐⭐ Forte |
 | **Novel.sh** | Slash menu + AI autocomplete (`++`) | ⭐⭐⭐⭐⭐ Forte |
 | **Medium** | Bubble menu minimal sur sélection | ⭐⭐⭐⭐ Élevée |
 | **Dropbox Paper** | Quick insert `+` + Slash commands | ⭐⭐⭐⭐ Élevée |
 | **Cursor / Windsurf** | AI Side Panel + Inline AI | ⭐⭐⭐⭐ Élevée |
 | **Google Docs** | Top toolbar traditionnelle | ⭐⭐ Faible (trop chargée) |
 | **Obsidian** | Command palette + Sidebar | ⭐⭐⭐ Moyenne |
 | **Tiptap** | API de menus : Fixed / Bubble / Floating / Slash | ⭐⭐⭐⭐⭐ Fondation technique |
 ---
 ## 🏆 Recommandation : Architecture Multi-Zone
 Les éditeurs modernes n'utilisent **plus une toolbar unique** en haut. Ils distribuent les contrôles dans **5 zones contextuelles** qui apparaissent uniquement quand elles sont pertinentes.
 ### Principe fondamental
 > **"Montre le bon contrôle, au bon endroit, au bon moment."**
 Une toolbar fixe traditionnelle (style Google Docs) **ne fonctionne plus** pour un éditeur moderne avec IA intégrée. La complexité est trop grande pour tout afficher en permanence.
 ---
 ## 📐 Zone 1 — Top Fixed Bar (toujours visible)
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ ☰ [Obsigate]  Document Title...    🔮 AI  📎 ⚙️ 💾    │
 └─────────────────────────────────────────────────────────┘
 ```
 ### Contenu
 | Position | Élément | Description |
 |----------|---------|-------------|
 | **Gauche** | ☰ Menu hamburger | Navigation, settings, historique |
 | **Gauche** | Titre du document | Éditable inline, se sauvegarde automatiquement |
 | **Droite** | 🔮 **AI Assistant** | Bouton principal, couleur d'accent — le différenciateur produit |
 | **Droite** | 📎 Quick Insert | Dropdown : Image, PDF, Table, Embed |
 | **Droite** | ⚙️ Actions | Export, Settings, Share |
 | **Droite** | 💾 Save indicator | Auto-save status (saved / saving / error) |
 ### Design notes
 - Hauteur : ~48px
 - Fond : légèrement distinct de l'éditeur (ombre ou bordure)
 - Le bouton AI est le plus visible (couleur primaire, légère glow)
 - Barre fixe au scroll (sticky top)
 ### Pourquoi
 Barre minimale, toujours accessible. Les actions document-level (PDF, images) sont à portée mais ne polluent pas l'interface. Le bouton AI est le **hero** — le différenciateur d'ObsiGate face aux autres éditeurs.
 ---
 ## 📐 Zone 2a — Slash Command Menu (tape `/` sur ligne vide)
 ```
 ┌──────────────────────────────────┐
 │ 🔍  Filtrer...                   │
 │ ──────────────────────────────── │
 │ 📝  Text              Just start │
 │ ✅  To-do List         Track...  │
 │ H1  Heading 1          Big...    │
 │ H2  Heading 2          Medium... │
 │ H3  Heading 3          Small...  │
 │ •   Bullet List        Simple... │
 │ 1.  Numbered List      Ordered.. │
 │ 💬  Quote              Block...  │
 │ 📋  Code Block         Syntax... │
 │ ──  Divider            Horiz...  │
 │ ──────────────────────────────── │
 │ 🖼️  Insert Image       Upload... │
 │ 📄  Insert PDF          Attach... │
 │ 📊  Insert Table        Data...   │
 │ 🔗  Insert Link         URL...    │
 │ ──────────────────────────────── │
 │ ✨  AI: Continue        Write...  │
 │ ✨  AI: Summarize       Condense  │
 │ ✨  AI: Translate       To...     │
 │ ✨  AI: Brainstorm      Ideas...  │
 │ ✨  AI: Fix grammar     Correct   │
 │ ✨  AI: Change tone     Formal... │
 └──────────────────────────────────┘
 ```
 ### Design notes
 - Menu flottant (popover) positionné sous le curseur
 - Hauteur max : ~400px, scroll si plus
 - Chaque item : **icône + titre + description courte**
 - Sections séparées par un divider subtil
 - Navigation : flèches ↑↓ + Entrée pour sélectionner
 - Barre de filtrage en haut (taper filtre les résultats)
 - Fond : blanc/carte avec ombre légère + border-radius 8px
 - Animation : fade-in + slide-up (150ms)
 ### Pourquoi c'est le game-changer
 Le slash menu **remplace 90% des besoins de toolbar**. Plus besoin d'une barre fixe pour les actions de formatage. L'utilisateur tape `/` et tout est là, accessible au clavier. C'est le pattern qui a fait le succès de Notion.
 ---
 ## 📐 Zone 2b — Bubble Menu (apparaît sur sélection de texte)
 ```
     ┌──────────────────────────────────────┐
     │  𝐁   𝐼   S̶   </>   🔗   ⋯   ✨ AI ▾ │
     └──────────────────────────────────────┘
 ```
 ### Contenu
 | Icône | Action | Raccourci |
 |-------|--------|-----------|
 | **B** | Bold | Ctrl+B |
 | *I* | Italic | Ctrl+I |
 | ~~S~~ | Strikethrough | Ctrl+Shift+X |
 | `</>` | Code inline | Ctrl+E |
 | 🔗 | Link | Ctrl+K |
 | ⋯ | More (Quote, Highlight) | — |
 | ✨ AI ▾ | Dropdown AI actions | — |
 ### Dropdown AI (✨)
 | Action | Description |
 |--------|-------------|
 | Improve writing | Améliore le style |
 | Fix spelling & grammar | Corrige les erreurs |
 | Translate to... | Traduit vers langue cible |
 | Continue writing | Continue le texte |
 | Summarize | Résume la sélection |
 | Change tone | Ajuste le ton (formel/informel) |
 | Explain | Explique le texte sélectionné |
 ### Design notes
 - Apparaît **au-dessus** de la sélection (évite de cacher le texte)
 - Position calculée dynamiquement (reste dans le viewport)
 - Animation : scale-in + fade (120ms)
 - Fond : blanc + ombre `0 4px 12px rgba(0,0,0,0.15)` + radius 8px
 - Disparaît quand la sélection est perdue
 - Délai d'apparition : 50ms après sélection (pas de flash intempestif)
 ### Pourquoi
 Pattern Medium/Notion. Le plus efficace car le curseur est déjà proche de la sélection. Évite les allers-retours avec une toolbar fixe distante.
 ---
 ## 📐 Zone 3 — Floating Quick Insert (ligne vide)
 ```
  ⊕ │___________________________________________
 ```
 ### Comportement
 - Apparaît à gauche d'une ligne vide quand le curseur est dessus
 - Au clic sur ⊕, ouvre un mini-menu compact (4-5 options)
 ```
  ┌─────────────────────┐
  │ 🖼️  Image           │
  │ 📄  PDF             │
  │ 📋  Code Block      │
  │ 📊  Table           │
  │ ✨  AI Actions ▸    │
  └─────────────────────┘
 ```
 ### Design notes
 - Icône ⊕ semi-transparente, devient opaque au hover
 - Cercle de 24px, centré verticalement sur la ligne
 - Mini-menu : compact, sans description (icône + texte uniquement)
 - Animation : fade-in (100ms)
 ### Pourquoi
 Pattern Dropbox Paper. **Ultra-rapide** pour les insertions fréquentes — pas besoin de taper `/` ni d'aller dans la toolbar. Complémentaire au slash menu.
 ---
 ## 📐 Zone 4 — AI Side Panel (toggle droite)
 ```
 ┌──────────────────────────┬──────────────────┐
 │                          │  ✨ AI Assistant  │
 │   Zone d'édition         │  ─────────────── │
 │                          │                  │
 │   Ceci est le contenu    │  💬 Chat         │
 │   du document en cours   │  ┌────────────┐  │
 │   d'édition...           │  │ Pose ta    │  │
 │                          │  │ question.. │  │
 │                          │  └────────────┘  │
 │                          │  [Send]          │
 │                          │                  │
 │                          │  📋 Suggestions  │
 │                          │  • Improve style │
 │                          │  • Add section   │
 │                          │  • Translate     │
 │                          │  • Generate PDF  │
 │                          │                  │
 └──────────────────────────┴──────────────────┘
 ```
 ### Contenu
 | Section | Description |
 |---------|-------------|
 | **Chat** | Conversation IA contextuelle (connaît le document) |
 | **Suggestions** | Actions IA contextuelles basées sur le contenu |
 | **History** | Historique des interactions IA récentes |
 | **One-click actions** | "Fix grammar", "Translate to EN", "Generate summary" |
 ### Design notes
 - Panel rétractable (toggle via bouton 🔮 de la Zone 1)
 - Largeur : 320-380px
 - Fond légèrement distinct
 - Slide-in depuis la droite (200ms)
 - L'éditeur se réduit (responsive, pas d'overlay)
 - Persiste entre les sessions (état sauvegardé)
 - Sur mobile : passe en bottom sheet
 ### Pourquoi
 Pour les interactions AI complexes (brainstorm, réécriture multi-paragraphes, recherche). Le bubble menu gère le micro ; le panel gère le macro. Pattern Cursor/Windsurf.
 ---
 ## 📐 Zone 5 — Drag & Drop Zone (invisible, toujours actif)
 ```
 ┌────────────────────────────────────────────────┐
 │                                                │
 │   ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐   │
 │   │                                        │   │
 │   │     🖼️  Déposez vos fichiers ici       │   │
 │   │     Images, PDFs, documents            │   │
 │   │                                        │   │
 │   └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘   │
 │                                                │
 └────────────────────────────────────────────────┘
 ```
 ### Comportement
 - Zone active sur tout l'éditeur
 - Au survol d'un fichier : bordure pointillée bleue + overlay semi-transparent
 - Accepte : images (png, jpg, webp, gif, svg), PDFs, .md, .txt
 - Feedback visuel pendant le drop : animation + barre de progression
 ### Design notes
 - Bordure pointillée : 2px dashed `#4A90D9`
 - Overlay : fond bleu à 5% d'opacité
 - Icône + texte centrés, large
 - Disparaît quand le drag quitte la zone
 - Upload progressif avec prévisualisation
 ---
 ## 🎨 Layout complet intégré
 ```
 ┌───────────────────────────────────────────────────────────────────┐
 │ ☰  [ObsiGate]  Mon Document...           🔮 AI  📎 Insert  ⚙️  💾 │ ← Zone 1
 ├───────────────────────────────────────────────────────────────────┤
 │                                                                   │
 │  ⊕ │  ## Introduction                                   │ ✨ AI   │ ← Zone 4
 │    │                                                    │─────── │
 │    │  Ceci est le contenu du document...                │        │
 │    │                                                    │ Chat   │
 │    │     ┌──────────────────────────┐                   │        │
 │    │     │ 𝐁  𝐼  S̶  </>  🔗  ✨ AI ▾│ ← Zone 2b (sel.)  │        │
 │    │     └──────────────────────────┘                   │        │
 │    │                                                    │        │
 │    │  Du texte sélectionné ici...                       │        │
 │    │                                                    │        │
 │  ⊕ │                                                    │        │
 │    │  /                                                │        │
 │    │  ┌──────────────────────────┐                     │        │
 │    │  │ 📝  Text                 │ ← Zone 2a (slash)   │        │
 │    │  │ H1  Heading 1            │                     │        │
 │    │  │ ✨  AI: Improve writing   │                     │        │
 │    │  └──────────────────────────┘                     │        │
 │    │                                                    │        │
 │    │                                                    │        │
 ├───────────────────────────────────────────────────────────────────┤
 │  ⌨️  / pour menu  |  Ctrl+K pour commandes  |  1200 mots         │
 └───────────────────────────────────────────────────────────────────┘
 ```
 ### Barre de statut (footer)
 - Toujours visible, fine (24-28px)
 - Affiche : raccourcis utiles, compteur de mots, statut connexion
 - Icône IA clignotante si l'IA est en train de traiter
 ---
 ## 🎯 Tableau comparatif : besoin vs solution
 | Besoin ObsiGate | Solution | Pattern utilisé par |
 |-----------------|----------|---------------------|
 | Édition Markdown rapide | Slash `/` + Bubble menu | Notion, Medium, Dropbox Paper |
 | Actions IA fréquentes | Bouton 🔮 proéminent + Bubble AI dropdown + Panel | Cursor, Novel.sh, Windsurf |
 | Insertion PDF/Images | Slash menu + Quick insert ⊕ + Drag & drop | Notion, Dropbox Paper |
 | Pas de clutter | Zones contextuelles (rien de visible inutilement) | Medium, iA Writer |
 | Accessibilité clavier | Tout accessible via `/`, `Ctrl+K`, `Ctrl+P` | Notion, Linear |
 | Feedback IA | Barre de statut + animations | Cursor, Copilot |
 ---
 ## 🔑 Les 3 patterns différenciateurs
 ### 1. Slash Command Menu
 Le **game-changer**. Plus besoin de toolbar fixe pour 90% des actions. Tu tapes `/` et tout est là, navigable au clavier.
 ### 2. L'IA comme citoyen de première classe
 L'IA n'est **pas cachée** dans un sous-menu. Elle est :
 - En bouton dédié visible (Zone 1)
 - Dans le slash menu (Zone 2a)
 - Dans le bubble menu (Zone 2b)
 - En panel latéral (Zone 4)
 ### 3. Bubble Menu on Selection
 Plus proche du curseur, plus rapide. Medium l'a popularisé, tout le monde l'a copié depuis.
 ---
 ## 🛠️ Implémentation technique recommandée
 ### Option A : Tiptap + Custom Extensions (recommandé)
 ```javascript
 // Base : Tiptap (React)
 import { Editor } from '@tiptap/react'
 import StarterKit from '@tiptap/starter-kit'
 // Extensions pour ObsiGate
 import { SlashCommand } from './extensions/slash-command'
 import { BubbleMenuAI } from './extensions/bubble-menu-ai'
 import { QuickInsert } from './extensions/quick-insert'
 import { AIPanel } from './extensions/ai-panel'
 import { DropZone } from './extensions/drop-zone'
 ```
 **Avantages** :
 - Contrôle total sur chaque zone
 - Écosystème mature (ProseMirror)
 - Extensions custom faciles à créer
 - Support React/Vue natif
 ### Option B : Novel.sh (rapide)
 ```javascript
 import { Editor } from 'novel'
 ```
 **Avantages** :
 - 80% du comportement Notion direct
 - Slash menu + AI autocomplete intégrés
 - MIT License
 - Moins flexible que Tiptap pur
 ### Bibliothèques UI complémentaires
 | Composant | Librairie | Usage |
 |-----------|-----------|-------|
 | Popover / Menu flottant | `@radix-ui/react-popover` | Slash menu, Bubble menu |
 | Panel rétractable | `@radix-ui/react-dialog` ou custom | AI Panel |
 | Drag & Drop | `react-dnd` ou natif HTML5 | Zone 5 |
 | Animations | `framer-motion` ou CSS transitions | Toutes les zones |
 ---
 ## 📱 Considérations Responsive / Mobile
 ### Desktop (>768px)
 - Toutes les zones actives
 - AI Panel : rétractable à droite
 ### Tablette (480-768px)
 - AI Panel : overlay (pas de réduction de l'éditeur)
 - Bubble menu : taille réduite
 - Slash menu : pleine largeur
 ### Mobile (<480px)
 - AI Panel : bottom sheet
 - Bubble menu : repositionné en bas d'écran
 - Top bar : simplifiée (icônes uniquement)
 - Quick insert ⊕ : plus grand (32px) pour le toucher
 ---
 ## ⚡ Raccourcis clavier
 | Raccourci | Action | Zone |
 |-----------|--------|------|
 | `/` | Slash command menu | 2a |
 | `Ctrl+B` | Bold | 2b |
 | `Ctrl+I` | Italic | 2b |
 | `Ctrl+K` | Insert link | 2b |
 | `Ctrl+Shift+I` | Insert image | 2a |
 | `Ctrl+Shift+P` | Insert PDF | 2a |
 | `Ctrl+J` | Toggle AI Panel | 4 |
 | `Ctrl+Shift+K` | AI quick action | 2b |
 | `Ctrl+P` | Quick open / Command palette | — |
 | `Ctrl+S` | Force save | 1 |
 | `Ctrl+/` | Show all shortcuts | — |
 ---
 ## 🧪 Prochaines étapes
 1. **Mockup HTML interactif** — Créer un prototype statique pour valider le layout
 2. **POC Tiptap** — Implémenter les zones 1, 2a, 2b dans un projet test
 3. **User testing** — Faire tester le prototype pour recueillir du feedback
 4. **Implémentation progressive** :
   - Sprint 1 : Zone 1 (Top bar) + Zone 2a (Slash menu)
   - Sprint 2 : Zone 2b (Bubble menu) + Zone 3 (Quick insert)
   - Sprint 3 : Zone 4 (AI Panel) + Zone 5 (Drag & drop)
 5. **Intégration IA** — Brancher le backend AI existant (`backend/ai_routes.py`) au panel et au bubble menu
 ---
 ## 📚 Références
 - [Tiptap Editor Documentation](https://tiptap.dev/docs)
 - [Novel.sh — Notion-style Editor](https://novel.sh)
 - [Notion — Onboarding & Editor Design](https://www.notion.so)
 - [Medium — Design Blog](https://medium.design)
 - [Dropbox Paper](https://www.dropbox.com/paper)
 - [Radix UI Primitives](https://www.radix-ui.com/primitives)
 - [ProseMirror](https://prosemirror.net)