@apollovisionlabs/guide-core 0.1.1 → 0.3.0

package/dist/index.cjs

@@ -21,19 +21,29 @@ 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,
+  HotspotContext: () => HotspotContext,
+  HotspotProvider: () => HotspotProvider,
   createBrowserStorage: () => createBrowserStorage,
   createMemoryStorage: () => createMemoryStorage,
   findMissingTargets: () => findMissingTargets,
   initialTourState: () => initialTourState,
+  isChecklistProgress: () => isChecklistProgress,
+  isHotspotsProgress: () => isHotspotsProgress,
   isLiteralRoute: () => isLiteralRoute,
+  isTourProgress: () => isTourProgress,
   matchRoute: () => matchRoute,
+  resolveText: () => resolveText,
   tourReducer: () => tourReducer,
   useAnnouncer: () => useAnnouncer,
+  useChecklist: () => useChecklist,
   useElementRect: () => useElementRect,
   useFocusTrap: () => useFocusTrap,
   useGuideStep: () => useGuideStep,
+  useHotspots: () => useHotspots,
   usePrefersReducedMotion: () => usePrefersReducedMotion,
   useTargetElement: () => useTargetElement,
   useTour: () => useTour
@@ -44,36 +54,51 @@ 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";
+}
+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) {
@@ -295,14 +320,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
-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 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,
@@ -327,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;
@@ -362,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 });
@@ -386,7 +440,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,18 +508,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]);
+  (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;
@@ -475,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,
@@ -518,21 +586,492 @@ 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 [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) => {
+    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;
+    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 = (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,
+      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 });
+}
+
+// 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 restored = context.restored[checklistId] ?? true;
+  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,
+      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
+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,
+  resolveText,
   tourReducer,
   useAnnouncer,
+  useChecklist,
   useElementRect,
   useFocusTrap,
   useGuideStep,
+  useHotspots,
   usePrefersReducedMotion,
   useTargetElement,
   useTour