@apollovisionlabs/guide-core 0.1.1 → 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;
@@ -35,9 +40,64 @@ interface TourProgress {
     status: 'in-progress' | 'completed';
     stepIndex: number;
 }
+interface ChecklistItem {
+    id: string;
+    title?: string;
+    titleKey?: string;
+    body?: string;
+    bodyKey?: string;
+    /** Tour launched when the item is activated. Completing it completes the item. */
+    tourId?: string;
+    /** Path navigated to when the item is activated and carries no tour. */
+    href?: string;
+}
+interface Checklist {
+    id: string;
+    items: ChecklistItem[];
+}
+interface ChecklistProgress {
+    completed: string[];
+    dismissed: boolean;
+}
+interface ResolvedChecklistItem {
+    id: string;
+    title: string;
+    body: string;
+    completed: boolean;
+    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 {
-    read(tourId: string): Promise<TourProgress | null>;
-    write(tourId: string, progress: TourProgress): Promise<void>;
+    /**
+     * Reads a previously written value. The key is namespaced by the caller,
+     * `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>;
 }
 type GuideEvent = {
     type: 'tour:start';
@@ -60,11 +120,42 @@ type GuideEvent = {
     tourId: string;
     stepIndex: number;
     target: string;
+} | {
+    type: 'checklist:item-complete';
+    checklistId: string;
+    itemId: string;
+} | {
+    type: 'checklist:complete';
+    checklistId: string;
+} | {
+    type: 'checklist:dismiss';
+    checklistId: string;
+} | {
+    type: 'hotspot:show';
+    hotspotId: string;
+} | {
+    type: 'hotspot:open';
+    hotspotId: string;
 };
 type Translate = (key: string) => string;
 
-declare function createMemoryStorage(initial?: Record<string, TourProgress>): GuideStorage;
+declare function createMemoryStorage(initial?: Record<string, unknown>): GuideStorage;
 declare function createBrowserStorage(namespace?: string): GuideStorage;
+/**
+ * A stored value survives code changes, browser extensions and hand editing,
+ * so nothing read back is trusted until its shape is checked.
+ */
+declare function isTourProgress(value: unknown): value is TourProgress;
+/**
+ * Same defensive posture as isTourProgress: a stored checklist value is
+ * 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;
@@ -122,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;
@@ -172,4 +271,103 @@ declare function findMissingTargets(tour: Tour, location: string | undefined, at
 
 declare function useGuideStep(): ActiveStep | null;
 
-export { type ActiveStep, GuideContext, type GuideContextValue, type GuideEvent, GuideProvider, type GuideProviderProps, type GuideStorage, type MissingTargetPolicy, type Placement, type Rect, type Step, type Tour, type TourAction, type TourProgress, type TourState, type TourStatus, type Translate, type UseFocusTrapOptions, type UseTargetElementOptions, type UseTourResult, createBrowserStorage, createMemoryStorage, findMissingTargets, initialTourState, isLiteralRoute, matchRoute, tourReducer, useAnnouncer, useElementRect, useFocusTrap, useGuideStep, usePrefersReducedMotion, useTargetElement, useTour };
+declare function resolveText(value: string | undefined, key: string | undefined, translate: Translate | undefined): string;
+
+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;
+    dismiss: (checklistId: string) => void;
+    reset: (checklistId: string) => void;
+}
+declare const ChecklistContext: react.Context<ChecklistContextValue | null>;
+interface ChecklistProviderProps {
+    checklists: Checklist[];
+    children: ReactNode;
+    storage?: GuideStorage;
+    translate?: Translate;
+    navigate?: (path: string) => void;
+    onEvent?: (event: GuideEvent) => void;
+}
+declare function ChecklistProvider({ checklists, children, storage, translate, navigate, onEvent, }: ChecklistProviderProps): react.JSX.Element;
+
+interface UseChecklistResult {
+    items: ResolvedChecklistItem[];
+    completedCount: number;
+    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;
+    dismiss: () => void;
+    reset: () => void;
+}
+declare function useChecklist(checklistId: string): UseChecklistResult;
+
+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 };