@eifi1/ui-kit 0.51.4 → 0.51.5

package/dist/tour/use-tour-progress.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tour/use-tour-progress.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport { readStored, removeStored, writeStored } from \"../lib/safe-storage\";\nimport { httpStatusOf } from \"../auth/auth-errors\";\nimport { isTourDone, type TourCompletions } from \"./tour-info\";\n\n/**\n * Which tours this device has completed (docs/tours-harmonization.md §2.6, §6.2) —\n * keksdose's `tour-progress-store` and kastlan's `completions.ts`, as one hook.\n *\n * - **Device storage, the app's key.** `storageKey` is always the app's: an app on shared\n *   devices scopes it per account (KS, bench PCs), and an app that lists its keys\n *   (KS `storage-keys.ts`) spells it there. Every access is guarded: a blocked or full\n *   storage keeps the marks for this page's life instead of throwing.\n * - **One store, every reader.** A change notifies every hook on the same key in this tab\n *   (an in-tab emitter) and in other tabs (the `storage` event), so the tours page and\n *   `TourMenu` agree without a reload (ka F3).\n * - **`migrate(raw)`** reads an older shape, so nobody loses their done marks at adoption:\n *   it gets the stored JSON (or the raw text, if it is no JSON) and returns the record for\n *   a shape it recognises, `undefined` for any other — the kit's own shape included,\n *   which it then reads itself. keksdose: zustand's `{state: {completed}, version: 1}`;\n *   kastlan: an array of ids, completed without a date (`null`). It runs only on a stored\n *   text that is not the kit's shape already, once per text and key. The FIRST `migrate`\n *   any reader, `TourProvider` or {@link completeTour} passes for a key is remembered for\n *   that key (later identities are ignored), so a reader without one, mounted first, no\n *   longer hides the old marks from the rest (keksdose B-2). **Still, define the options\n *   once, at module level, and hand the provider and every reader the same object.**\n * - **Never overwritten unread** (keksdose B-1): a write (`complete`, the provider's,\n *   `completeTour`) on a stored text that is neither empty nor the kit's shape, and that no\n *   known `migrate` reads, THROWS instead of replacing the old marks.\n * - **Resetting the device** (settings §11): register the key with `reset: () =>\n *   resetTourProgress(storageKey)`, which clears storage and the page's memory and tells\n *   every reader in this tab.\n *\n * **The stored shape** (§9.3, §9.6.6), for an app's tests and seeds: the JSON record\n * `{ [id]: ISO instant | \"\" }` under `storageKey`, where `\"\"` is a completion without a\n * date (a migrated record: kastlan's id list). That is the one written form; the hooks\n * and callbacks (`completed`, `TourCompletions`) give `null` for `\"\"`. A `null` read from\n * storage (or returned by `migrate`) is accepted as the same thing and written back as\n * `\"\"`. To write a completion from outside a page, use {@link completeTour}.\n *\n * **On the account** (0.45, §10.2–§10.3): with `account`, the device key becomes the\n * account's CACHE — see {@link TourProgressAccount}. Without it, nothing changes from 0.44.\n */\nexport interface UseTourProgressOptions {\n  storageKey: string;\n  migrate?: (raw: unknown) => Record<string, string | null> | undefined;\n  /**\n   * 0.45: the account's record behind the device key (§10.2.4). Remembered per key like\n   * `migrate` (the FIRST one any reader or the provider passes wins). With it,\n   * `storageKey` must be per account (a prefix plus the user id), so build the options per\n   * account and keep ONE stable object per key — memoise them in a `Map` by user id — and\n   * let `load`/`save` read the current token when they run, never capture one:\n   *\n   *     const byUser = new Map<string, UseTourProgressOptions>();\n   *     function tourProgressFor(user: { id: string; isDemo: boolean } | null) {\n   *       if (!user || user.isDemo) return { storageKey: \"app.tours.completions\" }; // no account\n   *       let options = byUser.get(user.id);\n   *       if (!options) byUser.set(user.id, (options = { storageKey: `app.tours.completions:${user.id}`, account }));\n   *       return options;\n   *     }\n   *\n   * Signed out, and in a demo, pass none (and a fixed key): the device record works as in\n   * 0.44, and a demo neither PATCHes into a 403 nor leaves an orphan key per demo id.\n   */\n  account?: TourProgressAccount;\n}\n\n/** The record on the wire (§10.2.2): tour id → ISO instant, or `\"\"` (done, no date). */\ntype TourProgressWire = Record<string, string>;\n\n/** The `PATCH /tours/progress` body (§10.2.2): what to mark done, and what to forget.\n *  An id is never in both. Either may be left out. */\nexport interface TourProgressBody {\n  completed?: TourProgressWire;\n  forget?: string[];\n}\n\n/**\n * Taking over a device-wide record from before the account (§10.2.5), on the FIRST load\n * of the account key on this page:\n * - `{storageKey, discard: true}` (kastlan): removes the old key and uploads nothing — a\n *   shared PC must not hand one person another's marks. Removing an absent key is a no-op.\n * - `{storageKey, migrate?}`: reads the old key once (through `migrate` for an older\n *   shape), uploads it to the first account that signs in on this device, then removes it.\n */\nexport type TourProgressAdopt =\n  | { storageKey: string; discard: true; migrate?: never }\n  | { storageKey: string; discard?: false; migrate?: UseTourProgressOptions[\"migrate\"] };\n\n/**\n * The app's account record (§10.3): `load()` is its `GET /tours/progress`, `save(body)`\n * its `PATCH`, each resolving to the parsed answer, `{completed}` — the whole record.\n *\n * - The page paints from the device key at once (and offline); the account is loaded on\n *   the first reader of the key on this page, on `online`, and after each save, and its\n *   answer replaces the cache.\n * - A write (`complete`, the provider's finish, `reset`) goes to the cache at once and to\n *   a PENDING record beside it, `<storageKey>:pending` (`{synced, completed, forget}`),\n *   sent as one PATCH and cleared by its answer. A failure with no answer (offline, 5xx,\n *   401) keeps it for the next load or `online`; a 402 (a lapsed plan) keeps it but sends it\n *   no more on this page (the next session or page load tries again); a 403 or 422 drops\n *   it and logs.\n * - `awarded` stays the device's answer against the cache (§10.2.4).\n * - The pending record is NOT the app's outbox: leave it out of any \"N waiting\" count\n *   and any sign-out guard (losing a tour mark is acceptable).\n * - A device record never synced (no `:pending` with `synced: true`) is uploaded whole on\n *   its first load, by the server's merge rule (later completion wins).\n * - On every end of a session call {@link signOutTourProgress}.\n */\nexport interface TourProgressAccount {\n  load: () => Promise<{ completed: TourProgressWire }>;\n  save: (body: TourProgressBody) => Promise<{ completed: TourProgressWire }>;\n  adopt?: TourProgressAdopt;\n}\n\n/** What `complete` takes: a tour id, or the tour (`{id, updated}`, a `TourInfo` fits). */\ntype CompletedTour = string | { id: string; updated?: { date: string } | null };\n\nexport interface TourProgress {\n  /** Tour id → the completion's ISO timestamp, or `null` when recorded without a date. */\n  completed: TourCompletions;\n  /**\n   * Record a completion. Keeps the FIRST completion's date, so a replay changes nothing —\n   * unless the tour was reset by an update since (§8): pass the tour (`{id, updated}`) and\n   * a completion from before `updated.date` is replaced by today's.\n   *\n   * Returns `true` when this counts as a new completion — the moment to award the tour's\n   * points and show the app's toast (§6.1) — and `false` for a replay.\n   *\n   * A tour started with `start(steps, {tour})` under a `TourProvider` that has `progress`\n   * is recorded by the provider (§9.6.2): do not call this from that start's `onFinish`\n   * too, or the second write answers `false`.\n   */\n  complete: (tour: CompletedTour) => boolean;\n  /** \"Mark as not done\": forget the completion. */\n  reset: (id: string) => void;\n}\n\n/* ── The store: one per key, shared by every hook ───────────────────────────── */\n\nconst EMPTY: TourCompletions = Object.freeze({});\n/** In-tab listeners per key. */\nconst listeners = new Map<string, Set<() => void>>();\n/** What this page wrote where storage refused to keep it (blocked, full): per key. */\nconst memory = new Map<string, string>();\n/**\n * The last raw text read per key and what it parsed to, so a snapshot keeps its identity:\n * the same text gives the same object, whichever reader asks and whatever `migrate` it\n * holds. Several readers of one key with inline `migrate` arrows used to evict each other\n * here and loop (kastlan B1, 0.43).\n */\nconst cache = new Map<string, { raw: string | null; value: TourCompletions; readable: boolean }>();\ntype Migrate = NonNullable<UseTourProgressOptions[\"migrate\"]>;\n/** Each key's migrate: the first one any reader, the provider or `completeTour` passes (B-2). */\nconst migrates = new Map<string, Migrate>();\n\n/**\n * Remember `migrate` for `key` if it is the first one, and return the key's migrate. A\n * snapshot parsed before the key had one is dropped and re-parsed, and the key's readers\n * hear of it after this render (never from inside one).\n * @internal Not part of the barrel; `TourProvider` registers its `progress` with it.\n */\nexport function rememberMigrate(key: string, migrate: UseTourProgressOptions[\"migrate\"]): Migrate | undefined {\n  if (migrate && !migrates.has(key)) {\n    migrates.set(key, migrate);\n    if (cache.delete(key)) queueMicrotask(() => emit(key));\n  }\n  return migrates.get(key);\n}\n\nfunction emit(key: string) {\n  listeners.get(key)?.forEach((listener) => listener());\n}\n\nfunction rawOf(key: string): string | null {\n  return memory.get(key) ?? readStored(key);\n}\n\n/** Is this the kit's own shape already: a record whose every value is a string or null? */\nfunction isKitShape(value: unknown): boolean {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n  return Object.values(value as Record<string, unknown>).every((at) => at === null || typeof at === \"string\");\n}\n\n/** The kit's own shape: a record of string or null; anything else is dropped. */\nfunction fromRecord(value: unknown): TourCompletions | undefined {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return undefined;\n  const out: Record<string, string | null> = {};\n  for (const [id, at] of Object.entries(value as Record<string, unknown>)) {\n    if (at === null || at === \"\") out[id] = null;\n    else if (typeof at === \"string\") out[id] = at;\n  }\n  return out;\n}\n\n/**\n * The record, and whether the text was READ (empty, the kit's shape, or a shape `migrate`\n * knows) rather than dropped: a write over an unread text would lose it (B-1).\n */\nfunction parse(raw: string | null, migrate: UseTourProgressOptions[\"migrate\"]): { value: TourCompletions; readable: boolean } {\n  if (raw === null || raw.trim() === \"\") return { value: EMPTY, readable: true };\n  let value: unknown = raw;\n  try {\n    value = JSON.parse(raw);\n  } catch {\n    // Not JSON: `migrate` still sees the text.\n  }\n  if (migrate && !isKitShape(value)) {\n    try {\n      const migrated = fromRecord(migrate(value));\n      if (migrated !== undefined) return { value: migrated, readable: true };\n    } catch {\n      // A migrate that throws reads as \"not a shape it knows\".\n    }\n  }\n  return { value: fromRecord(value) ?? EMPTY, readable: isKitShape(value) };\n}\n\nfunction snapshot(key: string, migrate: UseTourProgressOptions[\"migrate\"]): TourCompletions {\n  const known = rememberMigrate(key, migrate);\n  const raw = rawOf(key);\n  const hit = cache.get(key);\n  if (hit && hit.raw === raw) return hit.value;\n  const parsed = parse(raw, known);\n  cache.set(key, { raw, ...parsed });\n  return parsed.value;\n}\n\n/** The record a write builds on; throws rather than overwrite a text nobody could read (B-1). */\nfunction readForWrite(key: string, migrate: UseTourProgressOptions[\"migrate\"], own = false): TourCompletions {\n  // `own`: this migrate, even where the key registered another (completeTour's `{migrate}`).\n  const known = rememberMigrate(key, migrate);\n  const { value, readable } =\n    own && migrate && known !== migrate\n      ? parse(rawOf(key), migrate)\n      : { value: snapshot(key, migrate), readable: cache.get(key)?.readable };\n  if (!readable) {\n    throw new Error(\n      `[ui-kit] tour progress: the text stored under \"${key}\" is not the kit's shape and no migrate reads it; ` +\n        \"refusing to overwrite it. Pass the key's migrate (the shared useTourProgress / TourProvider options, \" +\n        \"or completeTour's {migrate}).\",\n    );\n  }\n  return value;\n}\n\n/** The one written form (§9.6.6): a completion without a date is stored as `\"\"`, never `null`. */\nfunction write(key: string, record: TourCompletions) {\n  const stored: Record<string, string> = {};\n  for (const [id, at] of Object.entries(record)) stored[id] = at ?? \"\";\n  const raw = JSON.stringify(stored);\n  writeStored(key, raw);\n  // Storage refused it (blocked, full): keep it for this page's life instead.\n  if (readStored(key) === raw) memory.delete(key);\n  else memory.set(key, raw);\n  emit(key);\n}\n\n/* ── The account behind the device key (0.45, §10.2.4–§10.2.8) ─────────────── */\n\n/** The key's account: the first one any reader or the provider passes (as `migrate`). */\nconst accounts = new Map<string, TourProgressAccount>();\n/** Keys whose account was loaded (or is loading) on this page: the first reader loads. */\nconst loaded = new Set<string>();\n/** Keys with a sync running, and those asked for another while it ran. */\nconst running = new Set<string>();\nconst rerun = new Set<string>();\n/** Keys with a sync queued for the end of this task: two writes in one handler, one PATCH. */\nconst queued = new Set<string>();\n/** Bumped by a sign-out: an answer that comes back after it never refills the cache. */\nconst epochs = new Map<string, number>();\n/** Keys whose PATCH got a 402 (a lapsed plan): the pending record is kept but not sent\n *  again on this page; the next session (or page load) tries once more. */\nconst parked = new Set<string>();\n/** The pending record where storage refused to keep it. */\nconst pendingMemory = new Map<string, string>();\nlet onlineListening = false;\n\n/** The pending record (§10.2.4): what waits to be sent, and whether the device key was\n *  ever synced. */\ninterface PendingRecord {\n  synced: boolean;\n  completed: TourProgressWire;\n  forget: string[];\n}\n\nconst pendingKey = (key: string) => `${key}:pending`;\n\nfunction devWarn(message: string) {\n  if (import.meta.env?.DEV) console.warn(message);\n}\n\n/**\n * Remember `account` for `key` if it is the first one, and return the key's account.\n * @internal Not part of the barrel; `TourProvider` registers its `progress` with it.\n */\nexport function rememberAccount(key: string, account: TourProgressAccount | undefined): TourProgressAccount | undefined {\n  if (account && !accounts.has(key)) {\n    accounts.set(key, account);\n    if (account.adopt && account.adopt.storageKey === key) {\n      devWarn(\n        `[ui-kit] tour progress: the account key \"${key}\" is the key \\`adopt\\` takes over. ` +\n          \"With an account the key must be per account (a prefix plus the user id), apart from the old device-wide key.\",\n      );\n    }\n    if (!onlineListening && typeof window !== \"undefined\") {\n      onlineListening = true;\n      window.addEventListener(\"online\", () => {\n        for (const known of loaded) void sync(known);\n      });\n    }\n  }\n  return accounts.get(key);\n}\n\nfunction readPending(key: string): PendingRecord | null {\n  const raw = pendingMemory.get(key) ?? readStored(pendingKey(key));\n  if (raw === null) return null;\n  try {\n    const value = JSON.parse(raw) as Partial<PendingRecord> | null;\n    if (!value || typeof value !== \"object\") return null;\n    const completed: TourProgressWire = {};\n    for (const [id, at] of Object.entries(value.completed ?? {})) {\n      if (typeof at === \"string\") completed[id] = at;\n      else if (at === null) completed[id] = \"\";\n    }\n    const forget = Array.isArray(value.forget) ? value.forget.filter((id): id is string => typeof id === \"string\") : [];\n    return { synced: value.synced === true, completed, forget };\n  } catch {\n    return null;\n  }\n}\n\nfunction writePending(key: string, record: PendingRecord) {\n  const raw = JSON.stringify(record);\n  writeStored(pendingKey(key), raw);\n  if (readStored(pendingKey(key)) === raw) pendingMemory.delete(key);\n  else pendingMemory.set(key, raw);\n}\n\nconst hasWork = (record: PendingRecord) => Object.keys(record.completed).length > 0 || record.forget.length > 0;\n\n/** \"Later completion wins\" (§10.2.3), as the server merges: an instant beats `\"\"`, `\"\"`\n *  beats nothing, and between two instants the later is kept. */\nfunction later(a: string | undefined, b: string): string {\n  if (a === undefined || a === \"\") return b;\n  if (b === \"\") return a;\n  return Date.parse(b) > Date.parse(a) ? b : a;\n}\n\n/** Note a completion (or, with `forget`, its removal) in the key's pending record. */\nfunction markPending(key: string, id: string, at: string | null | undefined, forget = false) {\n  const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };\n  if (forget) {\n    delete record.completed[id];\n    if (!record.forget.includes(id)) record.forget.push(id);\n  } else {\n    record.completed[id] = at ?? \"\";\n    record.forget = record.forget.filter((other) => other !== id);\n  }\n  writePending(key, record);\n}\n\n/** After an answer (or a 403/422): take what was sent out of the pending record, keeping\n *  what was written while the request ran. */\nfunction clearSent(key: string, sent: TourProgressBody, synced: boolean) {\n  const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };\n  for (const [id, at] of Object.entries(sent.completed ?? {})) {\n    if (record.completed[id] === at) delete record.completed[id];\n  }\n  const forgotten = new Set(sent.forget ?? []);\n  record.forget = record.forget.filter((id) => !forgotten.has(id));\n  record.synced = record.synced || synced;\n  writePending(key, record);\n}\n\n/** The account's answer as the cache, with what still waits to be sent laid over it. */\nfunction refill(key: string, answer: { completed: TourProgressWire } | null | undefined) {\n  const next: Record<string, string> = {};\n  for (const [id, at] of Object.entries(fromRecord(answer?.completed) ?? {})) next[id] = at ?? \"\";\n  const waiting = readPending(key);\n  if (waiting) {\n    for (const [id, at] of Object.entries(waiting.completed)) next[id] = later(next[id], at);\n    for (const id of waiting.forget) delete next[id];\n  }\n  const record: Record<string, string | null> = {};\n  for (const [id, at] of Object.entries(next)) record[id] = at === \"\" ? null : at;\n  write(key, record);\n}\n\n/** The first load of an account key on this page takes over the old device-wide key\n *  (§10.2.5). */\nfunction adoptOldRecord(key: string, account: TourProgressAccount) {\n  const adopt = account.adopt;\n  if (!adopt || adopt.storageKey === key) return;\n  const old = adopt.storageKey;\n  if (!adopt.discard) {\n    const { value } = parse(rawOf(old), adopt.migrate ?? migrates.get(old));\n    const entries = Object.entries(value);\n    if (entries.length > 0) {\n      const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };\n      for (const [id, at] of entries) record.completed[id] = later(record.completed[id], at ?? \"\");\n      writePending(key, record);\n    }\n  }\n  // Removed either way, at once: no second account on this device gets it.\n  removeStored(old);\n  memory.delete(old);\n  cache.delete(old);\n  emit(old);\n}\n\n/** A device record never synced is uploaded whole on its first load (§10.2.5). */\nfunction uploadUnsynced(key: string) {\n  const record = readPending(key);\n  if (record?.synced) return;\n  const device = snapshot(key, migrates.get(key));\n  const entries = Object.entries(device);\n  const next = record ?? { synced: false, completed: {}, forget: [] };\n  if (entries.length === 0 && record) return;\n  for (const [id, at] of entries) {\n    if (!next.forget.includes(id)) next.completed[id] = later(next.completed[id], at ?? \"\");\n  }\n  writePending(key, next);\n}\n\n/** The key's first sync on this page: take over the old record, upload a never-synced one. */\nfunction prepare(key: string) {\n  loaded.add(key);\n  adoptOldRecord(key, accounts.get(key)!);\n  uploadUnsynced(key);\n}\n\n/** Queue a sync for the end of this task, so a handler's writes go as one PATCH. */\nfunction queueSync(key: string) {\n  if (!loaded.has(key)) prepare(key);\n  if (queued.has(key)) return;\n  queued.add(key);\n  queueMicrotask(() => {\n    queued.delete(key);\n    void sync(key);\n  });\n}\n\n/** The first reader of an account key on this page loads it. */\nfunction ensureLoaded(key: string) {\n  if (!accounts.has(key) || loaded.has(key)) return;\n  prepare(key);\n  void sync(key);\n}\n\n/**\n * Send what waits (one PATCH) or, with nothing waiting, load; the answer replaces the\n * cache. One at a time per key; a request asked for while one runs follows it.\n */\nasync function sync(key: string): Promise<void> {\n  const account = accounts.get(key);\n  if (!account || !loaded.has(key)) return;\n  if (running.has(key)) {\n    rerun.add(key);\n    return;\n  }\n  if (typeof navigator !== \"undefined\" && navigator.onLine === false) return;\n  running.add(key);\n  const epoch = epochs.get(key) ?? 0;\n  try {\n    const waiting = readPending(key);\n    if (waiting && hasWork(waiting)) {\n      if (parked.has(key)) return;\n      const body: TourProgressBody = {};\n      if (Object.keys(waiting.completed).length > 0) body.completed = { ...waiting.completed };\n      if (waiting.forget.length > 0) body.forget = [...waiting.forget];\n      let answer: { completed: TourProgressWire };\n      try {\n        answer = await account.save(body);\n      } catch (error) {\n        const status = httpStatusOf(error);\n        if (status === 403 || status === 422) {\n          // Refused for good (a demo, a malformed or full record): dropped, not retried.\n          if ((epochs.get(key) ?? 0) === epoch) clearSent(key, body, false);\n          console.warn(`[ui-kit] tour progress: the account refused the pending record (${status}); dropped.`, error);\n        } else if (status === 402) {\n          // A lapsed plan refuses every write: kept, but not re-sent after each finish\n          // and each `online` — the next session or page load tries again.\n          parked.add(key);\n        }\n        // No answer (offline, 5xx, 401): it stays for the next load or `online`.\n        return;\n      }\n      if ((epochs.get(key) ?? 0) !== epoch) return;\n      clearSent(key, body, true);\n      refill(key, answer);\n    } else {\n      const answer = await account.load();\n      if ((epochs.get(key) ?? 0) !== epoch) return;\n      if (waiting && !waiting.synced) writePending(key, { ...waiting, synced: true });\n      else if (!waiting) writePending(key, { synced: true, completed: {}, forget: [] });\n      refill(key, answer);\n    }\n  } catch {\n    // A load that failed keeps the cache as it is.\n  } finally {\n    running.delete(key);\n    if (rerun.delete(key)) void sync(key);\n  }\n}\n\n/**\n * The end of a session (§10.2.6) — sign-out, a 401 nothing could renew, the account's\n * deletion, every path: removes the CACHE only (the device key and the page's snapshot;\n * every reader in this tab moves), synchronously and with no request, and KEEPS\n * `<storageKey>:pending`. That record sits under this person's own key, holds tour ids and\n * dates only, and goes out on their next sign-in. An answer still on its way is ignored.\n *\n *     function logout() { …; signOutTourProgress(`app.tours:${user.id}`); }\n */\nexport function signOutTourProgress(storageKey: string): void {\n  epochs.set(storageKey, (epochs.get(storageKey) ?? 0) + 1);\n  loaded.delete(storageKey);\n  rerun.delete(storageKey);\n  parked.delete(storageKey);\n  removeStored(storageKey);\n  memory.delete(storageKey);\n  cache.delete(storageKey);\n  emit(storageKey);\n}\n\nfunction subscribe(key: string, listener: () => void): () => void {\n  let set = listeners.get(key);\n  if (!set) listeners.set(key, (set = new Set()));\n  set.add(listener);\n  // Another tab wrote (or cleared all storage: `key` null).\n  const onStorage = (event: StorageEvent) => {\n    if (event.key !== null && event.key !== key) return;\n    memory.delete(key);\n    listener();\n  };\n  if (typeof window !== \"undefined\") window.addEventListener(\"storage\", onStorage);\n  return () => {\n    set.delete(listener);\n    if (typeof window !== \"undefined\") window.removeEventListener(\"storage\", onStorage);\n  };\n}\n\n/**\n * Forget every tour completion under `storageKey` on this device: the stored key, what the\n * page kept in memory where storage refused it, and every reader in this tab moves at\n * once. For \"Reset this device's settings\" (settings §11):\n *\n *     registerDeviceSetting({ key: TOUR_KEY, kind: \"view\", reset: () => resetTourProgress(TOUR_KEY) });\n *\n * With an account (0.45) it clears the cache only: the account is never written, the\n * pending record stays (\"anything waiting to be sent\", settings §11.2.2) and the next load\n * refills the cache. Tour progress is never registered with the device reset (§10.2.8).\n */\nexport function resetTourProgress(storageKey: string): void {\n  if (accounts.has(storageKey)) loaded.delete(storageKey);\n  removeStored(storageKey);\n  memory.delete(storageKey);\n  cache.delete(storageKey);\n  emit(storageKey);\n}\n\n/**\n * Record a completion under `storageKey`, as {@link TourProgress.complete} does: through\n * the one shared store and snapshot (never a copy), so every reader of the key moves.\n * Returns `true` when it counts anew. `TourProvider` calls this on a tour's last step.\n * @internal Not part of the barrel.\n */\nexport function completeStored(\n  storageKey: string,\n  migrate: UseTourProgressOptions[\"migrate\"],\n  tour: CompletedTour,\n): boolean {\n  const subject = typeof tour === \"string\" ? { id: tour } : tour;\n  // Read now rather than from a render: two completions in one handler both count.\n  const current = readForWrite(storageKey, migrate);\n  if (isTourDone(subject, current[subject.id])) return false;\n  const at = new Date().toISOString();\n  write(storageKey, { ...current, [subject.id]: at });\n  if (accounts.has(storageKey)) {\n    markPending(storageKey, subject.id, at);\n    queueSync(storageKey);\n  }\n  return true;\n}\n\n/** \"Mark as not done\" (§10.2.8): off the cache, and `forget` to the account. @internal */\nfunction resetStored(storageKey: string, migrate: UseTourProgressOptions[\"migrate\"], id: string) {\n  const current = snapshot(storageKey, migrate);\n  if (current[id] === undefined) return;\n  const next = { ...current };\n  delete next[id];\n  write(storageKey, next);\n  if (accounts.has(storageKey)) {\n    markPending(storageKey, id, undefined, true);\n    queueSync(storageKey);\n  }\n}\n\n/**\n * Write a completion from outside a page (§9.2): for an app's tests, seeds and scripts,\n * beside {@link resetTourProgress}. It writes the kit's stored shape (`{[id]: ISO | \"\"}`)\n * under `storageKey`, keeps the other tours' marks, and notifies every reader of the key\n * in this tab directly (the `storage` event reaches only OTHER tabs), so a mounted\n * `useTourProgress` or `TourCatalogue` moves at once.\n *\n * Unlike `complete`, it always writes (over a readable text; see below): `at` is the\n * completion's instant (an ISO string or a `Date`, default now), `null` a completion\n * without a date (stored as `\"\"`, read back as `null`).\n *\n *     completeTour(TOUR_KEY, \"budget\", \"2026-09-01T10:00:00Z\");\n *\n * A stored text in an app's older shape is read through `opts.migrate`, or else the\n * migrate a reader or the provider registered for the key. If the text is neither empty\n * nor the kit's shape and no migrate reads it, this THROWS and writes nothing (B-1):\n *\n *     completeTour(TOUR_KEY, \"budget\", undefined, { migrate: fromZustand });\n *\n * With an account on the key (0.45) it stays a device write — no request — and is marked\n * pending, so the next load sends it.\n */\nexport function completeTour(\n  storageKey: string,\n  tour: string | { id: string },\n  at?: string | Date | null,\n  opts?: { migrate?: UseTourProgressOptions[\"migrate\"] },\n): void {\n  const id = typeof tour === \"string\" ? tour : tour.id;\n  const when = at === null ? null : at instanceof Date ? at.toISOString() : (at ?? new Date().toISOString());\n  write(storageKey, { ...readForWrite(storageKey, opts?.migrate, true), [id]: when });\n  if (accounts.has(storageKey)) markPending(storageKey, id, when);\n}\n\n/** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */\nexport function useTourProgress({ storageKey, migrate, account }: UseTourProgressOptions): TourProgress {\n  // Held, not depended on: an inline arrow is a new function every render, and neither the\n  // snapshot nor the callbacks may change with it.\n  const migrateRef = useRef(migrate);\n  useEffect(() => {\n    migrateRef.current = migrate;\n  });\n  // The first account for the key wins (as `migrate`); its first reader on the page loads.\n  const accountRef = useRef(account);\n  useEffect(() => {\n    accountRef.current = account;\n  });\n  useEffect(() => {\n    if (rememberAccount(storageKey, accountRef.current)) ensureLoaded(storageKey);\n  }, [storageKey]);\n  const completed = useSyncExternalStore(\n    useCallback((listener: () => void) => subscribe(storageKey, listener), [storageKey]),\n    () => snapshot(storageKey, migrateRef.current),\n    () => EMPTY,\n  );\n\n  const complete = useCallback(\n    (tour: CompletedTour) => completeStored(storageKey, migrateRef.current, tour),\n    [storageKey],\n  );\n\n  const reset = useCallback((id: string) => resetStored(storageKey, migrateRef.current, id), [storageKey]);\n\n  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/tour/use-tour-progress.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport { readStored, removeStored, writeStored } from \"../lib/safe-storage\";\nimport { httpStatusOf } from \"../auth/auth-errors\";\nimport { isTourDone, type TourCompletions } from \"./tour-info\";\n\n/**\n * Which tours this device has completed (docs/tours-harmonization.md §2.6, §6.2) —\n * keksdose's `tour-progress-store` and kastlan's `completions.ts`, as one hook.\n *\n * - **Device storage, the app's key.** `storageKey` is always the app's: an app on shared\n *   devices scopes it per account (KS, bench PCs), and an app that lists its keys\n *   (KS `storage-keys.ts`) spells it there. Every access is guarded: a blocked or full\n *   storage keeps the marks for this page's life instead of throwing.\n * - **One store, every reader.** A change notifies every hook on the same key in this tab\n *   (an in-tab emitter) and in other tabs (the `storage` event), so the tours page and\n *   `TourMenu` agree without a reload (ka F3).\n * - **`migrate(raw)`** reads an older shape, so nobody loses their done marks at adoption:\n *   it gets the stored JSON (or the raw text, if it is no JSON) and returns the record for\n *   a shape it recognises, `undefined` for any other — the kit's own shape included,\n *   which it then reads itself. keksdose: zustand's `{state: {completed}, version: 1}`;\n *   kastlan: an array of ids, completed without a date (`null`). It runs only on a stored\n *   text that is not the kit's shape already, once per text and key. The FIRST `migrate`\n *   any reader, `TourProvider` or {@link completeTour} passes for a key is remembered for\n *   that key (later identities are ignored), so a reader without one, mounted first, no\n *   longer hides the old marks from the rest (keksdose B-2). **Still, define the options\n *   once, at module level, and hand the provider and every reader the same object.**\n * - **Never overwritten unread** (keksdose B-1): a write (`complete`, the provider's,\n *   `completeTour`) on a stored text that is neither empty nor the kit's shape, and that no\n *   known `migrate` reads, THROWS instead of replacing the old marks.\n * - **Resetting the device** (settings §11): register the key with `reset: () =>\n *   resetTourProgress(storageKey)`, which clears storage and the page's memory and tells\n *   every reader in this tab.\n *\n * **The stored shape** (§9.3, §9.6.6), for an app's tests and seeds: the JSON record\n * `{ [id]: ISO instant | \"\" }` under `storageKey`, where `\"\"` is a completion without a\n * date (a migrated record: kastlan's id list). That is the one written form; the hooks\n * and callbacks (`completed`, `TourCompletions`) give `null` for `\"\"`. A `null` read from\n * storage (or returned by `migrate`) is accepted as the same thing and written back as\n * `\"\"`. To write a completion from outside a page, use {@link completeTour}.\n *\n * **On the account** (0.45, §10.2–§10.3): with `account`, the device key becomes the\n * account's CACHE — see {@link TourProgressAccount}. Without it, nothing changes from 0.44.\n */\nexport interface UseTourProgressOptions {\n  storageKey: string;\n  migrate?: (raw: unknown) => Record<string, string | null> | undefined;\n  /**\n   * 0.45: the account's record behind the device key (§10.2.4). Remembered per key like\n   * `migrate` (the FIRST one any reader or the provider passes wins). With it,\n   * `storageKey` must be per account (a prefix plus the user id), so build the options per\n   * account and keep ONE stable object per key — memoise them in a `Map` by user id — and\n   * let `load`/`save` read the current token when they run, never capture one:\n   *\n   *     const byUser = new Map<string, UseTourProgressOptions>();\n   *     function tourProgressFor(user: { id: string; isDemo: boolean } | null) {\n   *       if (!user || user.isDemo) return { storageKey: \"app.tours.completions\" }; // no account\n   *       let options = byUser.get(user.id);\n   *       if (!options) byUser.set(user.id, (options = { storageKey: `app.tours.completions:${user.id}`, account }));\n   *       return options;\n   *     }\n   *\n   * Signed out, and in a demo, pass none (and a fixed key): the device record works as in\n   * 0.44, and a demo neither PATCHes into a 403 nor leaves an orphan key per demo id.\n   */\n  account?: TourProgressAccount;\n}\n\n/** The record on the wire (§10.2.2): tour id → ISO instant, or `\"\"` (done, no date). */\ntype TourProgressWire = Record<string, string>;\n\n/** The `PATCH /tours/progress` body (§10.2.2): what to mark done, and what to forget.\n *  An id is never in both. Either may be left out. */\nexport interface TourProgressBody {\n  completed?: TourProgressWire;\n  forget?: string[];\n}\n\n/**\n * Taking over a device-wide record from before the account (§10.2.5), on the FIRST load\n * of the account key on this page:\n * - `{storageKey, discard: true}` (kastlan): removes the old key and uploads nothing — a\n *   shared PC must not hand one person another's marks. Removing an absent key is a no-op.\n * - `{storageKey, migrate?}`: reads the old key once (through `migrate` for an older\n *   shape), uploads it to the first account that signs in on this device, then removes it.\n */\nexport type TourProgressAdopt =\n  | { storageKey: string; discard: true; migrate?: never }\n  | { storageKey: string; discard?: false; migrate?: UseTourProgressOptions[\"migrate\"] };\n\n/**\n * The app's account record (§10.3): `load()` is its `GET /tours/progress`, `save(body)`\n * its `PATCH`, each resolving to the parsed answer, `{completed}` — the whole record.\n *\n * - The page paints from the device key at once (and offline); the account is loaded on\n *   the first reader of the key on this page, on `online`, and after each save, and its\n *   answer replaces the cache.\n * - A write (`complete`, the provider's finish, `reset`) goes to the cache at once and to\n *   a PENDING record beside it, `<storageKey>:pending` (`{synced, completed, forget}`),\n *   sent as one PATCH and cleared by its answer. A failure with no answer (offline, 5xx,\n *   401) keeps it for the next load or `online`; a 402 (a lapsed plan) keeps it but sends it\n *   no more on this page (the next session or page load tries again); a 403 or 422 drops\n *   it and logs.\n * - `awarded` stays the device's answer against the cache (§10.2.4).\n * - The pending record is NOT the app's outbox: leave it out of any \"N waiting\" count\n *   and any sign-out guard (losing a tour mark is acceptable).\n * - A device record never synced (no `:pending` with `synced: true`) is uploaded whole on\n *   its first load, by the server's merge rule (later completion wins).\n * - On every end of a session call {@link signOutTourProgress}.\n */\nexport interface TourProgressAccount {\n  load: () => Promise<{ completed: TourProgressWire }>;\n  save: (body: TourProgressBody) => Promise<{ completed: TourProgressWire }>;\n  adopt?: TourProgressAdopt;\n}\n\n/** What `complete` takes: a tour id, or the tour (`{id, updated}`, a `TourInfo` fits). */\ntype CompletedTour = string | { id: string; updated?: { date: string } | null };\n\nexport interface TourProgress {\n  /** Tour id → the completion's ISO timestamp, or `null` when recorded without a date. */\n  completed: TourCompletions;\n  /**\n   * Record a completion. Keeps the FIRST completion's date, so a replay changes nothing —\n   * unless the tour was reset by an update since (§8): pass the tour (`{id, updated}`) and\n   * a completion from before `updated.date` is replaced by today's.\n   *\n   * Returns `true` when this counts as a new completion — the moment to award the tour's\n   * points and show the app's toast (§6.1) — and `false` for a replay.\n   *\n   * A tour started with `start(steps, {tour})` under a `TourProvider` that has `progress`\n   * is recorded by the provider (§9.6.2): do not call this from that start's `onFinish`\n   * too, or the second write answers `false`.\n   */\n  complete: (tour: CompletedTour) => boolean;\n  /** \"Mark as not done\": forget the completion. */\n  reset: (id: string) => void;\n}\n\n/* ── The store: one per key, shared by every hook ───────────────────────────── */\n\nconst EMPTY: TourCompletions = Object.freeze({});\n/** In-tab listeners per key. */\nconst listeners = new Map<string, Set<() => void>>();\n/** What this page wrote where storage refused to keep it (blocked, full): per key. */\nconst memory = new Map<string, string>();\n/**\n * The last raw text read per key and what it parsed to, so a snapshot keeps its identity:\n * the same text gives the same object, whichever reader asks and whatever `migrate` it\n * holds. Several readers of one key with inline `migrate` arrows used to evict each other\n * here and loop (kastlan B1, 0.43).\n */\nconst cache = new Map<string, { raw: string | null; value: TourCompletions; readable: boolean }>();\ntype Migrate = NonNullable<UseTourProgressOptions[\"migrate\"]>;\n/** Each key's migrate: the first one any reader, the provider or `completeTour` passes (B-2). */\nconst migrates = new Map<string, Migrate>();\n\n/**\n * Remember `migrate` for `key` if it is the first one, and return the key's migrate. A\n * snapshot parsed before the key had one is dropped and re-parsed, and the key's readers\n * hear of it after this render (never from inside one).\n * @internal Not part of the barrel; `TourProvider` registers its `progress` with it.\n */\nexport function rememberMigrate(key: string, migrate: UseTourProgressOptions[\"migrate\"]): Migrate | undefined {\n  if (migrate && !migrates.has(key)) {\n    migrates.set(key, migrate);\n    if (cache.delete(key)) queueMicrotask(() => emit(key));\n  }\n  return migrates.get(key);\n}\n\nfunction emit(key: string) {\n  listeners.get(key)?.forEach((listener) => listener());\n}\n\nfunction rawOf(key: string): string | null {\n  return memory.get(key) ?? readStored(key);\n}\n\n/** Is this the kit's own shape already: a record whose every value is a string or null? */\nfunction isKitShape(value: unknown): boolean {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n  return Object.values(value as Record<string, unknown>).every((at) => at === null || typeof at === \"string\");\n}\n\n/** The kit's own shape: a record of string or null; anything else is dropped. */\nfunction fromRecord(value: unknown): TourCompletions | undefined {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return undefined;\n  const out: Record<string, string | null> = {};\n  for (const [id, at] of Object.entries(value as Record<string, unknown>)) {\n    if (at === null || at === \"\") out[id] = null;\n    else if (typeof at === \"string\") out[id] = at;\n  }\n  return out;\n}\n\n/**\n * The record, and whether the text was READ (empty, the kit's shape, or a shape `migrate`\n * knows) rather than dropped: a write over an unread text would lose it (B-1).\n */\nfunction parse(\n  raw: string | null,\n  migrate: UseTourProgressOptions[\"migrate\"],\n): { value: TourCompletions; readable: boolean } {\n  if (raw === null || raw.trim() === \"\") return { value: EMPTY, readable: true };\n  let value: unknown = raw;\n  try {\n    value = JSON.parse(raw);\n  } catch {\n    // Not JSON: `migrate` still sees the text.\n  }\n  if (migrate && !isKitShape(value)) {\n    try {\n      const migrated = fromRecord(migrate(value));\n      if (migrated !== undefined) return { value: migrated, readable: true };\n    } catch {\n      // A migrate that throws reads as \"not a shape it knows\".\n    }\n  }\n  return { value: fromRecord(value) ?? EMPTY, readable: isKitShape(value) };\n}\n\nfunction snapshot(key: string, migrate: UseTourProgressOptions[\"migrate\"]): TourCompletions {\n  const known = rememberMigrate(key, migrate);\n  const raw = rawOf(key);\n  const hit = cache.get(key);\n  if (hit && hit.raw === raw) return hit.value;\n  const parsed = parse(raw, known);\n  cache.set(key, { raw, ...parsed });\n  return parsed.value;\n}\n\n/** The record a write builds on; throws rather than overwrite a text nobody could read (B-1). */\nfunction readForWrite(key: string, migrate: UseTourProgressOptions[\"migrate\"], own = false): TourCompletions {\n  // `own`: this migrate, even where the key registered another (completeTour's `{migrate}`).\n  const known = rememberMigrate(key, migrate);\n  const { value, readable } =\n    own && migrate && known !== migrate\n      ? parse(rawOf(key), migrate)\n      : { value: snapshot(key, migrate), readable: cache.get(key)?.readable };\n  if (!readable) {\n    throw new Error(\n      `[ui-kit] tour progress: the text stored under \"${key}\" is not the kit's shape and no migrate reads it; ` +\n        \"refusing to overwrite it. Pass the key's migrate (the shared useTourProgress / TourProvider options, \" +\n        \"or completeTour's {migrate}).\",\n    );\n  }\n  return value;\n}\n\n/** The one written form (§9.6.6): a completion without a date is stored as `\"\"`, never `null`. */\nfunction write(key: string, record: TourCompletions) {\n  const stored: Record<string, string> = {};\n  for (const [id, at] of Object.entries(record)) stored[id] = at ?? \"\";\n  const raw = JSON.stringify(stored);\n  writeStored(key, raw);\n  // Storage refused it (blocked, full): keep it for this page's life instead.\n  if (readStored(key) === raw) memory.delete(key);\n  else memory.set(key, raw);\n  emit(key);\n}\n\n/* ── The account behind the device key (0.45, §10.2.4–§10.2.8) ─────────────── */\n\n/** The key's account: the first one any reader or the provider passes (as `migrate`). */\nconst accounts = new Map<string, TourProgressAccount>();\n/** Keys whose account was loaded (or is loading) on this page: the first reader loads. */\nconst loaded = new Set<string>();\n/** Keys with a sync running, and those asked for another while it ran. */\nconst running = new Set<string>();\nconst rerun = new Set<string>();\n/** Keys with a sync queued for the end of this task: two writes in one handler, one PATCH. */\nconst queued = new Set<string>();\n/** Bumped by a sign-out: an answer that comes back after it never refills the cache. */\nconst epochs = new Map<string, number>();\n/** Keys whose PATCH got a 402 (a lapsed plan): the pending record is kept but not sent\n *  again on this page; the next session (or page load) tries once more. */\nconst parked = new Set<string>();\n/** The pending record where storage refused to keep it. */\nconst pendingMemory = new Map<string, string>();\nlet onlineListening = false;\n\n/** The pending record (§10.2.4): what waits to be sent, and whether the device key was\n *  ever synced. */\ninterface PendingRecord {\n  synced: boolean;\n  completed: TourProgressWire;\n  forget: string[];\n}\n\nconst pendingKey = (key: string) => `${key}:pending`;\n\nfunction devWarn(message: string) {\n  if (import.meta.env?.DEV) console.warn(message);\n}\n\n/**\n * Remember `account` for `key` if it is the first one, and return the key's account.\n * @internal Not part of the barrel; `TourProvider` registers its `progress` with it.\n */\nexport function rememberAccount(\n  key: string,\n  account: TourProgressAccount | undefined,\n): TourProgressAccount | undefined {\n  if (account && !accounts.has(key)) {\n    accounts.set(key, account);\n    if (account.adopt && account.adopt.storageKey === key) {\n      devWarn(\n        `[ui-kit] tour progress: the account key \"${key}\" is the key \\`adopt\\` takes over. ` +\n          \"With an account the key must be per account (a prefix plus the user id), apart from the old device-wide key.\",\n      );\n    }\n    if (!onlineListening && typeof window !== \"undefined\") {\n      onlineListening = true;\n      window.addEventListener(\"online\", () => {\n        for (const known of loaded) void sync(known);\n      });\n    }\n  }\n  return accounts.get(key);\n}\n\nfunction readPending(key: string): PendingRecord | null {\n  const raw = pendingMemory.get(key) ?? readStored(pendingKey(key));\n  if (raw === null) return null;\n  try {\n    const value = JSON.parse(raw) as Partial<PendingRecord> | null;\n    if (!value || typeof value !== \"object\") return null;\n    const completed: TourProgressWire = {};\n    for (const [id, at] of Object.entries(value.completed ?? {})) {\n      if (typeof at === \"string\") completed[id] = at;\n      else if (at === null) completed[id] = \"\";\n    }\n    const forget = Array.isArray(value.forget) ? value.forget.filter((id): id is string => typeof id === \"string\") : [];\n    return { synced: value.synced === true, completed, forget };\n  } catch {\n    return null;\n  }\n}\n\nfunction writePending(key: string, record: PendingRecord) {\n  const raw = JSON.stringify(record);\n  writeStored(pendingKey(key), raw);\n  if (readStored(pendingKey(key)) === raw) pendingMemory.delete(key);\n  else pendingMemory.set(key, raw);\n}\n\nconst hasWork = (record: PendingRecord) => Object.keys(record.completed).length > 0 || record.forget.length > 0;\n\n/** \"Later completion wins\" (§10.2.3), as the server merges: an instant beats `\"\"`, `\"\"`\n *  beats nothing, and between two instants the later is kept. */\nfunction later(a: string | undefined, b: string): string {\n  if (a === undefined || a === \"\") return b;\n  if (b === \"\") return a;\n  return Date.parse(b) > Date.parse(a) ? b : a;\n}\n\n/** Note a completion (or, with `forget`, its removal) in the key's pending record. */\nfunction markPending(key: string, id: string, at: string | null | undefined, forget = false) {\n  const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };\n  if (forget) {\n    delete record.completed[id];\n    if (!record.forget.includes(id)) record.forget.push(id);\n  } else {\n    record.completed[id] = at ?? \"\";\n    record.forget = record.forget.filter((other) => other !== id);\n  }\n  writePending(key, record);\n}\n\n/** After an answer (or a 403/422): take what was sent out of the pending record, keeping\n *  what was written while the request ran. */\nfunction clearSent(key: string, sent: TourProgressBody, synced: boolean) {\n  const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };\n  for (const [id, at] of Object.entries(sent.completed ?? {})) {\n    if (record.completed[id] === at) delete record.completed[id];\n  }\n  const forgotten = new Set(sent.forget ?? []);\n  record.forget = record.forget.filter((id) => !forgotten.has(id));\n  record.synced = record.synced || synced;\n  writePending(key, record);\n}\n\n/** The account's answer as the cache, with what still waits to be sent laid over it. */\nfunction refill(key: string, answer: { completed: TourProgressWire } | null | undefined) {\n  const next: Record<string, string> = {};\n  for (const [id, at] of Object.entries(fromRecord(answer?.completed) ?? {})) next[id] = at ?? \"\";\n  const waiting = readPending(key);\n  if (waiting) {\n    for (const [id, at] of Object.entries(waiting.completed)) next[id] = later(next[id], at);\n    for (const id of waiting.forget) delete next[id];\n  }\n  const record: Record<string, string | null> = {};\n  for (const [id, at] of Object.entries(next)) record[id] = at === \"\" ? null : at;\n  write(key, record);\n}\n\n/** The first load of an account key on this page takes over the old device-wide key\n *  (§10.2.5). */\nfunction adoptOldRecord(key: string, account: TourProgressAccount) {\n  const adopt = account.adopt;\n  if (!adopt || adopt.storageKey === key) return;\n  const old = adopt.storageKey;\n  if (!adopt.discard) {\n    const { value } = parse(rawOf(old), adopt.migrate ?? migrates.get(old));\n    const entries = Object.entries(value);\n    if (entries.length > 0) {\n      const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };\n      for (const [id, at] of entries) record.completed[id] = later(record.completed[id], at ?? \"\");\n      writePending(key, record);\n    }\n  }\n  // Removed either way, at once: no second account on this device gets it.\n  removeStored(old);\n  memory.delete(old);\n  cache.delete(old);\n  emit(old);\n}\n\n/** A device record never synced is uploaded whole on its first load (§10.2.5). */\nfunction uploadUnsynced(key: string) {\n  const record = readPending(key);\n  if (record?.synced) return;\n  const device = snapshot(key, migrates.get(key));\n  const entries = Object.entries(device);\n  const next = record ?? { synced: false, completed: {}, forget: [] };\n  if (entries.length === 0 && record) return;\n  for (const [id, at] of entries) {\n    if (!next.forget.includes(id)) next.completed[id] = later(next.completed[id], at ?? \"\");\n  }\n  writePending(key, next);\n}\n\n/** The key's first sync on this page: take over the old record, upload a never-synced one. */\nfunction prepare(key: string) {\n  loaded.add(key);\n  adoptOldRecord(key, accounts.get(key)!);\n  uploadUnsynced(key);\n}\n\n/** Queue a sync for the end of this task, so a handler's writes go as one PATCH. */\nfunction queueSync(key: string) {\n  if (!loaded.has(key)) prepare(key);\n  if (queued.has(key)) return;\n  queued.add(key);\n  queueMicrotask(() => {\n    queued.delete(key);\n    void sync(key);\n  });\n}\n\n/** The first reader of an account key on this page loads it. */\nfunction ensureLoaded(key: string) {\n  if (!accounts.has(key) || loaded.has(key)) return;\n  prepare(key);\n  void sync(key);\n}\n\n/**\n * Send what waits (one PATCH) or, with nothing waiting, load; the answer replaces the\n * cache. One at a time per key; a request asked for while one runs follows it.\n */\nasync function sync(key: string): Promise<void> {\n  const account = accounts.get(key);\n  if (!account || !loaded.has(key)) return;\n  if (running.has(key)) {\n    rerun.add(key);\n    return;\n  }\n  if (typeof navigator !== \"undefined\" && navigator.onLine === false) return;\n  running.add(key);\n  const epoch = epochs.get(key) ?? 0;\n  try {\n    const waiting = readPending(key);\n    if (waiting && hasWork(waiting)) {\n      if (parked.has(key)) return;\n      const body: TourProgressBody = {};\n      if (Object.keys(waiting.completed).length > 0) body.completed = { ...waiting.completed };\n      if (waiting.forget.length > 0) body.forget = [...waiting.forget];\n      let answer: { completed: TourProgressWire };\n      try {\n        answer = await account.save(body);\n      } catch (error) {\n        const status = httpStatusOf(error);\n        if (status === 403 || status === 422) {\n          // Refused for good (a demo, a malformed or full record): dropped, not retried.\n          if ((epochs.get(key) ?? 0) === epoch) clearSent(key, body, false);\n          console.warn(`[ui-kit] tour progress: the account refused the pending record (${status}); dropped.`, error);\n        } else if (status === 402) {\n          // A lapsed plan refuses every write: kept, but not re-sent after each finish\n          // and each `online` — the next session or page load tries again.\n          parked.add(key);\n        }\n        // No answer (offline, 5xx, 401): it stays for the next load or `online`.\n        return;\n      }\n      if ((epochs.get(key) ?? 0) !== epoch) return;\n      clearSent(key, body, true);\n      refill(key, answer);\n    } else {\n      const answer = await account.load();\n      if ((epochs.get(key) ?? 0) !== epoch) return;\n      if (waiting && !waiting.synced) writePending(key, { ...waiting, synced: true });\n      else if (!waiting) writePending(key, { synced: true, completed: {}, forget: [] });\n      refill(key, answer);\n    }\n  } catch {\n    // A load that failed keeps the cache as it is.\n  } finally {\n    running.delete(key);\n    if (rerun.delete(key)) void sync(key);\n  }\n}\n\n/**\n * The end of a session (§10.2.6) — sign-out, a 401 nothing could renew, the account's\n * deletion, every path: removes the CACHE only (the device key and the page's snapshot;\n * every reader in this tab moves), synchronously and with no request, and KEEPS\n * `<storageKey>:pending`. That record sits under this person's own key, holds tour ids and\n * dates only, and goes out on their next sign-in. An answer still on its way is ignored.\n *\n *     function logout() { …; signOutTourProgress(`app.tours:${user.id}`); }\n */\nexport function signOutTourProgress(storageKey: string): void {\n  epochs.set(storageKey, (epochs.get(storageKey) ?? 0) + 1);\n  loaded.delete(storageKey);\n  rerun.delete(storageKey);\n  parked.delete(storageKey);\n  removeStored(storageKey);\n  memory.delete(storageKey);\n  cache.delete(storageKey);\n  emit(storageKey);\n}\n\nfunction subscribe(key: string, listener: () => void): () => void {\n  let set = listeners.get(key);\n  if (!set) listeners.set(key, (set = new Set()));\n  set.add(listener);\n  // Another tab wrote (or cleared all storage: `key` null).\n  const onStorage = (event: StorageEvent) => {\n    if (event.key !== null && event.key !== key) return;\n    memory.delete(key);\n    listener();\n  };\n  if (typeof window !== \"undefined\") window.addEventListener(\"storage\", onStorage);\n  return () => {\n    set.delete(listener);\n    if (typeof window !== \"undefined\") window.removeEventListener(\"storage\", onStorage);\n  };\n}\n\n/**\n * Forget every tour completion under `storageKey` on this device: the stored key, what the\n * page kept in memory where storage refused it, and every reader in this tab moves at\n * once. For \"Reset this device's settings\" (settings §11):\n *\n *     registerDeviceSetting({ key: TOUR_KEY, kind: \"view\", reset: () => resetTourProgress(TOUR_KEY) });\n *\n * With an account (0.45) it clears the cache only: the account is never written, the\n * pending record stays (\"anything waiting to be sent\", settings §11.2.2) and the next load\n * refills the cache. Tour progress is never registered with the device reset (§10.2.8).\n */\nexport function resetTourProgress(storageKey: string): void {\n  if (accounts.has(storageKey)) loaded.delete(storageKey);\n  removeStored(storageKey);\n  memory.delete(storageKey);\n  cache.delete(storageKey);\n  emit(storageKey);\n}\n\n/**\n * Record a completion under `storageKey`, as {@link TourProgress.complete} does: through\n * the one shared store and snapshot (never a copy), so every reader of the key moves.\n * Returns `true` when it counts anew. `TourProvider` calls this on a tour's last step.\n * @internal Not part of the barrel.\n */\nexport function completeStored(\n  storageKey: string,\n  migrate: UseTourProgressOptions[\"migrate\"],\n  tour: CompletedTour,\n): boolean {\n  const subject = typeof tour === \"string\" ? { id: tour } : tour;\n  // Read now rather than from a render: two completions in one handler both count.\n  const current = readForWrite(storageKey, migrate);\n  if (isTourDone(subject, current[subject.id])) return false;\n  const at = new Date().toISOString();\n  write(storageKey, { ...current, [subject.id]: at });\n  if (accounts.has(storageKey)) {\n    markPending(storageKey, subject.id, at);\n    queueSync(storageKey);\n  }\n  return true;\n}\n\n/** \"Mark as not done\" (§10.2.8): off the cache, and `forget` to the account. @internal */\nfunction resetStored(storageKey: string, migrate: UseTourProgressOptions[\"migrate\"], id: string) {\n  const current = snapshot(storageKey, migrate);\n  if (current[id] === undefined) return;\n  const next = { ...current };\n  delete next[id];\n  write(storageKey, next);\n  if (accounts.has(storageKey)) {\n    markPending(storageKey, id, undefined, true);\n    queueSync(storageKey);\n  }\n}\n\n/**\n * Write a completion from outside a page (§9.2): for an app's tests, seeds and scripts,\n * beside {@link resetTourProgress}. It writes the kit's stored shape (`{[id]: ISO | \"\"}`)\n * under `storageKey`, keeps the other tours' marks, and notifies every reader of the key\n * in this tab directly (the `storage` event reaches only OTHER tabs), so a mounted\n * `useTourProgress` or `TourCatalogue` moves at once.\n *\n * Unlike `complete`, it always writes (over a readable text; see below): `at` is the\n * completion's instant (an ISO string or a `Date`, default now), `null` a completion\n * without a date (stored as `\"\"`, read back as `null`).\n *\n *     completeTour(TOUR_KEY, \"budget\", \"2026-09-01T10:00:00Z\");\n *\n * A stored text in an app's older shape is read through `opts.migrate`, or else the\n * migrate a reader or the provider registered for the key. If the text is neither empty\n * nor the kit's shape and no migrate reads it, this THROWS and writes nothing (B-1):\n *\n *     completeTour(TOUR_KEY, \"budget\", undefined, { migrate: fromZustand });\n *\n * With an account on the key (0.45) it stays a device write — no request — and is marked\n * pending, so the next load sends it.\n */\nexport function completeTour(\n  storageKey: string,\n  tour: string | { id: string },\n  at?: string | Date | null,\n  opts?: { migrate?: UseTourProgressOptions[\"migrate\"] },\n): void {\n  const id = typeof tour === \"string\" ? tour : tour.id;\n  const when = at === null ? null : at instanceof Date ? at.toISOString() : (at ?? new Date().toISOString());\n  write(storageKey, { ...readForWrite(storageKey, opts?.migrate, true), [id]: when });\n  if (accounts.has(storageKey)) markPending(storageKey, id, when);\n}\n\n/** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */\nexport function useTourProgress({ storageKey, migrate, account }: UseTourProgressOptions): TourProgress {\n  // Held, not depended on: an inline arrow is a new function every render, and neither the\n  // snapshot nor the callbacks may change with it.\n  const migrateRef = useRef(migrate);\n  useEffect(() => {\n    migrateRef.current = migrate;\n  });\n  // The first account for the key wins (as `migrate`); its first reader on the page loads.\n  const accountRef = useRef(account);\n  useEffect(() => {\n    accountRef.current = account;\n  });\n  useEffect(() => {\n    if (rememberAccount(storageKey, accountRef.current)) ensureLoaded(storageKey);\n  }, [storageKey]);\n  const completed = useSyncExternalStore(\n    useCallback((listener: () => void) => subscribe(storageKey, listener), [storageKey]),\n    () => snapshot(storageKey, migrateRef.current),\n    () => EMPTY,\n  );\n\n  const complete = useCallback(\n    (tour: CompletedTour) => completeStored(storageKey, migrateRef.current, tour),\n    [storageKey],\n  );\n\n  const reset = useCallback((id: string) => resetStored(storageKey, migrateRef.current, id), [storageKey]);\n\n  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);\n}\n"],"mappings":"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","names":[]}

