@apollovisionlabs/guide-core 0.1.0 → 0.2.0

package/README.md

@@ -101,43 +101,55 @@ the destination.
 
 ## Persistence
 
-`GuideStorage` is the two-method interface the provider reads from and writes to:
+`GuideStorage` is the two-method interface both `GuideProvider` and `ChecklistProvider` read from
+and write to. It is generic over the stored value, so one storage serves tour progress and
+checklist progress under different keys:
 
 ```ts
 interface GuideStorage {
-  read(tourId: string): Promise<TourProgress | null>
-  write(tourId: string, progress: TourProgress): Promise<void>
+  read<T>(key: string): Promise<T | null>
+  write<T>(key: string, value: T): Promise<void>
 }
 ```
 
+`GuideProvider` reads and writes tour progress under `tour:<id>`. `ChecklistProvider` reads and
+writes checklist progress under `checklist:<id>`. See [ADR 0016](docs/adr/0016-one-storage-contract-for-tours-and-checklists.md)
+for why the two share one interface.
+
 `@apollovisionlabs/guide-core` ships `createMemoryStorage()` for tests and `createBrowserStorage(namespace?)` for
 `localStorage`. Neither talks to a server. An implementation backed by your own API looks like
 this:
 
 ```ts
-import type { GuideStorage, TourProgress } from '@apollovisionlabs/guide-core'
+import type { GuideStorage } from '@apollovisionlabs/guide-core'
 
 function createServerStorage(): GuideStorage {
   return {
-    async read(tourId) {
-      const response = await fetch(`/api/tours/${tourId}/progress`)
+    async read<T>(key: string) {
+      const response = await fetch(`/api/guide/${key}`)
       if (!response.ok) return null
-      return (await response.json()) as TourProgress
+      return (await response.json()) as T
     },
-    async write(tourId, progress) {
-      await fetch(`/api/tours/${tourId}/progress`, {
+    async write<T>(key: string, value: T) {
+      await fetch(`/api/guide/${key}`, {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(progress),
+        body: JSON.stringify(value),
       })
     },
   }
 }
 ```
 
-Pass it as the `storage` prop. The provider reads on `start()` (unless an explicit `from` step
-index is passed, or `resume: false` is passed) and writes whenever a running tour advances or
-completes.
+Pass it as the `storage` prop on either provider. `GuideProvider` reads on `start()` (unless an
+explicit `from` step index is passed, or `resume: false` is passed) and writes whenever a running
+tour advances or completes. `ChecklistProvider` reads once on mount and writes whenever an item is
+ticked, completed or the checklist is dismissed.
+
+A value read back from storage is validated before it is trusted (`isTourProgress`,
+`isChecklistProgress`, both exported from `@apollovisionlabs/guide-core`): a value that does not
+match the expected shape, from a hand-edited store or an older version of this library, is treated
+the same as nothing stored, rather than crashing or resuming into a broken state.
 
 ## Translations
 
@@ -158,7 +170,8 @@ and nothing English remains:
 
 ## Events
 
-`onEvent` on `GuideProvider` receives every lifecycle event as a discriminated union:
+`onEvent` on `GuideProvider` and on `ChecklistProvider` each receive their own lifecycle events, as
+a discriminated union of `GuideEvent`:
 
 | Event | Payload | When |
 | --- | --- | --- |
@@ -167,6 +180,9 @@ and nothing English remains:
 | `tour:stop` | `{ tourId, stepIndex }` | The tour is stopped before completion. |
 | `step:show` | `{ tourId, stepIndex, target }` | A step's target is resolved and the step becomes visible. |
 | `target:missing` | `{ tourId, stepIndex, target }` | A step's target didn't appear within `targetTimeoutMs`. |
+| `checklist:item-complete` | `{ checklistId, itemId }` | An item is completed, by finishing its linked tour or by a manual tick. Not emitted for an item already complete. |
+| `checklist:complete` | `{ checklistId }` | The last incomplete item in a checklist is completed. Fires on every transition into the complete state, so unticking an item and reticking it emits a second time. Deduplicate downstream if you count completions. |
+| `checklist:dismiss` | `{ checklistId }` | `dismiss()` is called. |
 
 ## Accessibility
 
