@ciridae/ui 0.13.0 → 0.15.0

package/dist/components/walkthrough/presentation/WalkthroughCoach.d.ts

@@ -0,0 +1,14 @@
+import type { WalkthroughAdvance, WalkthroughStep } from "../runtime/walkthroughTypes.js";
+export type WalkthroughCoachState = "locating" | "missing" | "off-route" | "ready" | "restore";
+export declare function WalkthroughCoach({ advanceType, coachState, flowTitle, onBack, onNext, onPause, onReturn, step, stepCount, stepIndex, }: {
+    advanceType: WalkthroughAdvance["type"];
+    coachState: WalkthroughCoachState;
+    flowTitle: string;
+    onBack: () => void;
+    onNext: () => void;
+    onPause: () => void;
+    onReturn: () => void;
+    step: WalkthroughStep;
+    stepCount: number;
+    stepIndex: number;
+}): import("@types/react").JSX.Element;

package/dist/components/walkthrough/presentation/WalkthroughCoach.js

@@ -0,0 +1,32 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Button } from "../../ui/button.js";
+import { Card, CardContent } from "../../ui/card.js";
+export function WalkthroughCoach({ advanceType, coachState, flowTitle, onBack, onNext, onPause, onReturn, step, stepCount, stepIndex, }) {
+    return (_jsx(Card, { className: "border-foreground/20 shadow-sm", children: _jsxs(CardContent, { className: "grid gap-4 py-4", children: [_jsxs("div", { className: "grid gap-1", children: [_jsxs("p", { className: "text-meta text-muted-foreground", children: [flowTitle, " \u00B7 Step ", stepIndex + 1, " of ", stepCount] }), _jsx("h2", { className: "font-heading text-lg text-foreground", children: step.title }), _jsx("p", { className: "text-sm leading-relaxed text-muted-foreground", children: step.body }), _jsx(CoachStatus, { advanceType: advanceType, state: coachState })] }), _jsxs("div", { className: "flex flex-wrap justify-end gap-2", children: [_jsx(Button, { onClick: onPause, size: "sm", type: "button", variant: "ghost", children: "Pause" }), _jsx(Button, { disabled: stepIndex === 0, onClick: onBack, size: "sm", type: "button", variant: "outline", children: "Back" }), _jsx(CoachPrimaryAction, { advanceType: advanceType, coachState: coachState, isLast: stepIndex === stepCount - 1, onNext: onNext, onReturn: onReturn })] })] }) }));
+}
+function CoachStatus({ advanceType, state, }) {
+    if (state === "off-route") {
+        return _jsx("p", { className: "text-xs text-muted-foreground", children: "This page is outside the walkthrough." });
+    }
+    if (state === "missing") {
+        return (_jsx("p", { className: "text-xs text-muted-foreground", children: "The required control is not available in the current app state." }));
+    }
+    if (state === "locating") {
+        return _jsx("p", { className: "text-xs text-muted-foreground", children: "Locating the next control\u2026" });
+    }
+    if (state === "restore") {
+        return (_jsx("p", { className: "text-xs text-muted-foreground", children: "Use the highlighted control to reopen this step." }));
+    }
+    if (advanceType !== "manual") {
+        return (_jsx("p", { className: "text-xs text-muted-foreground", children: "Use the highlighted control to continue \u00B7 click elsewhere to pause" }));
+    }
+    return (_jsx("p", { className: "text-xs text-muted-foreground", children: "Next to continue \u00B7 click elsewhere to pause" }));
+}
+function CoachPrimaryAction({ advanceType, coachState, isLast, onNext, onReturn, }) {
+    if (coachState === "off-route") {
+        return (_jsx(Button, { onClick: onReturn, size: "sm", type: "button", children: "Return to step" }));
+    }
+    if (advanceType !== "manual" || coachState === "restore")
+        return null;
+    return (_jsx(Button, { disabled: coachState !== "ready", onClick: onNext, size: "sm", type: "button", children: isLast ? "Finish" : "Next" }));
+}

