datakeen-session-react 1.1.140-dev.24 → 1.1.140-dev.25

package/docs/navigation-history.md

@@ -0,0 +1,138 @@
+# Navigation History — Guide développeur
+
+## Vue d'ensemble
+
+Le SDK gère la navigation entre les étapes d'un parcours via un système d'historique interne, implémenté dans `src/hooks/useStepNavigation.ts`. Il ne s'appuie **pas** sur React Router ou l'historique du navigateur.
+
+---
+
+## Architecture
+
+### Représentation de l'état
+
+```typescript
+step: number          // étape courante (0 = écran de démarrage, 1+ = nœuds du template)
+history: number[]     // pile d'étapes visitées, ex: [0, 1, 3, 4]
+```
+
+L'index des étapes est **1-based** pour les nœuds du template : le nœud à l'index 0 dans `getOrderedJourneySteps()` correspond au step `1`.
+
+### Les 4 primitives exposées via `stepObject`
+
+| Primitive | Description |
+|-----------|-------------|
+| `step` | Étape courante |
+| `setStep(n, skipHistory?)` | Navigue vers l'étape `n`. Par défaut ajoute `n` à l'historique sauf si `skipHistory = true` |
+| `goBack()` | Dépile l'historique et navigue vers l'étape précédente |
+| `goToNextStep(nodeId, template, handle?)` | Suit le graphe d'edges depuis `nodeId` pour déterminer la prochaine étape |
+| `canGoBack` | `true` si `history.length > 1` |
+
+---
+
+## Cycle de vie de l'historique
+
+### 1. Initialisation
+
+Au montage, l'historique est initialisé à `[0]` (état d'attente de `initialStep`).
+
+Quand `initialStep` arrive depuis la base de données (via l'API), le hook initialise **une seule fois** (`hasInitialized.current`). Il distingue deux cas :
+
+```
+histoire déjà > 1 élément   →  l'utilisateur a navigué avant l'arrivée d'initialStep
+                                → l'historique existant est conservé
+
+histoire = 1 élément         →  reprise de session (page rouverte à mi-parcours)
+                                → l'historique est reconstruit via le graphe
+                                → reconstructHistoryToStep(initialStep, template)
+```
+
+### 2. Navigation forward
+
+`goToNextStep` suit les edges du template (définis dans `template.edges`) pour trouver l'index du nœud suivant. Il appelle ensuite `setStep(nextIndex)`, qui ajoute l'index à l'historique :
+
+```
+[0] → [0, 1] → [0, 1, 3] → [0, 1, 3, 4]
+```
+
+> Note : les indexes ne sont pas nécessairement consécutifs (+1) car le graphe peut avoir des sauts ou des branches.
+
+### 3. Navigation backward — `goBack()`
+
+`goBack()` dépile l'historique et saute automatiquement les nœuds **auto-exécutants** :
+
+```typescript
+const AUTO_EXECUTING_TYPES = new Set(["external-verification", "condition"]);
+```
+
+Exemple avec un nœud `condition` au step 3 :
+
+```
+history: [0, 1, 3, 4]
+
+1. pop() → candidate: 3 (condition) → skipped
+2. pop() → candidate: 1 (information-input) → stop
+
+→ navigation vers step 1
+```
+
+`setStep` est appelé avec `skipHistory = true` pour ne pas polluer l'historique lors d'un retour.
+
+### 4. Déduplication
+
+`setStep` ne pousse jamais deux fois le même index consécutivement :
+
+```typescript
+setHistory((prev) => {
+  if (prev[prev.length - 1] === newStep) return prev;
+  return [...prev, newStep];
+});
+```
+
+Cela évite le doublon `[..., 4, 4]` qui se produisait quand `initialStep` arrivait de l'API alors que l'utilisateur était déjà sur ce step.
+
+---
+
+## Reconstruction de l'historique (`reconstructHistoryToStep`)
+
+Définie dans `src/services/sessionService.ts`, cette fonction est utilisée lors d'une reprise de session.
+
+Elle suit les edges par défaut (première edge sortante de chaque nœud) depuis le step 0 jusqu'à `targetStep` :
+
+```typescript
+reconstructHistoryToStep(4, template)
+// → [0, 1, 2, 3, 4]  si le chemin linéaire existe dans le graphe
+// → [0, 4]           fallback si le graphe ne peut pas atteindre targetStep
+```
+
+> **Limitation** : la reconstruction suit toujours la première edge sortante de chaque nœud. Si le parcours réel a emprunté une branche conditionnelle (ex: `condition → true`), l'historique reconstruit peut différer du parcours original. Le retour sera correct tant que les nœuds intermédiaires sont rendus correctement.
+
+---
+
+## Pièges courants
+
+### Ne pas utiliser `setStep(step - 1)` pour le bouton retour
+
+```typescript
+// INCORRECT — décrémentation arithmétique, ignore le graphe réel
+const goOnPreviousStep = () => setStep(step - 1);
+
+// CORRECT — utilise l'historique
+const goOnPreviousStep = () => goBack();
+```
+
+`step - 1` peut pointer vers un step inexistant (si les indexes ne sont pas consécutifs), ou sauter par-dessus des nœuds auto-exécutants qui doivent être ignorés.
+
+### Ne pas appeler `setStep` directement depuis un composant pour naviguer en avant
+
+Préférer `goToNextStep(node.id, template)` qui résout automatiquement l'index suivant via le graphe. `setStep` est réservé aux cas où l'index de destination est déjà connu (ex: reprise de session, `goBack`).
+
+---
+
+## Fichiers de référence
+
+| Fichier | Rôle |
+|---------|------|
+| `src/hooks/useStepNavigation.ts` | Implémentation complète de l'historique |
+| `src/services/sessionService.ts` | `getOrderedJourneySteps`, `getNextStepIndex`, `reconstructHistoryToStep` |
+| `src/hooks/useUserInputForm.ts` | Exemple d'utilisation de `goBack()` dans un formulaire |
+| `src/components/session/ContactInfoForm.tsx` | Autre exemple de bouton retour correct |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datakeen-session-react",
-  "version": "1.1.140-dev.24",
+  "version": "1.1.140-dev.25",
   "description": "React SDK component to manage and render Datakeen session experiences easily.",
   "publishConfig": {
     "access": "public",