@@ -190,6 +206,88 @@ happens: `'skip'` moves to the next step, `'error'` stops the tour, and `'wait'`
 pauses and resumes automatically if the target appears later, for instance after a slow async
 render.
 
+## Checklist
+
+A checklist is a separate feature from the tour: a fixed list of items, each completed by
+finishing a linked tour or by a manual tick. An item can also carry an `href`, which navigates
+and nothing more. `ChecklistProvider` holds
+its state the way `GuideProvider` holds tour state, and nests inside it so that an item can launch
+a tour:
+
+```tsx
+import { GuideProvider, ChecklistProvider, type Tour, type Checklist } from '@apollovisionlabs/guide-core'
+import { GuideTour } from '@apollovisionlabs/guide-mui'
+import { ChecklistLauncher } from '@apollovisionlabs/guide-mui'
+
+const tour: Tour = {
+  id: 'welcome',
+  steps: [{ target: 'sidebar.projects', title: 'Your projects', body: 'Grouped under a project.' }],
+}
+
+const onboarding: Checklist = {
+  id: 'onboarding',
+  items: [
+    { id: 'tour', title: 'Take the tour', body: 'Two minutes.', tourId: 'welcome' },
+    { id: 'projects', title: 'Open your projects', body: 'See the list.', href: '/projects' },
+    { id: 'profile', title: 'Set your name', body: 'Manual, ticked by hand.' },
+  ],
+}
+
+function App() {
+  return (
+    <GuideProvider tours={[tour]} navigate={(path) => router.push(path)}>
+      <ChecklistProvider checklists={[onboarding]} navigate={(path) => router.push(path)}>
+        <Sidebar />
+        <GuideTour />
+        <ChecklistLauncher checklistId="onboarding" title="Get started" />
+      </ChecklistProvider>
+    </GuideProvider>
+  )
+}
+```
+
+An item with an `href`, or with neither `tourId` nor `href`, is completed by a manual tick only:
+activating an `href` item navigates and stops there, since arriving on a page is not evidence that
+anyone did anything on it. An item with `tourId`
+is completed automatically when that tour is finished (`next()` called on its last step); it can
+also be ticked by hand before that. Completion is idempotent: ticking an already-complete item, or
+finishing a tour whose item is already ticked, does nothing and emits no event.
+
+### `ChecklistProvider` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checklists` | `Checklist[]` | none | The checklists available to `useChecklist`. |
+| `children` | `ReactNode` | none | Your application. |
+| `storage` | `GuideStorage` | none | Persists checklist progress under `checklist:<id>`. See "Persistence". |
+| `translate` | `(key: string) => string` | none | Resolves `titleKey` / `bodyKey` on items. See "Translations". |
+| `navigate` | `(path: string) => void` | none | Called when an item with `href` is activated. |
+| `onEvent` | `(event: GuideEvent) => void` | none | Called for `checklist:item-complete`, `checklist:complete`, `checklist:dismiss`. See "Events". |
+
+### `useChecklist(checklistId)`
+
+Returns `{ items, completedCount, total, isComplete, dismissed, activate, toggle, complete, dismiss, reset }`.
+`items` is `ResolvedChecklistItem[]`: `{ id, title, body, completed, tourId?, href? }`, with
+`title` / `body` already resolved through `translate`. `activate(itemId)` runs an item's default
+action (start its tour, navigate to its `href`, or toggle it if it has neither); `toggle` and
+`complete` change completion directly; `dismiss()` and `reset()` act on the whole checklist.
+
+### `Checklist` and `ChecklistLauncher` (`@apollovisionlabs/guide-mui`)
+
+`Checklist` renders the list inline: a progress bar, one row per item with a checkbox and a
+dismiss button. `ChecklistLauncher` wraps it behind a floating action button showing
+`completedCount/total`, opened as a popover. The popover stays open while items are ticked one
+after another, and closes when an item hands off to something that needs the screen: launching a
+tour or navigating to an `href`. It does not close on a plain tick.
+
+```tsx
+import { Checklist, ChecklistLauncher } from '@apollovisionlabs/guide-mui'
+
+<Checklist checklistId="onboarding" title="Get started" />
+// or, as a floating launcher:
+<ChecklistLauncher checklistId="onboarding" title="Get started" placement="bottom-right" />
+```
+
 ## Compatibility
 
 | | Supported |

