@robertlinde/react-tour-kit 0.8.9 → 1.0.1

package/dist/shared/renderer/tour-overlay.js

@@ -0,0 +1,228 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isValidElement, useCallback, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { tourLayout, } from '../engine/tour-engine.js';
+import { containsPoint, inflate } from '../geometry/box.util.js';
+import { useTourView } from '../react/use-tour-view.hook.js';
+import { formatTemplate } from '../utils/i18n.util.js';
+import { entranceFor, fadeDuration, motion } from './motion.js';
+import { RendererContext, TooltipLimitsContext } from './renderer-context.js';
+function noop() {
+    // Intentionally empty.
+}
+/**
+ * The tour on screen, for every platform: decides what is visible, how it animates, what it
+ * says and what input means, and draws it with the platform's primitives ({@link TourRenderer}).
+ * Keeps the last step on screen while the tour fades out.
+ */
+export function TourOverlay(props) {
+    const view = useTourView(props.engine);
+    // When the tour ends, the last view stays on screen while it fades out. Worked out during render
+    // (not in an effect), so the overlay is never unmounted in between and the fade really plays.
+    const [tracked, setTracked] = useState(() => ({
+        view,
+        closing: undefined,
+    }));
+    let { closing } = tracked;
+    if (tracked.view !== view) {
+        const before = tracked.view;
+        closing = view.phase === 'idle' ? (before.phase === 'idle' ? closing : before) : undefined;
+        setTracked({ view, closing });
+    }
+    const onClosed = useCallback(() => {
+        setTracked((current) => ({ ...current, closing: undefined }));
+    }, []);
+    const isClosing = view.phase === 'idle' && closing !== undefined;
+    const rendered = view.phase === 'idle' ? closing : view;
+    return rendered ? _jsx(OverlayContent, { ...props, view: rendered, isClosing: isClosing, onClosed: onClosed }) : null;
+}
+function OverlayContent({ engine, renderer, theme, i18n, Tooltip, isOverlayDismissible, isReducedMotion, view, isClosing, onClosed, }) {
+    const { Layer, Backdrop, Spotlight } = renderer;
+    const id = useId();
+    const titleId = `${id}title`;
+    const descriptionId = `${id}description`;
+    const { shown, phase, measure } = view;
+    const totalSteps = view.steps.length;
+    // The first step can take a while (navigation in onBeforeStep): dim the screen after a moment.
+    const isWaitingDimmed = useDelayedFlag(!shown && !isClosing, motion.waitingDimDelayMs);
+    // Once on screen, the overlay stays until the tour ends (also when another tour takes over).
+    const [hasBeenVisible, setHasBeenVisible] = useState(false);
+    const isShowingSomething = shown !== undefined || isWaitingDimmed;
+    if (isShowingSomething && !isClosing && !hasBeenVisible) {
+        setHasBeenVisible(true);
+    }
+    const isVisible = !isClosing && (isShowingSomething || hasBeenVisible);
+    // When the overlay became visible: presses on the dimmed area only count once it has faded in.
+    const visibleSince = useRef(undefined);
+    useEffect(() => {
+        visibleSince.current = isVisible ? Date.now() : undefined;
+    }, [isVisible]);
+    const spotlight = useSpotlight(view, isVisible, isReducedMotion);
+    const announcement = useAnnouncement(shown, totalSteps, i18n, isClosing);
+    // Fade out, then unmount.
+    useEffect(() => {
+        if (!isClosing) {
+            return undefined;
+        }
+        const timer = setTimeout(onClosed, fadeDuration(true, isReducedMotion) + 20);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [isClosing, isReducedMotion, onClosed]);
+    const onIntent = useCallback((intent) => {
+        if (isClosing) {
+            return;
+        }
+        switch (intent) {
+            case 'next': {
+                engine.actions.nextStep();
+                break;
+            }
+            case 'previous': {
+                engine.actions.prevStep();
+                break;
+            }
+            case 'escape': {
+                engine.dismiss('escape');
+                break;
+            }
+            case 'back': {
+                engine.dismiss('closed');
+                break;
+            }
+        }
+    }, [engine, isClosing]);
+    const onBackdropPress = (point) => {
+        // Not while the overlay is still appearing (a double click on the button that started the
+        // tour), nor while a step change is under way (a second tap on Next falls through the busy tooltip).
+        const since = visibleSince.current;
+        const hasFadedIn = since !== undefined && Date.now() - since >= motion.fadeInMs;
+        const isChangingStep = shown !== undefined && phase !== 'showing';
+        if (!isOverlayDismissible || isClosing || !hasFadedIn || isChangingStep) {
+            return;
+        }
+        // Presses on the highlighted element go nowhere; presses on the dimmed area close the tour.
+        if (spotlight.hole === undefined || !containsPoint(spotlight.hole, point)) {
+            engine.dismiss('blur');
+        }
+    };
+    const context = useMemo(() => ({ renderer, theme, i18n }), [renderer, theme, i18n]);
+    const counter = shown
+        ? formatTemplate(i18n.stepCounterTemplate, { current: shown.stepIndex + 1, total: totalSteps })
+        : '';
+    return (_jsx(RendererContext.Provider, { value: context, children: _jsxs(Layer, { state: isClosing ? 'closing' : phase, isVisible: isVisible, fadeMs: fadeDuration(isClosing, isReducedMotion), isInteractive: !isClosing, theme: theme, titleId: shown ? titleId : undefined, descriptionId: shown ? descriptionId : undefined, fallbackLabel: (shown ? textOf(shown.step.title) : '') || counter, announcement: announcement, stepKey: shown?.transitionId, onIntent: onIntent, children: [_jsx(Backdrop, { isDismissible: isOverlayDismissible, onPress: onBackdropPress }), _jsx(Spotlight, { hole: spotlight.hole, transition: spotlight.transition, theme: theme }), shown ? (_jsx(ShownTooltip, { engine: engine, renderer: renderer, Tooltip: Tooltip, shown: shown, totalSteps: totalSteps, isBusy: phase === 'preparing' && !isClosing, isHidden: phase === 'revealing', isDelayed: spotlight.isMorphing, isReducedMotion: isReducedMotion, titleId: titleId, descriptionId: descriptionId, onIntent: onIntent }, shown.transitionId)) : null, measure && !isClosing ? (_jsx(MeasuredTooltip, { engine: engine, renderer: renderer, Tooltip: Tooltip, request: measure, totalSteps: totalSteps }, measure.id)) : null] }) }));
+}
+/** The step on screen: its tooltip in the platform's frame. Mounted once per shown step. */
+function ShownTooltip({ engine, renderer, Tooltip, shown, totalSteps, isBusy, isHidden, isDelayed, isReducedMotion, titleId, descriptionId, onIntent, }) {
+    const { TooltipFrame } = renderer;
+    const { transitionId, layout } = shown;
+    const onSize = useCallback((size) => {
+        engine.reportTooltipSize(transitionId, size);
+    }, [engine, transitionId]);
+    const onClose = useCallback(() => {
+        engine.dismiss('closed');
+    }, [engine]);
+    // The entrance is played once, when the step appears.
+    const [entrance] = useState(() => entranceFor(layout.placement, { isDelayed, isReducedMotion }));
+    return (_jsx(TooltipFrame, { layout: layout, entrance: entrance, isBusy: isBusy, isHidden: isHidden, onSize: onSize, onIntent: onIntent, children: _jsx(TooltipLimitsContext.Provider, { value: layout, children: _jsx(Tooltip, { step: shown.step, currentStep: shown.stepIndex, totalSteps: totalSteps, placement: layout.placement, arrowOffset: layout.arrowOffset, titleId: titleId, descriptionId: descriptionId, onNext: engine.actions.nextStep, onPrev: engine.actions.prevStep, onClose: onClose, onGoToStep: engine.actions.goToStep }) }) }));
+}
+/** The next step's tooltip, rendered invisibly with the same limits to learn its size: same content, no actions. */
+function MeasuredTooltip({ engine, renderer, Tooltip, request, totalSteps }) {
+    const { MeasureFrame } = renderer;
+    const id = useId();
+    const onSize = useCallback((size) => {
+        engine.reportTooltipSize(request.id, size);
+    }, [engine, request.id]);
+    return (_jsx(MeasureFrame, { maxWidth: request.maxWidth, maxHeight: request.maxHeight, onSize: onSize, children: _jsx(TooltipLimitsContext.Provider, { value: request, children: _jsx(Tooltip, { step: request.step, currentStep: request.stepIndex, totalSteps: totalSteps, placement: request.step.target === undefined ? 'center' : (request.step.placement ?? 'bottom'), arrowOffset: undefined, titleId: `${id}title`, descriptionId: `${id}description`, onNext: noop, onPrev: noop, onClose: noop, onGoToStep: noop }) }) }));
+}
+/** True once `isWaiting` has been true for `delayMs`, as long as it stays true. */
+function useDelayedFlag(isWaiting, delayMs) {
+    const [isDue, setIsDue] = useState(false);
+    const [wasWaiting, setWasWaiting] = useState(isWaiting);
+    if (wasWaiting !== isWaiting) {
+        setWasWaiting(isWaiting);
+        setIsDue(false);
+    }
+    useEffect(() => {
+        if (!isWaiting) {
+            return undefined;
+        }
+        const timer = setTimeout(() => {
+            setIsDue(true);
+        }, delayMs);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [isWaiting, delayMs]);
+    return isWaiting && isDue;
+}
+/**
+ * Where the spotlight's hole is and how it gets there. While the next target is scrolled into
+ * view, the hole goes with it (frame by frame, or straight to where it will end up); otherwise it
+ * marks the step on screen. Moving to another step is animated; following a target that moves on
+ * its own (layout changes, resizing) is instant. Nothing animates before the overlay has appeared.
+ */
+function useSpotlight(view, isVisible, isReducedMotion) {
+    const { shown, phase, revealHighlight, followsScroll } = view;
+    const isRevealing = phase === 'revealing';
+    const source = isRevealing ? revealHighlight : shown?.highlight;
+    const hole = source ? inflate(source, tourLayout.highlightPadding) : undefined;
+    const shownKey = shown?.transitionId ?? 'none';
+    const key = isRevealing ? `reveal:${shownKey}` : `${shownKey}:${hole ? 'open' : 'closed'}`;
+    // The key at which the overlay appeared: it appears in place, later changes animate.
+    const [appearedAtKey, setAppearedAtKey] = useState(undefined);
+    if (isVisible && appearedAtKey === undefined) {
+        setAppearedAtKey(key);
+    }
+    // A move to a new key keeps animating until it has had time to finish.
+    const [settledKey, setSettledKey] = useState(key);
+    useEffect(() => {
+        if (key === settledKey) {
+            return undefined;
+        }
+        const timer = setTimeout(() => {
+            setSettledKey(key);
+        }, motion.morphMs + 50);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [key, settledKey]);
+    const hasAppeared = appearedAtKey !== undefined;
+    const isMorphing = hasAppeared && key !== appearedAtKey && key !== settledKey;
+    let transition;
+    if (hasAppeared && !isReducedMotion) {
+        if (isRevealing && followsScroll) {
+            transition = { durationMs: motion.chaseMs, easing: 'linear' };
+        }
+        else if (isMorphing) {
+            transition = { durationMs: motion.morphMs, easing: 'standard' };
+        }
+    }
+    return { hole, transition, isMorphing };
+}
+/** "2 of 5: Title" when the step changes (the first step is announced by the tour appearing). */
+function useAnnouncement(shown, totalSteps, i18n, isClosing) {
+    const [firstKey, setFirstKey] = useState(undefined);
+    if (shown && firstKey === undefined) {
+        setFirstKey(shown.transitionId);
+    }
+    if (!shown || isClosing || shown.transitionId === firstKey) {
+        return '';
+    }
+    const counter = formatTemplate(i18n.stepCounterTemplate, { current: shown.stepIndex + 1, total: totalSteps });
+    const title = textOf(shown.step.title);
+    return title ? `${counter}: ${title}` : counter;
+}
+/** The plain text of React content (strings, numbers, arrays and the children of elements). */
+export function textOf(node) {
+    if (typeof node === 'string' || typeof node === 'number') {
+        return String(node);
+    }
+    if (Array.isArray(node)) {
+        return node.map((child) => textOf(child)).join('');
+    }
+    if (isValidElement(node)) {
+        return textOf(node.props.children);
+    }
+    return '';
+}
+//# sourceMappingURL=tour-overlay.js.map

package/dist/shared/renderer/tour-overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-overlay.js","sourceRoot":"","sources":["../../../src/shared/renderer/tour-overlay.tsx"],"names":[],"mappings":"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"}

package/dist/shared/types/tour-context.type.d.ts

@@ -1,13 +1,23 @@
-import { type StartTourOptions } from './tour-end-info.type';
-import { type TourStep } from './tour-step.type';
+import type { StartTourOptions } from './tour-end-info.type.js';
+import type { TourStep } from './tour-step.type.js';
+/** What `useTour()` returns. The functions keep their identity for the lifetime of the provider. */
 export type TourContextType = {
-    isActive: boolean;
-    currentStep: number;
-    steps: TourStep[];
-    currentTourId: string | undefined;
-    startTour: (steps: TourStep[], tourId?: string, options?: StartTourOptions) => void;
-    endTour: () => void;
-    nextStep: () => void;
-    prevStep: () => void;
-    goToStep: (step: number) => void;
+    /** `true` from `startTour` until the tour ends. */
+    readonly isActive: boolean;
+    /** Zero-based index of the step on screen. */
+    readonly currentStep: number;
+    readonly steps: readonly TourStep[];
+    readonly currentTourId: string | undefined;
+    /**
+     * Starts a tour. Starting the tour that is already running (same id, or same steps array without
+     * an id) does nothing; starting a different one ends the current tour with the reason `'closed'`.
+     */
+    readonly startTour: (steps: readonly TourStep[], tourId?: string, options?: StartTourOptions) => void;
+    /** Ends the tour with the reason `'closed'`. */
+    readonly endTour: () => void;
+    /** Goes to the next step, or completes the tour on the last step. */
+    readonly nextStep: () => void;
+    readonly prevStep: () => void;
+    readonly goToStep: (index: number) => void;
 };
+//# sourceMappingURL=tour-context.type.d.ts.map

package/dist/shared/types/tour-context.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-context.type.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tour-context.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAElD,oGAAoG;AACpG,MAAM,MAAM,eAAe,GAAG;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACtG,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C,CAAC"}

package/dist/shared/types/tour-end-info.type.d.ts

@@ -1,12 +1,29 @@
-import { type TourStep } from './tour-step.type';
-export type TourEndReason = 'completed' | 'closed' | 'blur' | 'escape' | 'target-missing';
+import type { TourStep } from './tour-step.type.js';
+/**
+ * Why a tour ended.
+ * - `completed`: the user finished the last step.
+ * - `closed`: the close button, `endTour()`, the Android back button, or another tour was started.
+ * - `blur`: the user clicked or tapped the dimmed area (see `closeOnOverlayClick`).
+ * - `escape`: Escape on the web, the VoiceOver escape gesture on iOS.
+ * - `target-missing`: no remaining step had a target that could be found and shown.
+ * - `error`: a step's `onBeforeStep` threw or rejected; see {@link TourEndInfo.error}.
+ */
+export type TourEndReason = 'completed' | 'closed' | 'blur' | 'escape' | 'target-missing' | 'error';
+/** Details about how and where a tour ended. */
 export type TourEndInfo = {
     readonly reason: TourEndReason;
+    /** Zero-based index of the step the user was on (for `target-missing`: the last step that was tried). */
     readonly stepIndex: number;
     readonly step: TourStep;
     readonly totalSteps: number;
+    /** The error thrown by `onBeforeStep` when `reason` is `'error'`. */
+    readonly error?: unknown;
 };
+/** Called once when a tour ends. */
 export type TourEndCallback = (tourId: string | undefined, info: TourEndInfo) => void;
+/** Options for a single tour, passed to `startTour`. */
 export type StartTourOptions = {
+    /** Called when this tour ends, before the provider's `onTourEnd`. */
     readonly onTourEnd?: TourEndCallback;
 };
+//# sourceMappingURL=tour-end-info.type.d.ts.map

package/dist/shared/types/tour-end-info.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-end-info.type.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tour-end-info.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAEpG,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,yGAAyG;IACzG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,oCAAoC;AACpC,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;AAEtF,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACtC,CAAC"}

package/dist/shared/types/tour-i18n.type.d.ts

@@ -1,8 +1,16 @@
+/** Texts of the built-in tooltip. Every key is optional. */
 export type TourI18n = {
+    /** @defaultValue `'Next'` */
     readonly nextLabel?: string;
+    /** @defaultValue `'Back'` */
     readonly prevLabel?: string;
+    /** Label of the Next button on the last step. @defaultValue `'Finish'` */
     readonly finishLabel?: string;
+    /** Step counter; `{current}` and `{total}` are replaced. @defaultValue `'{current} of {total}'` */
     readonly stepCounterTemplate?: string;
+    /** Accessible name of the close button. @defaultValue `'Close tour'` */
     readonly closeAriaLabel?: string;
+    /** Accessible name of each step dot; `{step}` and `{total}` are replaced. @defaultValue `'Go to step {step}'` */
     readonly dotAriaLabelTemplate?: string;
 };
+//# sourceMappingURL=tour-i18n.type.d.ts.map

package/dist/shared/types/tour-i18n.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-i18n.type.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tour-i18n.type.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,MAAM,MAAM,QAAQ,GAAG;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mGAAmG;IACnG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iHAAiH;IACjH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC,CAAC"}

package/dist/shared/types/tour-step.type.d.ts

@@ -1,8 +1,37 @@
-import { type TourTarget, type Placement } from './rect.type';
+import type { ReactNode, RefObject } from 'react';
+/**
+ * Preferred side of the target for the tooltip. If there is not enough room on that side, the
+ * tooltip moves to the opposite side, then to the roomier of the remaining sides.
+ */
+export type TourPlacement = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * What a step highlights.
+ * - Web: a CSS selector such as `'[data-tour="settings"]'`, or a ref to a DOM element.
+ * - React Native: an id registered with `useTourTarget`, or a ref to a native view.
+ */
+export type TourTarget = string | RefObject<unknown>;
+/** Second argument of {@link TourStep.onBeforeStep}. */
+export type TourStepContext = {
+    /**
+     * Aborted when the step is abandoned before it is shown (the user navigates elsewhere or the
+     * tour ends). Pass it to `fetch` or check `signal.aborted` in long-running work.
+     */
+    readonly signal: AbortSignal;
+};
 export type TourStep = {
-    target: TourTarget;
-    title: string;
-    content: string;
-    placement?: Placement;
-    onBeforeStep?: (target: TourTarget) => void | Promise<void>;
+    /** The element to highlight. Leave it out for a step that is shown in the centre of the screen. */
+    readonly target?: TourTarget;
+    readonly title: ReactNode;
+    readonly content: ReactNode;
+    /** @defaultValue `'bottom'` */
+    readonly placement?: TourPlacement;
+    /**
+     * Runs before the step is shown, for example to navigate to another page or open a menu.
+     * The tour then waits (up to 5 seconds) for the target to appear, so there is no need to poll.
+     *
+     * Make it idempotent: it runs again if the user comes back to this step.
+     * If it throws or rejects, the tour ends with the reason `'error'`.
+     */
+    readonly onBeforeStep?: (target: TourTarget | undefined, context: TourStepContext) => void | Promise<void>;
 };
+//# sourceMappingURL=tour-step.type.d.ts.map

package/dist/shared/types/tour-step.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-step.type.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tour-step.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AAErD,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,mGAAmG;IACnG,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,EAAE,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5G,CAAC"}

package/dist/shared/types/tour-theme.type.d.ts

@@ -1,9 +1,29 @@
+/** Colours of the built-in tooltip and overlay. Every key is optional. */
 export type TourTheme = {
+    /**
+     * Buttons, the step badge, the active dot and the highlight ring.
+     * @defaultValue `'#2563eb'`
+     */
     readonly primaryColor?: string;
+    /**
+     * Text on `primaryColor` (the Next button and the step badge).
+     * @defaultValue `'#ffffff'`
+     */
+    readonly primaryTextColor?: string;
+    /** @defaultValue `'#ffffff'` */
     readonly tooltipBackground?: string;
+    /** @defaultValue `'#111827'` */
     readonly titleColor?: string;
+    /**
+     * Body text. Muted elements (inactive dots, dividers, the Back button) are derived from it, so a
+     * dark theme only needs a dark `tooltipBackground` and light text colours.
+     * @defaultValue `'#4b5563'`
+     */
     readonly contentColor?: string;
+    /**
+     * The dimmed area around the highlighted element. Include transparency.
+     * @defaultValue `'rgba(0, 0, 0, 0.5)'`
+     */
     readonly overlayColor?: string;
 };
-export declare const defaultTheme: Required<TourTheme>;
-export declare function resolveTheme(theme?: TourTheme): Required<TourTheme>;
+//# sourceMappingURL=tour-theme.type.d.ts.map

package/dist/shared/types/tour-theme.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-theme.type.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tour-theme.type.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG;IACtB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,gCAAgC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,gCAAgC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC"}

package/dist/shared/types/tour-theme.type.js

@@ -1,17 +1,2 @@
-export const defaultTheme = {
-    primaryColor: '#3b82f6',
-    tooltipBackground: '#ffffff',
-    titleColor: '#1f2937',
-    contentColor: '#4b5563',
-    overlayColor: 'rgba(0, 0, 0, 0.5)',
-};
-export function resolveTheme(theme) {
-    if (!theme) {
-        return defaultTheme;
-    }
-    return {
-        ...defaultTheme,
-        ...theme,
-    };
-}
+export {};
 //# sourceMappingURL=tour-theme.type.js.map

package/dist/shared/types/tour-theme.type.js.map

@@ -1 +1 @@
-{"version":3,"file":"tour-theme.type.js","sourceRoot":"","sources":["../../../src/shared/types/tour-theme.type.ts"],"names":[],"mappings":"AAsCA,MAAM,CAAC,MAAM,YAAY,GAAwB;IAC/C,YAAY,EAAE,SAAS;IACvB,iBAAiB,EAAE,SAAS;IAC5B,UAAU,EAAE,SAAS;IACrB,YAAY,EAAE,SAAS;IACvB,YAAY,EAAE,oBAAoB;CACnC,CAAC;AAKF,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,OAAO;QACL,GAAG,YAAY;QACf,GAAG,KAAK;KACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tour-theme.type.js","sourceRoot":"","sources":["../../../src/shared/types/tour-theme.type.ts"],"names":[],"mappings":""}

package/dist/shared/types/tour-tooltip-props.type.d.ts

@@ -1,23 +1,27 @@
-import { type TourI18n } from './tour-i18n.type';
-import { type TourTheme } from './tour-theme.type';
+import type { TourPlacement, TourStep } from './tour-step.type.js';
+/**
+ * Props of a custom `TooltipComponent`. The component only renders the card's content: the tour
+ * measures, positions, animates and focuses it, and keeps it on screen.
+ */
 export type TourTooltipProps = {
-    readonly title: string;
-    readonly content: string;
+    readonly step: TourStep;
+    /** Zero-based index of the step. */
     readonly currentStep: number;
     readonly totalSteps: number;
-    readonly position: {
-        top: number;
-        left: number;
-    };
-    readonly isPositioned: boolean;
-    readonly onClose: () => void;
     readonly onNext: () => void;
     readonly onPrev: () => void;
-    readonly onGoToStep: (step: number) => void;
-    readonly theme: Required<TourTheme>;
-    readonly i18n?: TourI18n;
-    readonly onMeasured?: (size: {
-        width: number;
-        height: number;
-    }) => void;
+    readonly onClose: () => void;
+    readonly onGoToStep: (index: number) => void;
+    /** Side of the target the tooltip ended up on, or `'center'` for steps without a target. Use it to draw an arrow. */
+    readonly placement: TourPlacement | 'center';
+    /**
+     * Distance in pixels from the tooltip's left edge (for `top`/`bottom`) or top edge (for
+     * `left`/`right`) to where an arrow should point. `undefined` when no arrow should be drawn.
+     */
+    readonly arrowOffset: number | undefined;
+    /** Put `id={titleId}` on the element showing the title so screen readers announce it. */
+    readonly titleId: string;
+    /** Put `id={descriptionId}` on the element showing the content. */
+    readonly descriptionId: string;
 };
+//# sourceMappingURL=tour-tooltip-props.type.d.ts.map

package/dist/shared/types/tour-tooltip-props.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-tooltip-props.type.d.ts","sourceRoot":"","sources":["../../../src/shared/types/tour-tooltip-props.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAE,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,qHAAqH;IACrH,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,QAAQ,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC"}

package/dist/shared/utils/frame.util.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Calls `callback` before the next frame is drawn, or after about one frame where there are no
+ * frames (test environments without `requestAnimationFrame`). Returns the cancellation.
+ */
+export declare function requestFrame(callback: () => void): () => void;
+//# sourceMappingURL=frame.util.d.ts.map

package/dist/shared/utils/frame.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.util.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/frame.util.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAc7D"}

package/dist/shared/utils/frame.util.js

@@ -0,0 +1,20 @@
+const frameMs = 16;
+/**
+ * Calls `callback` before the next frame is drawn, or after about one frame where there are no
+ * frames (test environments without `requestAnimationFrame`). Returns the cancellation.
+ */
+export function requestFrame(callback) {
+    if (typeof globalThis.requestAnimationFrame === 'function') {
+        const frame = globalThis.requestAnimationFrame(() => {
+            callback();
+        });
+        return () => {
+            globalThis.cancelAnimationFrame(frame);
+        };
+    }
+    const timer = setTimeout(callback, frameMs);
+    return () => {
+        clearTimeout(timer);
+    };
+}
+//# sourceMappingURL=frame.util.js.map

package/dist/shared/utils/frame.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.util.js","sourceRoot":"","sources":["../../../src/shared/utils/frame.util.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,EAAE,CAAC;AAEnB;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAoB;IAC/C,IAAI,OAAO,UAAU,CAAC,qBAAqB,KAAK,UAAU,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,UAAU,CAAC,qBAAqB,CAAC,GAAG,EAAE;YAClD,QAAQ,EAAE,CAAC;QACb,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE;YACV,UAAU,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,GAAG,EAAE;QACV,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC"}

package/dist/shared/utils/get-truncated-dots.util.d.ts

@@ -1,11 +1,17 @@
-export declare const MAX_VISIBLE_DOTS = 7;
-export declare const DOT_SIZE = 8;
-export declare const DOT_GAP = 6;
-export declare const DOTS_CONTAINER_WIDTH: number;
+/** One item in the step indicator: a dot for a step, or an ellipsis standing in for several steps. */
 export type DotItem = {
-    type: 'dot';
-    index: number;
+    readonly type: 'dot';
+    readonly index: number;
 } | {
-    type: 'ellipsis';
+    readonly type: 'ellipsis';
+    readonly position: 'start' | 'end';
 };
+/**
+ * The step indicator for `totalSteps` steps with `currentStep` (zero-based) selected.
+ *
+ * Up to 7 steps every step gets a dot. Above that the result always has exactly 7 items, so the
+ * indicator keeps a constant width: the first and last step, the current step and its neighbours,
+ * and ellipses for the rest. An ellipsis always stands for at least two steps.
+ */
 export declare function getTruncatedDots(currentStep: number, totalSteps: number): DotItem[];
+//# sourceMappingURL=get-truncated-dots.util.d.ts.map

package/dist/shared/utils/get-truncated-dots.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-truncated-dots.util.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/get-truncated-dots.util.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,MAAM,MAAM,OAAO,GACjB;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAA;CAAC,CAAC;AASnH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,CA2BnF"}