AppShell
La coquille d'une application.
Elle n'invente rien : la navigation est le Sidebar, le tiroir est le Drawer, les droits viennent de @sia-ui/headless. Ce qu'elle apporte est l'assemblage — trois états de barre, une bascule mobile, et une seule source de vérité pour ce qui est visible et pour ce qui est actif.
Installation
bash
sia-ui add app-shellOu par le paquet, sans rien copier :
tsx
import { AppShell, AppShellBrand, AppShellRailItem } from "@sia-ui/react-web";Props de AppShellBrand
Identité de produit adaptée au rail de l'AppShell.
L'application fournit le symbole et le texte une seule fois. Le composant masque sa copie dès que son parent reçoit data-collapsed.
| Prop | Type | Défaut | Description |
|---|---|---|---|
* icon | ReactNode | — | Symbole conservé lorsque la navigation devient un rail. |
* name | ReactNode | — | Nom du produit, masqué automatiquement dans le rail. |
description | ReactNode | — | Ligne secondaire facultative, masquée avec le nom. |
Props de AppShellRailItem
Contenu icône + libellé qui s'adapte automatiquement au rail.
| Prop | Type | Défaut | Description |
|---|---|---|---|
* icon | ReactNode | — | Symbole toujours visible dans le rail. |
* label | string | — | Libellé masqué visuellement dans le rail et conservé comme nom accessible. |
as | "button" | "div" | "a" | div | Élément rendu : contenu simple, action ou lien. |
disabled | boolean | — | |
href | string | — | |
type | "button" | "submit" | "reset" | button |
Props de AppShell
| Prop | Type | Défaut | Description |
|---|---|---|---|
* nav | SidebarEntry[] | — | |
activeKey | string | — | La clé de l'entrée courante. Laissée vide, elle est déduite de currentPath. La fournir explicitement ne sert que si les clés ne correspondent à aucune adresse. |
ariaLabel | string | — | |
brand | ReactNode | — | En tête de barre latérale : logo, nom du produit, sélecteur d'entité. AppShellBrand masque son texte automatiquement dans le rail. Un contenu entièrement personnalisé reçoit toujours data-collapsed sur son parent. |
can | (rule: PermissionRule) => boolean | — | Évalue les règles de permission. Le filtrage est fait une seule fois ici : ni la barre latérale ni les onglets ne doivent avoir leur propre idée de ce qui est visible. |
className | string | — | |
collapsible | AppShellCollapsible | icon | |
contentWidth | "wide" | "narrow" | "full" | wide | La largeur de la zone de contenu. Décidée ici plutôt qu'écran par écran : des largeurs posées page après page finissent par diverger, et personne ne sait laquelle fait foi. |
currentPath | string | — | L'adresse courante — le point d'accroche du routeur. Une seule chaîne, que tous savent produire : tsx const { pathname } = useLocation(); // React Router const pathname = usePathname(); // Next.js const [pathname] = useLocation(); // wouter De là, la coquille déduit l'entrée active par le préfixe le plus long, et referme le tiroir mobile à chaque navigation — sans jamais importer de routeur. |
defaultSidebarState | "expanded" | "collapsed" | "hidden" | expanded | |
drawerProps | Partial<Omit<DrawerProps, "children" | "open" | "defaultOpen" | "onOpenChange">> | — | Réglages du tiroir mobile — taille, fermeture au clic extérieur, classe. |
footer | ReactNode | — | |
header | ReactNode | — | La barre du haut : recherche, notifications, avatar de compte. |
mobileBreakpoint | number | 768 | Sous cette largeur, la barre latérale cède la place. |
mobileNav | "both" | "drawer" | "tabs" | drawer | |
onNavigate | (item: SidebarItem) => void | — | |
onSidebarStateChange | (state: SidebarState) => void | — | |
page | ReactNode | — | Au-dessus du contenu, pleine largeur de la zone. L'endroit d'un PageHeader. La coquille ne prend pas de title : un <h1> rendu par la coquille force chaque page à passer par ses props, et une page qui veut deux titres ou une mise en page à elle doit se battre. |
renderLink | SidebarRenderLink | — | Branche les liens sur le routeur. À stabiliser avec useCallback. |
side | "left" | "right" | left | |
sidebarCollapsedWidth | string | — | |
sidebarFooter | ReactNode | — | Bas de la barre latérale, sous la navigation. C'est la place de la déconnexion et des réglages du compte — ce qui sort de l'application, par opposition à l'en-tête, réservé à ce qui agit sur l'écran courant. AppShellRailItem masque son libellé automatiquement ; un contenu personnalisé peut encore lire data-collapsed sur son parent. |
sidebarProps | Partial<Omit<SidebarProps, "variant" | "items" | "can" | "activeKey" | "renderLink" | "onNavigate" | "collapsed" | "side" | "header" | "footer" | "ariaLabel">> | — | Réglages de la barre latérale — taille, ton, accordéon, branches ouvertes, volets du rail. Ce que la coquille décide seule en est retiré : les entrées filtrées, l'entrée active, l'état réduit, les liens, l'en-tête et le pied, le côté et la variante — tous déjà réglables ici, et qui doivent rester d'accord avec la mise en page de la coquille. |
sidebarState | "expanded" | "collapsed" | "hidden" | — | |
sidebarWidth | string | — | Toute valeur CSS : 16rem, 280px, min(20vw, 320px). |
stickyHeader | boolean | true | L'en-tête suit-il le défilement. |
variant | "default" | "filled" | "floating" | default |
* obligatoire.
Voir aussi
- Le composant dans le catalogue — états, variantes, et bac à sable.
- La référence complète — tous les composants.