gnome-asus-kbd-rgb/docs/UI_SCHEMA.md

# Schéma de l'Interface Utilisateur

## Vue d'ensemble

L'extension ajoute une icône dans la barre supérieure de GNOME Shell. Au clic, un popover s'affiche avec tous les contrôles.

## Diagramme Mermaid - Architecture UI

```mermaid
graph TD
    A[Top Bar GNOME Shell] --> B[Panel Button avec icône clavier]
    B -->|Clic| C[Popover Menu]

    C --> D[Section Intensité]
    C --> E[Section Sliders RGB]
    C --> F[Section Info]
    C --> G[Section Presets]

    D --> D1[Bouton OFF]
    D --> D2[Bouton Faible]
    D --> D3[Bouton Moyen]
    D --> D4[Bouton Fort]

    E --> E1[Slider Rouge 0-255]
    E --> E2[Slider Vert 0-255]
    E --> E3[Slider Bleu 0-255]
    E --> E4[Slider Master 0-100%]

    F --> F1[Label RGB=r,g,b]
    F --> F2[Label HEX=#RRGGBB]
    F --> F3[Label Intensity=n/max]

    G --> G1[Preset 1: Orange]
    G --> G2[Preset 2: Rouge]
    G --> G3[Preset 3: Vert]
    G --> G4[Preset 4: Bleu]
    G --> G5[Preset 5: Blanc]
    G --> G6[Preset 6: Cyan]

    E1 -->|Change| H[Backend: Debounce]
    E2 -->|Change| H
    E3 -->|Change| H
    E4 -->|Change| H
    D1 -->|Click| H
    D2 -->|Click| H
    D3 -->|Click| H
    D4 -->|Click| H
    G1 -->|Click| H
    G2 -->|Click| H
    G3 -->|Click| H
    G4 -->|Click| H
    G5 -->|Click| H
    G6 -->|Click| H

    H --> I[Écriture sysfs]
    I --> J[/sys/class/leds/asus::kbd_backlight/]

    H --> K[Sauvegarde GSettings]
```

## Layout ASCII du Popover

```
┌─────────────────────────────────────────────────────┐
│  Rétroéclairage Clavier ASUS                        │
├─────────────────────────────────────────────────────┤
│                                                      │
│  Intensité:                                          │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐                   │
│  │ OFF │ │  1  │ │  2  │ │  3  │                   │
│  └─────┘ └─────┘ └─────┘ └─────┘                   │
│                                                      │
│  ┌────────────────────────────────────────────┐     │
│  │ Rouge    ●─────────────────────○   255     │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ Vert     ●─────────────────────○   255     │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ Bleu     ●─────────────────────○   255     │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ Master   ●─────────────────────○   100%    │     │
│  └────────────────────────────────────────────┘     │
│                                                      │
│  ┌────────────────────────────────────────────┐     │
│  │ RGB=(255,165,0)  #FFA500  Intensité=2/3    │     │
│  └────────────────────────────────────────────┘     │
│                                                      │
│  Couleurs prédéfinies:                               │
│  ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐              │
│  │ 🟠│ │🔴 │ │🟢 │ │🔵 │ │⚪ │ │🔵 │              │
│  └───┘ └───┘ └───┘ └───┘ └───┘ └───┘              │
│                                                      │
└─────────────────────────────────────────────────────┘
```

## Flux de Données

```
Utilisateur → Slider/Bouton → Event Handler (ui.js)
                                     ↓
                            Debounce Timer (50-100ms)
                                     ↓
                            Backend.applyRGB() (backend.js)
                                     ↓
                         Clamping + Master Gain
                                     ↓
                    ┌────────────────┴────────────────┐
                    ↓                                 ↓
          Écriture sysfs                    Sauvegarde GSettings
        (kbd_rgb_mode, brightness)          (persistance)
                    ↓                                 ↓
            Mise à jour matérielle            Restauration au démarrage
```

## Composants GNOME Shell Utilisés

- **PanelMenu.Button** : Bouton dans la top bar
- **PopupMenu.PopupBaseMenuItem** : Items personnalisés dans le menu
- **St.BoxLayout** : Layout vertical/horizontal
- **St.Button** : Boutons d'intensité
- **Slider** : Sliders RGB et Master (API GNOME Shell)
- **St.Label** : Labels et texte d'information
- **St.Bin** : Containers pour les presets couleur

## Interactions Utilisateur

### Actions Immédiates (sans confirmation)
- Déplacer un slider RGB → Application immédiate avec debounce
- Cliquer sur un bouton d'intensité → Application immédiate
- Cliquer sur une couleur preset → Application immédiate
- Déplacer le slider Master → Ajuste R/G/B proportionnellement

### Feedback Visuel
- Slider actif → Curseur se déplace
- Bouton intensité actif → Surligné/highlighted
- Info line → Mise à jour en temps réel
- Preset cliqué → Feedback visuel temporaire

## Gestion des Erreurs UI

### Permission refusée
```
┌─────────────────────────────────────────────────────┐
│  ⚠️  Permissions insuffisantes                       │
│                                                      │
│  Impossible d'accéder au rétroéclairage.             │
│  Veuillez configurer les règles udev.                │
│                                                      │
│  Voir: docs/INSTALL.md                               │
└─────────────────────────────────────────────────────┘
```

### Matériel non supporté
```
┌─────────────────────────────────────────────────────┐
│  ❌ Matériel non supporté                            │
│                                                      │
│  Aucun clavier ASUS RGB détecté sur ce système.     │
└─────────────────────────────────────────────────────┘
```

## Notes d'Implémentation

1. **Debouncing**: Utiliser `GLib.timeout_add()` avec timeout de 75ms
2. **Master Slider**: Multiplier R/G/B par (master/100) avant écriture
3. **Presets**: Stocker dans GSettings, charger au démarrage
4. **Info Line**: Mettre à jour via callback après chaque changement
5. **Style**: Utiliser `stylesheet.css` pour personnalisation minimale