veza/apps/web/docs/APP_SHELL.md

# App Shell — Référence

Vue d’ensemble du shell applicatif (layout principal) et des tokens CSS associés. Toute évolution du shell (sidebar, header, main, player) doit s’appuyer sur ces variables et classes pour rester cohérente.

## Rôle du shell

- **Sidebar** : navigation fixe à gauche (largeur pilotée par `--sidebar-width-expanded` / `--sidebar-width-collapsed`). Voir [index.css](../src/index.css) section "Sidebar layout".
- **Header** : barre fixe en haut (hauteur `--header-height`), dont le bord gauche suit la sidebar (expanded/collapsed).
- **Main** : zone scrollable (contenu des pages). Marges gauche pilotées par l’état de la sidebar ; padding top/bottom pour ne pas passer sous le header ni le player.
- **Player** : barre de lecture fixe en bas (rendue par `GlobalPlayer` dans `DashboardLayout`).

Fichiers principaux :

- [DashboardLayout.tsx](../src/components/layout/DashboardLayout.tsx) — assemblage Sidebar, zone main, Header, GlobalPlayer.
- [Header.tsx](../src/components/layout/Header.tsx) — barre supérieure (recherche, actions, user menu).

## Variables CSS (shell)

Définies dans `:root` dans [index.css](../src/index.css), section "App shell" :

| Variable | Valeur | Rôle |
|----------|--------|------|
| `--header-height` | 4rem | Hauteur de la barre header fixe |
| `--main-offset-top` | 5rem | Padding-top du `<main>` (dégager le header) |
| `--main-offset-bottom` | 8rem | Padding-bottom du `<main>` (réserve pour le player) |
| `--main-margin-left-expanded` | 18rem | Marge gauche du conteneur main quand sidebar ouverte (15rem sidebar + 3rem gap) |
| `--main-margin-left-collapsed` | 7rem | Marge gauche du main quand sidebar fermée (5rem + 2rem gap) |
| `--header-left-expanded` | 18rem | Position `left` de la barre header quand sidebar ouverte |
| `--header-left-collapsed` | 5rem | Position `left` de la barre header quand sidebar fermée |

Les largeurs sidebar sont définies à part : `--sidebar-width-expanded` (15rem), `--sidebar-width-collapsed` (5rem). Pour garder la cohérence, ne pas modifier les marges main/header sans ajuster ces tokens de façon cohérente.

## Classes utilitaires (shell)

Définies dans [index.css](../src/index.css) après les classes sidebar (`.left-sidebar`, `.z-sidebar`, etc.) :

| Classe | Propriété | Usage |
|--------|-----------|--------|
| `.h-header` | height | Barre header et div interne du header |
| `.pt-main` | padding-top | Élément `<main>` |
| `.pb-main` | padding-bottom | Élément `<main>` |
| `.ml-main-expanded` | margin-left | Conteneur principal (avec préfixe `lg:`) quand sidebar ouverte |
| `.ml-main-collapsed` | margin-left | Conteneur principal (avec `lg:`) quand sidebar fermée |
| `.left-header-expanded` | left | Barre header quand sidebar ouverte |
| `.left-header-collapsed` | left | Barre header quand sidebar fermée |

À utiliser avec le préfixe responsive `lg:` pour les marges/positions desktop (ex. `lg:ml-main-expanded`). En dessous de `lg`, la sidebar est en overlay et le main utilise `ml-0`, le header `left-0` (`max-lg:left-0`).

## Comportement responsive

- **lg (1024px et plus)** : sidebar fixe à gauche, main et header utilisent les classes tokenisées (expanded/collapsed selon `sidebarOpen`).
- **En dessous de lg** : sidebar en overlay (ouverte/fermée par toggle), conteneur main en pleine largeur (`ml-0`), header en pleine largeur (`max-lg:left-0`).

## Breakpoints et viewports de test

| Breakpoint | Largeur | Comportement attendu |
|------------|---------|----------------------|
| Mobile | 320px | Sidebar overlay, main pleine largeur, header pleine largeur. |
| Tablet | 768px | Idem (sidebar overlay jusqu’à lg). |
| Desktop | 1024px (lg) | Sidebar fixe, main et header avec marges/positions tokenisées. |
| Large desktop | 1280px | Même comportement que lg, contenu limité par `max-w-layout-content` si applicable. |

Vérifier visuellement (ou via tests Playwright) que Sidebar, Header et Main se comportent correctement sur ces largeurs.

## Référence croisée

- Tokens sidebar (largeurs, offsets, z-index) : [index.css](../src/index.css) — "Sidebar layout" et classes `.w-sidebar-expanded`, `.left-sidebar`, `.top-sidebar`, `.bottom-sidebar`, `.z-sidebar`, `.z-sidebar-overlay`.
- Layout primitives (max-width contenu, min-height pages) : mêmes variables `--layout-content-max-width`, `--layout-page-min-height`, etc. Le `<main>` contient un wrapper `max-w-layout-content` pour le contenu.