@apollovisionlabs/guide-core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -19,6 +19,11 @@ interface Step {
     placement?: Placement;
     /** Lets the user interact with the page during the step. */
     interactive?: boolean;
+    /**
+     * Advances the tour when the user clicks the target. Implies `interactive`: a step that
+     * waits for a click has to let the click through.
+     */
+    advanceOn?: 'click';
     title?: string;
     titleKey?: string;
     body?: string;
@@ -62,10 +67,34 @@ interface ResolvedChecklistItem {
     tourId?: string;
     href?: string;
 }
+interface Hotspot {
+    id: string;
+    /** Logical key carried by the data-guide attribute on the element. */
+    target: string;
+    title?: string;
+    titleKey?: string;
+    body?: string;
+    bodyKey?: string;
+    /** Tour started from the hotspot's bubble. */
+    tourId?: string;
+    placement?: Placement;
+}
+interface ResolvedHotspot {
+    id: string;
+    target: string;
+    title: string;
+    body: string;
+    seen: boolean;
+    tourId?: string;
+    placement?: Placement;
+}
+interface HotspotsProgress {
+    seen: string[];
+}
 interface GuideStorage {
     /**
      * Reads a previously written value. The key is namespaced by the caller,
-     * `tour:<id>` or `checklist:<id>`, so one storage serves both.
+     * `tour:<id>`, `checklist:<id>`, or `hotspots:seen`, so one storage serves them all.
      */
     read<T>(key: string): Promise<T | null>;
     write<T>(key: string, value: T): Promise<void>;
@@ -101,6 +130,12 @@ type GuideEvent = {
 } | {
     type: 'checklist:dismiss';
     checklistId: string;
+} | {
+    type: 'hotspot:show';
+    hotspotId: string;
+} | {
+    type: 'hotspot:open';
+    hotspotId: string;
 };
 type Translate = (key: string) => string;
 
@@ -116,6 +151,11 @@ declare function isTourProgress(value: unknown): value is TourProgress;
  * never trusted until its shape is checked.
  */
 declare function isChecklistProgress(value: unknown): value is ChecklistProgress;
+/**
+ * Same defensive posture as the two guards above: a stored hotspot value is never trusted
+ * until its shape is checked.
+ */
+declare function isHotspotsProgress(value: unknown): value is HotspotsProgress;
 
 declare function isLiteralRoute(pattern: string): boolean;
 declare function matchRoute(pattern: string, pathname: string): boolean;
@@ -173,6 +213,14 @@ interface ActiveStep {
     stepCount: number;
     element: HTMLElement | null;
     rect: Rect | null;
+    /**
+     * Whether the page stays reachable during the step. True when the step declares
+     * `interactive`, and also when it declares `advanceOn`, whose click has to reach the
+     * element. Renderers read this instead of `step.interactive`, so the rule lives here.
+     */
+    interactive: boolean;
+    /** True when the step advances on a user action rather than on a button. */
+    awaitsAction: boolean;
     title: string;
     body: string;
     isFirst: boolean;
@@ -229,6 +277,15 @@ interface ChecklistContextValue {
     checklists: Checklist[];
     progress: Record<string, ChecklistProgress>;
     translate?: Translate;
+    /**
+     * Whether each checklist's initial restore from storage has settled, keyed by checklist id:
+     * true immediately for a checklist when no `storage` prop was given (there is nothing to
+     * wait for), and true once that checklist's own read has resolved or rejected. Settled
+     * independently per checklist, so a slow or hung read for one checklist never holds another
+     * checklist's rendering hostage, and a renderer can wait for its own entry without a broken
+     * backend hiding it forever.
+     */
+    restored: Record<string, boolean>;
     activate: (checklistId: string, itemId: string) => void;
     toggle: (checklistId: string, itemId: string) => void;
     complete: (checklistId: string, itemId: string) => void;
@@ -252,6 +309,14 @@ interface UseChecklistResult {
     total: number;
     isComplete: boolean;
     dismissed: boolean;
+    /**
+     * Whether this checklist's own initial restore from storage has settled. A renderer should
+     * wait for this before drawing anything, or a checklist already dismissed or partly
+     * completed in storage can flash its empty initial state on screen once before the restore
+     * lands. Settled per checklist: a slow or hung read for a different checklist on the same
+     * provider never holds this one false.
+     */
+    restored: boolean;
     activate: (itemId: string) => void;
     toggle: (itemId: string) => void;
     complete: (itemId: string) => void;
@@ -260,4 +325,49 @@ interface UseChecklistResult {
 }
 declare function useChecklist(checklistId: string): UseChecklistResult;
 
-export { type ActiveStep, type Checklist, ChecklistContext, type ChecklistContextValue, type ChecklistItem, type ChecklistProgress, ChecklistProvider, type ChecklistProviderProps, GuideContext, type GuideContextValue, type GuideEvent, GuideProvider, type GuideProviderProps, type GuideStorage, type MissingTargetPolicy, type Placement, type Rect, type ResolvedChecklistItem, type Step, type Tour, type TourAction, type TourProgress, type TourState, type TourStatus, type Translate, type UseChecklistResult, type UseFocusTrapOptions, type UseTargetElementOptions, type UseTourResult, createBrowserStorage, createMemoryStorage, findMissingTargets, initialTourState, isChecklistProgress, isLiteralRoute, isTourProgress, matchRoute, resolveText, tourReducer, useAnnouncer, useChecklist, useElementRect, useFocusTrap, useGuideStep, usePrefersReducedMotion, useTargetElement, useTour };
+interface HotspotContextValue {
+    hotspots: Hotspot[];
+    seen: string[];
+    translate?: Translate;
+    /**
+     * Whether the initial restore from storage has settled: true immediately when no `storage`
+     * prop was given (there is nothing to wait for), and true once the read resolves or
+     * rejects, so a renderer can wait for it without a broken backend hiding hotspots forever.
+     */
+    restored: boolean;
+    open: (hotspotId: string) => void;
+    startTour: (hotspotId: string) => void;
+    reset: () => void;
+    notifyShown: (hotspotId: string) => void;
+}
+declare const HotspotContext: react.Context<HotspotContextValue | null>;
+interface HotspotProviderProps {
+    hotspots: Hotspot[];
+    children: ReactNode;
+    storage?: GuideStorage;
+    translate?: Translate;
+    onEvent?: (event: GuideEvent) => void;
+}
+declare function HotspotProvider({ hotspots, children, storage, translate, onEvent, }: HotspotProviderProps): react.JSX.Element;
+
+interface UseHotspotsResult {
+    /**
+     * Every hotspot, each carrying its own `seen`, rather than the unseen ones alone. A
+     * renderer has to keep a marker mounted while its own bubble closes, so it needs the seen
+     * one too; filtering is one line at the call site.
+     */
+    hotspots: ResolvedHotspot[];
+    /**
+     * Whether the initial restore from storage has settled. A renderer should wait for this
+     * before drawing any marker, or a hotspot already seen in storage can flash on screen once
+     * before the restore lands.
+     */
+    restored: boolean;
+    open: (hotspotId: string) => void;
+    startTour: (hotspotId: string) => void;
+    reset: () => void;
+    notifyShown: (hotspotId: string) => void;
+}
+declare function useHotspots(): UseHotspotsResult;
+
+export { type ActiveStep, type Checklist, ChecklistContext, type ChecklistContextValue, type ChecklistItem, type ChecklistProgress, ChecklistProvider, type ChecklistProviderProps, GuideContext, type GuideContextValue, type GuideEvent, GuideProvider, type GuideProviderProps, type GuideStorage, type Hotspot, HotspotContext, type HotspotContextValue, HotspotProvider, type HotspotProviderProps, type HotspotsProgress, type MissingTargetPolicy, type Placement, type Rect, type ResolvedChecklistItem, type ResolvedHotspot, type Step, type Tour, type TourAction, type TourProgress, type TourState, type TourStatus, type Translate, type UseChecklistResult, type UseFocusTrapOptions, type UseHotspotsResult, type UseTargetElementOptions, type UseTourResult, createBrowserStorage, createMemoryStorage, findMissingTargets, initialTourState, isChecklistProgress, isHotspotsProgress, isLiteralRoute, isTourProgress, matchRoute, resolveText, tourReducer, useAnnouncer, useChecklist, useElementRect, useFocusTrap, useGuideStep, useHotspots, usePrefersReducedMotion, useTargetElement, useTour };

package/dist/index.mjs

@@ -44,6 +44,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) {
@@ -283,6 +288,24 @@ function resolveText(value, key, translate) {
 // 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,
@@ -307,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;
@@ -342,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 });
@@ -440,12 +472,23 @@ function GuideProvider({
       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;
@@ -456,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,
@@ -532,6 +577,11 @@ function ChecklistProvider({
     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) => {
@@ -563,31 +613,33 @@ function ChecklistProvider({
   useEffect5(() => {
     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;
     };
@@ -725,8 +777,18 @@ function ChecklistProvider({
     [resolveItem, guide, navigate, toggle, warnNoGuide, warnNoNavigate, warnTourStartFailure]
   );
   const value = useMemo3(
-    () => ({ 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__ */ jsx2(ChecklistContext.Provider, { value, children });
 }
@@ -743,6 +805,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 = useMemo4(
     () => checklist.items.map((item) => ({
       id: item.id,
@@ -765,6 +828,7 @@ function useChecklist(checklistId) {
       total,
       isComplete,
       dismissed,
+      restored,
       activate: (itemId) => activate(checklistId, itemId),
       toggle: (itemId) => toggle(checklistId, itemId),
       complete: (itemId) => complete(checklistId, itemId),
@@ -777,6 +841,7 @@ function useChecklist(checklistId) {
       total,
       isComplete,
       dismissed,
+      restored,
       activate,
       toggle,
       complete,
@@ -786,16 +851,189 @@ function useChecklist(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,
@@ -806,6 +1044,7 @@ export {
   useElementRect,
   useFocusTrap,
   useGuideStep,
+  useHotspots,
   usePrefersReducedMotion,
   useTargetElement,
   useTour