Navigation navigateur

11 min

Vue d'ensemble

Les projets construits avec le framework OIP naviguent entre les vues via des transitions pilotées par le serveur. En parallèle, l'interface du navigateur WEB expose ses boutons Précédent et Suivant, que l'utilisateur peut activer à tout moment durant sa progression. Le framework OIP offre une navigation cohérente et configurable pour réconcilier ces deux sources de navigation et garantir la cohérence de l'état applicatif.

Le composant Router expose la prop browserNavigationMode qui contrôle comment les événements popstate (Précédent / Suivant du navigateur) sont traités. Trois modes sont disponibles :

standard (défaut) : la navigation navigateur déclenche une transition en ciblant directement la vue encodée dans l'entrée d'historique correspondante. La pile d'historique est réutilisée telle quelle, sans ajout d'entrées supplémentaires ;

oip : la navigation navigateur transite par le moteur de transitions OIP (onPrev ou onNext selon la direction détectée). À chaque navigation, une nouvelle entrée est ajoutée en fin de pile d'historique ;

disabled : toute tentative de navigation navigateur est annulée silencieusement, sans appel serveur ni changement de vue.

Le hook useBlockBrowserNav permet de bloquer ponctuellement la navigation navigateur pour une vue spécifique, indépendamment du mode configuré sur le Router.

Prérequis

Un projet utilisant le framework OIP ;

Version 4.1.0 ou supérieure de la bibliothèque @fasstech/oip-starter-utils ;

L'utilisation du composant Router exposé par la bibliothèque @fasstech/oip-starter-utils.

Configuration

La navigation navigateur se configure via la prop browserNavigationMode du composant <Router>. En l'absence de cette prop, le mode standard est utilisé par défaut.

// Mode standard (défaut)
<Router views={views} browserNavigationMode="standard" />

// Mode OIP
<Router views={views} browserNavigationMode="oip" />

// Navigation navigateur désactivée
<Router views={views} browserNavigationMode="disabled" />

Le mode disabled désactive complètement la navigation navigateur de manière silencieuse : à chaque clic sur Précédent ou Suivant, le navigateur est immédiatement remis à sa position courante via history.go(), sans déclencher d'appel serveur ni de changement de vue. L'état applicatif reste intact.

Exemple de configuration

Le composant App est passé en paramètre à la fonction start dans le fichier index.js et implémente le composant Router :

import { start as startApp } from '@fasstech/oip-starter-utils/app';
import { App } from './App';

(async () => {
  startApp({
    app: App,
    // ...
  });
})();

Mode standard

En mode standard, la navigation navigateur est traitée comme une transition directe vers la vue cible encodée dans l'entrée d'historique. C'est le mode recommandé pour les OAV qui souhaitent respecter le comportement de navigation standard WEB.

À noter que dans ce mode, lors d'une navigation navigateur, le moteur de transition OIP et le workflow des vues défini dans le dossier transitions sont ignorés : le navigateur se déplace sur l'entrée relative de la pile d'historique et charge la vue correspondante.

Fonctionnement détaillé

Lorsque l'utilisateur appuie sur Précédent ou Suivant :

L'événement popstate se déclenche. Le Router lit __oipIdx (compteur monotone permettant de détecter la direction) et __oipViewId (identifiant de la vue cible) depuis l'entrée d'historique de destination ;

Bounce-back immédiat : history.go(-delta) est appelé pour ramener le navigateur à sa position courante pendant le traitement serveur. L'affichage ne change pas — le rendu est piloté par context.viewId, jamais par l'URL ;

goTo(destViewId, viewData) (handler interne) est envoyé au serveur. Si l'entrée d'historique possède un __oipViewDataKey, les données de vue associées à cette position (stockées en sessionStorage lors de la navigation initiale vers cette entrée) sont transmises à goTo. Chaque entrée d'historique possède sa propre clé UUID, ce qui permet à une même vue présente à plusieurs positions dans la stack de restaurer des données indépendantes ;

Lorsque le serveur répond, context.viewId est mis à jour, ce qui déclenche l'effet viewId ;

L'effet viewId détecte que destIdxRef est renseigné et appelle history.go(delta) pour déplacer le navigateur vers l'entrée d'historique existante, sans créer de nouvelle entrée. oipIdxRef est mis à jour en conséquence.

La pile d'historique n'est jamais étendue lors d'une navigation navigateur en mode standard : le navigateur se déplace simplement vers une entrée déjà présente dans la stack.

