datakeen-session-react 1.1.140-rc.21 → 1.1.140-rc.23

package/docs/multi-runs.md

@@ -0,0 +1,100 @@
+# Multi-runs — Pré-remplissage par run avec `userInputList`
+
+## Vue d'ensemble
+
+Un parcours peut contenir une **boucle** : un nœud `condition` avec `conditionFalseMode: "loop"` pointe via son edge "false" vers un nœud antérieur (ex: `information-input`). Cela permet de faire saisir des données à plusieurs personnes successivement dans la même session (ex: déclaration de plusieurs bénéficiaires).
+
+Ce guide explique comment pré-remplir le formulaire différemment à chaque passage.
+
+---
+
+## Convention `_list`
+
+À la **création de session**, l'intégrateur peut passer un tableau de pré-remplissages via la clé réservée `_list` dans `userInput` :
+
+```json
+POST /backend/api/v1/session
+{
+  "journeyId": "...",
+  "userInput": {
+    "_list": [
+      { "firstName": "Alice", "lastName": "Dupont" },
+      { "firstName": "Bob",   "lastName": "Martin" }
+    ]
+  }
+}
+```
+
+- `_list[0]` → pré-rempli au **1er passage** sur le nœud
+- `_list[1]` → pré-rempli au **2e passage**
+- Si l'index est hors borne → **formulaire vide** (pas de reprise des valeurs du run précédent)
+
+> **Aucun changement de schéma backend requis.** La clé `_list` est stockée dans le champ `userInput` (Json) existant.
+
+---
+
+## Compteur de run
+
+Le SDK utilise `session.retryCounts[nodeId]` comme **index du run courant** (0-indexed).
+
+Ce champ est déjà géré automatiquement :
+- incrémenté par `ConditionNodeHandler` lorsque la condition évalue à `false` et `conditionFalseMode: "loop"` navigue en arrière
+- persisté en base via `PATCH /session/sdk/:id`
+
+Il n'y a **rien à configurer** — le SDK sélectionne automatiquement la bonne entrée de `_list`.
+
+---
+
+## Comportement détaillé
+
+| Situation | `initialUserInput` reçu par le formulaire |
+|-----------|------------------------------------------|
+| `userInput` sans `_list` | `userInput` global (comportement inchangé) |
+| `_list` présent, run 0 | `_list[0]` |
+| `_list` présent, run 1 | `_list[1]` |
+| `_list` présent, run N ≥ longueur | `{}` (formulaire vide) |
+
+---
+
+## Retour arrière
+
+Le bouton "Retour" utilise `goBack()` qui remonte dans l'historique de navigation vers le **nœud précédent dans le graphe**. Il ne revient pas au run précédent sur le même nœud.
+
+---
+
+## Exemple de parcours complet
+
+```
+start → information-input → condition (loop si false) → end
+                   ↑_____________________|
+```
+
+Payload de création avec 2 personnes à déclarer :
+```json
+{
+  "journeyId": "journey-id",
+  "userInput": {
+    "_list": [
+      { "firstName": "Alice", "lastName": "Dupont", "birthDate": "1990-01-15" },
+      { "firstName": "Bob",   "lastName": "Martin", "birthDate": "1985-06-22" }
+    ]
+  }
+}
+```
+
+**Déroulé :**
+1. Run 0 → formulaire pré-rempli avec Alice → condition évalue les données → false → retour sur le formulaire
+2. Run 1 → formulaire pré-rempli avec Bob → condition évalue → true → fin
+3. Run 2 (si prévu) → formulaire vide
+
+---
+
+## Fichiers de référence
+
+| Fichier | Rôle |
+|---------|------|
+| `src/services/sessionService.ts` | `getRunPrefillData(userInput, runIndex)` |
+| `src/components/template/TemplateNodeRenderer.tsx` | Calcul de `initialUserInput` pour `information-input` |
+| `src/services/retryService.ts` | `getNodeRetryCount(session, nodeId)` |
+| `src/components/template/ConditionNodeHandler.tsx` | Incrémente `retryCounts` en mode loop |
+| `src/hooks/useStepNavigation.ts` | `goBack()` — retour au nœud précédent |

package/package.json

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