package/dist/tour/use-tour-url-sync.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tour/use-tour-url-sync.ts"],"sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from \"react\";\nimport * as ReactRouter from \"react-router\";\nimport { useLocation, useNavigate, type Navigator } from \"react-router\";\nimport { useSearchParamsState } from \"../hooks/use-search-param-state\";\nimport { useTourOptional, type TourEngine, type TourStart } from \"./tour\";\nimport { liveEngine } from \"./tour-engine\";\nimport { devWarnings } from \"./tour-gates\";\n\n/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */\n\nexport interface UseTourUrlSyncOptions {\n  /**\n   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the\n   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points\n   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:\n   * the parameters are kept until it settles. Under a `TourProvider` the third argument is\n   * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves\n   * both; the fourth is its whole engine, read live (0.50.1, `TourEngine`: `stop`, `next`,\n   * `active`, …). Without a provider `start` and the engine's methods do nothing (a\n   * development build warns) and the engine reads as idle.\n   */\n  launch: (\n    id: string,\n    options: { startIndex: number },\n    start: TourStart,\n    engine: TourEngine,\n  ) => void | Promise<unknown>;\n  /**\n   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the\n   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so\n   * an F5 mid-tour resumes the right variant at the right step. Default `true`.\n   */\n  ready?: boolean;\n  /**\n   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's\n   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.\n   */\n  stepAliases?: readonly string[];\n}\n\ntype Place = { pathname: string; search: string; hash: string };\n\n/**\n * Has the router already moved on from the location React is still rendering?\n * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built\n * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.\n *\n * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build\n *   review 0.43, kastlan A2), so the router's own state answers — a navigation still\n *   loading, or a location it has committed that React has not rendered yet.\n * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and\n *   carries where it is.\n * - Anything else answers \"not in flight\".\n */\nfunction navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {\n  const state = dataRouter?.router?.state;\n  if (state && (state.navigation?.state ?? \"idle\") !== \"idle\") return true;\n  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;\n  if (!live) return false;\n  return (\n    live.pathname !== rendered.pathname || (live.search ?? \"\") !== rendered.search || (live.hash ?? \"\") !== rendered.hash\n  );\n}\n\ntype NavigationProbe = { navigator?: Navigator } | null;\nconst NO_NAVIGATION = createContext<NavigationProbe>(null);\n/** The data router's state, as `useSearchParamState` reads it. */\ntype DataRouterProbe = {\n  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };\n} | null;\nconst NO_DATA_ROUTER = createContext<DataRouterProbe>(null);\nconst DataRouterContext: Context<DataRouterProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??\n      NO_DATA_ROUTER\n    );\n  } catch {\n    return NO_DATA_ROUTER;\n  }\n})();\n/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:\n *  a test's partial `vi.mock(\"react-router\")` throws on an export it does not define. */\nconst NavigationContext: Context<NavigationProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??\n      NO_NAVIGATION\n    );\n  } catch {\n    return NO_NAVIGATION;\n  }\n})();\n\n/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based. */\nfunction stepOf(params: URLSearchParams, aliases: readonly string[]): number {\n  const step = Number(params.get(\"tourStep\"));\n  if (params.has(\"tourStep\")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;\n  for (const alias of aliases) {\n    const value = Number(params.get(alias));\n    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n  }\n  return 0;\n}\n\n/**\n * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,\n * on the kit's engine (`useTourOptional`):\n *\n * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app\n *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —\n *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.\n * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied\n *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.\n * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.\n *\n * Mount it once inside the router and the `TourProvider`. Without a provider it still\n * launches through `launch` and never mirrors.\n */\nexport function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {\n  const navigate = useNavigate();\n  const location = useLocation();\n  const { pathname, search, hash } = location;\n  const history = useContext(NavigationContext)?.navigator;\n  const dataRouter = useContext(DataRouterContext);\n  const engine = useTourOptional();\n  const active = engine?.active ?? false;\n  const activeId = engine?.activeId ?? null;\n  const index = engine?.index ?? 0;\n  const urlTour = new URLSearchParams(search).get(\"tour\");\n  const aliases = stepAliases.join(\"\\n\");\n\n  const launchRef = useRef(launch);\n  const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);\n  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS, NO_PROVIDER_ENGINE));\n  const activeIdRef = useRef(activeId);\n  useLayoutEffect(() => {\n    launchRef.current = launch;\n    startRef.current = engine?.start ?? noProviderStart;\n    live.set(engine ?? NO_PROVIDER_ENGINE);\n    activeIdRef.current = active ? activeId : null;\n  });\n  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */\n  const seenRef = useRef<string | null>(null);\n  /** A deep link waiting for `ready`. */\n  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);\n  /** A launch under way (an app's `prepare()`). */\n  const launchingRef = useRef(false);\n  /** Bumped when a launch settles, so the mirror looks again. */\n  const [settled, setSettled] = useState(0);\n\n  useEffect(() => {\n    if (urlTour !== seenRef.current) {\n      seenRef.current = urlTour;\n      // Its own mirror writing the running tour back is no new link.\n      pendingRef.current =\n        urlTour && urlTour !== activeIdRef.current\n          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split(\"\\n\") : []) }\n          : null;\n    }\n    const pending = pendingRef.current;\n    if (!pending || !ready) return;\n    pendingRef.current = null;\n    launchingRef.current = true;\n    void Promise.resolve()\n      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine))\n      .catch(() => undefined)\n      .finally(() => {\n        launchingRef.current = false;\n        setSettled((n) => n + 1);\n      });\n    // Only a change of the parameter, or readiness, starts a tour.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [urlTour, ready]);\n\n  useEffect(() => {\n    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;\n    // A link not yet used keeps its parameters: a reload in that window resumes.\n    if (pendingRef.current || launchingRef.current) return;\n    const tourId = active && activeId ? activeId : null;\n    const own = [\"tour\", \"tourStep\", ...(aliases ? aliases.split(\"\\n\") : [])];\n    const current = new URLSearchParams(search);\n    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace\n    // clobbers a page's own just-issued navigation, keksdose feedback #4).\n    if (!tourId && !own.some((key) => current.has(key))) return;\n    const next = new URLSearchParams(search);\n    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the\n    // tour's own) go.\n    for (const key of tourId ? own.slice(2) : own) next.delete(key);\n    if (tourId) {\n      next.set(\"tour\", tourId);\n      next.set(\"tourStep\", String(index + 1));\n    }\n    if (next.toString() === current.toString()) return;\n    // Spelled out, not `setSearchParams` (\"?…\" drops the hash, keksdose dev#495).\n    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [active, activeId, index, pathname, search, hash, settled, aliases]);\n}\n\n/** `start` for a launcher run with no `TourProvider` above `useTourUrlSync`. */\nconst noProviderStart: TourStart = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.\");\n};\n\nconst noProviderCall = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.\");\n};\n/** The engine for a launcher run with no `TourProvider` above `useTourUrlSync`: idle. */\nconst NO_PROVIDER_ENGINE: TourEngine = {\n  active: false,\n  activeId: null,\n  start: noProviderStart,\n  stop: noProviderCall,\n  next: noProviderCall,\n  prev: noProviderCall,\n  goToStep: noProviderCall,\n  index: 0,\n  total: 0,\n  position: 0,\n  count: 0,\n};\nconst ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE) as (keyof TourEngine)[];\n\n/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */\n\n/** The catalogue's state filter. */\nexport type TourStateFilter = \"all\" | \"todo\" | \"done\";\n\n/** The catalogue's filters: the search, the group (`null`: every group), the state. */\nexport interface TourCatalogueFilter {\n  query: string;\n  group: string | null;\n  state: TourStateFilter;\n}\n\nconst STATES: readonly TourStateFilter[] = [\"all\", \"todo\", \"done\"];\n\n/**\n * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each\n * written with `replace` (typing does not bury the Back button), the defaults as the\n * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.\n * `params` renames them (kastlan's `?group`). Requires a react-router Router.\n */\nexport function useTourCatalogueUrlState(\n  params: { query?: string; group?: string; state?: string } = {},\n): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {\n  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({\n    query: { param: params.query ?? \"q\", default: \"\", history: \"replace\" },\n    group: { param: params.group ?? \"topic\", default: null, history: \"replace\", parse: (raw) => raw || undefined },\n    state: {\n      param: params.state ?? \"state\",\n      default: \"all\",\n      history: \"replace\",\n      parse: (raw) => STATES.find((x) => x === raw),\n    },\n  });\n  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.\n  return { ...filter, onChange: setFilter };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/tour/use-tour-url-sync.ts"],"sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from \"react\";\nimport * as ReactRouter from \"react-router\";\nimport { useLocation, useNavigate, type Navigator } from \"react-router\";\nimport { useSearchParamsState } from \"../hooks/use-search-param-state\";\nimport { useTourOptional, type TourEngine, type TourStart } from \"./tour\";\nimport { liveEngine } from \"./tour-engine\";\nimport { devWarnings } from \"./tour-gates\";\n\n/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */\n\nexport interface UseTourUrlSyncOptions {\n  /**\n   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the\n   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points\n   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:\n   * the parameters are kept until it settles. Under a `TourProvider` the third argument is\n   * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves\n   * both; the fourth is its whole engine, read live (0.50.1, `TourEngine`: `stop`, `next`,\n   * `active`, …). Without a provider `start` and the engine's methods do nothing (a\n   * development build warns) and the engine reads as idle.\n   */\n  launch: (\n    id: string,\n    options: { startIndex: number },\n    start: TourStart,\n    engine: TourEngine,\n  ) => void | Promise<unknown>;\n  /**\n   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the\n   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so\n   * an F5 mid-tour resumes the right variant at the right step. Default `true`.\n   */\n  ready?: boolean;\n  /**\n   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's\n   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.\n   */\n  stepAliases?: readonly string[];\n}\n\ntype Place = { pathname: string; search: string; hash: string };\n\n/**\n * Has the router already moved on from the location React is still rendering?\n * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built\n * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.\n *\n * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build\n *   review 0.43, kastlan A2), so the router's own state answers — a navigation still\n *   loading, or a location it has committed that React has not rendered yet.\n * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and\n *   carries where it is.\n * - Anything else answers \"not in flight\".\n */\nfunction navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {\n  const state = dataRouter?.router?.state;\n  if (state && (state.navigation?.state ?? \"idle\") !== \"idle\") return true;\n  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;\n  if (!live) return false;\n  return (\n    live.pathname !== rendered.pathname ||\n    (live.search ?? \"\") !== rendered.search ||\n    (live.hash ?? \"\") !== rendered.hash\n  );\n}\n\ntype NavigationProbe = { navigator?: Navigator } | null;\nconst NO_NAVIGATION = createContext<NavigationProbe>(null);\n/** The data router's state, as `useSearchParamState` reads it. */\ntype DataRouterProbe = {\n  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };\n} | null;\nconst NO_DATA_ROUTER = createContext<DataRouterProbe>(null);\nconst DataRouterContext: Context<DataRouterProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??\n      NO_DATA_ROUTER\n    );\n  } catch {\n    return NO_DATA_ROUTER;\n  }\n})();\n/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:\n *  a test's partial `vi.mock(\"react-router\")` throws on an export it does not define. */\nconst NavigationContext: Context<NavigationProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??\n      NO_NAVIGATION\n    );\n  } catch {\n    return NO_NAVIGATION;\n  }\n})();\n\n/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based. */\nfunction stepOf(params: URLSearchParams, aliases: readonly string[]): number {\n  const step = Number(params.get(\"tourStep\"));\n  if (params.has(\"tourStep\")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;\n  for (const alias of aliases) {\n    const value = Number(params.get(alias));\n    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n  }\n  return 0;\n}\n\n/**\n * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,\n * on the kit's engine (`useTourOptional`):\n *\n * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app\n *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —\n *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.\n * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied\n *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.\n * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.\n *\n * Mount it once inside the router and the `TourProvider`. Without a provider it still\n * launches through `launch` and never mirrors.\n */\nexport function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {\n  const navigate = useNavigate();\n  const location = useLocation();\n  const { pathname, search, hash } = location;\n  const history = useContext(NavigationContext)?.navigator;\n  const dataRouter = useContext(DataRouterContext);\n  const engine = useTourOptional();\n  const active = engine?.active ?? false;\n  const activeId = engine?.activeId ?? null;\n  const index = engine?.index ?? 0;\n  const urlTour = new URLSearchParams(search).get(\"tour\");\n  const aliases = stepAliases.join(\"\\n\");\n\n  const launchRef = useRef(launch);\n  const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);\n  const [live] = useState(() => liveEngine<TourEngine>(ENGINE_KEYS, NO_PROVIDER_ENGINE));\n  const activeIdRef = useRef(activeId);\n  useLayoutEffect(() => {\n    launchRef.current = launch;\n    startRef.current = engine?.start ?? noProviderStart;\n    live.set(engine ?? NO_PROVIDER_ENGINE);\n    activeIdRef.current = active ? activeId : null;\n  });\n  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */\n  const seenRef = useRef<string | null>(null);\n  /** A deep link waiting for `ready`. */\n  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);\n  /** A launch under way (an app's `prepare()`). */\n  const launchingRef = useRef(false);\n  /** Bumped when a launch settles, so the mirror looks again. */\n  const [settled, setSettled] = useState(0);\n\n  useEffect(() => {\n    if (urlTour !== seenRef.current) {\n      seenRef.current = urlTour;\n      // Its own mirror writing the running tour back is no new link.\n      pendingRef.current =\n        urlTour && urlTour !== activeIdRef.current\n          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split(\"\\n\") : []) }\n          : null;\n    }\n    const pending = pendingRef.current;\n    if (!pending || !ready) return;\n    pendingRef.current = null;\n    launchingRef.current = true;\n    void Promise.resolve()\n      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current, live.engine))\n      .catch(() => undefined)\n      .finally(() => {\n        launchingRef.current = false;\n        setSettled((n) => n + 1);\n      });\n    // Only a change of the parameter, or readiness, starts a tour.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [urlTour, ready]);\n\n  useEffect(() => {\n    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;\n    // A link not yet used keeps its parameters: a reload in that window resumes.\n    if (pendingRef.current || launchingRef.current) return;\n    const tourId = active && activeId ? activeId : null;\n    const own = [\"tour\", \"tourStep\", ...(aliases ? aliases.split(\"\\n\") : [])];\n    const current = new URLSearchParams(search);\n    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace\n    // clobbers a page's own just-issued navigation, keksdose feedback #4).\n    if (!tourId && !own.some((key) => current.has(key))) return;\n    const next = new URLSearchParams(search);\n    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the\n    // tour's own) go.\n    for (const key of tourId ? own.slice(2) : own) next.delete(key);\n    if (tourId) {\n      next.set(\"tour\", tourId);\n      next.set(\"tourStep\", String(index + 1));\n    }\n    if (next.toString() === current.toString()) return;\n    // Spelled out, not `setSearchParams` (\"?…\" drops the hash, keksdose dev#495).\n    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [active, activeId, index, pathname, search, hash, settled, aliases]);\n}\n\n/** `start` for a launcher run with no `TourProvider` above `useTourUrlSync`. */\nconst noProviderStart: TourStart = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.\");\n};\n\nconst noProviderCall = () => {\n  if (devWarnings()) console.warn(\"[ui-kit] useTourUrlSync: the launcher's engine needs a TourProvider above it.\");\n};\n/** The engine for a launcher run with no `TourProvider` above `useTourUrlSync`: idle. */\nconst NO_PROVIDER_ENGINE: TourEngine = {\n  active: false,\n  activeId: null,\n  start: noProviderStart,\n  stop: noProviderCall,\n  next: noProviderCall,\n  prev: noProviderCall,\n  goToStep: noProviderCall,\n  index: 0,\n  total: 0,\n  position: 0,\n  count: 0,\n};\nconst ENGINE_KEYS = Object.keys(NO_PROVIDER_ENGINE) as (keyof TourEngine)[];\n\n/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */\n\n/** The catalogue's state filter. */\nexport type TourStateFilter = \"all\" | \"todo\" | \"done\";\n\n/** The catalogue's filters: the search, the group (`null`: every group), the state. */\nexport interface TourCatalogueFilter {\n  query: string;\n  group: string | null;\n  state: TourStateFilter;\n}\n\nconst STATES: readonly TourStateFilter[] = [\"all\", \"todo\", \"done\"];\n\n/**\n * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each\n * written with `replace` (typing does not bury the Back button), the defaults as the\n * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.\n * `params` renames them (kastlan's `?group`). Requires a react-router Router.\n */\nexport function useTourCatalogueUrlState(\n  params: { query?: string; group?: string; state?: string } = {},\n): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {\n  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({\n    query: { param: params.query ?? \"q\", default: \"\", history: \"replace\" },\n    group: { param: params.group ?? \"topic\", default: null, history: \"replace\", parse: (raw) => raw || undefined },\n    state: {\n      param: params.state ?? \"state\",\n      default: \"all\",\n      history: \"replace\",\n      parse: (raw) => STATES.find((x) => x === raw),\n    },\n  });\n  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.\n  return { ...filter, onChange: setFilter };\n}\n"],"mappings":"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","names":[]}

