@apollovisionlabs/guide-core 0.1.1 → 0.3.0

package/dist/index.mjs

@@ -4,36 +4,51 @@
 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";
+}
+function isHotspotsProgress(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return Array.isArray(candidate.seen) && candidate.seen.every((entry) => typeof entry === "string");
+}
 
 // src/matchRoute.ts
 function segments(value) {
@@ -263,14 +278,34 @@ 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
-import { jsx } from "react/jsx-runtime";
-var GuideContext = 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
+import { jsx } from "react/jsx-runtime";
+var GuideContext = createContext(null);
+function focusFallback(element) {
+  const needsTabIndex = !element.hasAttribute("tabindex") && element.tabIndex < 0;
+  if (!needsTabIndex) {
+    element.focus();
+    return;
+  }
+  element.setAttribute("tabindex", "-1");
+  element.focus();
+  if (document.activeElement !== element) {
+    element.removeAttribute("tabindex");
+    return;
+  }
+  const onBlur = () => {
+    element.removeAttribute("tabindex");
+    element.removeEventListener("blur", onBlur);
+  };
+  element.addEventListener("blur", onBlur);
+}
 function GuideProvider({
   tours,
   children,
@@ -295,6 +330,7 @@ function GuideProvider({
   const [state, dispatch] = useReducer(tourReducer, initialTourState);
   const announce = useAnnouncer();
   const focusOriginRef = useRef(null);
+  const lastElementRef = useRef(null);
   const storageWarnedRef = useRef(false);
   const warnStorageFailure = useCallback2((error) => {
     if (storageWarnedRef.current) return;
@@ -330,6 +366,14 @@ function GuideProvider({
     dispatch({ type: "NEXT", stepCount: tour.steps.length });
     if (isLast) emit({ type: "tour:complete", tourId: tour.id });
   }, [tour, state.stepIndex, emit]);
+  const nextRef = useRef(next);
+  nextRef.current = next;
+  useEffect4(() => {
+    if (state.status !== "running" || !element || step?.advanceOn !== "click") return;
+    const onClick = () => nextRef.current();
+    element.addEventListener("click", onClick);
+    return () => element.removeEventListener("click", onClick);
+  }, [state.status, element, step?.advanceOn]);
   const previous = useCallback2(() => dispatch({ type: "PREVIOUS" }), []);
   const stop = useCallback2(() => {
     if (tour) emit({ type: "tour:stop", tourId: tour.id, stepIndex: state.stepIndex });
@@ -354,7 +398,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);
         }
@@ -421,18 +466,29 @@ 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);
     }
   }, [storage, state.tourId, state.status, state.stepIndex, warnStorageFailure]);
+  useEffect4(() => {
+    if (element) lastElementRef.current = element;
+  }, [element]);
   useEffect4(() => {
     if (state.status !== "idle" && state.status !== "completed") return;
     const origin = focusOriginRef.current;
-    if (!origin) return;
+    const fallback = lastElementRef.current;
     focusOriginRef.current = null;
-    if (typeof document !== "undefined" && document.contains(origin)) origin.focus();
+    lastElementRef.current = null;
+    if (typeof document === "undefined") return;
+    if (origin && document.contains(origin)) {
+      origin.focus();
+      return;
+    }
+    if (document.activeElement !== document.body) return;
+    if (!fallback || !document.contains(fallback)) return;
+    focusFallback(fallback);
   }, [state.status]);
   const activeStep = useMemo(() => {
     if (!tour || !step || !isActive) return null;
@@ -443,6 +499,8 @@ function GuideProvider({
       stepCount: tour.steps.length,
       element,
       rect,
+      interactive: step.interactive === true || step.advanceOn !== void 0,
+      awaitsAction: step.advanceOn !== void 0,
       title: resolveText(step.title, step.titleKey, translate),
       body: resolveText(step.body, step.bodyKey, translate),
       isFirst: state.stepIndex === 0,
@@ -486,20 +544,507 @@ function useGuideStep() {
   if (!context) throw new Error("[guide] useGuideStep must be used inside a GuideProvider");
   return context.activeStep;
 }
+
+// src/ChecklistProvider.tsx
+import {
+  createContext as createContext2,
+  useCallback as useCallback3,
+  useContext as useContext3,
+  useEffect as useEffect5,
+  useMemo as useMemo3,
+  useRef as useRef2,
+  useState as useState5
+} from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var ChecklistContext = createContext2(null);
+var emptyProgress = { completed: [], dismissed: false };
+function ChecklistProvider({
+  checklists,
+  children,
+  storage,
+  translate,
+  navigate,
+  onEvent
+}) {
+  const checklistsById = useMemo3(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const candidate of checklists) map.set(candidate.id, candidate);
+    return map;
+  }, [checklists]);
+  const [progress, setProgress] = useState5(() => {
+    const initial = {};
+    for (const candidate of checklists) initial[candidate.id] = emptyProgress;
+    return initial;
+  });
+  const progressRef = useRef2(progress);
+  const [restoredById, setRestoredById] = useState5(() => {
+    const initial = {};
+    for (const candidate of checklists) initial[candidate.id] = !storage;
+    return initial;
+  });
+  const guide = useContext3(GuideContext);
+  const storageWarnedRef = useRef2(false);
+  const warnStorageFailure = useCallback3((error) => {
+    if (storageWarnedRef.current) return;
+    storageWarnedRef.current = true;
+    console.warn("[guide] storage failed; checklist progress will not be persisted", error);
+  }, []);
+  const noGuideWarnedRef = useRef2(false);
+  const warnNoGuide = useCallback3(() => {
+    if (noGuideWarnedRef.current) return;
+    noGuideWarnedRef.current = true;
+    console.warn("[guide] a checklist item needs a GuideProvider to launch a tour");
+  }, []);
+  const tourStartFailedWarnedRef = useRef2(false);
+  const warnTourStartFailure = useCallback3((error) => {
+    if (tourStartFailedWarnedRef.current) return;
+    tourStartFailedWarnedRef.current = true;
+    console.warn("[guide] starting a tour for a checklist item failed", error);
+  }, []);
+  const noNavigateWarnedRef = useRef2(false);
+  const warnNoNavigate = useCallback3(() => {
+    if (noNavigateWarnedRef.current) return;
+    noNavigateWarnedRef.current = true;
+    console.warn("[guide] a checklist item declares an href but no navigate function was provided");
+  }, []);
+  const onEventRef = useRef2(onEvent);
+  onEventRef.current = onEvent;
+  const emit = useCallback3((event) => onEventRef.current?.(event), []);
+  useEffect5(() => {
+    if (!storage) return;
+    let cancelled = false;
+    for (const candidate of checklists) {
+      void (async () => {
+        try {
+          const stored = await storage.read(`checklist:${candidate.id}`);
+          if (!cancelled && isChecklistProgress(stored)) {
+            const live = progressRef.current[candidate.id] ?? emptyProgress;
+            const merged = {
+              ...progressRef.current,
+              [candidate.id]: {
+                completed: live.completed.concat(
+                  stored.completed.filter((id) => !live.completed.includes(id))
+                ),
+                dismissed: live.dismissed || stored.dismissed
+              }
+            };
+            progressRef.current = merged;
+            setProgress(merged);
+          }
+        } catch (error) {
+          warnStorageFailure(error);
+        } finally {
+          if (!cancelled) {
+            setRestoredById((current) => ({ ...current, [candidate.id]: true }));
+          }
+        }
+      })();
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [storage]);
+  const applyProgress = useCallback3(
+    (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 = useCallback3(
+    (checklistId) => {
+      const checklist = checklistsById.get(checklistId);
+      if (!checklist) {
+        console.warn(`[guide] unknown checklist "${checklistId}"`);
+        return null;
+      }
+      return checklist;
+    },
+    [checklistsById]
+  );
+  const resolveItem = useCallback3(
+    (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 = useCallback3(
+    (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 = useCallback3(
+    (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 = useRef2(null);
+  useEffect5(() => {
+    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 = useCallback3(
+    (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 = useCallback3(
+    (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 = useCallback3(
+    (checklistId) => {
+      if (!resolveChecklist(checklistId)) return;
+      applyProgress(checklistId, { completed: [], dismissed: false });
+    },
+    [resolveChecklist, applyProgress]
+  );
+  const activate = useCallback3(
+    (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 = useMemo3(
+    () => ({
+      checklists,
+      progress,
+      translate,
+      restored: restoredById,
+      activate,
+      toggle,
+      complete,
+      dismiss,
+      reset
+    }),
+    [checklists, progress, translate, restoredById, activate, toggle, complete, dismiss, reset]
+  );
+  return /* @__PURE__ */ jsx2(ChecklistContext.Provider, { value, children });
+}
+
+// src/useChecklist.ts
+import { useContext as useContext4, useMemo as useMemo4 } from "react";
+function useChecklist(checklistId) {
+  const context = useContext4(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 restored = context.restored[checklistId] ?? true;
+  const items = useMemo4(
+    () => 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 useMemo4(
+    () => ({
+      items,
+      completedCount,
+      total,
+      isComplete,
+      dismissed,
+      restored,
+      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,
+      restored,
+      activate,
+      toggle,
+      complete,
+      dismiss,
+      reset,
+      checklistId
+    ]
+  );
+}
+
+// src/HotspotProvider.tsx
+import {
+  createContext as createContext3,
+  useCallback as useCallback4,
+  useContext as useContext5,
+  useEffect as useEffect6,
+  useMemo as useMemo5,
+  useRef as useRef3,
+  useState as useState6
+} from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var STORAGE_KEY = "hotspots:seen";
+var HotspotContext = createContext3(null);
+function HotspotProvider({
+  hotspots,
+  children,
+  storage,
+  translate,
+  onEvent
+}) {
+  const hotspotsById = useMemo5(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const candidate of hotspots) {
+      if (map.has(candidate.id)) {
+        throw new Error(`[guide] duplicate hotspot id: ${candidate.id}`);
+      }
+      map.set(candidate.id, candidate);
+    }
+    return map;
+  }, [hotspots]);
+  const [seen, setSeen] = useState6([]);
+  const [restored, setRestored] = useState6(() => !storage);
+  const seenRef = useRef3(seen);
+  const guide = useContext5(GuideContext);
+  const storageWarnedRef = useRef3(false);
+  const warnStorageFailure = useCallback4((error) => {
+    if (storageWarnedRef.current) return;
+    storageWarnedRef.current = true;
+    console.warn("[guide] storage failed; hotspot state will not be persisted", error);
+  }, []);
+  const noGuideWarnedRef = useRef3(false);
+  const warnNoGuide = useCallback4(() => {
+    if (noGuideWarnedRef.current) return;
+    noGuideWarnedRef.current = true;
+    console.warn("[guide] a hotspot needs a GuideProvider to launch a tour");
+  }, []);
+  const tourStartFailedWarnedRef = useRef3(false);
+  const warnTourStartFailure = useCallback4((error) => {
+    if (tourStartFailedWarnedRef.current) return;
+    tourStartFailedWarnedRef.current = true;
+    console.warn("[guide] starting a tour for a hotspot failed", error);
+  }, []);
+  const onEventRef = useRef3(onEvent);
+  onEventRef.current = onEvent;
+  const emit = useCallback4((event) => onEventRef.current?.(event), []);
+  useEffect6(() => {
+    if (!storage) return;
+    let cancelled = false;
+    void (async () => {
+      let stored = null;
+      try {
+        stored = await storage.read(STORAGE_KEY);
+      } catch (error) {
+        warnStorageFailure(error);
+        if (!cancelled) setRestored(true);
+        return;
+      }
+      if (cancelled) return;
+      if (isHotspotsProgress(stored)) {
+        const merged = seenRef.current.concat(
+          stored.seen.filter((id) => !seenRef.current.includes(id))
+        );
+        seenRef.current = merged;
+        setSeen(merged);
+      }
+      setRestored(true);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, warnStorageFailure]);
+  const applySeen = useCallback4(
+    (next) => {
+      seenRef.current = next;
+      setSeen(next);
+      if (!storage) return;
+      try {
+        void Promise.resolve(storage.write(STORAGE_KEY, { seen: next })).catch(
+          warnStorageFailure
+        );
+      } catch (error) {
+        warnStorageFailure(error);
+      }
+    },
+    [storage, warnStorageFailure]
+  );
+  const resolve = useCallback4(
+    (hotspotId) => {
+      const hotspot = hotspotsById.get(hotspotId);
+      if (!hotspot) {
+        console.warn(`[guide] unknown hotspot "${hotspotId}"`);
+        return null;
+      }
+      return hotspot;
+    },
+    [hotspotsById]
+  );
+  const open = useCallback4(
+    (hotspotId) => {
+      if (!resolve(hotspotId)) return;
+      emit({ type: "hotspot:open", hotspotId });
+      if (seenRef.current.includes(hotspotId)) return;
+      applySeen([...seenRef.current, hotspotId]);
+    },
+    [resolve, applySeen, emit]
+  );
+  const startTour = useCallback4(
+    (hotspotId) => {
+      const hotspot = resolve(hotspotId);
+      if (!hotspot?.tourId) return;
+      if (!guide) {
+        warnNoGuide();
+        return;
+      }
+      void guide.start(hotspot.tourId).catch(warnTourStartFailure);
+    },
+    [resolve, guide, warnNoGuide, warnTourStartFailure]
+  );
+  const reset = useCallback4(() => applySeen([]), [applySeen]);
+  const shownRef = useRef3(/* @__PURE__ */ new Set());
+  const notifyShown = useCallback4(
+    (hotspotId) => {
+      if (shownRef.current.has(hotspotId)) return;
+      shownRef.current.add(hotspotId);
+      emit({ type: "hotspot:show", hotspotId });
+    },
+    [emit]
+  );
+  const value = useMemo5(
+    () => ({ hotspots, seen, translate, restored, open, startTour, reset, notifyShown }),
+    [hotspots, seen, translate, restored, open, startTour, reset, notifyShown]
+  );
+  return /* @__PURE__ */ jsx3(HotspotContext.Provider, { value, children });
+}
+
+// src/useHotspots.ts
+import { useContext as useContext6, useMemo as useMemo6 } from "react";
+function useHotspots() {
+  const context = useContext6(HotspotContext);
+  if (!context)
+    throw new Error("[guide] useHotspots must be used inside a HotspotProvider");
+  const { seen, translate, restored, open, startTour, reset, notifyShown } = context;
+  const hotspots = useMemo6(
+    () => context.hotspots.map((hotspot) => ({
+      id: hotspot.id,
+      target: hotspot.target,
+      title: resolveText(hotspot.title, hotspot.titleKey, translate),
+      body: resolveText(hotspot.body, hotspot.bodyKey, translate),
+      seen: seen.includes(hotspot.id),
+      tourId: hotspot.tourId,
+      placement: hotspot.placement
+    })),
+    [context.hotspots, seen, translate]
+  );
+  return useMemo6(
+    () => ({ hotspots, restored, open, startTour, reset, notifyShown }),
+    [hotspots, restored, open, startTour, reset, notifyShown]
+  );
+}
 export {
+  ChecklistContext,
+  ChecklistProvider,
   GuideContext,
   GuideProvider,
+  HotspotContext,
+  HotspotProvider,
   createBrowserStorage,
   createMemoryStorage,
   findMissingTargets,
   initialTourState,
+  isChecklistProgress,
+  isHotspotsProgress,
   isLiteralRoute,
+  isTourProgress,
   matchRoute,
+  resolveText,
   tourReducer,
   useAnnouncer,
+  useChecklist,
   useElementRect,
   useFocusTrap,
   useGuideStep,
+  useHotspots,
   usePrefersReducedMotion,
   useTargetElement,
   useTour