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 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 — assemblage Sidebar, zone main, Header, GlobalPlayer.
• Header.tsx — barre supérieure (recherche, actions, user menu).

Variables CSS (shell)

Définies dans :root dans 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 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 — "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.