package/dist/wizard/stepper-nav.js

@@ -149,10 +149,7 @@ function StepperNav({
           !isLast && /* @__PURE__ */ jsx(
             "div",
             {
-              className: cn(
-                "mx-2 h-0.5 flex-1",
-                status === "completed" ? "bg-brand" : "bg-[var(--border)]"
-              )
+              className: cn("mx-2 h-0.5 flex-1", status === "completed" ? "bg-brand" : "bg-[var(--border)]")
             }
           )
         ] }, step.id);
@@ -164,32 +161,14 @@ function StepperNav({
       ] })
     ] }),
     /* @__PURE__ */ jsx(WizardContextProvider, { value: contextValue, children: /* @__PURE__ */ jsx("div", { style: contentFloor > 0 ? { minHeight: contentFloor } : void 0, children: /* @__PURE__ */ jsx("div", { ref: contentRef, children }) }) }),
-    wizard.error && /* @__PURE__ */ jsx(
-      "div",
-      {
-        role: "alert",
-        className: cn(
-          "text-sm text-danger",
-          alertFrameClass("danger")
-        ),
-        children: wizard.error
-      }
-    ),
+    wizard.error && /* @__PURE__ */ jsx("div", { role: "alert", className: cn("text-sm text-danger", alertFrameClass("danger")), children: wizard.error }),
     /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between border-t border-subtle pt-4", children: [
       wizard.canCancel ? /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: wizard.cancel, children: l.cancel }) : /* @__PURE__ */ jsx("span", {}),
       /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
         wizard.canGoBack && // Disabled, not hidden, while the commit runs: it comes back if the commit
         // fails, and a button that vanishes mid-click is its own kind of surprise.
         /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: wizard.goBack, disabled: wizard.isSubmitting, children: l.back }),
