Skip to content

Navigation mobile, session SIA et Expo Router ​

Le socle natif fournit BottomBar, Sidebar, AppShell, RequireSession et StateScreen. L’entrée optionnelle @sia-ui/react-native/expo-router fournit SiaExpoStack, SiaExpoLayout, useExpoSessionReturn et SiaExpoErrorBoundary.

Il réutilise le store de session SIA existant : hydratation, statuts, permissions, rôles, expiration et déconnexion restent dans @sia-ui/headless. Il ne crée pas une deuxième session et ne demande pas de recopier ces états dans le routeur. Les composants visuels restent utilisables avec un autre routeur.

Configuration minimale ​

Installer Expo Router avec les commandes officielles de votre SDK :

bash
pnpm exec expo install expo-router react-native-screens expo-linking expo-constants react-native-safe-area-context

La matrice vérifiée du prototype utilise Expo 58.0.23, Expo Router 58.0.30, React Native 0.88.1 et React 19.3.0. Le peer Expo Router est optionnel pour le package : importer le sous-chemin seulement dans une application qui l’utilise. Configurer main: "expo-router/entry", le plugin expo-router et un schéma de liens dans app.json, selon l’intégration officielle. Conserver l’intégration Uniwind, les polices et les zones sûres du guide mobile.

Dans le layout racine, brancher le store existant :

tsx
// app/_layout.tsx — après chargement des polices et préférences éventuelles
import '../global.css';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { SiaNativeProvider } from '@sia-ui/react-native';
import { SiaExpoStack } from '@sia-ui/react-native/expo-router';
import { session } from '../src/session';

export default function RootLayout() {
  return <SafeAreaProvider>
    <SiaNativeProvider>
      <SiaExpoStack session={session} privateGroup="(app)"
        signInScreen="sign-in" incompleteScreen="complete-profile"
        screenOptions={{ headerShown: false }} />
    </SiaNativeProvider>
  </SafeAreaProvider>;
}

privateGroup, signInScreen et incompleteScreen sont des noms de fichiers ou groupes Expo Router. Le dernier est facultatif. Le Stack garde les routes privées pendant checking, mais RequireSession attend avant d’afficher leur contenu. Une session anonyme ou incomplète retire le groupe privé et son historique grâce à Stack.Protected. Les écrans publics supplémentaires peuvent être ajoutés comme enfants Stack.Screen, selon le contrat Expo Router.

tsx
// app/(app)/_layout.tsx
import { SiaExpoLayout } from '@sia-ui/react-native/expo-router';
import { session } from '../../src/session';

const navigation = [
  { key: 'home', label: 'Accueil', href: '/' },
  { key: 'projects', label: 'Projets', href: '/projects' },
  { key: 'admin', label: 'Administration', href: '/admin', permission: 'admin.read' },
];

export default function PrivateLayout() {
  return <SiaExpoLayout session={session} items={navigation}
    title="Mon application" navigationMode="auto"
    signInPath="/sign-in" incompletePath="/complete-profile" />;
}

Sans enfant fourni, le layout installe le Stack privé avec une boundary par écran ; une nouvelle tentative ne recrée donc pas toute la navigation. Un enfant personnalisé permet de fournir son propre navigateur Expo Router si nécessaire.

Les destinations actives sont déduites de l’adresse avec navKeyForPath : une page de détail reste dans sa branche. Les droits des parents et de la destination sont vérifiés aussi en accès direct. routeRules ajoute des règles pour les pages qui ne sont pas représentées dans le menu. Un préfixe correspond à une frontière de segment : /admin couvre /admin/users, pas /administrator.

La session déclenche le refiltrage du menu quand permissions, rôles ou tenant changent. Les descendants d’une entrée désactivée restent désactivés, y compris lorsqu’ils sont présentés à plat dans la bottom bar. L’affichage ne remplace pas les autorisations des API : le serveur continue à contrôler ses données.

Sur la page de connexion :