package/dist/components/walkthrough/presentation/WalkthroughHighlight.d.ts

@@ -0,0 +1,5 @@
+import type { WalkthroughTargetRect } from "../targeting/useWalkthroughTargetRect.js";
+export declare function WalkthroughHighlight({ rect, stepNumber, }: {
+    rect: WalkthroughTargetRect;
+    stepNumber: number;
+}): import("@types/react").JSX.Element;

package/dist/components/walkthrough/presentation/WalkthroughHighlight.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+export function WalkthroughHighlight({ rect, stepNumber, }) {
+    const pad = 6;
+    const left = Math.min(window.innerWidth, Math.max(0, rect.left - pad));
+    const top = Math.min(window.innerHeight, Math.max(0, rect.top - pad));
+    const right = Math.max(left, Math.min(window.innerWidth, rect.left + rect.width + pad));
+    const bottom = Math.max(top, Math.min(window.innerHeight, rect.top + rect.height + pad));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": true, className: "absolute inset-x-0 top-0 bg-foreground/40", style: { height: top } }), _jsx("div", { "aria-hidden": true, className: "absolute bottom-0 inset-x-0 bg-foreground/40", style: { top: bottom } }), _jsx("div", { "aria-hidden": true, className: "absolute bg-foreground/40", style: { bottom: window.innerHeight - bottom, left: 0, top, width: left } }), _jsx("div", { "aria-hidden": true, className: "absolute bg-foreground/40", style: { bottom: window.innerHeight - bottom, left: right, right: 0, top } }), _jsx("div", { "aria-hidden": true, className: "absolute rounded-md ring-2 ring-foreground", style: { height: bottom - top, left, top, width: right - left } }), _jsx("div", { "aria-hidden": true, className: "absolute z-10 grid size-7 place-items-center rounded-full bg-foreground font-mono text-xs text-background", style: { left: Math.max(8, left - 10), top: Math.max(8, top - 10) }, children: stepNumber })] }));
+}

package/dist/components/walkthrough/presentation/WalkthroughOverlay.d.ts

@@ -0,0 +1 @@
+export declare function WalkthroughOverlay(): import("@types/react").JSX.Element | null;