package/dist/index.cjs

@@ -21,16 +21,22 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ChecklistContext: () => ChecklistContext,
+  ChecklistProvider: () => ChecklistProvider,
   GuideContext: () => GuideContext,
   GuideProvider: () => GuideProvider,
   createBrowserStorage: () => createBrowserStorage,
   createMemoryStorage: () => createMemoryStorage,
   findMissingTargets: () => findMissingTargets,
   initialTourState: () => initialTourState,
+  isChecklistProgress: () => isChecklistProgress,
   isLiteralRoute: () => isLiteralRoute,
+  isTourProgress: () => isTourProgress,
   matchRoute: () => matchRoute,
+  resolveText: () => resolveText,
   tourReducer: () => tourReducer,
   useAnnouncer: () => useAnnouncer,
+  useChecklist: () => useChecklist,
   useElementRect: () => useElementRect,
   useFocusTrap: () => useFocusTrap,
   useGuideStep: () => useGuideStep,
@@ -44,36 +50,46 @@ module.exports = __toCommonJS(index_exports);
 function createMemoryStorage(initial = {}) {
   const store = new Map(Object.entries(initial));
   return {
-    async read(tourId) {
-      return store.get(tourId) ?? null;
+    async read(key) {
+      return store.get(key) ?? null;
     },
-    async write(tourId, progress) {
-      store.set(tourId, progress);
+    async write(key, value) {
+      store.set(key, value);
     }
   };
 }
 function createBrowserStorage(namespace = "guide") {
-  const key = (tourId) => `${namespace}:${tourId}`;
+  const key = (storageKey) => `${namespace}:${storageKey}`;
   const available = () => typeof window !== "undefined" && !!window.localStorage;
   return {
-    async read(tourId) {
+    async read(storageKey) {
       if (!available()) return null;
       try {
-        const raw = window.localStorage.getItem(key(tourId));
+        const raw = window.localStorage.getItem(key(storageKey));
         return raw ? JSON.parse(raw) : null;
       } catch {
         return null;
       }
     },
-    async write(tourId, progress) {
+    async write(storageKey, value) {
       if (!available()) return;
       try {
-        window.localStorage.setItem(key(tourId), JSON.stringify(progress));
+        window.localStorage.setItem(key(storageKey), JSON.stringify(value));
       } catch {
       }
     }
   };
 }
+function isTourProgress(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.stepIndex === "number" && Number.isInteger(candidate.stepIndex) && candidate.stepIndex >= 0 && (candidate.status === "in-progress" || candidate.status === "completed");
+}
+function isChecklistProgress(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return Array.isArray(candidate.completed) && candidate.completed.every((entry) => typeof entry === "string") && typeof candidate.dismissed === "boolean";
+}
 
 // src/matchRoute.ts
 function segments(value) {
@@ -295,14 +311,16 @@ function findMissingTargets(tour, location, attribute = "data-guide") {
   return tour.steps.filter((step) => !step.route || location === void 0 || matchRoute(step.route, location)).map((step) => step.target).filter((target) => !document.querySelector(targetSelector(target, attribute)));
 }
 
-// src/GuideProvider.tsx
-var import_jsx_runtime = require("react/jsx-runtime");
-var GuideContext = (0, import_react4.createContext)(null);
+// src/resolveText.ts
 function resolveText(value, key, translate) {
   if (value !== void 0) return value;
   if (key === void 0) return "";
   return translate ? translate(key) : key;
 }
+
+// src/GuideProvider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var GuideContext = (0, import_react4.createContext)(null);
 function GuideProvider({
   tours,
   children,
@@ -386,7 +404,8 @@ function GuideProvider({
       if (options?.from === void 0 && options?.resume !== false && storage) {
         let progress = null;
         try {
-          progress = await storage.read(tourId);
+          const stored = await storage.read(`tour:${tourId}`);
+          progress = isTourProgress(stored) ? stored : null;
         } catch (error) {
           warnStorageFailure(error);
         }
@@ -453,7 +472,7 @@ function GuideProvider({
     if (!status) return;
     try {
       void Promise.resolve(
-        storage.write(state.tourId, { status, stepIndex: state.stepIndex })
+        storage.write(`tour:${state.tourId}`, { status, stepIndex: state.stepIndex })
       ).catch(warnStorageFailure);
     } catch (error) {
       warnStorageFailure(error);
@@ -518,18 +537,303 @@ function useGuideStep() {
   if (!context) throw new Error("[guide] useGuideStep must be used inside a GuideProvider");
   return context.activeStep;
 }
+
+// src/ChecklistProvider.tsx
+var import_react7 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var ChecklistContext = (0, import_react7.createContext)(null);
+var emptyProgress = { completed: [], dismissed: false };
+function ChecklistProvider({
+  checklists,
+  children,
+  storage,
+  translate,
+  navigate,
+  onEvent
+}) {
+  const checklistsById = (0, import_react7.useMemo)(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const candidate of checklists) map.set(candidate.id, candidate);
+    return map;
+  }, [checklists]);
+  const [progress, setProgress] = (0, import_react7.useState)(() => {
+    const initial = {};
+    for (const candidate of checklists) initial[candidate.id] = emptyProgress;
+    return initial;
+  });
+  const progressRef = (0, import_react7.useRef)(progress);
+  const guide = (0, import_react7.useContext)(GuideContext);
+  const storageWarnedRef = (0, import_react7.useRef)(false);
+  const warnStorageFailure = (0, import_react7.useCallback)((error) => {
+    if (storageWarnedRef.current) return;
+    storageWarnedRef.current = true;
+    console.warn("[guide] storage failed; checklist progress will not be persisted", error);
+  }, []);
+  const noGuideWarnedRef = (0, import_react7.useRef)(false);
+  const warnNoGuide = (0, import_react7.useCallback)(() => {
+    if (noGuideWarnedRef.current) return;
+    noGuideWarnedRef.current = true;
+    console.warn("[guide] a checklist item needs a GuideProvider to launch a tour");
+  }, []);
+  const tourStartFailedWarnedRef = (0, import_react7.useRef)(false);
+  const warnTourStartFailure = (0, import_react7.useCallback)((error) => {
+    if (tourStartFailedWarnedRef.current) return;
+    tourStartFailedWarnedRef.current = true;
+    console.warn("[guide] starting a tour for a checklist item failed", error);
+  }, []);
+  const noNavigateWarnedRef = (0, import_react7.useRef)(false);
+  const warnNoNavigate = (0, import_react7.useCallback)(() => {
+    if (noNavigateWarnedRef.current) return;
+    noNavigateWarnedRef.current = true;
+    console.warn("[guide] a checklist item declares an href but no navigate function was provided");
+  }, []);
+  const onEventRef = (0, import_react7.useRef)(onEvent);
+  onEventRef.current = onEvent;
+  const emit = (0, import_react7.useCallback)((event) => onEventRef.current?.(event), []);
+  (0, import_react7.useEffect)(() => {
+    if (!storage) return;
+    let cancelled = false;
+    void (async () => {
+      const restored = {};
+      for (const candidate of checklists) {
+        try {
+          const stored = await storage.read(`checklist:${candidate.id}`);
+          if (isChecklistProgress(stored)) restored[candidate.id] = stored;
+        } catch (error) {
+          warnStorageFailure(error);
+        }
+      }
+      if (!cancelled && Object.keys(restored).length > 0) {
+        const merged = { ...progressRef.current };
+        for (const [checklistId, stored] of Object.entries(restored)) {
+          const live = merged[checklistId] ?? emptyProgress;
+          merged[checklistId] = {
+            completed: live.completed.concat(
+              stored.completed.filter((id) => !live.completed.includes(id))
+            ),
+            dismissed: live.dismissed || stored.dismissed
+          };
+        }
+        progressRef.current = merged;
+        setProgress(merged);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [storage]);
+  const applyProgress = (0, import_react7.useCallback)(
+    (checklistId, next) => {
+      const merged = { ...progressRef.current, [checklistId]: next };
+      progressRef.current = merged;
+      setProgress(merged);
+      if (!storage) return;
+      try {
+        void Promise.resolve(storage.write(`checklist:${checklistId}`, next)).catch(
+          warnStorageFailure
+        );
+      } catch (error) {
+        warnStorageFailure(error);
+      }
+    },
+    [storage, warnStorageFailure]
+  );
+  const resolveChecklist = (0, import_react7.useCallback)(
+    (checklistId) => {
+      const checklist = checklistsById.get(checklistId);
+      if (!checklist) {
+        console.warn(`[guide] unknown checklist "${checklistId}"`);
+        return null;
+      }
+      return checklist;
+    },
+    [checklistsById]
+  );
+  const resolveItem = (0, import_react7.useCallback)(
+    (checklistId, itemId) => {
+      const checklist = resolveChecklist(checklistId);
+      if (!checklist) return null;
+      const item = checklist.items.find((candidate) => candidate.id === itemId);
+      if (!item) {
+        console.warn(`[guide] unknown checklist item "${itemId}"`);
+        return null;
+      }
+      return { checklist, item };
+    },
+    [resolveChecklist]
+  );
+  const complete = (0, import_react7.useCallback)(
+    (checklistId, itemId) => {
+      const resolved = resolveItem(checklistId, itemId);
+      if (!resolved) return;
+      const { checklist } = resolved;
+      const current = progressRef.current[checklistId] ?? emptyProgress;
+      if (current.completed.includes(itemId)) return;
+      const wasComplete = checklist.items.length > 0 && checklist.items.every((candidate) => current.completed.includes(candidate.id));
+      const nextCompleted = [...current.completed, itemId];
+      applyProgress(checklistId, { ...current, completed: nextCompleted });
+      emit({ type: "checklist:item-complete", checklistId, itemId });
+      const isNowComplete = checklist.items.length > 0 && checklist.items.every((candidate) => nextCompleted.includes(candidate.id));
+      if (isNowComplete && !wasComplete) emit({ type: "checklist:complete", checklistId });
+    },
+    [resolveItem, applyProgress, emit]
+  );
+  const completeItemsForTour = (0, import_react7.useCallback)(
+    (tourId) => {
+      for (const candidate of checklists) {
+        for (const item of candidate.items) {
+          if (item.tourId === tourId) complete(candidate.id, item.id);
+        }
+      }
+    },
+    [checklists, complete]
+  );
+  const handledCompletionRef = (0, import_react7.useRef)(null);
+  (0, import_react7.useEffect)(() => {
+    const state = guide?.state;
+    if (!state || state.status !== "completed" || !state.tourId) {
+      handledCompletionRef.current = null;
+      return;
+    }
+    if (handledCompletionRef.current === state.tourId) return;
+    handledCompletionRef.current = state.tourId;
+    completeItemsForTour(state.tourId);
+  }, [guide?.state, completeItemsForTour]);
+  const toggle = (0, import_react7.useCallback)(
+    (checklistId, itemId) => {
+      const resolved = resolveItem(checklistId, itemId);
+      if (!resolved) return;
+      const current = progressRef.current[checklistId] ?? emptyProgress;
+      if (current.completed.includes(itemId)) {
+        const nextCompleted = current.completed.filter((id) => id !== itemId);
+        applyProgress(checklistId, { ...current, completed: nextCompleted });
+        return;
+      }
+      complete(checklistId, itemId);
+    },
+    [resolveItem, applyProgress, complete]
+  );
+  const dismiss = (0, import_react7.useCallback)(
+    (checklistId) => {
+      if (!resolveChecklist(checklistId)) return;
+      const current = progressRef.current[checklistId] ?? emptyProgress;
+      applyProgress(checklistId, { ...current, dismissed: true });
+      emit({ type: "checklist:dismiss", checklistId });
+    },
+    [resolveChecklist, applyProgress, emit]
+  );
+  const reset = (0, import_react7.useCallback)(
+    (checklistId) => {
+      if (!resolveChecklist(checklistId)) return;
+      applyProgress(checklistId, { completed: [], dismissed: false });
+    },
+    [resolveChecklist, applyProgress]
+  );
+  const activate = (0, import_react7.useCallback)(
+    (checklistId, itemId) => {
+      const resolved = resolveItem(checklistId, itemId);
+      if (!resolved) return;
+      const { item } = resolved;
+      if (item.tourId) {
+        if (!guide) {
+          warnNoGuide();
+          return;
+        }
+        void guide.start(item.tourId).catch(warnTourStartFailure);
+        return;
+      }
+      if (item.href) {
+        if (!navigate) {
+          warnNoNavigate();
+          return;
+        }
+        navigate(item.href);
+        return;
+      }
+      toggle(checklistId, itemId);
+    },
+    [resolveItem, guide, navigate, toggle, warnNoGuide, warnNoNavigate, warnTourStartFailure]
+  );
+  const value = (0, import_react7.useMemo)(
+    () => ({ checklists, progress, translate, activate, toggle, complete, dismiss, reset }),
+    [checklists, progress, translate, activate, toggle, complete, dismiss, reset]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ChecklistContext.Provider, { value, children });
+}
+
+// src/useChecklist.ts
+var import_react8 = require("react");
+function useChecklist(checklistId) {
+  const context = (0, import_react8.useContext)(ChecklistContext);
+  if (!context)
+    throw new Error("[guide] useChecklist must be used inside a ChecklistProvider");
+  const checklist = context.checklists.find((entry) => entry.id === checklistId);
+  if (!checklist) throw new Error(`[guide] unknown checklist "${checklistId}"`);
+  const progress = context.progress[checklistId];
+  const completed = progress?.completed ?? [];
+  const dismissed = progress?.dismissed ?? false;
+  const translate = context.translate;
+  const items = (0, import_react8.useMemo)(
+    () => checklist.items.map((item) => ({
+      id: item.id,
+      title: resolveText(item.title, item.titleKey, translate),
+      body: resolveText(item.body, item.bodyKey, translate),
+      completed: completed.includes(item.id),
+      tourId: item.tourId,
+      href: item.href
+    })),
+    [checklist, completed, translate]
+  );
+  const total = checklist.items.length;
+  const completedCount = items.filter((item) => item.completed).length;
+  const isComplete = total > 0 && completedCount === total;
+  const { activate, toggle, complete, dismiss, reset } = context;
+  return (0, import_react8.useMemo)(
+    () => ({
+      items,
+      completedCount,
+      total,
+      isComplete,
+      dismissed,
+      activate: (itemId) => activate(checklistId, itemId),
+      toggle: (itemId) => toggle(checklistId, itemId),
+      complete: (itemId) => complete(checklistId, itemId),
+      dismiss: () => dismiss(checklistId),
+      reset: () => reset(checklistId)
+    }),
+    [
+      items,
+      completedCount,
+      total,
+      isComplete,
+      dismissed,
+      activate,
+      toggle,
+      complete,
+      dismiss,
+      reset,
+      checklistId
+    ]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ChecklistContext,
+  ChecklistProvider,
   GuideContext,
   GuideProvider,
   createBrowserStorage,
   createMemoryStorage,
   findMissingTargets,
   initialTourState,
+  isChecklistProgress,
   isLiteralRoute,
+  isTourProgress,
   matchRoute,
+  resolveText,
   tourReducer,
   useAnnouncer,
+  useChecklist,
   useElementRect,
   useFocusTrap,
   useGuideStep,