tsx
const { returnTo } = useLocalSearchParams();
const state = useExpoSessionReturn(session, { returnTo });
// Le formulaire appelle session.signIn(credentials), comme sur le web.

Le hook reprend une destination interne après authentification. Les retours externes, les doubles slashs et les chemins ambigus sont refusés. Le layout conserve aussi le chemin de reprise pour une expiration et une arrivée directe sur une page protégée. Une déconnexion explicite retire cette reprise dans le Stack SIA. Cette mécanique reprend une adresse, pas les données d’un formulaire ni des caches métier. Les identifiants et leurs transports restent ceux du store et de l’application ; aucune nouvelle stratégie de stockage de jetons n’est imposée.

Composants de navigation ​

ComposantConfigurationResponsabilité
AppShellnavigationMode, breakpoint, title, headerActions, brand, sidebarFooterPlacer navigation et contenu, gérer le tiroir et les zones sûres.
Sidebaritems, activeKey, onNavigate, collapsed, width, railWidth, variantArbre, branches ouvertes, rail et sous-menus en feuille.
BottomBaritems, activeKey, onNavigate, maxItems, showLabels, variantOnglets, état courant et destinations supplémentaires via Plus.
RequireSessionsession, require, pending, fallback, forbiddenAttendre le store et ne monter le contenu qu’après validation.
StateScreentitle, description, code, loading, actionLabel, onActionComposer une attente, une page 404, un refus, une erreur ou un état vide.

navigationMode="auto" choisit le sidebar à partir de 768 unités et la bottom bar sur petit écran. bottom garde la barre basse ; sidebar utilise le sidebar sur grand écran et un tiroir sur petit écran ; drawer garde le tiroir. Le contenu reste au même endroit dans l’arbre React lorsque le mode ou le rail change : une saisie n’est pas remontée pour ce seul changement de présentation. Le clavier masque la bottom bar par défaut (hideBottomBarOnKeyboard={false} conserve son affichage) et une navigation ferme le clavier.

Chaque entrée accepte un shortLabel pour le libellé compact du bas (son nom accessible complet reste label), une icône React ou une fonction recevant color, active et size, un badge, des enfants, un état désactivé et une permission. Le header et le footer du sidebar peuvent être des fonctions recevant collapsed, pour adapter logo et actions au rail. sidebarProps et bottomBarProps exposent les réglages des composants depuis AppShell. Les variantes solid et floating utilisent les mêmes palettes SIA.

BottomBar limite les destinations visibles à cinq au maximum. Avec un débordement, le dernier onglet devient Plus et donne accès à l’arborescence complète. Sa sélection reflète aussi une destination active dans ce groupe. Le rail ouvre ses branches dans une feuille plutôt que de rendre les enfants inatteignables. Les libellés accessibles restent présents quand leur texte visuel est masqué.

Personnaliser la barre basse et ses transitions ​

La barre propose une capsule animée autour de l’icône active, des badges chiffrés (99+ au-delà de 99), une cible tactile d’au moins 48 unités par défaut et un focus visible. Le menu Plus utilise le même rendu et les mêmes animations que les autres onglets. Les noms accessibles restent complets, même avec des icônes seules.

tsx
<SiaExpoLayout
  session={session}
  items={navigation}
  navigationMode="bottom"
  screenOptions={{ animation: "fade", animationDuration: 300 }}
  bottomBarProps={{
    variant: "floating",
    appearance: "pill",
    labelVisibility: "active",
    iconSize: 24,
    height: 68,
    radius: 28,
    itemRadius: 18,
    horizontalInset: 16,
    gap: 2,
    colors: { active: "#0f766e", activeBackground: "#ccfbf1" },
    animation: {
      type: "spring", damping: 22, stiffness: 260, mass: 1,
      activeScale: 1.08, lift: 2, pressScale: 0.94,
    },
  }}
