# Guide de Démarrage Rapide - Graph View & Search Assistant

## 🚀 Lancement

```bash
# Installation des dépendances (si nécessaire)
npm install

# Démarrage du serveur de développement
npm start

# L'application sera accessible sur http://localhost:4000
```

## 📍 Accès aux Fonctionnalités

### 1. Assistant de Recherche (3 emplacements)

#### A. Barre Latérale (Vue Mobile/Desktop)
1. Cliquer sur l'icône de recherche dans la navigation
2. Le champ de recherche avec assistant apparaît
3. Focus → popover s'ouvre automatiquement

#### B. Header Central (Vue Desktop)
1. Barre de recherche toujours visible en haut
2. Focus → popover s'ouvre avec suggestions

#### C. Graph Settings → Filters
1. Ouvrir Graph View (icône graphe)
2. Panel "Graph settings" à droite
3. Section "Filters" → champ "Search files..."

### 2. Graph View avec Filtres

**Accès:**
1. Cliquer sur l'icône Graph View (4ème icône navigation)
2. Panel "Graph settings" s'ouvre à droite

**Filtres disponibles:**
- ☑️ **Tags**: Afficher les nœuds de tags (#code, #todo, etc.)
- ☑️ **Attachments**: Afficher fichiers PDF, PNG, etc.
- ☑️ **Existing files only**: Masquer les liens non résolus
- ☑️ **Orphans**: Afficher les nœuds sans connexions

**Recherche avancée:**
- Taper dans "Search files..." pour filtrer par requête Obsidian

### 3. Groups (Colorisation)

**Créer un groupe:**
1. Graph View → Section "Groups"
2. Cliquer "New group"
3. Éditer la requête (ex: `tag:#code`, `file:test`, `path:folder/`)
4. Le groupe colore automatiquement les nœuds matchant

**Gérer les groupes:**
- **Modifier**: Éditer directement la requête dans l'input
- **Supprimer**: Cliquer l'icône ❌
- **Réorganiser**: L'ordre détermine la priorité (haut = prioritaire)

## 🔍 Syntaxe de Recherche Obsidian

### Préfixes Supportés

| Préfixe | Description | Exemple |
|---------|-------------|---------|
| `path:` | Chemin du fichier | `path:folder/subfolder/` |
| `file:` | Nom du fichier | `file:readme` |
| `tag:` | Tag Obsidian | `tag:#todo` ou `tag:#code` |
| `line:` | Mots sur la même ligne | `line:important deadline` |
| `section:` | Sous le même heading | `section:Introduction` |
| `[property]` | Propriété YAML | `[title:test]` ou `[author]` |

### Opérateurs

| Opérateur | Description | Exemple |
|-----------|-------------|---------|
| `OR` | Union (l'un OU l'autre) | `tag:#todo OR tag:#urgent` |
| `AND` | Intersection (implicite) | `tag:#code file:test` |
| `-` | Exclusion (NOT) | `-tag:#done` |
| `"..."` | Phrase exacte | `"exact phrase"` |
| `*` | Wildcard | `test*` ou `*ing` |
| `()` | Groupes | `(tag:#a OR tag:#b) file:test` |

### Exemples de Requêtes

```
# Fichiers avec tag #code
tag:#code

# Fichiers dans le dossier "docs"
path:docs/

# Fichiers contenant "TODO" mais pas "DONE"
TODO -DONE

# Tags #todo OU #urgent dans le dossier "projects"
(tag:#todo OR tag:#urgent) path:projects/

# Fichiers avec propriété YAML "author: John"
[author:John]

# Phrase exacte
"fonction principale"

# Wildcard sur nom de fichier
file:test*
```

## 📚 Utilisation de l'Assistant

### Options de Recherche (Cliquables)

Au focus dans un champ de recherche, le popover affiche:

```
┌─────────────────────────────────────┐
│ Search options              ⓘ Help │
├─────────────────────────────────────┤
│ path:    match path of the file     │
│ file:    match file name            │
│ tag:     search for tags            │
│ line:    search keywords on line    │
│ section: search under same heading  │
│ [property] match property           │
└─────────────────────────────────────┘
```

**Cliquer une option** → insère le préfixe dans l'input

### Suggestions Dynamiques

**Taper `path:`** → Liste des dossiers:
```
┌─────────────────────────┐
│ attachments             │
│ folder                  │
│ deep                    │
│ deep/path               │
│ tata/briana             │
└─────────────────────────┘
```

**Taper `tag:`** → Liste des tags:
```
┌─────────────────────────┐
│ #code                   │
│ #todo                   │
│ #markdown               │
│ #test                   │
└─────────────────────────┘
```

**Taper `file:`** → Liste des fichiers:
```
┌─────────────────────────┐
│ README.md               │
│ test.md                 │
│ welcome.md              │
└─────────────────────────┘
```

### Historique

Après avoir soumis des requêtes, l'historique apparaît:

```
┌─────────────────────────────────────┐
│ History              Clear history  │
├─────────────────────────────────────┤
│ tag:#code OR tag:#test              │
│ path:docs/                          │
│ file:readme                         │
│ [description:page]                  │
└─────────────────────────────────────┘
```

- **Cliquer un item** → applique la requête
- **Clear history** → vide l'historique (localStorage)
- **Maximum**: 10 requêtes récentes

### Navigation Clavier

- **↓** : Sélectionner suggestion suivante
- **↑** : Sélectionner suggestion précédente
- **Enter** : Appliquer suggestion sélectionnée
- **Esc** : Fermer le popover

## 🎨 Colorisation avec Groups

### Exemple: Colorer tous les fichiers de test en rose

1. Graph View → "Groups" → "New group"
2. Query: `file:test`
3. Le groupe applique automatiquement la couleur rose aux fichiers contenant "test"

### Exemple: Colorer par tags

```
Groupe 1 (violet): tag:#code
Groupe 2 (bleu):   tag:#documentation
Groupe 3 (vert):   tag:#todo
```

**Priorité**: Si un fichier a `#code` ET `#todo`, il sera violet (groupe 1 prioritaire)

### Exemple: Colorer par dossier

```
Groupe 1 (rouge):  path:important/
Groupe 2 (jaune):  path:drafts/
Groupe 3 (gris):   path:archive/
```

## 🔧 Configuration Persistée

### Fichier `.obsidian/graph.json`

Tous les réglages sont sauvegardés automatiquement:

```json
{
  "search": "tag:#code",
  "showTags": true,
  "showAttachments": true,
  "hideUnresolved": true,
  "showOrphans": true,
  "colorGroups": [
    {
      "query": "file:test",
      "color": {
        "a": 1,
        "rgb": 14701188
      }
    }
  ],
  "showArrow": true,
  "textFadeMultiplier": -1.7,
  "nodeSizeMultiplier": 1,
  "lineSizeMultiplier": 1,
  "centerStrength": 0.518713248970312,
  "repelStrength": 10,
  "linkStrength": 0.690311418685121,
  "linkDistance": 102
}
```

- **Debounce**: 250ms après modification
- **Polling**: Détection changements externes toutes les 2s
- **Atomic writes**: .tmp + rename pour éviter corruption

### localStorage

Historiques de recherche stockés par contexte:

```
obsidian-search-history-vault-sidebar  → Sidebar mobile
obsidian-search-history-vault-header   → Header desktop
obsidian-search-history-graph          → Graph filters
```

## 🐛 Dépannage

### Le popover ne s'ouvre pas
- Vérifier que le focus est bien dans l'input
- Console browser → chercher erreurs JavaScript

### Les suggestions sont vides
- Vérifier que le vault contient des fichiers/tags
- L'index se rebuild au chargement des notes
- Console → vérifier `GraphIndexService.rebuildIndex` appelé

### Les filtres ne s'appliquent pas
- Vérifier `.obsidian/graph.json` existe et est valide JSON
- Recharger la page pour forcer rechargement config
- Tester avec config minimale

### Les couleurs de groupe ne s'appliquent pas
- Vérifier syntaxe de la requête (utiliser l'assistant)
- Tester requête dans "Search files..." d'abord
- Vérifier ordre des groupes (priorité haut → bas)

## 📊 Vérification de Parité

### Checklist Image 1 vs ObsiViewer

- [ ] Même nombre de nœuds visibles
- [ ] Tags affichés comme nœuds (#code, #markdown, etc.)
- [ ] Attachments visibles (PDF, PNG)
- [ ] Liens vers fichiers non résolus masqués (si "Existing files only")
- [ ] Orphans affichés/masqués selon toggle
- [ ] Groupe rose appliqué aux fichiers matchant `file:test`
- [ ] Flèches sur les arêtes (si "Arrows" activé)

## 🎯 Cas d'Usage Courants

### 1. Trouver tous les TODOs urgents
```
tag:#todo tag:#urgent -tag:#done
```

### 2. Documentation projet spécifique
```
path:docs/project-x/ file:*.md
```

### 3. Fichiers récents avec keyword
```
"important meeting" [date:2024-10]
```

### 4. Code non testé
```
path:src/ -file:*test* -file:*spec*
```

### 5. Groupe de couleurs par statut
```
Groupe 1 (vert):  tag:#done
Groupe 2 (jaune): tag:#in-progress
Groupe 3 (rouge): tag:#blocked
```

## 📖 Ressources

- **Documentation complète**: `GRAPH_VIEW_SEARCH_IMPLEMENTATION.md`
- **Tests**: `src/core/search/search-parser.spec.ts`
- **Obsidian Search Docs**: https://help.obsidian.md/Plugins/Search

---

**Bon usage! 🎉**