package/dist/components/walkthrough/presentation/WalkthroughOverlay.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { listenForWalkthroughEvent, listenForWalkthroughTargetClick, } from "../runtime/walkthroughEvents.js";
+import { walkthroughHrefMatches } from "../runtime/walkthroughLocation.js";
+import { useWalkthrough } from "../runtime/useWalkthrough.js";
+import { listenForOutsideWalkthroughInteraction } from "../targeting/listenForOutsideWalkthroughInteraction.js";
+import { useWalkthroughTargetRect, } from "../targeting/useWalkthroughTargetRect.js";
+import { WalkthroughCoach } from "./WalkthroughCoach.js";
+import { WalkthroughHighlight } from "./WalkthroughHighlight.js";
+import { useWalkthroughCoachPosition } from "./useWalkthroughCoachPosition.js";
+export function WalkthroughOverlay() {
+    const walkthrough = useWalkthrough();
+    if (walkthrough.progress?.status !== "active" ||
+        !walkthrough.selectedWalkthrough ||
+        !walkthrough.currentStep) {
+        return null;
+    }
+    return (_jsx(WalkthroughStepOverlay, { advance: walkthrough.advance, currentHref: walkthrough.currentHref, flowTitle: walkthrough.selectedWalkthrough.title, goBack: walkthrough.goBack, navigateToCurrentStep: walkthrough.navigateToCurrentStep, pause: walkthrough.pauseWalkthrough, step: walkthrough.currentStep, stepCount: walkthrough.selectedWalkthrough.steps.length, stepIndex: walkthrough.progress.stepIndex }, `${walkthrough.selectedWalkthrough.id}:${walkthrough.currentStep.id}`));
+}
+function WalkthroughStepOverlay({ advance, currentHref, flowTitle, goBack, navigateToCurrentStep, pause, step, stepCount, stepIndex, }) {
+    const onStepRoute = walkthroughHrefMatches(currentHref, step.href);
+    const targetObservation = useWalkthroughTargetRect(onStepRoute ? step.target : null);
+    const restoreObservation = useWalkthroughTargetRect(onStepRoute && targetObservation.status === "missing" ? (step.restoreTarget ?? null) : null);
+    const advanceRef = useLatestValue(advance);
+    const onStepRouteRef = useLatestValue(onStepRoute);
+    const coachRef = useRef(null);
+    const coachState = resolveCoachState(onStepRoute, Boolean(step.restoreTarget), targetObservation, restoreObservation);
+    const observation = coachState === "restore" ? restoreObservation : targetObservation;
+    const coachPosition = useWalkthroughCoachPosition(observation, coachRef);
+    useEffect(() => listenForStepCompletion(step, () => onStepRouteRef.current, () => advanceRef.current()), [advanceRef, onStepRouteRef, step]);
+    useEffect(() => listenForOutsideInteractionOnStepRoute(onStepRoute, step, pause), [onStepRoute, pause, step]);
+    const rect = observation.status === "found" && onStepRoute ? observation.rect : null;
+    return createPortal(_jsxs("div", { "aria-live": "polite", className: "pointer-events-none fixed inset-0 z-[100]", children: [rect ? _jsx(WalkthroughHighlight, { rect: rect, stepNumber: stepIndex + 1 }) : null, _jsx("div", { className: "pointer-events-auto absolute w-[min(24rem,calc(100%-2rem))]", "data-walkthrough-coach": "", ref: coachRef, style: coachPosition && rect
+                    ? { left: coachPosition.left, top: coachPosition.top }
+                    : { bottom: 16, right: 16 }, children: _jsx(WalkthroughCoach, { advanceType: step.advance.type, coachState: coachState, flowTitle: flowTitle, onBack: goBack, onNext: advance, onPause: pause, onReturn: navigateToCurrentStep, step: step, stepCount: stepCount, stepIndex: stepIndex }) })] }), document.body);
+}
+function listenForOutsideInteractionOnStepRoute(onStepRoute, step, pause) {
+    return onStepRoute ? listenForOutsideWalkthroughInteraction(step, pause) : undefined;
+}
+function useLatestValue(value) {
+    const valueRef = useRef(value);
+    useLayoutEffect(() => {
+        valueRef.current = value;
+    }, [value]);
+    return valueRef;
+}
+function listenForStepCompletion(step, canComplete, advance) {
+    if (step.advance.type === "manual")
+        return () => undefined;
+    if (step.advance.type === "target-click") {
+        return listenForWalkthroughTargetClick(step.target, canComplete, advance);
+    }
+    return listenForWalkthroughEvent(step.advance.event, canComplete, advance);
+}
+function resolveCoachState(onStepRoute, canRestore, targetObservation, restoreObservation) {
+    if (!onStepRoute)
+        return "off-route";
+    if (targetObservation.status === "locating")
+        return "locating";
+    if (targetObservation.status === "found")
+        return "ready";
+    if (!canRestore)
+        return "missing";
+    if (restoreObservation.status === "found")
+        return "restore";
+    if (restoreObservation.status === "locating")
+        return "locating";
+    return "missing";
+}

package/dist/components/walkthrough/presentation/positionWalkthroughCoach.d.ts

@@ -0,0 +1,11 @@
+import type { WalkthroughTargetRect } from "../targeting/useWalkthroughTargetRect.js";
+export type WalkthroughCoachPosition = {
+    left: number;
+    top: number;
+};
+type Size = {
+    height: number;
+    width: number;
+};
+export declare function positionWalkthroughCoach(target: WalkthroughTargetRect, coach: Size, viewport: Size): WalkthroughCoachPosition;
+export {};

package/dist/components/walkthrough/presentation/positionWalkthroughCoach.js