Scénario : l'utilisateur a navigué dans l'ordre Vue A → Vue B → Vue C via les transitions OIP. La pile d'historique contient trois entrées.

Etat initial
------------------------------------------------------------
[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                                              ^
                                   position actuelle (oipIdx=2)


Etape 1 – L'utilisateur appuie sur Précédent
------------------------------------------------------------
  Le navigateur se déplace sur l'entrée Vue B (idx=1).
  popstate déclenché : destIdx=1, delta=-1.

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                        ^
                 position navigateur (temporaire)


Etape 2 – Bounce-back : history.go(1)
------------------------------------------------------------
  Le navigateur revient sur Vue C (idx=2).
  L'affichage reste sur Vue C pendant le traitement serveur.

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                                              ^
                                  position restaurée temporairement


Etape 3 – goTo("Vue B") envoyé au serveur
          Serveur répond : context.viewId = "Vue B"
          viewId effect déclenché.
------------------------------------------------------------
  destIdxRef=1 → history.go(-1), navigateur se déplace sur Vue B.
  oipIdx mis à jour à 1.

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                        ^
                 position finale (oipIdx=1)

  La pile est inchangée. L'entrée Vue C reste accessible via Suivant.

Mode OIP

En mode oip, la navigation navigateur est traitée comme une transition OIP classique : Précédent appelle onPrev, Suivant appelle onNext. Le serveur évalue et détermine la vue de destination selon le workflow de vues défini. C'est le mode adapté aux OAV qui souhaitent respecter le moteur de transition OIP lors d'une navigation navigateur.

Fonctionnement détaillé

Lorsque l'utilisateur appuie sur Précédent ou Suivant :

L'événement popstate se déclenche. Le Router lit __oipIdx depuis l'entrée d'historique de destination pour calculer delta = destIdx - oipIdxRef. Un delta négatif indique un appui sur Précédent, un delta positif indique un appui sur Suivant ;

Bounce-back immédiat : history.go(-delta) est appelé pour ramener le navigateur à sa position courante. L'affichage ne change pas ;

onPrev() ou onNext() est appelé selon la direction. Les arguments sont toujours un objet vide {} — transitionData et resolvedViewData ne sont pas transmis lors d'une navigation navigateur ;

Lorsque le serveur répond, context.viewId est mis à jour, ce qui déclenche l'effet viewId ;

L'effet viewId appelle history.pushState, ce qui ajoute une nouvelle entrée en fin de pile d'historique. oipIdxRef est incrémenté.

Contrairement au mode standard, la pile d'historique grossit à chaque navigation navigateur. Le bouton Suivant est inaccessible après chaque navigation navigateur car le pushState écrase l'historique en avant.

Important : pour des raisons techniques et de sécurité transitionData et resolvedViewData ne sont jamais transmis lors d'une navigation navigateur en mode oip ; les handlers onPrev et onNext reçoivent toujours {}. L'événement popstate est émis par le navigateur indépendamment du composant de vue affiché : Router l'écoute au niveau global et ne dispose d'aucune référence au composant courant au moment du déclenchement. En conséquence, chaque navigation navigateur en mode oip est traitée comme une transition nue, sans contexte formulaire : si la logique d'évaluation dépend de données saisies dans la vue, elle ne s'exécutera pas comme prévu lors d'une navigation navigateur. Cette contrainte doit être prise en compte lors du choix du mode de navigation.

Scénario : l'utilisateur a navigué dans l'ordre Vue A → Vue B → Vue C via les transitions OIP.

Etat initial
------------------------------------------------------------
[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                                              ^
                                   position actuelle (oipIdx=2)


Etape 1 – L'utilisateur appuie sur Précédent
------------------------------------------------------------
  Le navigateur se déplace sur l'entrée Vue B (idx=1).
  popstate déclenché : destIdx=1, delta=-1.

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                        ^
                 position navigateur (temporaire)


Etape 2 – Bounce-back : history.go(1)
------------------------------------------------------------
  Le navigateur revient sur Vue C (idx=2).
  L'affichage reste sur Vue C pendant le traitement serveur.

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) ]
                                              ^
                                  position restaurée temporairement


Etape 3 – onPrev({}) envoyé au serveur
          Serveur répond : context.viewId = "Vue B"
          viewId effect déclenché → pushState (oipIdx=3)