/>
RéglageUtilité
appearance: dock, pill, underline, minimalDock SIA avec sélection pleine derrière l’onglet (défaut), capsule derrière l’icône, trait en haut ou sélection uniquement par couleur.
labelVisibility: always, active, inactive, neverAfficher tous les libellés, celui de l’onglet actif, ceux des onglets inactifs ou les icônes seules ; showLabels reste compatible si ce réglage n’est pas fourni.
iconSize, height, radius, itemRadius, horizontalInset, gapAjuster la densité, les arrondis et l’espacement ; horizontalInset concerne la variante flottante.
colorsSurcharger background, border, active, inactive, activeBackground, badge, badgeText, sans changer tout le thème.
barStyle, itemStyle, activeItemStyle, labelStyle, activeLabelStyleAppliquer des styles ciblés au conteneur, aux onglets et aux libellés ; style reste celui de l’enveloppe avec la zone sûre.
renderIcon, renderLabelFournir un rendu recevant { item, active, color, size }, tout en gardant appui, nom accessible, sélection, menu Plus et filtrage SIA.
animation.typeRessort (spring, défaut), interpolation temporelle (timing) ou aucune animation (none).
animation.duration, animation.easingDurée en millisecondes et courbe SIA standard, entrance, exit, spring du mode timing.
animation.damping, stiffness, massRégler l’amortissement, la raideur et la masse du mode ressort.
animation.activeScale, lift, pressScaleRégler l’échelle sélectionnée, l’élévation de l’icône et le retour tactile à l’appui.

Les animations d’onglets utilisent le pilote natif pour les transformations et l’opacité. La réduction des animations du système ou du provider désactive ces transitions et les transitions de pages du navigateur privé par défaut. screenOptions de SiaExpoLayout accepte les options officielles du Stack Expo Router, sous forme d’objet ou de fonction par écran. Les options comme la durée et les gestes dépendent de la plateforme et de la transition native choisie : animationDuration n’est pas appliqué uniformément sur Android et iOS. Si un navigateur personnalisé est fourni via children, ses transitions se configurent sur ce navigateur plutôt que via screenOptions du layout.

Dans la démo, Personnaliser → Barre basse / Couleurs de la barre basse / Animations de navigation permet de régler ces éléments, de changer les transitions entre pages et de retrouver ses choix après relancement. La démo emploie les icônes SIA SVG partagées avec le web, avec react-native-svg comme moteur natif.

Couleurs locales et portails ​

tsx
<SiaNativeProvider mode="dark" colors={{
  light: { primary: '#0f766e' },
  dark: { primary: '#2dd4bf', background: '#071d1c' },
}}>
  {children}
</SiaNativeProvider>

Le provider fusionne les palettes avec les tokens, calcule le texte du primaire si nécessaire et utilise ScopedVariables d’Uniwind. Les classes et les valeurs inline lisent donc les mêmes couleurs. Deux arbres de providers ne modifient pas un thème global partagé. NativeThemeScope rétablit ces variables dans les portails web ; les modales et le tiroir SIA l’utilisent automatiquement. L’application peut l’utiliser pour ses propres portails. Les couleurs personnalisées doivent rester lisibles ; les erreurs conservent le rouge sémantique tant que danger est inchangé.

Démonstration complète ​

bash
pnpm native

La démo utilise désormais de vraies pages Expo Router. Ouvrir une session locale comme Membre ou Administrateur, puis essayer :

  1. la galerie et le Switch SIA personnalisé ;
  2. le formulaire, ses erreurs rouges et sa sélection recherchable ;
  3. le bouton Personnaliser dans l’en-tête : navigation, rail, variante flottante, clair/sombre/système, palettes et couleurs hexadécimales ;
  4. la conservation d’une saisie en changeant les réglages depuis ce panneau ;
  5. Compte : déconnexion, expiration et profil incomplet ;
  6. l’accès direct à /admin comme membre, puis avec le rôle administrateur ;
  7. Aide : page inexistante et retour vers l’accueil ;
  8. le rechargement pour vérifier préférences et compte local, puis la déconnexion.