@@ -0,0 +1,24 @@
+const GAP = 16;
+const VIEWPORT_MARGIN = 16;
+export function positionWalkthroughCoach(target, coach, viewport) {
+    const candidates = [
+        { left: target.left + target.width + GAP, top: target.top },
+        { left: target.left - coach.width - GAP, top: target.top },
+        { left: target.left, top: target.top + target.height + GAP },
+        { left: target.left, top: target.top - coach.height - GAP },
+    ];
+    const fitting = candidates.find((candidate) => fits(candidate, coach, viewport));
+    return clamp(fitting ?? candidates[2], coach, viewport);
+}
+function fits(position, coach, viewport) {
+    return (position.left >= VIEWPORT_MARGIN &&
+        position.top >= VIEWPORT_MARGIN &&
+        position.left + coach.width <= viewport.width - VIEWPORT_MARGIN &&
+        position.top + coach.height <= viewport.height - VIEWPORT_MARGIN);
+}
+function clamp(position, coach, viewport) {
+    return {
+        left: Math.max(VIEWPORT_MARGIN, Math.min(position.left, viewport.width - coach.width - VIEWPORT_MARGIN)),
+        top: Math.max(VIEWPORT_MARGIN, Math.min(position.top, viewport.height - coach.height - VIEWPORT_MARGIN)),
+    };
+}

package/dist/components/walkthrough/presentation/useWalkthroughCoachPosition.d.ts

@@ -0,0 +1,4 @@
+import { type RefObject } from "react";
+import { type WalkthroughCoachPosition } from "./positionWalkthroughCoach.js";
+import type { WalkthroughTargetObservation } from "../targeting/useWalkthroughTargetRect.js";
+export declare function useWalkthroughCoachPosition(observation: WalkthroughTargetObservation, coachRef: RefObject<HTMLDivElement | null>): WalkthroughCoachPosition | null;

package/dist/components/walkthrough/presentation/useWalkthroughCoachPosition.js

@@ -0,0 +1,17 @@
+import { useLayoutEffect, useState } from "react";
+import { positionWalkthroughCoach } from "./positionWalkthroughCoach.js";
+const FALLBACK_COACH_SIZE = { height: 232, width: 384 };
+export function useWalkthroughCoachPosition(observation, coachRef) {
+    const [position, setPosition] = useState(null);
+    useLayoutEffect(() => {
+        if (observation.status !== "found")
+            return;
+        const box = coachRef.current?.getBoundingClientRect();
+        const coach = box ? { height: box.height, width: box.width } : FALLBACK_COACH_SIZE;
+        setPosition(positionWalkthroughCoach(observation.rect, coach, {
+            height: window.innerHeight,
+            width: window.innerWidth,
+        }));
+    }, [coachRef, observation]);
+    return position;
+}

package/dist/components/walkthrough/runtime/WalkthroughContextDefinition.d.ts

@@ -0,0 +1,20 @@
+import type { WalkthroughDefinition, WalkthroughProgress, WalkthroughStep } from "./walkthroughTypes.js";
+export type WalkthroughContextValue = {
+    advance: () => void;
+    clearWalkthrough: () => void;
+    currentHref: string;
+    currentStep: WalkthroughStep | null;
+    emitEvent: (event: string) => void;
+    goBack: () => void;
+    navigateToCurrentStep: () => void;
+    pauseWalkthrough: () => void;
+    progress: WalkthroughProgress | null;
+    resumeWalkthrough: () => void;
+    selectedWalkthrough: WalkthroughDefinition | null;
+    startWalkthrough: (walkthroughId: string) => Promise<void>;
+    targetProps: (target: string) => {
+        "data-walkthrough-target": string;
+    };
+    walkthroughs: readonly WalkthroughDefinition[];
+};
+export declare const WalkthroughContext: import("@types/react").Context<WalkthroughContextValue | undefined>;

package/dist/components/walkthrough/runtime/WalkthroughContextDefinition.js

@@ -0,0 +1,2 @@
+import { createContext } from "react";
+export const WalkthroughContext = createContext(undefined);

