@eifi1/ui-kit 0.44.0 → 0.46.0

package/src/tour/use-tour-progress.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import { readStored, removeStored, writeStored } from "../lib/safe-storage";
+import { httpStatusOf } from "../auth/auth-errors";
 import { isTourDone, type TourCompletions } from "./tour-info";
 
 /**
@@ -36,10 +37,80 @@ import { isTourDone, type TourCompletions } from "./tour-info";
  * and callbacks (`completed`, `TourCompletions`) give `null` for `""`. A `null` read from
  * storage (or returned by `migrate`) is accepted as the same thing and written back as
  * `""`. To write a completion from outside a page, use {@link completeTour}.
+ *
+ * **On the account** (0.45, §10.2–§10.3): with `account`, the device key becomes the
+ * account's CACHE — see {@link TourProgressAccount}. Without it, nothing changes from 0.44.
  */
 export interface UseTourProgressOptions {
   storageKey: string;
   migrate?: (raw: unknown) => Record<string, string | null> | undefined;
+  /**
+   * 0.45: the account's record behind the device key (§10.2.4). Remembered per key like
+   * `migrate` (the FIRST one any reader or the provider passes wins). With it,
+   * `storageKey` must be per account (a prefix plus the user id), so build the options per
+   * account and keep ONE stable object per key — memoise them in a `Map` by user id — and
+   * let `load`/`save` read the current token when they run, never capture one:
+   *
+   *     const byUser = new Map<string, UseTourProgressOptions>();
+   *     function tourProgressFor(user: { id: string; isDemo: boolean } | null) {
+   *       if (!user || user.isDemo) return { storageKey: "app.tours.completions" }; // no account
+   *       let options = byUser.get(user.id);
+   *       if (!options) byUser.set(user.id, (options = { storageKey: `app.tours.completions:${user.id}`, account }));
+   *       return options;
+   *     }
+   *
+   * Signed out, and in a demo, pass none (and a fixed key): the device record works as in
+   * 0.44, and a demo neither PATCHes into a 403 nor leaves an orphan key per demo id.
+   */
+  account?: TourProgressAccount;
+}
+
+/** The record on the wire (§10.2.2): tour id → ISO instant, or `""` (done, no date). */
+type TourProgressWire = Record<string, string>;
+
+/** The `PATCH /tours/progress` body (§10.2.2): what to mark done, and what to forget.
+ *  An id is never in both. Either may be left out. */
+export interface TourProgressBody {
+  completed?: TourProgressWire;
+  forget?: string[];
+}
+
+/**
+ * Taking over a device-wide record from before the account (§10.2.5), on the FIRST load
+ * of the account key on this page:
+ * - `{storageKey, discard: true}` (kastlan): removes the old key and uploads nothing — a
+ *   shared PC must not hand one person another's marks. Removing an absent key is a no-op.
+ * - `{storageKey, migrate?}`: reads the old key once (through `migrate` for an older
+ *   shape), uploads it to the first account that signs in on this device, then removes it.
+ */
+export type TourProgressAdopt =
+  | { storageKey: string; discard: true; migrate?: never }
+  | { storageKey: string; discard?: false; migrate?: UseTourProgressOptions["migrate"] };
+
+/**
+ * The app's account record (§10.3): `load()` is its `GET /tours/progress`, `save(body)`
+ * its `PATCH`, each resolving to the parsed answer, `{completed}` — the whole record.
+ *
+ * - The page paints from the device key at once (and offline); the account is loaded on
+ *   the first reader of the key on this page, on `online`, and after each save, and its
+ *   answer replaces the cache.
+ * - A write (`complete`, the provider's finish, `reset`) goes to the cache at once and to
+ *   a PENDING record beside it, `<storageKey>:pending` (`{synced, completed, forget}`),
+ *   sent as one PATCH and cleared by its answer. A failure with no answer (offline, 5xx,
+ *   401) keeps it for the next load or `online`; a 402 (a lapsed plan) keeps it but sends it
+ *   no more on this page (the next session or page load tries again); a 403 or 422 drops
+ *   it and logs.
+ * - `awarded` stays the device's answer against the cache (§10.2.4).
+ * - The pending record is NOT the app's outbox: leave it out of any "N waiting" count
+ *   and any sign-out guard (losing a tour mark is acceptable).
+ * - A device record never synced (no `:pending` with `synced: true`) is uploaded whole on
+ *   its first load, by the server's merge rule (later completion wins).
+ * - On every end of a session call {@link signOutTourProgress}.
+ */
+export interface TourProgressAccount {
+  load: () => Promise<{ completed: TourProgressWire }>;
+  save: (body: TourProgressBody) => Promise<{ completed: TourProgressWire }>;
+  adopt?: TourProgressAdopt;
 }
 
 /** What `complete` takes: a tour id, or the tour (`{id, updated}`, a `TourInfo` fits). */