-        wizard.currentStep.optional && !wizard.isLastStep && !wizard.isCommitStep && /* @__PURE__ */ jsx(
-          Button,
-          {
-            variant: "ghost",
-            onClick: wizard.skip,
-            disabled: wizard.nextBlocked || wizard.isValidating,
-            children: l.skip
-          }
-        ),
+        wizard.currentStep.optional && !wizard.isLastStep && !wizard.isCommitStep && /* @__PURE__ */ jsx(Button, { variant: "ghost", onClick: wizard.skip, disabled: wizard.nextBlocked || wizard.isValidating, children: l.skip }),
         forwardButton
       ] })
     ] }),

package/dist/wizard/stepper-nav.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/wizard/stepper-nav.tsx"],"sourcesContent":["import { useId, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport type { ReactElement, ReactNode } from \"react\";\nimport { Check } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { Button } from \"../components/button\";\nimport { Spinner } from \"../components/spinner\";\nimport type { ButtonVariant } from \"../components/button-look\";\nimport { Modal } from \"../components/modal\";\nimport { alertFrameClass } from \"../components/alert-banner\";\nimport { WizardContextProvider } from \"./wizard-context\";\nimport { DEFAULT_WIZARD_LABELS } from \"./types\";\nimport { useKitLabels, type LabelOverride } from \"../i18n/kit-labels\";\nimport type { UseWizardReturn, WizardFinishResult, WizardLabels } from \"./types\";\nimport type { CommitScope } from \"../components/write-lock\";\nimport { useTourGateRelease } from \"../tour/tour-gates\";\n\n/**\n * The chrome around a wizard: the step indicator, the step content, and the\n * Cancel / Back / Skip / Next / Finish bar — plus the cancel-confirmation\n * dialog, because \"are you sure you want to lose this\" is part of the wizard's\n * contract rather than something each app should re-decide.\n *\n * It is a component and not a set of parts for one reason: which button shows,\n * and whether it is enabled, is a function of `wizard` state that was getting\n * re-derived (and re-derived slightly differently) at every call site. Finish is\n * gated on `canFinish`, Next and Skip on `nextBlocked`, and Skip only appears on\n * an `optional` step that is not the last — that policy lives here now.\n *\n * The `<StepperNav>` is also what publishes {@link WizardContextProvider}, which\n * is how a mounted step registers its own validator. A step's\n * `useRhfWizardStep` / `useWizardStepValidate` therefore only works inside one.\n *\n * Which buttons show is read off `wizard` (`canCancel`, `canGoBack`, `canDone`,\n * `isCommitStep`), so the policy options — `cancellable`, `onExit`, `commits`,\n * `onDone` — are all set on `useWizard`. What is set HERE is how the Finish button\n * looks and what wraps it, because that is presentation and usually depends on\n * state the app holds (a \"replace everything\" toggle, a write lock — `finishCommit`).\n */\nexport function StepperNav<TData extends Record<string, unknown>>({\n  wizard,\n  children,\n  title,\n  description,\n  className,\n  labels,\n  finishVariant = \"accent\",\n  finishDisabled = false,\n  finishCommit,\n  finishDisabledReason,\n  doneDisabled = false,\n  renderFinish,\n}: {\n  wizard: UseWizardReturn<TData>;\n  children: ReactNode;\n  title?: ReactNode;\n  description?: ReactNode;\n  className?: string;\n  labels?: LabelOverride<WizardLabels>;\n  /** The Finish button's variant — `\"danger\"` for a destructive commit (an import\n   *  that replaces what is there). Default `\"accent\"`. Next keeps `\"accent\"`. */\n  finishVariant?: ButtonVariant;\n  /** Disable Finish for a reason of the app's own, on top of the kit's gates\n   *  (`canFinish`, submitting, validating). */\n  finishDisabled?: boolean;\n  /**\n   * Finish COMMITS — {@link Button}'s `commit`, handed to the Finish button. Under a\n   * locked {@link WriteLockProvider} it is `aria-disabled` but focusable, with the lock's\n   * reason in the kit Tooltip, and a click (or Enter) does not run `wizard.finish`.\n   * Every other button of the bar stays live: the steps before the commit write nothing,\n   * so the whole wizard can still be walked through on a read-only page.\n   *\n   * keksdose G1: its YNAB import runs the mapping wizard on the read-only demo (dev#497)\n   * and locks only the confirm step's Finish — by cloning `commit` into the element\n   * `renderFinish` hands it, because StepperNav took no `commit` of its own. That clone\n   * still works; this is the same thing without one. Named `finishCommit` beside\n   * `finishVariant` / `finishDisabled` rather than a bare `commit`, which on a component\n   * with five buttons would not say which one saves — and would read like `useWizard`'s\n   * `commits`, which is a step's policy, not a lock.\n   */\n  finishCommit?: CommitScope;\n  /**\n   * Why Finish is not available — {@link Button}'s `disabledReason` on the Finish button:\n   * `aria-disabled` and focusable, the reason in the kit Tooltip and on the button's\n   * `aria-describedby`, `wizard.finish` not run. The explained form of `finishDisabled`\n   * (a native `disabled` takes the button out of the tab order, so its reason never\n   * reaches a keyboard). Under a lock with `finishCommit`, the lock's reason wins.\n   */\n  finishDisabledReason?: ReactNode;\n  /**\n   * Disable Done — the button of the last step after a commit — while the step still\n   * has work of its own running. keksdose's YNAB import ends on a recurring step whose\n   * convert loop writes one rule at a time (ynab-import-panel.tsx): leaving mid-loop\n   * abandons the rest. Until now the panel dropped `onDone` for the duration, which\n   * takes the button away instead of saying \"not yet\": disabled, it stays where the\n   * eye left it and comes back to life when the loop ends.\n   */\n  doneDisabled?: boolean;\n  /**\n   * Wrap the Finish button: receives the kit's button element — already labelled,\n   * gated and wired to `wizard.finish` — and returns what to render in its place.\n   *\n   * ```tsx\n   * renderFinish={(button) => <SaveGuard lock={lock}>{button}</SaveGuard>}\n   * ```\n   *\n   * A wrapper and not a replacement (`finishButton: (props) => …`) or a hook\n   * (`onBeforeFinish`): the app's need is to put something AROUND the commit — a\n   * write-lock tooltip, which has to sit on a wrapping element because a disabled\n   * button receives no pointer events — while the kit keeps owning what the button\n   * says and when it is enabled. A replacement would hand every app the gating to\n   * re-derive (the problem this component exists to end); `onBeforeFinish` can veto\n   * a click but cannot explain a disabled button. The element is a plain `<Button>`,\n   * so a wrapper that clones it with `disabled` works as expected.\n   *\n   * For the write lock itself there is no need to wrap any more: `finishCommit` (and\n   * `finishDisabledReason`) put the kit Button's own Tooltip on Finish. An element\n   * cloned with `commit` here keeps working the same way.\n   */\n  renderFinish?: (button: ReactElement) => ReactNode;\n}) {\n  const l = useKitLabels(\"wizard\", DEFAULT_WIZARD_LABELS, labels);\n  const cancelTitleId = useId();\n\n  // The step area never shrinks below the tallest step shown so far, so the button\n  // bar does not jump up and down as Next and Back move between a long step and a\n  // short one. This replaces a fixed `min-h-[300px]` (carried over from Kastlan,\n  // whose steps are all long forms), which did the same for steps under 300px but\n  // left a short wizard — two fields a step — with a ~200px hole above its buttons.\n  // Measured rather than guessed: the floor is whatever the app's own steps need.\n  const contentRef = useRef<HTMLDivElement>(null);\n  const [contentFloor, setContentFloor] = useState(0);\n  useLayoutEffect(() => {\n    const el = contentRef.current;\n    if (!el || typeof ResizeObserver === \"undefined\") return;\n    const observer = new ResizeObserver(() => {\n      const h = el.offsetHeight;\n      setContentFloor((floor) => (h > floor ? h : floor));\n    });\n    observer.observe(el);\n    return () => observer.disconnect();\n  }, []);\n\n  const contextValue = useMemo(\n    () => ({\n      registerStepValidate: wizard.registerStepValidate,\n      setNextBlocked: wizard.setNextBlocked,\n    }),\n    [wizard.registerStepValidate, wizard.setNextBlocked],\n  );\n\n  // Finish is only valid once every step before the last has been completed or\n  // skipped (derived once in useWizard). Prevents a restored last-step index\n  // (empty data after a reload) from firing an empty submit.\n  const canFinish = wizard.canFinish;\n\n  // A running tour's `awaitGate` steps (0.50, docs/tours-harmonization.md §11.9): Next\n  // releases \"wizard-next\" when the wizard moved and refuses it when a validator kept it\n  // in place; Finish releases \"wizard-finish\" once `onComplete` resolved and refuses it,\n  // with the error's message, when it threw. No-ops without a TourProvider or a tour.\n  const tourGates = useTourGateRelease();\n  // `useWizard`'s goNext/finish resolve their outcome at run time (see their types); a\n  // wizard object built some other way resolves nothing, and nothing is signalled.\n  const goNext = async () => {\n    const moved = (await wizard.goNext()) as unknown as boolean | undefined;\n    if (moved === true) tourGates.release(\"wizard-next\");\n    else if (moved === false) tourGates.refuse(\"wizard-next\");\n  };\n  const finish = async () => {\n    const result = (await wizard.finish()) as unknown as WizardFinishResult | undefined;\n    if (!result) return;\n    if (result.ok) tourGates.release(\"wizard-finish\");\n    else tourGates.refuse(\"wizard-finish\", result.error);\n  };\n\n  // Pending while the step's validators run (an async server check): a spinner and\n  // `aria-busy`, and disabled — the hook's own re-entry guard still refuses a second\n  // press, this just stops it looking like the first one did nothing.\n  const pending = wizard.isValidating;\n  const stepNextLabel = wizard.currentStep.nextLabel;\n\n  // Every branch below assigns it; no initial value to overwrite.\n  let forwardButton: ReactNode;\n  if (wizard.isCommitStep) {\n    const finishButton = (\n      <Button\n        variant={finishVariant}\n        data-tour=\"wizard-finish\"\n        onClick={() => void finish()}\n        // The kit Button's lock: a reason (its own or, with `commit`, the provider's)\n        // wins over `disabled` and keeps the button reachable, saying why.\n        commit={finishCommit}\n        disabledReason={finishDisabledReason}\n        disabled={wizard.isSubmitting || pending || !canFinish || finishDisabled}\n        aria-busy={wizard.isSubmitting || pending || undefined}\n      >\n        {/* Decorative: the button's text is what a reader hears. */}\n        {pending && <Spinner label={null} className=\"size-4\" />}\n        {wizard.isSubmitting ? l.submitting : (stepNextLabel ?? l.finish)}\n      </Button>\n    );\n    forwardButton = renderFinish ? renderFinish(finishButton) : finishButton;\n  } else if (wizard.isLastStep) {\n    // The last step after a commit. Nothing to finish; Done only when the app gave\n    // an `onDone` — otherwise the step carries its own way out.\n    forwardButton = wizard.canDone ? (\n      <Button variant=\"accent\" data-tour=\"wizard-done\" onClick={wizard.done} disabled={doneDisabled}>\n        {stepNextLabel ?? l.done ?? DEFAULT_WIZARD_LABELS.done}\n      </Button>\n    ) : null;\n  } else {\n    forwardButton = (\n      <Button\n        variant=\"accent\"\n        data-tour=\"wizard-next\"\n        onClick={() => void goNext()}\n        disabled={wizard.nextBlocked || pending}\n        aria-busy={pending || undefined}\n      >\n        {pending && <Spinner label={null} className=\"size-4\" />}\n        {stepNextLabel ?? l.next}\n      </Button>\n    );\n  }\n\n  return (\n    <div className={cn(\"flex flex-col gap-6\", className)}>\n      {(title || description) && (\n        <div>\n          {title && (\n            <h1 className=\"text-2xl font-bold tracking-tight text-primary\">\n              {title}\n            </h1>\n          )}\n          {description && (\n            <p className=\"mt-1 text-sm text-muted\">{description}</p>\n          )}\n        </div>\n      )}\n\n      {/* Step indicator */}\n      <nav aria-label={l.steps}>\n        <ol className=\"flex w-full items-center\">\n          {wizard.steps.map((step, index) => {\n            const status = wizard.stepStatus(index);\n            const isLast = index === wizard.steps.length - 1;\n\n            return (\n              <li key={step.id} className={cn(\"flex items-center\", !isLast && \"flex-1\")}>\n                <button\n                  type=\"button\"\n                  onClick={() => wizard.goToStep(index)}\n                  // `canGoToStep` adds the commit lock: once past a committing step,\n                  // the steps up to it are done with and cannot be reopened.\n                  disabled={status === \"upcoming\" || !wizard.canGoToStep(index)}\n                  aria-current={status === \"active\" ? \"step\" : undefined}\n                  className={cn(\n                    \"group flex flex-col items-center gap-1.5\",\n                    status === \"upcoming\" ? \"cursor-default\" : \"cursor-pointer\",\n                  )}\n                >\n                  {/* Circle */}\n                  <span\n                    className={cn(\n                      \"flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-xs font-semibold transition-colors\",\n                      status === \"completed\" &&\n                        \"border-brand bg-brand text-brand-contrast\",\n                      status === \"active\" &&\n                        \"border-brand bg-surface text-brand\",\n                      status === \"upcoming\" &&\n                        \"border-subtle bg-surface text-placeholder\",\n                      status === \"skipped\" &&\n                        \"border-subtle bg-surface-2 text-muted\",\n                    )}\n                  >\n                    {status === \"completed\" ? <Check className=\"size-4\" /> : index + 1}\n                  </span>\n                  {/* Label — hidden on mobile, where the line below carries it */}\n                  <span\n                    className={cn(\n                      \"hidden text-xs font-medium md:block\",\n                      status === \"active\" || status === \"completed\"\n                        ? \"text-primary\"\n                        : \"text-muted\",\n                    )}\n                  >\n                    {step.label}\n                  </span>\n                </button>\n\n                {/* Connector line */}\n                {!isLast && (\n                  <div\n                    className={cn(\n                      \"mx-2 h-0.5 flex-1\",\n                      status === \"completed\" ? \"bg-brand\" : \"bg-[var(--border)]\",\n                    )}\n                  />\n                )}\n              </li>\n            );\n          })}\n        </ol>\n        {/* Mobile: the labels above are hidden, so name the current step here */}\n        <p className=\"mt-2 text-center text-sm font-medium text-primary md:hidden\">\n          {l.step(wizard.currentStepIndex + 1, wizard.steps.length)}\n          {\" — \"}\n          {wizard.currentStep.label}\n        </p>\n      </nav>\n\n      {/* Step content */}\n      <WizardContextProvider value={contextValue}>\n        <div style={contentFloor > 0 ? { minHeight: contentFloor } : undefined}>\n          <div ref={contentRef}>{children}</div>\n        </div>\n      </WizardContextProvider>\n\n      {/* Submit error */}\n      {wizard.error && (\n        <div\n          role=\"alert\"\n          className={cn(\n            \"text-sm text-danger\",\n            alertFrameClass(\"danger\"),\n          )}\n        >\n          {wizard.error}\n        </div>\n      )}\n\n      {/* Navigation bar */}\n      <div className=\"flex items-center justify-between border-t border-subtle pt-4\">\n        {/* The empty span keeps the right-hand group on the right when Cancel is off. */}\n        {wizard.canCancel ? (\n          <Button variant=\"secondary\" onClick={wizard.cancel}>\n            {l.cancel}\n          </Button>\n        ) : (\n          <span />\n        )}\n        <div className=\"flex items-center gap-2\">\n          {wizard.canGoBack && (\n            // Disabled, not hidden, while the commit runs: it comes back if the commit\n            // fails, and a button that vanishes mid-click is its own kind of surprise.\n            <Button variant=\"secondary\" onClick={wizard.goBack} disabled={wizard.isSubmitting}>\n              {l.back}\n            </Button>\n          )}\n          {wizard.currentStep.optional && !wizard.isLastStep && !wizard.isCommitStep && (\n            <Button\n              variant=\"ghost\"\n              onClick={wizard.skip}\n              disabled={wizard.nextBlocked || wizard.isValidating}\n            >\n              {l.skip}\n            </Button>\n          )}\n          {forwardButton}\n        </div>\n      </div>\n\n      {/* Cancel confirmation */}\n      {wizard.showCancelDialog && (\n        <Modal onClose={wizard.dismissCancel} labelledBy={cancelTitleId} className=\"space-y-4\">\n          <div className=\"space-y-1.5\">\n            <h2 id={cancelTitleId} className=\"text-lg font-semibold text-primary\">\n              {l.cancelTitle}\n            </h2>\n            <p className=\"text-sm text-muted\">{l.confirmCancel}</p>\n          </div>\n          <div className=\"flex flex-col-reverse gap-2 sm:flex-row sm:justify-end\">\n            <Button variant=\"secondary\" onClick={wizard.dismissCancel}>\n              {l.cancelDismissLabel}\n            </Button>\n            <Button variant=\"danger\" onClick={wizard.confirmCancel}>\n              {l.cancelConfirmLabel}\n            </Button>\n          </div>\n        </Modal>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/wizard/stepper-nav.tsx"],"sourcesContent":["import { useId, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport type { ReactElement, ReactNode } from \"react\";\nimport { Check } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { Button } from \"../components/button\";\nimport { Spinner } from \"../components/spinner\";\nimport type { ButtonVariant } from \"../components/button-look\";\nimport { Modal } from \"../components/modal\";\nimport { alertFrameClass } from \"../components/alert-banner\";\nimport { WizardContextProvider } from \"./wizard-context\";\nimport { DEFAULT_WIZARD_LABELS } from \"./types\";\nimport { useKitLabels, type LabelOverride } from \"../i18n/kit-labels\";\nimport type { UseWizardReturn, WizardFinishResult, WizardLabels } from \"./types\";\nimport type { CommitScope } from \"../components/write-lock\";\nimport { useTourGateRelease } from \"../tour/tour-gates\";\n\n/**\n * The chrome around a wizard: the step indicator, the step content, and the\n * Cancel / Back / Skip / Next / Finish bar — plus the cancel-confirmation\n * dialog, because \"are you sure you want to lose this\" is part of the wizard's\n * contract rather than something each app should re-decide.\n *\n * It is a component and not a set of parts for one reason: which button shows,\n * and whether it is enabled, is a function of `wizard` state that was getting\n * re-derived (and re-derived slightly differently) at every call site. Finish is\n * gated on `canFinish`, Next and Skip on `nextBlocked`, and Skip only appears on\n * an `optional` step that is not the last — that policy lives here now.\n *\n * The `<StepperNav>` is also what publishes {@link WizardContextProvider}, which\n * is how a mounted step registers its own validator. A step's\n * `useRhfWizardStep` / `useWizardStepValidate` therefore only works inside one.\n *\n * Which buttons show is read off `wizard` (`canCancel`, `canGoBack`, `canDone`,\n * `isCommitStep`), so the policy options — `cancellable`, `onExit`, `commits`,\n * `onDone` — are all set on `useWizard`. What is set HERE is how the Finish button\n * looks and what wraps it, because that is presentation and usually depends on\n * state the app holds (a \"replace everything\" toggle, a write lock — `finishCommit`).\n */\nexport function StepperNav<TData extends Record<string, unknown>>({\n  wizard,\n  children,\n  title,\n  description,\n  className,\n  labels,\n  finishVariant = \"accent\",\n  finishDisabled = false,\n  finishCommit,\n  finishDisabledReason,\n  doneDisabled = false,\n  renderFinish,\n}: {\n  wizard: UseWizardReturn<TData>;\n  children: ReactNode;\n  title?: ReactNode;\n  description?: ReactNode;\n  className?: string;\n  labels?: LabelOverride<WizardLabels>;\n  /** The Finish button's variant — `\"danger\"` for a destructive commit (an import\n   *  that replaces what is there). Default `\"accent\"`. Next keeps `\"accent\"`. */\n  finishVariant?: ButtonVariant;\n  /** Disable Finish for a reason of the app's own, on top of the kit's gates\n   *  (`canFinish`, submitting, validating). */\n  finishDisabled?: boolean;\n  /**\n   * Finish COMMITS — {@link Button}'s `commit`, handed to the Finish button. Under a\n   * locked {@link WriteLockProvider} it is `aria-disabled` but focusable, with the lock's\n   * reason in the kit Tooltip, and a click (or Enter) does not run `wizard.finish`.\n   * Every other button of the bar stays live: the steps before the commit write nothing,\n   * so the whole wizard can still be walked through on a read-only page.\n   *\n   * keksdose G1: its YNAB import runs the mapping wizard on the read-only demo (dev#497)\n   * and locks only the confirm step's Finish — by cloning `commit` into the element\n   * `renderFinish` hands it, because StepperNav took no `commit` of its own. That clone\n   * still works; this is the same thing without one. Named `finishCommit` beside\n   * `finishVariant` / `finishDisabled` rather than a bare `commit`, which on a component\n   * with five buttons would not say which one saves — and would read like `useWizard`'s\n   * `commits`, which is a step's policy, not a lock.\n   */\n  finishCommit?: CommitScope;\n  /**\n   * Why Finish is not available — {@link Button}'s `disabledReason` on the Finish button:\n   * `aria-disabled` and focusable, the reason in the kit Tooltip and on the button's\n   * `aria-describedby`, `wizard.finish` not run. The explained form of `finishDisabled`\n   * (a native `disabled` takes the button out of the tab order, so its reason never\n   * reaches a keyboard). Under a lock with `finishCommit`, the lock's reason wins.\n   */\n  finishDisabledReason?: ReactNode;\n  /**\n   * Disable Done — the button of the last step after a commit — while the step still\n   * has work of its own running. keksdose's YNAB import ends on a recurring step whose\n   * convert loop writes one rule at a time (ynab-import-panel.tsx): leaving mid-loop\n   * abandons the rest. Until now the panel dropped `onDone` for the duration, which\n   * takes the button away instead of saying \"not yet\": disabled, it stays where the\n   * eye left it and comes back to life when the loop ends.\n   */\n  doneDisabled?: boolean;\n  /**\n   * Wrap the Finish button: receives the kit's button element — already labelled,\n   * gated and wired to `wizard.finish` — and returns what to render in its place.\n   *\n   * ```tsx\n   * renderFinish={(button) => <SaveGuard lock={lock}>{button}</SaveGuard>}\n   * ```\n   *\n   * A wrapper and not a replacement (`finishButton: (props) => …`) or a hook\n   * (`onBeforeFinish`): the app's need is to put something AROUND the commit — a\n   * write-lock tooltip, which has to sit on a wrapping element because a disabled\n   * button receives no pointer events — while the kit keeps owning what the button\n   * says and when it is enabled. A replacement would hand every app the gating to\n   * re-derive (the problem this component exists to end); `onBeforeFinish` can veto\n   * a click but cannot explain a disabled button. The element is a plain `<Button>`,\n   * so a wrapper that clones it with `disabled` works as expected.\n   *\n   * For the write lock itself there is no need to wrap any more: `finishCommit` (and\n   * `finishDisabledReason`) put the kit Button's own Tooltip on Finish. An element\n   * cloned with `commit` here keeps working the same way.\n   */\n  renderFinish?: (button: ReactElement) => ReactNode;\n}) {\n  const l = useKitLabels(\"wizard\", DEFAULT_WIZARD_LABELS, labels);\n  const cancelTitleId = useId();\n\n  // The step area never shrinks below the tallest step shown so far, so the button\n  // bar does not jump up and down as Next and Back move between a long step and a\n  // short one. This replaces a fixed `min-h-[300px]` (carried over from Kastlan,\n  // whose steps are all long forms), which did the same for steps under 300px but\n  // left a short wizard — two fields a step — with a ~200px hole above its buttons.\n  // Measured rather than guessed: the floor is whatever the app's own steps need.\n  const contentRef = useRef<HTMLDivElement>(null);\n  const [contentFloor, setContentFloor] = useState(0);\n  useLayoutEffect(() => {\n    const el = contentRef.current;\n    if (!el || typeof ResizeObserver === \"undefined\") return;\n    const observer = new ResizeObserver(() => {\n      const h = el.offsetHeight;\n      setContentFloor((floor) => (h > floor ? h : floor));\n    });\n    observer.observe(el);\n    return () => observer.disconnect();\n  }, []);\n\n  const contextValue = useMemo(\n    () => ({\n      registerStepValidate: wizard.registerStepValidate,\n      setNextBlocked: wizard.setNextBlocked,\n    }),\n    [wizard.registerStepValidate, wizard.setNextBlocked],\n  );\n\n  // Finish is only valid once every step before the last has been completed or\n  // skipped (derived once in useWizard). Prevents a restored last-step index\n  // (empty data after a reload) from firing an empty submit.\n  const canFinish = wizard.canFinish;\n\n  // A running tour's `awaitGate` steps (0.50, docs/tours-harmonization.md §11.9): Next\n  // releases \"wizard-next\" when the wizard moved and refuses it when a validator kept it\n  // in place; Finish releases \"wizard-finish\" once `onComplete` resolved and refuses it,\n  // with the error's message, when it threw. No-ops without a TourProvider or a tour.\n  const tourGates = useTourGateRelease();\n  // `useWizard`'s goNext/finish resolve their outcome at run time (see their types); a\n  // wizard object built some other way resolves nothing, and nothing is signalled.\n  const goNext = async () => {\n    const moved = (await wizard.goNext()) as unknown as boolean | undefined;\n    if (moved === true) tourGates.release(\"wizard-next\");\n    else if (moved === false) tourGates.refuse(\"wizard-next\");\n  };\n  const finish = async () => {\n    const result = (await wizard.finish()) as unknown as WizardFinishResult | undefined;\n    if (!result) return;\n    if (result.ok) tourGates.release(\"wizard-finish\");\n    else tourGates.refuse(\"wizard-finish\", result.error);\n  };\n\n  // Pending while the step's validators run (an async server check): a spinner and\n  // `aria-busy`, and disabled — the hook's own re-entry guard still refuses a second\n  // press, this just stops it looking like the first one did nothing.\n  const pending = wizard.isValidating;\n  const stepNextLabel = wizard.currentStep.nextLabel;\n\n  // Every branch below assigns it; no initial value to overwrite.\n  let forwardButton: ReactNode;\n  if (wizard.isCommitStep) {\n    const finishButton = (\n      <Button\n        variant={finishVariant}\n        data-tour=\"wizard-finish\"\n        onClick={() => void finish()}\n        // The kit Button's lock: a reason (its own or, with `commit`, the provider's)\n        // wins over `disabled` and keeps the button reachable, saying why.\n        commit={finishCommit}\n        disabledReason={finishDisabledReason}\n        disabled={wizard.isSubmitting || pending || !canFinish || finishDisabled}\n        aria-busy={wizard.isSubmitting || pending || undefined}\n      >\n        {/* Decorative: the button's text is what a reader hears. */}\n        {pending && <Spinner label={null} className=\"size-4\" />}\n        {wizard.isSubmitting ? l.submitting : (stepNextLabel ?? l.finish)}\n      </Button>\n    );\n    forwardButton = renderFinish ? renderFinish(finishButton) : finishButton;\n  } else if (wizard.isLastStep) {\n    // The last step after a commit. Nothing to finish; Done only when the app gave\n    // an `onDone` — otherwise the step carries its own way out.\n    forwardButton = wizard.canDone ? (\n      <Button variant=\"accent\" data-tour=\"wizard-done\" onClick={wizard.done} disabled={doneDisabled}>\n        {stepNextLabel ?? l.done ?? DEFAULT_WIZARD_LABELS.done}\n      </Button>\n    ) : null;\n  } else {\n    forwardButton = (\n      <Button\n        variant=\"accent\"\n        data-tour=\"wizard-next\"\n        onClick={() => void goNext()}\n        disabled={wizard.nextBlocked || pending}\n        aria-busy={pending || undefined}\n      >\n        {pending && <Spinner label={null} className=\"size-4\" />}\n        {stepNextLabel ?? l.next}\n      </Button>\n    );\n  }\n\n  return (\n    <div className={cn(\"flex flex-col gap-6\", className)}>\n      {(title || description) && (\n        <div>\n          {title && <h1 className=\"text-2xl font-bold tracking-tight text-primary\">{title}</h1>}\n          {description && <p className=\"mt-1 text-sm text-muted\">{description}</p>}\n        </div>\n      )}\n\n      {/* Step indicator */}\n      <nav aria-label={l.steps}>\n        <ol className=\"flex w-full items-center\">\n          {wizard.steps.map((step, index) => {\n            const status = wizard.stepStatus(index);\n            const isLast = index === wizard.steps.length - 1;\n\n            return (\n              <li key={step.id} className={cn(\"flex items-center\", !isLast && \"flex-1\")}>\n                <button\n                  type=\"button\"\n                  onClick={() => wizard.goToStep(index)}\n                  // `canGoToStep` adds the commit lock: once past a committing step,\n                  // the steps up to it are done with and cannot be reopened.\n                  disabled={status === \"upcoming\" || !wizard.canGoToStep(index)}\n                  aria-current={status === \"active\" ? \"step\" : undefined}\n                  className={cn(\n                    \"group flex flex-col items-center gap-1.5\",\n                    status === \"upcoming\" ? \"cursor-default\" : \"cursor-pointer\",\n                  )}\n                >\n                  {/* Circle */}\n                  <span\n                    className={cn(\n                      \"flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-xs font-semibold transition-colors\",\n                      status === \"completed\" && \"border-brand bg-brand text-brand-contrast\",\n                      status === \"active\" && \"border-brand bg-surface text-brand\",\n                      status === \"upcoming\" && \"border-subtle bg-surface text-placeholder\",\n                      status === \"skipped\" && \"border-subtle bg-surface-2 text-muted\",\n                    )}\n                  >\n                    {status === \"completed\" ? <Check className=\"size-4\" /> : index + 1}\n                  </span>\n                  {/* Label — hidden on mobile, where the line below carries it */}\n                  <span\n                    className={cn(\n                      \"hidden text-xs font-medium md:block\",\n                      status === \"active\" || status === \"completed\" ? \"text-primary\" : \"text-muted\",\n                    )}\n                  >\n                    {step.label}\n                  </span>\n                </button>\n\n                {/* Connector line */}\n                {!isLast && (\n                  <div\n                    className={cn(\"mx-2 h-0.5 flex-1\", status === \"completed\" ? \"bg-brand\" : \"bg-[var(--border)]\")}\n                  />\n                )}\n              </li>\n            );\n          })}\n        </ol>\n        {/* Mobile: the labels above are hidden, so name the current step here */}\n        <p className=\"mt-2 text-center text-sm font-medium text-primary md:hidden\">\n          {l.step(wizard.currentStepIndex + 1, wizard.steps.length)}\n          {\" — \"}\n          {wizard.currentStep.label}\n        </p>\n      </nav>\n\n      {/* Step content */}\n      <WizardContextProvider value={contextValue}>\n        <div style={contentFloor > 0 ? { minHeight: contentFloor } : undefined}>\n          <div ref={contentRef}>{children}</div>\n        </div>\n      </WizardContextProvider>\n\n      {/* Submit error */}\n      {wizard.error && (\n        <div role=\"alert\" className={cn(\"text-sm text-danger\", alertFrameClass(\"danger\"))}>\n          {wizard.error}\n        </div>\n      )}\n\n      {/* Navigation bar */}\n      <div className=\"flex items-center justify-between border-t border-subtle pt-4\">\n        {/* The empty span keeps the right-hand group on the right when Cancel is off. */}\n        {wizard.canCancel ? (\n          <Button variant=\"secondary\" onClick={wizard.cancel}>\n            {l.cancel}\n          </Button>\n        ) : (\n          <span />\n        )}\n        <div className=\"flex items-center gap-2\">\n          {wizard.canGoBack && (\n            // Disabled, not hidden, while the commit runs: it comes back if the commit\n            // fails, and a button that vanishes mid-click is its own kind of surprise.\n            <Button variant=\"secondary\" onClick={wizard.goBack} disabled={wizard.isSubmitting}>\n              {l.back}\n            </Button>\n          )}\n          {wizard.currentStep.optional && !wizard.isLastStep && !wizard.isCommitStep && (\n            <Button variant=\"ghost\" onClick={wizard.skip} disabled={wizard.nextBlocked || wizard.isValidating}>\n              {l.skip}\n            </Button>\n          )}\n          {forwardButton}\n        </div>\n      </div>\n\n      {/* Cancel confirmation */}\n      {wizard.showCancelDialog && (\n        <Modal onClose={wizard.dismissCancel} labelledBy={cancelTitleId} className=\"space-y-4\">\n          <div className=\"space-y-1.5\">\n            <h2 id={cancelTitleId} className=\"text-lg font-semibold text-primary\">\n              {l.cancelTitle}\n            </h2>\n            <p className=\"text-sm text-muted\">{l.confirmCancel}</p>\n          </div>\n          <div className=\"flex flex-col-reverse gap-2 sm:flex-row sm:justify-end\">\n            <Button variant=\"secondary\" onClick={wizard.dismissCancel}>\n              {l.cancelDismissLabel}\n            </Button>\n            <Button variant=\"danger\" onClick={wizard.confirmCancel}>\n              {l.cancelConfirmLabel}\n            </Button>\n          </div>\n        </Modal>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/wizard/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/wizard/types.ts"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { DEFAULT_WIZARD_LABELS } from \"./wizard-labels\";\n\nexport type FieldErrors = Record<string, string>;\n\nexport type ValidateResult = boolean | { ok: boolean; errors?: FieldErrors };\n\nexport interface WizardStepConfig {\n  /** Unique step identifier. */\n  id: string;\n  /**\n   * What the step is called in the indicator.\n   *\n   * A `ReactNode`, not a translation key: the engine never resolves strings.\n   * An app with i18n maps its own keys at the `useWizard` call — the same split\n   * `TourStep` and `DataTableLabels` already use.\n   */\n  label: ReactNode;\n  /** Whether the step can be skipped. */\n  optional?: boolean;\n  /**\n   * Validation gate before advancing.\n   * - Return `true` / `false` to just block.\n   * - Return `{ ok: false, errors: { fieldName: \"message\" } }` to also surface\n   *   per-field error messages via `wizard.fieldErrors`.\n   */\n  validate?: () => ValidateResult | Promise<ValidateResult>;\n  /**\n   * The forward button's label on THIS step, in place of `labels.next` — \"Analyse\",\n   * \"Import\", \"Send code\". On the committing step (see {@link commits}) it labels\n   * Finish instead of `labels.finish`; `labels.submitting` still replaces it while\n   * the commit runs. Like `label`, a node the app has already translated.\n   */\n  nextLabel?: ReactNode;\n  /**\n   * This step's forward button COMMITS: it runs `onComplete` (via `finish`) instead\n   * of just advancing. Without the flag the last step commits, as it always has.\n   *\n   * Flag a step before the last and every step after it becomes a post-commit step —\n   * an import's \"here is what happened, set up recurring rules?\" page:\n   *  - a successful `onComplete` advances onto the next step (a failed one stays, with\n   *    `wizard.error`, exactly like a last-step Finish);\n   *  - from there Back, the indicator and `goBack`/`goToStep` cannot cross back over\n   *    the commit, and Cancel is hidden — there is nothing left to discard;\n   *  - the last post-commit step's button is Done, which calls `onDone` (and is not\n   *    shown when there is no `onDone`: the step then carries its own way out).\n   *\n   * Only the FIRST flagged step counts. Steps after it may still validate, skip and\n   * use `nextLabel` like any other.\n   */\n  commits?: boolean;\n}\n\n/**\n * Where the active step lives. `true` (the default) mirrors it to `?step=N` through\n * react-router, as every wizard before 0.8 did; `{ param }` renames that param (two\n * wizards on one page, or a page that already uses `step`); `false` keeps it in\n * memory only and needs no router at all.\n *\n * Read once, at mount: switching it on a mounted wizard has no effect.\n */\nexport type WizardUrlSync = boolean | { param?: string };\n\nexport interface UseWizardOptions<TData extends Record<string, unknown>> {\n  steps: WizardStepConfig[];\n  initialData?: Partial<TData>;\n  onComplete?: (data: TData) => void | Promise<void>;\n  onCancel?: () => void;\n  /**\n   * Leave the wizard BACKWARDS: when given, Back is shown on the first step too and\n   * calls this — keksdose's import panel, whose first step's Back returns to the\n   * dropzone the file came from. No confirm dialog: going back is not discarding.\n   */\n  onExit?: () => void;\n  /**\n   * The Done button on the last step after a committing step (see\n   * {@link WizardStepConfig.commits}). Without it no Done button is rendered, and the\n   * post-commit step is expected to carry its own way out.\n   */\n  onDone?: () => void;\n  /**\n   * Whether the chrome offers Cancel at all. Default `true`. `false` hides the button\n   * (`wizard.canCancel` is false); `wizard.cancel()` still works if the app calls it.\n   */\n  cancellable?: boolean;\n  /**\n   * Whether Cancel asks first (\"Discard this form?\"). Default `true`. `false` makes\n   * `cancel()` call `onCancel` straight away — for a wizard that has nothing to lose\n   * yet, or one whose data is kept elsewhere.\n   */\n  confirmCancel?: boolean;\n  /**\n   * Mirror the active step to the URL. Default `true` (`?step=N`, needs a router).\n   * See {@link WizardUrlSync}.\n   *\n   * The param is WRITTEN only, never read back (see the note in `use-wizard.ts`). It\n   * is removed again when the wizard is left through the kit: a confirmed Cancel,\n   * `onExit` from the first step's Back, and Done — each before the app's callback\n   * runs, so an app that navigates away navigates from a clean URL. It is NOT removed\n   * after `onComplete` on a last step: an app navigating away there would otherwise\n   * be pulled back by the kit's own URL write. An app that stays on the page after a\n   * final Finish drops the param itself, or uses `urlSync: false`.\n   */\n  urlSync?: WizardUrlSync;\n  /**\n   * Shown when a step blocks with no per-field detail — an RHF step surfacing\n   * its own inline messages, say — so the user learns why the wizard did not\n   * advance. Falls back to `wizard.missingRequired` from the {@link UiKitProvider},\n   * then to English.\n   */\n  missingRequiredMessage?: string;\n  /**\n   * How to surface {@link missingRequiredMessage}. Defaults to the kit's `toast.error`\n   * (sonner, an optional peer, is loaded only when a toast is shown). Pass your own to\n   * route it somewhere else, or to a no-op to silence it.\n   */\n  onValidationFailed?: (message: string) => void;\n}\n\nexport type StepStatus = \"upcoming\" | \"active\" | \"completed\" | \"skipped\";\n\n\n/** What `finish` resolves to at run time (0.50): whether the commit went through, and the\n *  error's message when `onComplete` threw. `undefined` when there was nothing to run. */\nexport interface WizardFinishResult {\n  ok: boolean;\n  error?: string;\n}\nexport interface UseWizardReturn<TData extends Record<string, unknown>> {\n  // Navigation\n  currentStepIndex: number;\n  currentStep: WizardStepConfig;\n  steps: WizardStepConfig[];\n  isFirstStep: boolean;\n  isLastStep: boolean;\n  /** True once every step before the committing one (the last, unless a step is\n   *  flagged `commits`) has been completed or skipped. */\n  canFinish: boolean;\n  /** The step whose forward button commits: the first `commits` step, else the last. */\n  commitStepIndex: number;\n  /** The active step is {@link commitStepIndex}: the chrome shows Finish, not Next. */\n  isCommitStep: boolean;\n  /** `onComplete` has resolved. Once the active step is past the committing one, Back\n   *  cannot cross it and Cancel is hidden. */\n  committed: boolean;\n  /** Whether Back is offered here: not on the first step unless `onExit` was given,\n   *  and never back across a commit. (Disabled, not hidden, while `isSubmitting`.) */\n  canGoBack: boolean;\n  /** Whether Cancel is offered: `cancellable`, and not after a commit. */\n  canCancel: boolean;\n  /** Whether Done is offered: the last step, past a commit, with an `onDone`. */\n  canDone: boolean;\n  /** Whether the indicator may jump to `index` — a completed/skipped/active step on\n   *  the right side of any commit. `goToStep` refuses anything this rejects. */\n  canGoToStep: (index: number) => boolean;\n  /** Validates the step and moves on. (0.50: at run time it resolves `true` when it\n   *  moved, `false` when a validator kept it in place — what StepperNav tells a running\n   *  tour, docs/tours-harmonization.md §11.9. The declared type stays `Promise<void>`.) */\n  goNext: () => Promise<void>;\n  /** One step back — or, on the first step, `onExit`. Refused while submitting. */\n  goBack: () => void;\n  goToStep: (index: number) => void;\n  skip: () => void;\n  cancel: () => void;\n  /** Validates and commits (`onComplete`). (0.50: at run time it resolves `{ ok, error? }`\n   *  — see {@link WizardFinishResult}; the declared type stays `Promise<void>`.) */\n  finish: () => Promise<void>;\n  /** Leave after the post-commit steps: drops the URL param, then calls `onDone`. */\n  done: () => void;\n  /** Register a validator for the mounted step (used by useRhfWizardStep). */\n  registerStepValidate: (\n    fn: () => ValidateResult | Promise<ValidateResult>,\n  ) => () => void;\n  /** True when the mounted step has blocked forward navigation (Next/Skip disabled). */\n  nextBlocked: boolean;\n  /** Set by the active step (via useWizardNextGate) to disable/enable Next+Skip. */\n  setNextBlocked: (blocked: boolean) => void;\n\n  // Step state\n  stepStatus: (index: number) => StepStatus;\n  completedSteps: Set<number>;\n\n  // Data\n  data: TData;\n  updateData: (partial: Partial<TData>) => void;\n\n  // Loading / error\n  isSubmitting: boolean;\n  /** A `goNext`/`finish` is running the step's validators (an async server check,\n   *  say). The chrome shows Next pending — spinner, `aria-busy`, disabled. */\n  isValidating: boolean;\n  error: string | null;\n  clearError: () => void;\n\n  // Per-field validation errors (populated by the last failed goNext)\n  fieldErrors: FieldErrors;\n  clearFieldErrors: () => void;\n\n  // Cancel dialog\n  showCancelDialog: boolean;\n  confirmCancel: () => void;\n  dismissCancel: () => void;\n}\n\nexport interface SummaryItem {\n  label: ReactNode;\n  value: ReactNode;\n}\n\nexport interface SummarySection {\n  label: ReactNode;\n  /**\n   * Which step the section's edit button jumps back to. Leave it out for a section\n   * that belongs to no step — file-level counts, a total — and the card has no edit\n   * button, instead of borrowing one from whichever step it was parked under.\n   */\n  stepIndex?: number;\n  items: SummaryItem[];\n}\n\n/**\n * Every string the wizard chrome shows. All optional with English defaults, so a\n * monolingual app can mount `StepperNav` bare; a translated app passes the whole\n * object once (typically from a thin app-side wrapper).\n */\nexport interface WizardLabels {\n  cancel: string;\n  back: string;\n  next: string;\n  skip: string;\n  finish: string;\n  /** Shown on Finish while `isSubmitting`. */\n  submitting: string;\n  /** `aria-label` for the step indicator's `<nav>`. */\n  steps: string;\n  /** The mobile \"Step 2 of 5\" line. */\n  step: (current: number, total: number) => string;\n  /** Heading of the cancel-confirmation dialog. */\n  cancelTitle: string;\n  /** Body of the cancel-confirmation dialog. */\n  confirmCancel: string;\n  /** Confirm button in the cancel dialog. */\n  cancelConfirmLabel: string;\n  /** Dismiss button in the cancel dialog (\"keep editing\"). */\n  cancelDismissLabel: string;\n  /** Heading above a {@link WizardSummary}. */\n  reviewTitle: string;\n  /** `aria-label` on a summary section's edit button. */\n  edit: string;\n  /**\n   * Toasted (or handed to `onValidationFailed`) when a step blocks Next without\n   * saying which field is at fault. `useWizard`'s `missingRequiredMessage` wins.\n   *\n   * This and `genericError` are OPTIONAL, unlike every key above, for the reason\n   * `TwoFactorSettingLabels.qrAlt` is: apps annotate a full translation as\n   * `const DE: WizardLabels = {…}`, and a new required key would be a compile error\n   * in each of them on the next update. The defaults below always carry both.\n   */\n  missingRequired?: string;\n  /** `wizard.error` when `onComplete` rejects with nothing readable — a thrown\n   *  non-Error, or an Error whose message is empty. Optional: see above. */\n  genericError?: string;\n  /** The button on the last step after a committing step (`onDone`). Optional: see\n   *  `missingRequired`. */\n  done?: string;\n}\n\n// The English words live in ./wizard-labels, a module of words (round 0.34).\nexport { DEFAULT_WIZARD_LABELS };\n"],"mappings":";AACA,SAAS,6BAA6B;","names":[]}
+{"version":3,"sources":["../../src/wizard/types.ts"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { DEFAULT_WIZARD_LABELS } from \"./wizard-labels\";\n\nexport type FieldErrors = Record<string, string>;\n\nexport type ValidateResult = boolean | { ok: boolean; errors?: FieldErrors };\n\nexport interface WizardStepConfig {\n  /** Unique step identifier. */\n  id: string;\n  /**\n   * What the step is called in the indicator.\n   *\n   * A `ReactNode`, not a translation key: the engine never resolves strings.\n   * An app with i18n maps its own keys at the `useWizard` call — the same split\n   * `TourStep` and `DataTableLabels` already use.\n   */\n  label: ReactNode;\n  /** Whether the step can be skipped. */\n  optional?: boolean;\n  /**\n   * Validation gate before advancing.\n   * - Return `true` / `false` to just block.\n   * - Return `{ ok: false, errors: { fieldName: \"message\" } }` to also surface\n   *   per-field error messages via `wizard.fieldErrors`.\n   */\n  validate?: () => ValidateResult | Promise<ValidateResult>;\n  /**\n   * The forward button's label on THIS step, in place of `labels.next` — \"Analyse\",\n   * \"Import\", \"Send code\". On the committing step (see {@link commits}) it labels\n   * Finish instead of `labels.finish`; `labels.submitting` still replaces it while\n   * the commit runs. Like `label`, a node the app has already translated.\n   */\n  nextLabel?: ReactNode;\n  /**\n   * This step's forward button COMMITS: it runs `onComplete` (via `finish`) instead\n   * of just advancing. Without the flag the last step commits, as it always has.\n   *\n   * Flag a step before the last and every step after it becomes a post-commit step —\n   * an import's \"here is what happened, set up recurring rules?\" page:\n   *  - a successful `onComplete` advances onto the next step (a failed one stays, with\n   *    `wizard.error`, exactly like a last-step Finish);\n   *  - from there Back, the indicator and `goBack`/`goToStep` cannot cross back over\n   *    the commit, and Cancel is hidden — there is nothing left to discard;\n   *  - the last post-commit step's button is Done, which calls `onDone` (and is not\n   *    shown when there is no `onDone`: the step then carries its own way out).\n   *\n   * Only the FIRST flagged step counts. Steps after it may still validate, skip and\n   * use `nextLabel` like any other.\n   */\n  commits?: boolean;\n}\n\n/**\n * Where the active step lives. `true` (the default) mirrors it to `?step=N` through\n * react-router, as every wizard before 0.8 did; `{ param }` renames that param (two\n * wizards on one page, or a page that already uses `step`); `false` keeps it in\n * memory only and needs no router at all.\n *\n * Read once, at mount: switching it on a mounted wizard has no effect.\n */\nexport type WizardUrlSync = boolean | { param?: string };\n\nexport interface UseWizardOptions<TData extends Record<string, unknown>> {\n  steps: WizardStepConfig[];\n  initialData?: Partial<TData>;\n  onComplete?: (data: TData) => void | Promise<void>;\n  onCancel?: () => void;\n  /**\n   * Leave the wizard BACKWARDS: when given, Back is shown on the first step too and\n   * calls this — keksdose's import panel, whose first step's Back returns to the\n   * dropzone the file came from. No confirm dialog: going back is not discarding.\n   */\n  onExit?: () => void;\n  /**\n   * The Done button on the last step after a committing step (see\n   * {@link WizardStepConfig.commits}). Without it no Done button is rendered, and the\n   * post-commit step is expected to carry its own way out.\n   */\n  onDone?: () => void;\n  /**\n   * Whether the chrome offers Cancel at all. Default `true`. `false` hides the button\n   * (`wizard.canCancel` is false); `wizard.cancel()` still works if the app calls it.\n   */\n  cancellable?: boolean;\n  /**\n   * Whether Cancel asks first (\"Discard this form?\"). Default `true`. `false` makes\n   * `cancel()` call `onCancel` straight away — for a wizard that has nothing to lose\n   * yet, or one whose data is kept elsewhere.\n   */\n  confirmCancel?: boolean;\n  /**\n   * Mirror the active step to the URL. Default `true` (`?step=N`, needs a router).\n   * See {@link WizardUrlSync}.\n   *\n   * The param is WRITTEN only, never read back (see the note in `use-wizard.ts`). It\n   * is removed again when the wizard is left through the kit: a confirmed Cancel,\n   * `onExit` from the first step's Back, and Done — each before the app's callback\n   * runs, so an app that navigates away navigates from a clean URL. It is NOT removed\n   * after `onComplete` on a last step: an app navigating away there would otherwise\n   * be pulled back by the kit's own URL write. An app that stays on the page after a\n   * final Finish drops the param itself, or uses `urlSync: false`.\n   */\n  urlSync?: WizardUrlSync;\n  /**\n   * Shown when a step blocks with no per-field detail — an RHF step surfacing\n   * its own inline messages, say — so the user learns why the wizard did not\n   * advance. Falls back to `wizard.missingRequired` from the {@link UiKitProvider},\n   * then to English.\n   */\n  missingRequiredMessage?: string;\n  /**\n   * How to surface {@link missingRequiredMessage}. Defaults to the kit's `toast.error`\n   * (sonner, an optional peer, is loaded only when a toast is shown). Pass your own to\n   * route it somewhere else, or to a no-op to silence it.\n   */\n  onValidationFailed?: (message: string) => void;\n}\n\nexport type StepStatus = \"upcoming\" | \"active\" | \"completed\" | \"skipped\";\n\n/** What `finish` resolves to at run time (0.50): whether the commit went through, and the\n *  error's message when `onComplete` threw. `undefined` when there was nothing to run. */\nexport interface WizardFinishResult {\n  ok: boolean;\n  error?: string;\n}\nexport interface UseWizardReturn<TData extends Record<string, unknown>> {\n  // Navigation\n  currentStepIndex: number;\n  currentStep: WizardStepConfig;\n  steps: WizardStepConfig[];\n  isFirstStep: boolean;\n  isLastStep: boolean;\n  /** True once every step before the committing one (the last, unless a step is\n   *  flagged `commits`) has been completed or skipped. */\n  canFinish: boolean;\n  /** The step whose forward button commits: the first `commits` step, else the last. */\n  commitStepIndex: number;\n  /** The active step is {@link commitStepIndex}: the chrome shows Finish, not Next. */\n  isCommitStep: boolean;\n  /** `onComplete` has resolved. Once the active step is past the committing one, Back\n   *  cannot cross it and Cancel is hidden. */\n  committed: boolean;\n  /** Whether Back is offered here: not on the first step unless `onExit` was given,\n   *  and never back across a commit. (Disabled, not hidden, while `isSubmitting`.) */\n  canGoBack: boolean;\n  /** Whether Cancel is offered: `cancellable`, and not after a commit. */\n  canCancel: boolean;\n  /** Whether Done is offered: the last step, past a commit, with an `onDone`. */\n  canDone: boolean;\n  /** Whether the indicator may jump to `index` — a completed/skipped/active step on\n   *  the right side of any commit. `goToStep` refuses anything this rejects. */\n  canGoToStep: (index: number) => boolean;\n  /** Validates the step and moves on. (0.50: at run time it resolves `true` when it\n   *  moved, `false` when a validator kept it in place — what StepperNav tells a running\n   *  tour, docs/tours-harmonization.md §11.9. The declared type stays `Promise<void>`.) */\n  goNext: () => Promise<void>;\n  /** One step back — or, on the first step, `onExit`. Refused while submitting. */\n  goBack: () => void;\n  goToStep: (index: number) => void;\n  skip: () => void;\n  cancel: () => void;\n  /** Validates and commits (`onComplete`). (0.50: at run time it resolves `{ ok, error? }`\n   *  — see {@link WizardFinishResult}; the declared type stays `Promise<void>`.) */\n  finish: () => Promise<void>;\n  /** Leave after the post-commit steps: drops the URL param, then calls `onDone`. */\n  done: () => void;\n  /** Register a validator for the mounted step (used by useRhfWizardStep). */\n  registerStepValidate: (fn: () => ValidateResult | Promise<ValidateResult>) => () => void;\n  /** True when the mounted step has blocked forward navigation (Next/Skip disabled). */\n  nextBlocked: boolean;\n  /** Set by the active step (via useWizardNextGate) to disable/enable Next+Skip. */\n  setNextBlocked: (blocked: boolean) => void;\n\n  // Step state\n  stepStatus: (index: number) => StepStatus;\n  completedSteps: Set<number>;\n\n  // Data\n  data: TData;\n  updateData: (partial: Partial<TData>) => void;\n\n  // Loading / error\n  isSubmitting: boolean;\n  /** A `goNext`/`finish` is running the step's validators (an async server check,\n   *  say). The chrome shows Next pending — spinner, `aria-busy`, disabled. */\n  isValidating: boolean;\n  error: string | null;\n  clearError: () => void;\n\n  // Per-field validation errors (populated by the last failed goNext)\n  fieldErrors: FieldErrors;\n  clearFieldErrors: () => void;\n\n  // Cancel dialog\n  showCancelDialog: boolean;\n  confirmCancel: () => void;\n  dismissCancel: () => void;\n}\n\nexport interface SummaryItem {\n  label: ReactNode;\n  value: ReactNode;\n}\n\nexport interface SummarySection {\n  label: ReactNode;\n  /**\n   * Which step the section's edit button jumps back to. Leave it out for a section\n   * that belongs to no step — file-level counts, a total — and the card has no edit\n   * button, instead of borrowing one from whichever step it was parked under.\n   */\n  stepIndex?: number;\n  items: SummaryItem[];\n}\n\n/**\n * Every string the wizard chrome shows. All optional with English defaults, so a\n * monolingual app can mount `StepperNav` bare; a translated app passes the whole\n * object once (typically from a thin app-side wrapper).\n */\nexport interface WizardLabels {\n  cancel: string;\n  back: string;\n  next: string;\n  skip: string;\n  finish: string;\n  /** Shown on Finish while `isSubmitting`. */\n  submitting: string;\n  /** `aria-label` for the step indicator's `<nav>`. */\n  steps: string;\n  /** The mobile \"Step 2 of 5\" line. */\n  step: (current: number, total: number) => string;\n  /** Heading of the cancel-confirmation dialog. */\n  cancelTitle: string;\n  /** Body of the cancel-confirmation dialog. */\n  confirmCancel: string;\n  /** Confirm button in the cancel dialog. */\n  cancelConfirmLabel: string;\n  /** Dismiss button in the cancel dialog (\"keep editing\"). */\n  cancelDismissLabel: string;\n  /** Heading above a {@link WizardSummary}. */\n  reviewTitle: string;\n  /** `aria-label` on a summary section's edit button. */\n  edit: string;\n  /**\n   * Toasted (or handed to `onValidationFailed`) when a step blocks Next without\n   * saying which field is at fault. `useWizard`'s `missingRequiredMessage` wins.\n   *\n   * This and `genericError` are OPTIONAL, unlike every key above, for the reason\n   * `TwoFactorSettingLabels.qrAlt` is: apps annotate a full translation as\n   * `const DE: WizardLabels = {…}`, and a new required key would be a compile error\n   * in each of them on the next update. The defaults below always carry both.\n   */\n  missingRequired?: string;\n  /** `wizard.error` when `onComplete` rejects with nothing readable — a thrown\n   *  non-Error, or an Error whose message is empty. Optional: see above. */\n  genericError?: string;\n  /** The button on the last step after a committing step (`onDone`). Optional: see\n   *  `missingRequired`. */\n  done?: string;\n}\n\n// The English words live in ./wizard-labels, a module of words (round 0.34).\nexport { DEFAULT_WIZARD_LABELS };\n"],"mappings":";AACA,SAAS,6BAA6B;","names":[]}