package/dist/components/walkthrough/runtime/WalkthroughProvider.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+import type { WalkthroughDefinition, WalkthroughFreshStartHandlers } from "./walkthroughTypes.js";
+export type WalkthroughProviderProps = {
+    children: ReactNode;
+    currentHref: string;
+    freshStartHandlers: WalkthroughFreshStartHandlers;
+    navigate: (href: string) => unknown;
+    readCurrentHref: () => string;
+    storageKey: string;
+    walkthroughs: readonly WalkthroughDefinition[];
+};
+export declare function WalkthroughProvider({ children, currentHref, freshStartHandlers, navigate, readCurrentHref, storageKey, walkthroughs, }: WalkthroughProviderProps): import("@types/react").JSX.Element;

package/dist/components/walkthrough/runtime/WalkthroughProvider.js

@@ -0,0 +1,190 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { WalkthroughContext } from "./WalkthroughContextDefinition.js";
+import { emitWalkthroughEvent } from "./walkthroughEvents.js";
+import { walkthroughHrefForNavigation, walkthroughHrefMatches } from "./walkthroughLocation.js";
+import { readWalkthroughProgress, writeWalkthroughProgress } from "./walkthroughStorage.js";
+import { WalkthroughOverlay } from "../presentation/WalkthroughOverlay.js";
+import { walkthroughTargetProps } from "../targeting/walkthroughTarget.js";
+export function WalkthroughProvider({ children, currentHref, freshStartHandlers, navigate, readCurrentHref, storageKey, walkthroughs, }) {
+    const startRequests = useMemo(() => createWalkthroughStartRequests(), []);
+    const [progress, setProgress] = useState(() => readInitialProgress(storageKey, walkthroughs));
+    useEffect(() => () => startRequests.cancel(), [startRequests]);
+    useEffect(() => {
+        writeWalkthroughProgress(storageKey, progress);
+    }, [progress, storageKey]);
+    const selectedWalkthrough = walkthroughById(walkthroughs, progress?.walkthroughId);
+    const currentStep = selectedWalkthrough
+        ? stepAt(selectedWalkthrough, progress?.stepIndex ?? -1)
+        : null;
+    const controller = useMemo(() => ({
+        freshStartHandlers,
+        navigate,
+        progress,
+        readCurrentHref,
+        selectedWalkthrough,
+        setProgress,
+        startRequests,
+        walkthroughs,
+    }), [
+        freshStartHandlers,
+        navigate,
+        progress,
+        readCurrentHref,
+        selectedWalkthrough,
+        startRequests,
+        walkthroughs,
+    ]);
+    const value = useMemo(() => buildContextValue(controller, currentHref, currentStep), [controller, currentHref, currentStep]);
+    return (_jsxs(WalkthroughContext.Provider, { value: value, children: [children, _jsx(WalkthroughOverlay, {})] }));
+}
+function buildContextValue(controller, currentHref, currentStep) {
+    return {
+        advance: () => {
+            advanceWalkthrough(controller);
+        },
+        clearWalkthrough: () => {
+            controller.startRequests.cancel();
+            controller.setProgress(null);
+        },
+        currentHref,
+        currentStep,
+        emitEvent: emitWalkthroughEvent,
+        goBack: () => {
+            goBack(controller);
+        },
+        navigateToCurrentStep: () => {
+            navigateToCurrentStep(controller);
+        },
+        pauseWalkthrough: () => {
+            pauseWalkthrough(controller);
+        },
+        progress: controller.progress,
+        resumeWalkthrough: () => {
+            resumeWalkthrough(controller);
+        },
+        selectedWalkthrough: controller.selectedWalkthrough,
+        startWalkthrough: (walkthroughId) => startWalkthrough(controller, walkthroughId),
+        targetProps: walkthroughTargetProps,
+        walkthroughs: controller.walkthroughs,
+    };
+}
+async function startWalkthrough(controller, walkthroughId) {
+    const walkthrough = walkthroughById(controller.walkthroughs, walkthroughId);
+    if (!walkthrough)
+        throw new Error(`Unknown walkthrough: ${walkthroughId}`);
+    if (walkthrough.steps.length === 0)
+        throw new Error(`Walkthrough has no steps: ${walkthroughId}`);
+    const freshStart = walkthrough.freshStart
+        ? controller.freshStartHandlers[walkthrough.freshStart]
+        : null;
+    if (walkthrough.freshStart && !freshStart) {
+        throw new Error(`Missing fresh-start handler: ${walkthrough.freshStart}`);
+    }
+    const startRequest = controller.startRequests.begin();
+    controller.setProgress(null);
+    if (freshStart) {
+        try {
+            await freshStart();
+        }
+        catch (error) {
+            controller.startRequests.finishIfLatest(startRequest);
+            throw error;
+        }
+    }
+    if (!controller.startRequests.finishIfLatest(startRequest))
+        return;
+    controller.setProgress({
+        status: "active",
+        stepIndex: 0,
+        version: walkthrough.version,
+        walkthroughId,
+    });
+    navigateToStep(controller, walkthrough, 0);
+}
+function createWalkthroughStartRequests() {
+    let latestRequest = null;
+    return {
+        begin: () => {
+            const request = {};
+            latestRequest = request;
+            return request;
+        },
+        cancel: () => {
+            latestRequest = null;
+        },
+        finishIfLatest: (request) => {
+            if (latestRequest !== request)
+                return false;
+            latestRequest = null;
+            return true;
+        },
+    };
+}
+function advanceWalkthrough(controller) {
+    const { progress, selectedWalkthrough } = controller;
+    if (!progress || progress.status !== "active" || !selectedWalkthrough)
+        return;
+    const nextStepIndex = progress.stepIndex + 1;
+    if (nextStepIndex >= selectedWalkthrough.steps.length) {
+        controller.setProgress({ ...progress, status: "completed" });
+        return;
+    }
+    controller.setProgress({ ...progress, stepIndex: nextStepIndex });
+    navigateToStep(controller, selectedWalkthrough, nextStepIndex);
+}
+function goBack(controller) {
+    const { progress, selectedWalkthrough } = controller;
+    if (!progress || progress.status !== "active" || !selectedWalkthrough)
+        return;
+    const previousStepIndex = progress.stepIndex - 1;
+    if (previousStepIndex < 0)
+        return;
+    controller.setProgress({ ...progress, stepIndex: previousStepIndex });
+    navigateToStep(controller, selectedWalkthrough, previousStepIndex);
+}
+function pauseWalkthrough(controller) {
+    const { progress } = controller;
+    if (progress?.status === "active") {
+        controller.setProgress({ ...progress, status: "paused" });
+    }
+}
+function resumeWalkthrough(controller) {
+    const { progress, selectedWalkthrough } = controller;
+    if (progress?.status !== "paused" || !selectedWalkthrough)
+        return;
+    controller.setProgress({ ...progress, status: "active" });
+    navigateToStep(controller, selectedWalkthrough, progress.stepIndex);
+}
+function navigateToCurrentStep(controller) {
+    if (!controller.progress || !controller.selectedWalkthrough)
+        return;
+    navigateToStep(controller, controller.selectedWalkthrough, controller.progress.stepIndex);
+}
+function navigateToStep(controller, walkthrough, stepIndex) {
+    const step = stepAt(walkthrough, stepIndex);
+    const currentHref = controller.readCurrentHref();
+    if (step && !walkthroughHrefMatches(currentHref, step.href)) {
+        controller.navigate(walkthroughHrefForNavigation(currentHref, step.href));
+    }
+}
+function stepAt(walkthrough, stepIndex) {
+    return walkthrough.steps.find((_step, index) => index === stepIndex) ?? null;
+}
+function readInitialProgress(storageKey, walkthroughs) {
+    const stored = readWalkthroughProgress(storageKey);
+    if (!stored)
+        return null;
+    const walkthrough = walkthroughById(walkthroughs, stored.walkthroughId);
+    if (!walkthrough ||
+        walkthrough.version !== stored.version ||
+        stored.stepIndex >= walkthrough.steps.length) {
+        return null;
+    }
+    return stored.status === "active" ? { ...stored, status: "paused" } : stored;
+}
+function walkthroughById(walkthroughs, walkthroughId) {
+    if (!walkthroughId)
+        return null;
+    return walkthroughs.find((walkthrough) => walkthrough.id === walkthroughId) ?? null;
+}