@@ -185,6 +256,275 @@ function write(key: string, record: TourCompletions) {
   emit(key);
 }
 
+/* ── The account behind the device key (0.45, §10.2.4–§10.2.8) ─────────────── */
+
+/** The key's account: the first one any reader or the provider passes (as `migrate`). */
+const accounts = new Map<string, TourProgressAccount>();
+/** Keys whose account was loaded (or is loading) on this page: the first reader loads. */
+const loaded = new Set<string>();
+/** Keys with a sync running, and those asked for another while it ran. */
+const running = new Set<string>();
+const rerun = new Set<string>();
+/** Keys with a sync queued for the end of this task: two writes in one handler, one PATCH. */
+const queued = new Set<string>();
+/** Bumped by a sign-out: an answer that comes back after it never refills the cache. */
+const epochs = new Map<string, number>();
+/** Keys whose PATCH got a 402 (a lapsed plan): the pending record is kept but not sent
+ *  again on this page; the next session (or page load) tries once more. */
+const parked = new Set<string>();
+/** The pending record where storage refused to keep it. */
+const pendingMemory = new Map<string, string>();
+let onlineListening = false;
+
+/** The pending record (§10.2.4): what waits to be sent, and whether the device key was
+ *  ever synced. */
+interface PendingRecord {
+  synced: boolean;
+  completed: TourProgressWire;
+  forget: string[];
+}
+
+const pendingKey = (key: string) => `${key}:pending`;
+
+function devWarn(message: string) {
+  if (import.meta.env?.DEV) console.warn(message);
+}
+
+/**
+ * Remember `account` for `key` if it is the first one, and return the key's account.
+ * @internal Not part of the barrel; `TourProvider` registers its `progress` with it.
+ */
+export function rememberAccount(key: string, account: TourProgressAccount | undefined): TourProgressAccount | undefined {
+  if (account && !accounts.has(key)) {
+    accounts.set(key, account);
+    if (account.adopt && account.adopt.storageKey === key) {
+      devWarn(
+        `[ui-kit] tour progress: the account key "${key}" is the key \`adopt\` takes over. ` +
+          "With an account the key must be per account (a prefix plus the user id), apart from the old device-wide key.",
+      );
+    }
+    if (!onlineListening && typeof window !== "undefined") {
+      onlineListening = true;
+      window.addEventListener("online", () => {
+        for (const known of loaded) void sync(known);
+      });
+    }
+  }
+  return accounts.get(key);
+}
+
+function readPending(key: string): PendingRecord | null {
+  const raw = pendingMemory.get(key) ?? readStored(pendingKey(key));
+  if (raw === null) return null;
+  try {
+    const value = JSON.parse(raw) as Partial<PendingRecord> | null;
+    if (!value || typeof value !== "object") return null;
+    const completed: TourProgressWire = {};
+    for (const [id, at] of Object.entries(value.completed ?? {})) {
+      if (typeof at === "string") completed[id] = at;
+      else if (at === null) completed[id] = "";
+    }
+    const forget = Array.isArray(value.forget) ? value.forget.filter((id): id is string => typeof id === "string") : [];
+    return { synced: value.synced === true, completed, forget };
+  } catch {
+    return null;
+  }
+}
+
+function writePending(key: string, record: PendingRecord) {
+  const raw = JSON.stringify(record);
+  writeStored(pendingKey(key), raw);
+  if (readStored(pendingKey(key)) === raw) pendingMemory.delete(key);
+  else pendingMemory.set(key, raw);
+}
+
+const hasWork = (record: PendingRecord) => Object.keys(record.completed).length > 0 || record.forget.length > 0;
+
+/** "Later completion wins" (§10.2.3), as the server merges: an instant beats `""`, `""`
+ *  beats nothing, and between two instants the later is kept. */
+function later(a: string | undefined, b: string): string {
+  if (a === undefined || a === "") return b;
+  if (b === "") return a;
+  return Date.parse(b) > Date.parse(a) ? b : a;
+}
+
+/** Note a completion (or, with `forget`, its removal) in the key's pending record. */
+function markPending(key: string, id: string, at: string | null | undefined, forget = false) {
+  const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };
+  if (forget) {
+    delete record.completed[id];
+    if (!record.forget.includes(id)) record.forget.push(id);
+  } else {
+    record.completed[id] = at ?? "";
+    record.forget = record.forget.filter((other) => other !== id);
+  }
+  writePending(key, record);
+}
+
+/** After an answer (or a 403/422): take what was sent out of the pending record, keeping
+ *  what was written while the request ran. */
+function clearSent(key: string, sent: TourProgressBody, synced: boolean) {
+  const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };
+  for (const [id, at] of Object.entries(sent.completed ?? {})) {
+    if (record.completed[id] === at) delete record.completed[id];
+  }
+  const forgotten = new Set(sent.forget ?? []);
+  record.forget = record.forget.filter((id) => !forgotten.has(id));
+  record.synced = record.synced || synced;
+  writePending(key, record);
+}
+
+/** The account's answer as the cache, with what still waits to be sent laid over it. */
+function refill(key: string, answer: { completed: TourProgressWire } | null | undefined) {
+  const next: Record<string, string> = {};
+  for (const [id, at] of Object.entries(fromRecord(answer?.completed) ?? {})) next[id] = at ?? "";
+  const waiting = readPending(key);
+  if (waiting) {
+    for (const [id, at] of Object.entries(waiting.completed)) next[id] = later(next[id], at);
+    for (const id of waiting.forget) delete next[id];
+  }
+  const record: Record<string, string | null> = {};
+  for (const [id, at] of Object.entries(next)) record[id] = at === "" ? null : at;
+  write(key, record);
+}
+
+/** The first load of an account key on this page takes over the old device-wide key
+ *  (§10.2.5). */
+function adoptOldRecord(key: string, account: TourProgressAccount) {
+  const adopt = account.adopt;
+  if (!adopt || adopt.storageKey === key) return;
+  const old = adopt.storageKey;
+  if (!adopt.discard) {
+    const { value } = parse(rawOf(old), adopt.migrate ?? migrates.get(old));
+    const entries = Object.entries(value);
+    if (entries.length > 0) {
+      const record = readPending(key) ?? { synced: false, completed: {}, forget: [] };
+      for (const [id, at] of entries) record.completed[id] = later(record.completed[id], at ?? "");
+      writePending(key, record);
+    }
+  }
+  // Removed either way, at once: no second account on this device gets it.
+  removeStored(old);
+  memory.delete(old);
+  cache.delete(old);
+  emit(old);
+}
+
+/** A device record never synced is uploaded whole on its first load (§10.2.5). */
+function uploadUnsynced(key: string) {
+  const record = readPending(key);
+  if (record?.synced) return;
+  const device = snapshot(key, migrates.get(key));
+  const entries = Object.entries(device);
+  const next = record ?? { synced: false, completed: {}, forget: [] };
+  if (entries.length === 0 && record) return;
+  for (const [id, at] of entries) {
+    if (!next.forget.includes(id)) next.completed[id] = later(next.completed[id], at ?? "");
+  }
+  writePending(key, next);
+}
+
+/** The key's first sync on this page: take over the old record, upload a never-synced one. */
+function prepare(key: string) {
+  loaded.add(key);
+  adoptOldRecord(key, accounts.get(key)!);
+  uploadUnsynced(key);
+}
+
+/** Queue a sync for the end of this task, so a handler's writes go as one PATCH. */
+function queueSync(key: string) {
+  if (!loaded.has(key)) prepare(key);
+  if (queued.has(key)) return;
+  queued.add(key);
+  queueMicrotask(() => {
+    queued.delete(key);
+    void sync(key);
+  });
+}
+
+/** The first reader of an account key on this page loads it. */
+function ensureLoaded(key: string) {
+  if (!accounts.has(key) || loaded.has(key)) return;
+  prepare(key);
+  void sync(key);
+}
+
+/**
+ * Send what waits (one PATCH) or, with nothing waiting, load; the answer replaces the
+ * cache. One at a time per key; a request asked for while one runs follows it.
+ */
+async function sync(key: string): Promise<void> {
+  const account = accounts.get(key);
+  if (!account || !loaded.has(key)) return;
+  if (running.has(key)) {
+    rerun.add(key);
+    return;
+  }
+  if (typeof navigator !== "undefined" && navigator.onLine === false) return;
+  running.add(key);
+  const epoch = epochs.get(key) ?? 0;
+  try {
+    const waiting = readPending(key);
+    if (waiting && hasWork(waiting)) {
+      if (parked.has(key)) return;
+      const body: TourProgressBody = {};
+      if (Object.keys(waiting.completed).length > 0) body.completed = { ...waiting.completed };
+      if (waiting.forget.length > 0) body.forget = [...waiting.forget];
+      let answer: { completed: TourProgressWire };
+      try {
+        answer = await account.save(body);
+      } catch (error) {
+        const status = httpStatusOf(error);
+        if (status === 403 || status === 422) {
+          // Refused for good (a demo, a malformed or full record): dropped, not retried.
+          if ((epochs.get(key) ?? 0) === epoch) clearSent(key, body, false);
+          console.warn(`[ui-kit] tour progress: the account refused the pending record (${status}); dropped.`, error);
+        } else if (status === 402) {
+          // A lapsed plan refuses every write: kept, but not re-sent after each finish
+          // and each `online` — the next session or page load tries again.
+          parked.add(key);
+        }
+        // No answer (offline, 5xx, 401): it stays for the next load or `online`.
+        return;
+      }
+      if ((epochs.get(key) ?? 0) !== epoch) return;
+      clearSent(key, body, true);
+      refill(key, answer);
+    } else {
+      const answer = await account.load();
+      if ((epochs.get(key) ?? 0) !== epoch) return;
+      if (waiting && !waiting.synced) writePending(key, { ...waiting, synced: true });
+      else if (!waiting) writePending(key, { synced: true, completed: {}, forget: [] });
+      refill(key, answer);
+    }
+  } catch {
+    // A load that failed keeps the cache as it is.
+  } finally {
+    running.delete(key);
+    if (rerun.delete(key)) void sync(key);
+  }
+}
+
+/**
+ * The end of a session (§10.2.6) — sign-out, a 401 nothing could renew, the account's
+ * deletion, every path: removes the CACHE only (the device key and the page's snapshot;
+ * every reader in this tab moves), synchronously and with no request, and KEEPS
+ * `<storageKey>:pending`. That record sits under this person's own key, holds tour ids and
+ * dates only, and goes out on their next sign-in. An answer still on its way is ignored.
+ *
+ *     function logout() { …; signOutTourProgress(`app.tours:${user.id}`); }
+ */
+export function signOutTourProgress(storageKey: string): void {
+  epochs.set(storageKey, (epochs.get(storageKey) ?? 0) + 1);
+  loaded.delete(storageKey);
+  rerun.delete(storageKey);
+  parked.delete(storageKey);
+  removeStored(storageKey);
+  memory.delete(storageKey);
+  cache.delete(storageKey);
+  emit(storageKey);
+}
+
 function subscribe(key: string, listener: () => void): () => void {
   let set = listeners.get(key);
   if (!set) listeners.set(key, (set = new Set()));
@@ -208,8 +548,13 @@ function subscribe(key: string, listener: () => void): () => void {
  * once. For "Reset this device's settings" (settings §11):
  *
  *     registerDeviceSetting({ key: TOUR_KEY, kind: "view", reset: () => resetTourProgress(TOUR_KEY) });
+ *
+ * With an account (0.45) it clears the cache only: the account is never written, the
+ * pending record stays ("anything waiting to be sent", settings §11.2.2) and the next load
+ * refills the cache. Tour progress is never registered with the device reset (§10.2.8).
  */
 export function resetTourProgress(storageKey: string): void {
+  if (accounts.has(storageKey)) loaded.delete(storageKey);
   removeStored(storageKey);
   memory.delete(storageKey);
   cache.delete(storageKey);
@@ -231,10 +576,28 @@ export function completeStored(
   // Read now rather than from a render: two completions in one handler both count.
   const current = readForWrite(storageKey, migrate);
   if (isTourDone(subject, current[subject.id])) return false;
-  write(storageKey, { ...current, [subject.id]: new Date().toISOString() });
+  const at = new Date().toISOString();
+  write(storageKey, { ...current, [subject.id]: at });
+  if (accounts.has(storageKey)) {
+    markPending(storageKey, subject.id, at);
+    queueSync(storageKey);
+  }
   return true;
 }
 
+/** "Mark as not done" (§10.2.8): off the cache, and `forget` to the account. @internal */
+function resetStored(storageKey: string, migrate: UseTourProgressOptions["migrate"], id: string) {
+  const current = snapshot(storageKey, migrate);
+  if (current[id] === undefined) return;
+  const next = { ...current };
+  delete next[id];
+  write(storageKey, next);
+  if (accounts.has(storageKey)) {
+    markPending(storageKey, id, undefined, true);
+    queueSync(storageKey);
+  }
+}
+
 /**
  * Write a completion from outside a page (§9.2): for an app's tests, seeds and scripts,
  * beside {@link resetTourProgress}. It writes the kit's stored shape (`{[id]: ISO | ""}`)
@@ -253,6 +616,9 @@ export function completeStored(
  * nor the kit's shape and no migrate reads it, this THROWS and writes nothing (B-1):
  *
  *     completeTour(TOUR_KEY, "budget", undefined, { migrate: fromZustand });
+ *
+ * With an account on the key (0.45) it stays a device write — no request — and is marked
+ * pending, so the next load sends it.
  */
 export function completeTour(
   storageKey: string,
@@ -263,16 +629,25 @@ export function completeTour(
   const id = typeof tour === "string" ? tour : tour.id;
   const when = at === null ? null : at instanceof Date ? at.toISOString() : (at ?? new Date().toISOString());
   write(storageKey, { ...readForWrite(storageKey, opts?.migrate, true), [id]: when });
+  if (accounts.has(storageKey)) markPending(storageKey, id, when);
 }
 
 /** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */
-export function useTourProgress({ storageKey, migrate }: UseTourProgressOptions): TourProgress {
+export function useTourProgress({ storageKey, migrate, account }: UseTourProgressOptions): TourProgress {
   // Held, not depended on: an inline arrow is a new function every render, and neither the
   // snapshot nor the callbacks may change with it.
   const migrateRef = useRef(migrate);
   useEffect(() => {
     migrateRef.current = migrate;
   });
+  // The first account for the key wins (as `migrate`); its first reader on the page loads.
+  const accountRef = useRef(account);
+  useEffect(() => {
+    accountRef.current = account;
+  });
+  useEffect(() => {
+    if (rememberAccount(storageKey, accountRef.current)) ensureLoaded(storageKey);
+  }, [storageKey]);
   const completed = useSyncExternalStore(
     useCallback((listener: () => void) => subscribe(storageKey, listener), [storageKey]),
     () => snapshot(storageKey, migrateRef.current),
@@ -284,16 +659,7 @@ export function useTourProgress({ storageKey, migrate }: UseTourProgressOptions)
     [storageKey],
   );
 
-  const reset = useCallback(
-    (id: string) => {
-      const current = snapshot(storageKey, migrateRef.current);
-      if (current[id] === undefined) return;
-      const next = { ...current };
-      delete next[id];
-      write(storageKey, next);
-    },
-    [storageKey],
-  );
+  const reset = useCallback((id: string) => resetStored(storageKey, migrateRef.current, id), [storageKey]);
 
   return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);
 }

package/src/tour.ts

@@ -11,5 +11,8 @@ export type { TourInfo, TourGroup, TourUpdate, TourCompletions } from "./tour/to
 // 0.44.0: the writer outside a page (§9.2).
 export { useTourProgress, resetTourProgress, completeTour } from "./tour/use-tour-progress";
 export type { UseTourProgressOptions, TourProgress } from "./tour/use-tour-progress";
+// 0.45.0: progress on the account (§10.2–§10.3) and the end of a session.
+export { signOutTourProgress } from "./tour/use-tour-progress";
+export type { TourProgressAccount, TourProgressAdopt, TourProgressBody } from "./tour/use-tour-progress";
 export { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync";
 export type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from "./tour/use-tour-url-sync";