roadwave/docs/interfaces/mobile/navigation.md

# Navigation & Architecture Mobile

## Architecture de navigation

L'application mobile utilise une navigation par onglets (Bottom Navigation Bar) avec 4 sections principales.

```mermaid
graph TD
    A[App Shell] --> B[🏠 Accueil]
    A --> C[🗺️ Carte]
    A --> D[🎵 Bibliothèque]
    A --> E[👤 Profil]

    B --> B1[Feed Recommandations]
    B --> B2[Lecteur Audio]

    C --> C1[Vue Carte]
    C --> C2[Détail Point]

    D --> D1[Mes Playlists]
    D --> D2[Contenus Sauvegardés]
    D --> D3[Historique]

    E --> E1[Jauges Intérêt]
    E --> E2[Paramètres]
    E --> E3[Abonnements]
```

## Bottom Navigation Bar

### Onglet 1 : Accueil 🏠
Point d'entrée principal après le lancement de l'app.

**Fonctionnalités** :
- Feed de recommandations basé sur la géolocalisation + intérêts
- Rafraîchissement pull-to-refresh
- Lecture directe depuis le feed

**Navigation vers** :
- Détail d'un contenu (push)
- Lecteur plein écran (modal)
- Profil d'un créateur (push)

### Onglet 2 : Carte 🗺️
Exploration visuelle des contenus par géolocalisation.

**Fonctionnalités** :
- Carte interactive (MapLibre GL)
- Markers pour contenus à proximité
- Clusters pour zones denses
- Recherche par adresse

**Navigation vers** :
- Détail d'un point (bottom sheet)
- Lecteur audio (modal persistant)

### Onglet 3 : Bibliothèque 🎵
Accès aux contenus sauvegardés, historique, playlists.

**Fonctionnalités** :
- Playlists personnelles
- Contenus favoris
- Historique d'écoute
- Téléchargements offline

### Onglet 4 : Profil 👤
Gestion du compte, préférences, jauges d'intérêt.

**Fonctionnalités** :
- Visualisation/édition jauges d'intérêt
- Paramètres de l'app
- Gestion abonnement Premium
- Déconnexion

## Lecteur Audio (Modal persistant)

Le lecteur est un composant modal qui persiste lors de la navigation entre onglets.

```mermaid
stateDiagram-v2
    [*] --> Collapsed: Lecture démarre
    Collapsed --> Expanded: Tap sur mini-player
    Expanded --> Collapsed: Swipe down
    Collapsed --> [*]: Stop audio

    Expanded --> Queue: Tap "À suivre"
    Queue --> Expanded: Retour
```

=== "État Collapsed (Mini-player)"
    - Hauteur : 60dp
    - Position : Bottom (au-dessus de la Bottom Nav Bar)
    - Affiche : Titre, artiste, play/pause, skip
    - Interaction : Tap pour expand

=== "État Expanded (Lecteur plein écran)"
    - Plein écran modal
    - Cover art grande taille
    - Contrôles avancés (repeat, shuffle, queue)
    - Scrubber timeline
    - Boutons : like, share, download, add to playlist

## Routing Flutter

### Configuration

Utilisation de **go_router** (voir [ADR-020](../../adr/020-librairies-flutter.md)).

```dart
// Exemple simplifié
GoRouter(
  routes: [
    ShellRoute(
      builder: (context, state, child) => AppShell(child: child),
      routes: [
        GoRoute(path: '/home', builder: (context, state) => HomeScreen()),
        GoRoute(path: '/map', builder: (context, state) => MapScreen()),
        GoRoute(path: '/library', builder: (context, state) => LibraryScreen()),
        GoRoute(path: '/profile', builder: (context, state) => ProfileScreen()),
      ],
    ),
    GoRoute(
      path: '/content/:id',
      builder: (context, state) => ContentDetailScreen(
        contentId: state.pathParameters['id']!,
      ),
    ),
  ],
);
```

### Deep Links

L'app supporte les deep links pour :
- `roadwave://content/{id}` : Ouvrir un contenu spécifique
- `roadwave://map?lat={lat}&lon={lon}` : Ouvrir la carte à une position
- `roadwave://profile` : Ouvrir le profil

## Gestion d'état

- **Provider** pour l'état global (user, player, location)
- **BLoC** pour les features complexes (recommendation, map)
- **Riverpod** pour l'injection de dépendances

Voir [ADR-020](../../adr/020-librairies-flutter.md) pour les détails.

## Permissions système

La navigation gère les demandes de permissions de manière contextuelle :

1. **Géolocalisation** : Demandée au premier lancement, avant d'afficher l'accueil
2. **Notifications** : Demandée après 3 sessions utilisateur (opt-in soft)
3. **Stockage** : Demandée lors du premier téléchargement offline

Voir [mobile/permissions-strategy.md](../../mobile/permissions-strategy.md) pour la stratégie complète.

## Transitions et animations

### Transitions entre onglets
- Aucune animation (changement instantané)
- Préservation du scroll state sur chaque onglet

### Navigation push/pop
- iOS : Slide transition (standard Cupertino)
- Android : Fade + Slide transition (Material Design)

### Mini-player expand/collapse
- Spring animation (bounce léger)
- Durée : 300ms
- Curve : `Curves.easeInOutCubic`

## Gestion du back button (Android)

```mermaid
graph TD
    A[Back pressed] --> B{Lecteur expanded?}
    B -->|Oui| C[Collapse lecteur]
    B -->|Non| D{Sur onglet Accueil?}
    D -->|Non| E[Retour à Accueil]
    D -->|Oui| F{Audio en cours?}
    F -->|Oui| G[Dialog: Quitter?]
    F -->|Non| H[Quitter app]
    G -->|Confirme| H
    G -->|Annule| I[Rester]
```

## Accessibilité

- **Screen readers** : Labels sémantiques sur tous les boutons
- **Navigation clavier** : Support complet (pour tablettes avec clavier)
- **Contraste** : WCAG 2.1 AA minimum (4.5:1 pour texte)
- **Taille des touch targets** : 48dp minimum

## Mode sombre

Support obligatoire du mode sombre (conduite de nuit).

=== "Mode Clair"
    - Fond : White / Light Gray (#F5F5F5)
    - Texte : Dark Gray (#212121)
    - Accent : Indigo (#3F51B5)

=== "Mode Sombre"
    - Fond : Dark (#121212)
    - Texte : White (#FFFFFF)
    - Accent : Indigo clair (#7986CB)

Détection automatique via `MediaQuery.platformBrightness` ou choix manuel dans les paramètres.