package/dist/components/walkthrough/runtime/useWalkthrough.d.ts

@@ -0,0 +1 @@
+export declare function useWalkthrough(): import("./WalkthroughContextDefinition.js").WalkthroughContextValue;

package/dist/components/walkthrough/runtime/useWalkthrough.js

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+import { WalkthroughContext } from "./WalkthroughContextDefinition.js";
+export function useWalkthrough() {
+    const context = useContext(WalkthroughContext);
+    if (!context)
+        throw new Error("useWalkthrough must be used within WalkthroughProvider");
+    return context;
+}

package/dist/components/walkthrough/runtime/walkthroughEvents.d.ts

@@ -0,0 +1,3 @@
+export declare function emitWalkthroughEvent(event: string): void;
+export declare function listenForWalkthroughEvent(event: string, canComplete: () => boolean, onComplete: () => void): () => void;
+export declare function listenForWalkthroughTargetClick(target: string, canComplete: () => boolean, onComplete: () => void): () => void;

package/dist/components/walkthrough/runtime/walkthroughEvents.js

@@ -0,0 +1,55 @@
+import { isEnabledWalkthroughTarget, WALKTHROUGH_TARGET_ATTRIBUTE, } from "../targeting/walkthroughTarget.js";
+const WALKTHROUGH_EVENT_PREFIX = "ciridae:walkthrough:";
+export function emitWalkthroughEvent(event) {
+    window.dispatchEvent(new Event(walkthroughEventType(event)));
+}
+export function listenForWalkthroughEvent(event, canComplete, onComplete) {
+    const eventType = walkthroughEventType(event);
+    const eventListener = () => {
+        if (canComplete())
+            onComplete();
+    };
+    window.addEventListener(eventType, eventListener);
+    return () => {
+        window.removeEventListener(eventType, eventListener);
+    };
+}
+export function listenForWalkthroughTargetClick(target, canComplete, onComplete) {
+    let completionScheduled = false;
+    let completed = false;
+    const clickListener = (event) => {
+        if (completionScheduled || completed)
+            return;
+        if (!enabledTargetForEvent(event, target))
+            return;
+        if (!canComplete())
+            return;
+        completionScheduled = true;
+        queueMicrotask(() => {
+            completionScheduled = false;
+            if (completed)
+                return;
+            completed = true;
+            onComplete();
+        });
+    };
+    document.addEventListener("click", clickListener, true);
+    return () => {
+        document.removeEventListener("click", clickListener, true);
+    };
+}
+function enabledTargetForEvent(event, target) {
+    const element = event.target;
+    if (!(element instanceof Element))
+        return null;
+    const targetElement = element.closest(`[${WALKTHROUGH_TARGET_ATTRIBUTE}]`);
+    if (targetElement?.getAttribute(WALKTHROUGH_TARGET_ATTRIBUTE) !== target)
+        return null;
+    if (!isEnabledWalkthroughTarget(targetElement))
+        return null;
+    const disabledControl = element.closest(":disabled, [aria-disabled='true']");
+    return disabledControl && targetElement.contains(disabledControl) ? null : targetElement;
+}
+function walkthroughEventType(event) {
+    return `${WALKTHROUGH_EVENT_PREFIX}${event}`;
+}

