---
title: Navigation navigateur
slug: oip-next/P6-k-na
icon: {"lucideIcon":"📘"}
createdAt: 2026-06-24T17:01:46.000Z
---

# 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.

```javascript
// 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` :

:::CodeblockTabs
index.js

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

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

App.jsx

```javascript
import { Router } from "@fasstech/oip-starter-utils/app";
import views from "../views/views.mjs";

export const App = () => {
  // .. some logic

  return (
    <SomeProvider>
      <Router views={views} browserNavigationMode="standard" />
    </SomeProvider>
  );
};
```
:::

# 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.&#x20;

À 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 :

1. 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 ;
2. **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 ;
3. `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 ;
4. Lorsque le serveur répond, `context.viewId` est mis à jour, ce qui déclenche l'effet `viewId` ;
5. 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.

## Exemple de navigation

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.

```markdown
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 :

1. 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 ;
2. **Bounce-back immédiat** : `history.go(-delta)` est appelé pour ramener le navigateur à sa position courante. L'affichage ne change pas ;
3. `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 ;
4. Lorsque le serveur répond, `context.viewId` est mis à jour, ce qui déclenche l'effet `viewId` ;
5. 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.

:::BlockQuote
**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.
:::

## Exemple de navigation

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

```markdown
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)
```

# Bloquer la navigation navigateur pour une vue spécifique

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.

:::BlockQuote
**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

:::CodeblockTabs
MyView\.jsx

```javascript
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`.