------------------------------------------------------------
  Une nouvelle entrée Vue B est ajoutée en fin de pile.
  oipIdx mis à jour à 3.

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) | Vue B (idx=3) ]
                                                              ^
                                                  position finale (oipIdx=3)

  La pile s'est étendue. L'entrée Vue C (idx=2) n'est plus accessible via Suivant.


Etape 4 – L'utilisateur appuie à nouveau sur Précédent
------------------------------------------------------------
  popstate déclenché : destIdx=2, delta=-1.
  Bounce-back, puis onPrev({}) envoyé au serveur.
  Serveur répond : context.viewId = "Vue A"
  pushState (oipIdx=4)

[ Vue A (idx=0) | Vue B (idx=1) | Vue C (idx=2) | Vue B (idx=3) | Vue A (idx=4) ]
                                                                               ^
                                                                 position finale (oipIdx=4)

Le hook useBlockBrowserNav permet de bloquer la navigation navigateur (Précédent / Suivant) pour la durée de vie d'un composant monté. Lorsque le bloc est actif, toute tentative de navigation navigateur est annulée silencieusement via un bounce-back, sans appel serveur ni changement de vue.

Ce hook est efficace en mode oip et standard. En mode disabled, la navigation est déjà bloquée globalement et useBlockBrowserNav n'a aucun effet supplémentaire.

Avertissement : un seul appel actif de useBlockBrowserNav par arbre de vue est supporté. Si plusieurs composants appellent ce hook simultanément, c'est le dernier à se démonter qui l'emporte : son cleanup positionne blockedRef à false, débloquant silencieusement la navigation même si d'autres consommateurs sont encore montés et actifs. Appelez ce hook une seule fois, dans le composant de vue de plus haut niveau.

Exemple d'implémentation dans une vue

import { useState } from "react";
import { useProcess, useBlockBrowserNav } from "@fasstech/oip-starter-utils/app";

const MyView = () => {
  const { context, processHandlers } = useProcess();
  const [isDirty, setIsDirty] = useState(false);

  // Block always
  useBlockBrowserNav();

  // OR Block conditionally (e.g. unsaved changes)
  useBlockBrowserNav(isDirty);

  return (
    <div>
      <h1>MY FORM</h1>
      ...
    </div>
  );
};

Dans cet exemple :

useBlockBrowserNav() sans argument bloque en permanence la navigation navigateur tant que MyView est monté. C'est utile pour les vues qui nécessitent de bloquer la navigation navigateur de manière permanente et inconditionnelle ;

useBlockBrowserNav(isDirty) conditionne le blocage à la valeur de isDirty. Tant que l'utilisateur n'a pas sauvegardé ses modifications (isDirty === true), la navigation navigateur est bloquée. Dès que isDirty repasse à false, le bloc est automatiquement levé sans démontage du composant.

Dans les deux cas, le blocage est levé automatiquement au démontage du composant via le cleanup de l'effet.

Résumé

Le mode de navigation navigateur se configure via la prop browserNavigationMode de <Router> ; le mode standard est actif par défaut ;

En mode standard, la navigation navigateur déclenche directement une transition vers la vue cible et le viewData extraits de l'entrée d'historique. La pile d'historique n'est jamais étendue lors d'une navigation navigateur — le navigateur se déplace vers une entrée existante ;

En mode oip, la navigation navigateur appelle onPrev ou onNext selon la direction. Une nouvelle entrée est ajoutée à la pile à chaque navigation navigateur. transitionData et resolvedViewData ne sont pas transmis ;

En mode disabled, toute navigation navigateur est annulée silencieusement sans appel serveur ni changement de vue ;

Le hook useBlockBrowserNav bloque la navigation navigateur pour une vue spécifique, tant que le composant est monté. Il accepte un paramètre booléen optionnel (true par défaut) pour un blocage conditionnel ;

useBlockBrowserNav ne doit être appelé qu'une seule fois par arbre de vue : plusieurs appels simultanés produisent un comportement imprévisible au démontage ;

Le rendu est toujours piloté par context.viewId (état serveur), jamais par l'URL du navigateur. L'URL est maintenue en synchronisation via pushState et replaceState.

Navigation navigateur

Vue d'ensemble

Prérequis

Configuration

Exemple de configuration

Mode standard

Fonctionnement détaillé

Exemple de navigation

Mode OIP

Fonctionnement détaillé

Exemple de navigation

Bloquer la navigation navigateur pour une vue spécifique

Exemple d'implémentation dans une vue

Résumé