package/dist/components/walkthrough/runtime/walkthroughLocation.d.ts

@@ -0,0 +1,2 @@
+export declare function walkthroughHrefMatches(currentHref: string, stepHref: string): boolean;
+export declare function walkthroughHrefForNavigation(currentHref: string, stepHref: string): string;

package/dist/components/walkthrough/runtime/walkthroughLocation.js

@@ -0,0 +1,27 @@
+export function walkthroughHrefMatches(currentHref, stepHref) {
+    const current = new URL(currentHref, window.location.origin);
+    const step = new URL(stepHref, window.location.origin);
+    if (normalizePathname(current.pathname) !== normalizePathname(step.pathname))
+        return false;
+    if (step.hash && current.hash !== step.hash)
+        return false;
+    for (const [key, value] of step.searchParams) {
+        if (current.searchParams.get(key) !== value)
+            return false;
+    }
+    return true;
+}
+export function walkthroughHrefForNavigation(currentHref, stepHref) {
+    const current = new URL(currentHref, window.location.origin);
+    const step = new URL(stepHref, window.location.origin);
+    if (normalizePathname(current.pathname) !== normalizePathname(step.pathname))
+        return stepHref;
+    for (const [key, value] of step.searchParams)
+        current.searchParams.set(key, value);
+    if (step.hash)
+        current.hash = step.hash;
+    return `${current.pathname}${current.search}${current.hash}`;
+}
+function normalizePathname(pathname) {
+    return pathname.length > 1 ? pathname.replace(/\/$/, "") : pathname;
+}