package/dist/wizard/use-wizard.js

@@ -99,23 +99,16 @@ function useWizard(options) {
   });
   const missingRequired = wizardLabels.missingRequired ?? DEFAULT_WIZARD_LABELS.missingRequired;
   const genericError = wizardLabels.genericError ?? DEFAULT_WIZARD_LABELS.genericError;
-  const validatorsRef = useRef(
-    /* @__PURE__ */ new Map()
-  );
-  const registerStepValidate = useCallback(
-    (fn) => {
-      const token = /* @__PURE__ */ Symbol();
-      validatorsRef.current.set(token, fn);
-      return () => {
-        validatorsRef.current.delete(token);
-      };
-    },
-    []
-  );
+  const validatorsRef = useRef(/* @__PURE__ */ new Map());
+  const registerStepValidate = useCallback((fn) => {
+    const token = /* @__PURE__ */ Symbol();
+    validatorsRef.current.set(token, fn);
+    return () => {
+      validatorsRef.current.delete(token);
+    };
+  }, []);
   const [useStepUrl] = useState(() => urlSync === false ? useNoStepUrl : useSearchParamStepUrl);
-  const [urlParam] = useState(
-    () => typeof urlSync === "object" && urlSync.param ? urlSync.param : "step"
-  );
+  const [urlParam] = useState(() => typeof urlSync === "object" && urlSync.param ? urlSync.param : "step");
   const initialStep = 0;
   const reducer = createReducer(steps.length);
   const [state, dispatch] = useReducer(reducer, {
@@ -131,10 +124,7 @@ function useWizard(options) {
     committedStepIndex: null
   });
   const [nextBlocked, setNextBlockedState] = useState(false);
-  const setNextBlocked = useCallback(
-    (blocked) => setNextBlockedState(blocked),
-    []
-  );
+  const setNextBlocked = useCallback((blocked) => setNextBlockedState(blocked), []);
   const clearStepUrl = useStepUrl(urlParam, state.currentStepIndex);
   const currentStep = steps[state.currentStepIndex];
   const isFirstStep = state.currentStepIndex === 0;
@@ -350,18 +340,24 @@ function useSearchParamStepUrl(param, index) {
   const leftRef = useRef(false);
   useEffect(() => {
     if (leftRef.current) return;
-    setUrlParams((prev) => {
-      prev.set(param, String(index));
-      return prev;
-    }, { replace: true });
+    setUrlParams(
+      (prev) => {
+        prev.set(param, String(index));
+        return prev;
+      },
+      { replace: true }
+    );
   }, [param, index, setUrlParams]);
   return useCallback(() => {
     if (leftRef.current) return;
     leftRef.current = true;
-    setUrlParams((prev) => {
-      prev.delete(param);
-      return prev;
-    }, { replace: true });
+    setUrlParams(
+      (prev) => {
+        prev.delete(param);
+        return prev;
+      },
+      { replace: true }
+    );
   }, [param, setUrlParams]);
 }
 function useNoStepUrl(_param, _index) {