@apollovisionlabs/guide-core 0.2.0 → 0.3.1

package/dist/index.cjs

@@ -25,11 +25,14 @@ __export(index_exports, {
   ChecklistProvider: () => ChecklistProvider,
   GuideContext: () => GuideContext,
   GuideProvider: () => GuideProvider,
+  HotspotContext: () => HotspotContext,
+  HotspotProvider: () => HotspotProvider,
   createBrowserStorage: () => createBrowserStorage,
   createMemoryStorage: () => createMemoryStorage,
   findMissingTargets: () => findMissingTargets,
   initialTourState: () => initialTourState,
   isChecklistProgress: () => isChecklistProgress,
+  isHotspotsProgress: () => isHotspotsProgress,
   isLiteralRoute: () => isLiteralRoute,
   isTourProgress: () => isTourProgress,
   matchRoute: () => matchRoute,
@@ -40,6 +43,7 @@ __export(index_exports, {
   useElementRect: () => useElementRect,
   useFocusTrap: () => useFocusTrap,
   useGuideStep: () => useGuideStep,
+  useHotspots: () => useHotspots,
   usePrefersReducedMotion: () => usePrefersReducedMotion,
   useTargetElement: () => useTargetElement,
   useTour: () => useTour
@@ -90,6 +94,11 @@ function isChecklistProgress(value) {
   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) {
@@ -321,6 +330,24 @@ function resolveText(value, key, translate) {
 // src/GuideProvider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var GuideContext = (0, import_react4.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,
@@ -345,6 +372,7 @@ function GuideProvider({
   const [state, dispatch] = (0, import_react4.useReducer)(tourReducer, initialTourState);
   const announce = useAnnouncer();
   const focusOriginRef = (0, import_react4.useRef)(null);
+  const lastElementRef = (0, import_react4.useRef)(null);
   const storageWarnedRef = (0, import_react4.useRef)(false);
   const warnStorageFailure = (0, import_react4.useCallback)((error) => {
     if (storageWarnedRef.current) return;
@@ -380,6 +408,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 = (0, import_react4.useRef)(next);
+  nextRef.current = next;
+  (0, import_react4.useEffect)(() => {
+    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 = (0, import_react4.useCallback)(() => dispatch({ type: "PREVIOUS" }), []);
   const stop = (0, import_react4.useCallback)(() => {
     if (tour) emit({ type: "tour:stop", tourId: tour.id, stepIndex: state.stepIndex });
@@ -478,12 +514,23 @@ function GuideProvider({
       warnStorageFailure(error);
     }
   }, [storage, state.tourId, state.status, state.stepIndex, warnStorageFailure]);
+  (0, import_react4.useEffect)(() => {
+    if (element) lastElementRef.current = element;
+  }, [element]);
   (0, import_react4.useEffect)(() => {
     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 = (0, import_react4.useMemo)(() => {
     if (!tour || !step || !isActive) return null;
@@ -494,6 +541,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,
@@ -562,6 +611,11 @@ function ChecklistProvider({
     return initial;
   });
   const progressRef = (0, import_react7.useRef)(progress);
+  const [restoredById, setRestoredById] = (0, import_react7.useState)(() => {
+    const initial = {};
+    for (const candidate of checklists) initial[candidate.id] = !storage;
+    return initial;
+  });
   const guide = (0, import_react7.useContext)(GuideContext);
   const storageWarnedRef = (0, import_react7.useRef)(false);
   const warnStorageFailure = (0, import_react7.useCallback)((error) => {
@@ -593,31 +647,33 @@ function ChecklistProvider({
   (0, import_react7.useEffect)(() => {
     if (!storage) return;
     let cancelled = false;
-    void (async () => {
-      const restored = {};
-      for (const candidate of checklists) {
+    for (const candidate of checklists) {
+      void (async () => {
         try {
           const stored = await storage.read(`checklist:${candidate.id}`);
-          if (isChecklistProgress(stored)) restored[candidate.id] = stored;
+          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 }));
+          }
         }
-      }
-      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;
     };
@@ -755,8 +811,18 @@ function ChecklistProvider({
     [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]
+    () => ({
+      checklists,
+      progress,
+      translate,
+      restored: restoredById,
+      activate,
+      toggle,
+      complete,
+      dismiss,
+      reset
+    }),
+    [checklists, progress, translate, restoredById, activate, toggle, complete, dismiss, reset]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ChecklistContext.Provider, { value, children });
 }
@@ -773,6 +839,7 @@ function useChecklist(checklistId) {
   const completed = progress?.completed ?? [];
   const dismissed = progress?.dismissed ?? false;
   const translate = context.translate;
+  const restored = context.restored[checklistId] ?? true;
   const items = (0, import_react8.useMemo)(
     () => checklist.items.map((item) => ({
       id: item.id,
@@ -795,6 +862,7 @@ function useChecklist(checklistId) {
       total,
       isComplete,
       dismissed,
+      restored,
       activate: (itemId) => activate(checklistId, itemId),
       toggle: (itemId) => toggle(checklistId, itemId),
       complete: (itemId) => complete(checklistId, itemId),
@@ -807,6 +875,7 @@ function useChecklist(checklistId) {
       total,
       isComplete,
       dismissed,
+      restored,
       activate,
       toggle,
       complete,
@@ -816,17 +885,182 @@ function useChecklist(checklistId) {
     ]
   );
 }
+
+// src/HotspotProvider.tsx
+var import_react9 = require("react");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var STORAGE_KEY = "hotspots:seen";
+var HotspotContext = (0, import_react9.createContext)(null);
+function HotspotProvider({
+  hotspots,
+  children,
+  storage,
+  translate,
+  onEvent
+}) {
+  const hotspotsById = (0, import_react9.useMemo)(() => {
+    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] = (0, import_react9.useState)([]);
+  const [restored, setRestored] = (0, import_react9.useState)(() => !storage);
+  const seenRef = (0, import_react9.useRef)(seen);
+  const guide = (0, import_react9.useContext)(GuideContext);
+  const storageWarnedRef = (0, import_react9.useRef)(false);
+  const warnStorageFailure = (0, import_react9.useCallback)((error) => {
+    if (storageWarnedRef.current) return;
+    storageWarnedRef.current = true;
+    console.warn("[guide] storage failed; hotspot state will not be persisted", error);
+  }, []);
+  const noGuideWarnedRef = (0, import_react9.useRef)(false);
+  const warnNoGuide = (0, import_react9.useCallback)(() => {
+    if (noGuideWarnedRef.current) return;
+    noGuideWarnedRef.current = true;
+    console.warn("[guide] a hotspot needs a GuideProvider to launch a tour");
+  }, []);
+  const tourStartFailedWarnedRef = (0, import_react9.useRef)(false);
+  const warnTourStartFailure = (0, import_react9.useCallback)((error) => {
+    if (tourStartFailedWarnedRef.current) return;
+    tourStartFailedWarnedRef.current = true;
+    console.warn("[guide] starting a tour for a hotspot failed", error);
+  }, []);
+  const onEventRef = (0, import_react9.useRef)(onEvent);
+  onEventRef.current = onEvent;
+  const emit = (0, import_react9.useCallback)((event) => onEventRef.current?.(event), []);
+  (0, import_react9.useEffect)(() => {
+    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 = (0, import_react9.useCallback)(
+    (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 = (0, import_react9.useCallback)(
+    (hotspotId) => {
+      const hotspot = hotspotsById.get(hotspotId);
+      if (!hotspot) {
+        console.warn(`[guide] unknown hotspot "${hotspotId}"`);
+        return null;
+      }
+      return hotspot;
+    },
+    [hotspotsById]
+  );
+  const open = (0, import_react9.useCallback)(
+    (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 = (0, import_react9.useCallback)(
+    (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 = (0, import_react9.useCallback)(() => applySeen([]), [applySeen]);
+  const shownRef = (0, import_react9.useRef)(/* @__PURE__ */ new Set());
+  const notifyShown = (0, import_react9.useCallback)(
+    (hotspotId) => {
+      if (shownRef.current.has(hotspotId)) return;
+      shownRef.current.add(hotspotId);
+      emit({ type: "hotspot:show", hotspotId });
+    },
+    [emit]
+  );
+  const value = (0, import_react9.useMemo)(
+    () => ({ hotspots, seen, translate, restored, open, startTour, reset, notifyShown }),
+    [hotspots, seen, translate, restored, open, startTour, reset, notifyShown]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(HotspotContext.Provider, { value, children });
+}
+
+// src/useHotspots.ts
+var import_react10 = require("react");
+function useHotspots() {
+  const context = (0, import_react10.useContext)(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 = (0, import_react10.useMemo)(
+    () => 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 (0, import_react10.useMemo)(
+    () => ({ hotspots, restored, open, startTour, reset, notifyShown }),
+    [hotspots, restored, open, startTour, reset, notifyShown]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ChecklistContext,
   ChecklistProvider,
   GuideContext,
   GuideProvider,
+  HotspotContext,
+  HotspotProvider,
   createBrowserStorage,
   createMemoryStorage,
   findMissingTargets,
   initialTourState,
   isChecklistProgress,
+  isHotspotsProgress,
   isLiteralRoute,
   isTourProgress,
   matchRoute,
@@ -837,6 +1071,7 @@ function useChecklist(checklistId) {
   useElementRect,
   useFocusTrap,
   useGuideStep,
+  useHotspots,
   usePrefersReducedMotion,
   useTargetElement,
   useTour