package/dist/components/walkthrough/runtime/walkthroughStorage.d.ts

@@ -0,0 +1,3 @@
+import type { WalkthroughProgress } from "./walkthroughTypes.js";
+export declare function readWalkthroughProgress(storageKey: string): WalkthroughProgress | null;
+export declare function writeWalkthroughProgress(storageKey: string, progress: WalkthroughProgress | null): void;

package/dist/components/walkthrough/runtime/walkthroughStorage.js

@@ -0,0 +1,54 @@
+import { readStoredValue, removeStoredValue, writeStoredValue } from "../../../lib/browser-storage.js";
+export function readWalkthroughProgress(storageKey) {
+    const raw = readStoredValue(storageKey);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return isWalkthroughProgress(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeWalkthroughProgress(storageKey, progress) {
+    if (!progress) {
+        removeStoredValue(storageKey);
+        return;
+    }
+    writeStoredValue(storageKey, JSON.stringify(progress));
+}
+function isWalkthroughProgress(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    if (!hasWalkthroughProgressFields(value))
+        return false;
+    if (!isWalkthroughStatus(value.status))
+        return false;
+    if (!isNonnegativeInteger(value.stepIndex))
+        return false;
+    if (!isPositiveInteger(value.version))
+        return false;
+    return isNonemptyString(value.walkthroughId);
+}
+function isWalkthroughStatus(value) {
+    return value === "active" || value === "completed" || value === "paused";
+}
+function hasWalkthroughProgressFields(value) {
+    if (!("status" in value))
+        return false;
+    if (!("stepIndex" in value))
+        return false;
+    if (!("version" in value))
+        return false;
+    return "walkthroughId" in value;
+}
+function isNonnegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonemptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}

package/dist/components/walkthrough/runtime/walkthroughTypes.d.ts

@@ -0,0 +1,32 @@
+export type WalkthroughAdvance = {
+    type: "manual";
+} | {
+    type: "target-click";
+} | {
+    event: string;
+    type: "event";
+};
+export type WalkthroughStep = {
+    advance: WalkthroughAdvance;
+    body: string;
+    href: string;
+    id: string;
+    restoreTarget?: string;
+    target: string;
+    title: string;
+};
+export type WalkthroughDefinition = {
+    description: string;
+    freshStart?: string;
+    id: string;
+    steps: readonly WalkthroughStep[];
+    title: string;
+    version: number;
+};
+export type WalkthroughProgress = {
+    status: "active" | "completed" | "paused";
+    stepIndex: number;
+    version: number;
+    walkthroughId: string;
+};
+export type WalkthroughFreshStartHandlers = Readonly<Partial<Record<string, () => Promise<unknown>>>>;

package/dist/components/walkthrough/runtime/walkthroughTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/components/walkthrough/targeting/listenForOutsideWalkthroughInteraction.d.ts

@@ -0,0 +1,2 @@
+import type { WalkthroughStep } from "../runtime/walkthroughTypes.js";
+export declare function listenForOutsideWalkthroughInteraction(step: WalkthroughStep, pause: () => void): () => void;