Les transitions d’écran de la démo utilisent le Stack natif et suivent la préférence de mouvement réduit. Metro suit les sources de la bibliothèque sur les trois plateformes ; native:prepare construit les fondations et le thème avant le démarrage.

Le compte local et les préférences passent par AsyncStorage, uniquement dans la démo. Ils ne constituent pas une authentification réelle et ne contiennent aucun jeton ou mot de passe. Le composant réutilisable ne dépend pas d’AsyncStorage. Une application réelle branche son store SIA déjà connecté à son API ou SDK.

La page +not-found.tsx fournit le rendu 404. Un layout sous SiaNativeProvider peut réutiliser directement la récupération d’erreur :

tsx
export { SiaExpoErrorBoundary as ErrorBoundary } from '@sia-ui/react-native/expo-router';

La démo contient une page d’erreur volontaire, un bouton Réessayer et une boundary racine de secours. Les détails techniques de l’exception ne sont pas montrés. La boundary du groupe privé conserve le provider, les préférences et la session. Pour l’export web single, configurer l’hébergement pour renvoyer index.html sur les routes clientes. Le rendu 404 du navigateur ne fixe pas à lui seul le statut HTTP du serveur.

Validation et limites ​

Les tests couvrent état courant, branches du rail, débordement, droits hérités, attente de session, accès direct, reprise interne, palettes isolées et conservation de saisie lors d’un changement de navigation. L’export Metro/Hermes vérifie Android, iOS et web ; les essais navigateur portent sur l’aperçu web.

Restant sur appareils : liens profonds natifs, Retour Android, lecteurs d’écran, focus du tiroir, clavier, grandes tailles de texte, zones sûres et fluidité. Les composants restent expérimentaux. Ce lot n’ajoute pas de cache métier, de gestion de jetons serveur, de recherche distante ni de gestes de navigation avancés.

Le tiroir AppShell regroupe la marque et la fermeture dans un seul en-tête. Sa navigation reste sans marges flottantes pour tenir dans la largeur disponible ; la variante flottante reste applicable à la sidebar persistante. SiaExpoStack masque son en-tête par défaut pour laisser le layout SIA afficher celui de l’application. Un screenOptions.headerShown explicite reste prioritaire.

Le fond du tiroir et son voile couvrent toute la fenêtre, y compris les zones système sur Android. Les insets haut/bas sont appliqués à l’intérieur du panneau pour protéger les commandes sans laisser de bandes vides autour du tiroir.

Présentation Dock SIA ​

La barre utilise une surface plus discrète, un arrondi de 24, des marges de 12 et un espacement de 8 entre les cibles. Les onglets gardent une cible minimale de 48, avec une hauteur de base de 56 et des libellés de 12. La hauteur peut grandir avec le texte système. Le dock remplit l’onglet actif avec la couleur principale ; sa couleur de contenu est calculée avec readableOn, sauf surcharge colors.active. colors.activeBackground, itemRadius, les styles et les rendus restent personnalisables. Les autres apparences restent disponibles.

tsx
<BottomBar
  items={navigation}
  activeKey={activeKey}
  onNavigate={navigate}
  variant="floating"
  appearance="dock"
  labelVisibility="inactive"
/>

Avec inactive, le libellé de l’onglet sélectionné s’efface et ceux des autres restent visibles. L’espace des libellés est réservé pour éviter un changement de hauteur et tous les onglets conservent leur nom accessible complet. Les animations utilisent seulement transformations et opacité, avec une échelle de 1,04 et sans saut vertical par défaut. Les zones sûres et le masquage au clavier sont conservés.

La démo propose Dock SIA et Onglets inactifs dans les réglages. L’ancien préréglage non personnalisé (capsule, arrondi 28, hauteur 64) est migré une seule fois ; les autres configurations et les couleurs choisies sont conservées.

Publié sous licence MIT.