@flanksource/clicky-ui 0.3.17 → 0.3.18

package/dist/overlay/tour-types.d.ts

@@ -0,0 +1,144 @@
+import { ReactNode } from 'react';
+import { Placement } from '@floating-ui/react';
+/**
+ * Public shape of a guided tour. Types only — the runtime lives in tour-model.ts
+ * (pure sequencing), tour-geometry.ts (pure spotlight maths), tour-anchor.ts (the
+ * only DOM lookups) and Tour.tsx / TourProvider.tsx (rendering and state).
+ */
+/**
+ * Where a tour looks up its anchors. `document` is the application case; a
+ * ShadowRoot or a subtree element scopes the tour to an embedded UI — a docs
+ * site rendering the same steps over a mock inside a shadow root, where
+ * `document.querySelector` finds nothing.
+ */
+export type TourRoot = Document | ShadowRoot | HTMLElement;
+/**
+ * A root, or a getter re-invoked while waiting, so a root that mounts late (a
+ * shadow root attached in an effect) resolves inside the same timeout budget
+ * rather than needing a second mechanism.
+ */
+export type TourRootSource = TourRoot | (() => TourRoot | null | undefined);
+/**
+ * How a step names its anchor. A resolver receives the resolved root, so a
+ * consumer can match on things `querySelector` cannot express (visible text, a
+ * ref it already holds) without the library learning about them.
+ */
+export type TourTarget = string | HTMLElement | ((root: TourRoot) => HTMLElement | null | undefined);
+/** What happens when a step's anchor never appears within its wait budget. */
+export type TourMissingAnchor = 
+/** Render the card centred with no spotlight. The step still counts. */
+"center"
+/** Advance past the step as if it were not in the tour. */
+ | "skip"
+/** Throw. For stories and tests, where a broken fixture must fail the build. */
+ | "fail";
+/** Pointer behaviour of the dim layer. */
+export type TourInteraction = 
+/** Dim swallows clicks; the cutout passes them through to the anchor. Default. */
+"allow-anchor"
+/** Nothing under the overlay is clickable, including the anchor. */
+ | "block-all"
+/** The overlay is purely decorative; the whole page stays live. */
+ | "allow-all";
+export type TourDirection = "start" | "next" | "back" | "jump";
+export type TourStepContext = {
+    step: TourStep;
+    /** Zero-based index within the running tour. */
+    index: number;
+    total: number;
+    /** Resolved anchor, or `null` for an anchorless step or one degraded to centred. */
+    anchor: HTMLElement | null;
+    direction: TourDirection;
+};
+export type TourStep = {
+    /** Stable identity: React key, `goTo` target, and the id reported on error. Unique within the tour. */
+    id: string;
+    /** Element the step points at. Omit for a centred, anchorless step (intro/outro). */
+    target?: TourTarget;
+    /** Card heading, and the accessible name of the step dialog. */
+    title: ReactNode;
+    /** Card body. Mutually exclusive with `markdown`. */
+    body?: ReactNode;
+    /** Markdown body, rendered by the lazily loaded `Markdown`. Mutually exclusive with `body`. */
+    markdown?: string;
+    /**
+     * Route this step lives on. When it differs from the route the tour is already
+     * on, `onNavigate` fires before the anchor wait. The tour never waits on a
+     * route change — the anchor appearing is the only completion signal, which is
+     * what lets the same steps run where there is no router at all.
+     */
+    route?: string;
+    /** Preferred card placement around the anchor; flips and shifts to fit. Defaults to `"bottom"`. */
+    placement?: Placement;
+    /** Extra px of spotlight around the anchor's border box. Defaults to the tour's `padding`. */
+    padding?: number;
+    /** Cutout corner radius in px. Defaults to the anchor's own computed radius, grown by the padding. */
+    radius?: number;
+    /** Per-step override of the tour's `missingAnchor` policy. */
+    onMissing?: TourMissingAnchor;
+    /** Per-step override of the tour's anchor wait budget, in ms. */
+    timeoutMs?: number;
+    /**
+     * Shown while the anchor has not appeared, for a step that depends on state the
+     * tour does not own ("open a plan from the tree to continue"). Its presence
+     * also blocks Next, so the operator is never advanced past a stop they have not
+     * reached. Unset means the step is expected to resolve on its own.
+     */
+    hint?: ReactNode;
+    /** Let Next through even while `hint` is showing. */
+    hintOptional?: boolean;
+    /**
+     * Extra classes for this step's card, merged after the tour-level `className`.
+     * The intended use is widening the card for a step whose body needs the room
+     * (e.g. `w-[min(30rem,calc(100vw-2rem))]`) — tailwind-merge resolves the
+     * conflict with the default width.
+     */
+    cardClassName?: string;
+    /** Evaluated on entry in both directions; a `false` result skips the step. For role/feature-gated UI. */
+    enabled?: () => boolean;
+    /** Runs on entry once the anchor resolves — e.g. open a panel the next step needs. */
+    onEnter?: (ctx: TourStepContext) => void | Promise<void>;
+    /** Runs on exit, in either direction. */
+    onExit?: (ctx: TourStepContext) => void;
+};
+export type TourDefinition = {
+    /** Stable identity: the persistence key and the `start(id)` argument. */
+    id: string;
+    /** Human name, for a "Take a tour" menu. */
+    title?: string;
+    /** Bump to invalidate prior completions so a reworked tour runs again. Defaults to `1`. */
+    version?: number;
+    /** Ordered steps. Must be non-empty — an empty tour throws at registration. */
+    steps: TourStep[];
+    /**
+     * Rendered at the foot of every step card. Intended for a link back to the
+     * fuller written guide the tour condenses, so the two surfaces point at each
+     * other rather than competing.
+     */
+    footer?: ReactNode;
+    /** Run automatically for a user who has neither completed nor dismissed it. */
+    autoStart?: boolean;
+    /** Route auto-start is allowed on. Defaults to the first step's `route`. */
+    autoStartRoute?: string;
+};
+export type TourStepErrorInfo = {
+    tourId: string;
+    step: TourStep;
+    index: number;
+    reason: "anchor-timeout" | "anchor-invalid" | "step-error";
+    /** The declared target, stringified for logging. */
+    target: string;
+    error?: unknown;
+};
+export type TourLabels = {
+    back: string;
+    next: string;
+    done: string;
+    skip: string;
+    close: string;
+    /** `current` is 1-based. */
+    counter: (current: number, total: number) => string;
+    /** Announced in the polite live region on every step change. */
+    announce: (current: number, total: number, title: string) => string;
+};
+//# sourceMappingURL=tour-types.d.ts.map

package/dist/overlay/tour-types.d.ts.map

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

package/dist/overlay/use-tour-anchor.cjs

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const tourAnchor = require("./tour-anchor.cjs");
+function prefersReducedMotion(element) {
+  var _a;
+  const view = element.ownerDocument.defaultView;
+  return ((_a = view == null ? void 0 : view.matchMedia) == null ? void 0 : _a.call(view, "(prefers-reduced-motion: reduce)").matches) ?? false;
+}
+function useTourAnchor(options) {
+  const { root, target, timeoutMs, scrollIntoView = true, key } = options;
+  const [result, setResult] = react.useState({ anchor: null, state: "idle" });
+  const scrollRef = react.useRef(scrollIntoView);
+  scrollRef.current = scrollIntoView;
+  react.useEffect(() => {
+    if (target === void 0) {
+      setResult({ anchor: null, state: "idle" });
+      return;
+    }
+    setResult({ anchor: null, state: "waiting" });
+    const controller = new AbortController();
+    void tourAnchor.resolveAnchor({ root, target, timeoutMs, signal: controller.signal }).then(
+      (resolution) => {
+        if (controller.signal.aborted) return;
+        if (resolution.status !== "found") {
+          setResult({ anchor: null, state: "missing" });
+          return;
+        }
+        setResult({ anchor: resolution.element, state: "found" });
+        if (!scrollRef.current || !resolution.element.scrollIntoView) return;
+        resolution.element.scrollIntoView({
+          block: "center",
+          inline: "nearest",
+          behavior: prefersReducedMotion(resolution.element) ? "auto" : "smooth"
+        });
+      }
+    );
+    return () => controller.abort();
+  }, [key, timeoutMs]);
+  return result;
+}
+exports.useTourAnchor = useTourAnchor;
+//# sourceMappingURL=use-tour-anchor.cjs.map

package/dist/overlay/use-tour-anchor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-anchor.cjs","sources":["../../src/overlay/use-tour-anchor.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { resolveAnchor } from \"./tour-anchor\";\nimport type { TourRootSource, TourTarget } from \"./tour-types\";\n\n/**\n * React lifecycle around `resolveAnchor`: one bounded wait per step, aborted when\n * the step changes or the tour unmounts, plus the scroll-into-view that makes the\n * spotlight land somewhere the operator can actually see.\n */\n\nexport type TourAnchorState = \"idle\" | \"waiting\" | \"found\" | \"missing\";\n\nexport type UseTourAnchorOptions = {\n  root: TourRootSource;\n  /** Omit for an anchorless (centred) step; the hook then reports `idle`. */\n  target?: TourTarget | undefined;\n  timeoutMs: number;\n  /** Scroll the anchor into view once it resolves. Defaults to `true`. */\n  scrollIntoView?: boolean | undefined;\n  /** Changes to this restart the wait — pass the step id. */\n  key: string;\n};\n\nexport type UseTourAnchorResult = {\n  anchor: HTMLElement | null;\n  state: TourAnchorState;\n};\n\nfunction prefersReducedMotion(element: HTMLElement): boolean {\n  const view = element.ownerDocument.defaultView;\n  return view?.matchMedia?.(\"(prefers-reduced-motion: reduce)\").matches ?? false;\n}\n\nexport function useTourAnchor(options: UseTourAnchorOptions): UseTourAnchorResult {\n  const { root, target, timeoutMs, scrollIntoView = true, key } = options;\n  const [result, setResult] = useState<UseTourAnchorResult>({ anchor: null, state: \"idle\" });\n  const scrollRef = useRef(scrollIntoView);\n  scrollRef.current = scrollIntoView;\n\n  useEffect(() => {\n    if (target === undefined) {\n      setResult({ anchor: null, state: \"idle\" });\n      return;\n    }\n\n    setResult({ anchor: null, state: \"waiting\" });\n    const controller = new AbortController();\n\n    void resolveAnchor({ root, target, timeoutMs, signal: controller.signal }).then(\n      (resolution) => {\n        if (controller.signal.aborted) return;\n        if (resolution.status !== \"found\") {\n          setResult({ anchor: null, state: \"missing\" });\n          return;\n        }\n        setResult({ anchor: resolution.element, state: \"found\" });\n        if (!scrollRef.current || !resolution.element.scrollIntoView) return;\n        resolution.element.scrollIntoView({\n          block: \"center\",\n          inline: \"nearest\",\n          behavior: prefersReducedMotion(resolution.element) ? \"auto\" : \"smooth\",\n        });\n      },\n    );\n\n    return () => controller.abort();\n    // `root` and `target` are re-created per render by most callers; `key` (the\n    // step id) is the identity that should restart the wait.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [key, timeoutMs]);\n\n  return result;\n}\n"],"names":["useState","useRef","useEffect","resolveAnchor"],"mappings":";;;;AA4BA,SAAS,qBAAqB,SAA+B;;AAC3D,QAAM,OAAO,QAAQ,cAAc;AACnC,WAAO,kCAAM,eAAN,8BAAmB,oCAAoC,YAAW;AAC3E;AAEO,SAAS,cAAc,SAAoD;AAChF,QAAM,EAAE,MAAM,QAAQ,WAAW,iBAAiB,MAAM,QAAQ;AAChE,QAAM,CAAC,QAAQ,SAAS,IAAIA,MAAAA,SAA8B,EAAE,QAAQ,MAAM,OAAO,QAAQ;AACzF,QAAM,YAAYC,MAAAA,OAAO,cAAc;AACvC,YAAU,UAAU;AAEpBC,QAAAA,UAAU,MAAM;AACd,QAAI,WAAW,QAAW;AACxB,gBAAU,EAAE,QAAQ,MAAM,OAAO,QAAQ;AACzC;AAAA,IACF;AAEA,cAAU,EAAE,QAAQ,MAAM,OAAO,WAAW;AAC5C,UAAM,aAAa,IAAI,gBAAA;AAEvB,SAAKC,WAAAA,cAAc,EAAE,MAAM,QAAQ,WAAW,QAAQ,WAAW,OAAA,CAAQ,EAAE;AAAA,MACzE,CAAC,eAAe;AACd,YAAI,WAAW,OAAO,QAAS;AAC/B,YAAI,WAAW,WAAW,SAAS;AACjC,oBAAU,EAAE,QAAQ,MAAM,OAAO,WAAW;AAC5C;AAAA,QACF;AACA,kBAAU,EAAE,QAAQ,WAAW,SAAS,OAAO,SAAS;AACxD,YAAI,CAAC,UAAU,WAAW,CAAC,WAAW,QAAQ,eAAgB;AAC9D,mBAAW,QAAQ,eAAe;AAAA,UAChC,OAAO;AAAA,UACP,QAAQ;AAAA,UACR,UAAU,qBAAqB,WAAW,OAAO,IAAI,SAAS;AAAA,QAAA,CAC/D;AAAA,MACH;AAAA,IAAA;AAGF,WAAO,MAAM,WAAW,MAAA;AAAA,EAI1B,GAAG,CAAC,KAAK,SAAS,CAAC;AAEnB,SAAO;AACT;;"}

package/dist/overlay/use-tour-anchor.d.ts

@@ -0,0 +1,23 @@
+import { TourRootSource, TourTarget } from './tour-types';
+/**
+ * React lifecycle around `resolveAnchor`: one bounded wait per step, aborted when
+ * the step changes or the tour unmounts, plus the scroll-into-view that makes the
+ * spotlight land somewhere the operator can actually see.
+ */
+export type TourAnchorState = "idle" | "waiting" | "found" | "missing";
+export type UseTourAnchorOptions = {
+    root: TourRootSource;
+    /** Omit for an anchorless (centred) step; the hook then reports `idle`. */
+    target?: TourTarget | undefined;
+    timeoutMs: number;
+    /** Scroll the anchor into view once it resolves. Defaults to `true`. */
+    scrollIntoView?: boolean | undefined;
+    /** Changes to this restart the wait — pass the step id. */
+    key: string;
+};
+export type UseTourAnchorResult = {
+    anchor: HTMLElement | null;
+    state: TourAnchorState;
+};
+export declare function useTourAnchor(options: UseTourAnchorOptions): UseTourAnchorResult;
+//# sourceMappingURL=use-tour-anchor.d.ts.map

package/dist/overlay/use-tour-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-anchor.d.ts","sourceRoot":"","sources":["../../src/overlay/use-tour-anchor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;GAIG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAOF,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,mBAAmB,CAuChF"}

package/dist/overlay/use-tour-anchor.js

@@ -0,0 +1,43 @@
+import { useState, useRef, useEffect } from "react";
+import { resolveAnchor } from "./tour-anchor.js";
+function prefersReducedMotion(element) {
+  var _a;
+  const view = element.ownerDocument.defaultView;
+  return ((_a = view == null ? void 0 : view.matchMedia) == null ? void 0 : _a.call(view, "(prefers-reduced-motion: reduce)").matches) ?? false;
+}
+function useTourAnchor(options) {
+  const { root, target, timeoutMs, scrollIntoView = true, key } = options;
+  const [result, setResult] = useState({ anchor: null, state: "idle" });
+  const scrollRef = useRef(scrollIntoView);
+  scrollRef.current = scrollIntoView;
+  useEffect(() => {
+    if (target === void 0) {
+      setResult({ anchor: null, state: "idle" });
+      return;
+    }
+    setResult({ anchor: null, state: "waiting" });
+    const controller = new AbortController();
+    void resolveAnchor({ root, target, timeoutMs, signal: controller.signal }).then(
+      (resolution) => {
+        if (controller.signal.aborted) return;
+        if (resolution.status !== "found") {
+          setResult({ anchor: null, state: "missing" });
+          return;
+        }
+        setResult({ anchor: resolution.element, state: "found" });
+        if (!scrollRef.current || !resolution.element.scrollIntoView) return;
+        resolution.element.scrollIntoView({
+          block: "center",
+          inline: "nearest",
+          behavior: prefersReducedMotion(resolution.element) ? "auto" : "smooth"
+        });
+      }
+    );
+    return () => controller.abort();
+  }, [key, timeoutMs]);
+  return result;
+}
+export {
+  useTourAnchor
+};
+//# sourceMappingURL=use-tour-anchor.js.map

package/dist/overlay/use-tour-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-anchor.js","sources":["../../src/overlay/use-tour-anchor.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { resolveAnchor } from \"./tour-anchor\";\nimport type { TourRootSource, TourTarget } from \"./tour-types\";\n\n/**\n * React lifecycle around `resolveAnchor`: one bounded wait per step, aborted when\n * the step changes or the tour unmounts, plus the scroll-into-view that makes the\n * spotlight land somewhere the operator can actually see.\n */\n\nexport type TourAnchorState = \"idle\" | \"waiting\" | \"found\" | \"missing\";\n\nexport type UseTourAnchorOptions = {\n  root: TourRootSource;\n  /** Omit for an anchorless (centred) step; the hook then reports `idle`. */\n  target?: TourTarget | undefined;\n  timeoutMs: number;\n  /** Scroll the anchor into view once it resolves. Defaults to `true`. */\n  scrollIntoView?: boolean | undefined;\n  /** Changes to this restart the wait — pass the step id. */\n  key: string;\n};\n\nexport type UseTourAnchorResult = {\n  anchor: HTMLElement | null;\n  state: TourAnchorState;\n};\n\nfunction prefersReducedMotion(element: HTMLElement): boolean {\n  const view = element.ownerDocument.defaultView;\n  return view?.matchMedia?.(\"(prefers-reduced-motion: reduce)\").matches ?? false;\n}\n\nexport function useTourAnchor(options: UseTourAnchorOptions): UseTourAnchorResult {\n  const { root, target, timeoutMs, scrollIntoView = true, key } = options;\n  const [result, setResult] = useState<UseTourAnchorResult>({ anchor: null, state: \"idle\" });\n  const scrollRef = useRef(scrollIntoView);\n  scrollRef.current = scrollIntoView;\n\n  useEffect(() => {\n    if (target === undefined) {\n      setResult({ anchor: null, state: \"idle\" });\n      return;\n    }\n\n    setResult({ anchor: null, state: \"waiting\" });\n    const controller = new AbortController();\n\n    void resolveAnchor({ root, target, timeoutMs, signal: controller.signal }).then(\n      (resolution) => {\n        if (controller.signal.aborted) return;\n        if (resolution.status !== \"found\") {\n          setResult({ anchor: null, state: \"missing\" });\n          return;\n        }\n        setResult({ anchor: resolution.element, state: \"found\" });\n        if (!scrollRef.current || !resolution.element.scrollIntoView) return;\n        resolution.element.scrollIntoView({\n          block: \"center\",\n          inline: \"nearest\",\n          behavior: prefersReducedMotion(resolution.element) ? \"auto\" : \"smooth\",\n        });\n      },\n    );\n\n    return () => controller.abort();\n    // `root` and `target` are re-created per render by most callers; `key` (the\n    // step id) is the identity that should restart the wait.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [key, timeoutMs]);\n\n  return result;\n}\n"],"names":[],"mappings":";;AA4BA,SAAS,qBAAqB,SAA+B;;AAC3D,QAAM,OAAO,QAAQ,cAAc;AACnC,WAAO,kCAAM,eAAN,8BAAmB,oCAAoC,YAAW;AAC3E;AAEO,SAAS,cAAc,SAAoD;AAChF,QAAM,EAAE,MAAM,QAAQ,WAAW,iBAAiB,MAAM,QAAQ;AAChE,QAAM,CAAC,QAAQ,SAAS,IAAI,SAA8B,EAAE,QAAQ,MAAM,OAAO,QAAQ;AACzF,QAAM,YAAY,OAAO,cAAc;AACvC,YAAU,UAAU;AAEpB,YAAU,MAAM;AACd,QAAI,WAAW,QAAW;AACxB,gBAAU,EAAE,QAAQ,MAAM,OAAO,QAAQ;AACzC;AAAA,IACF;AAEA,cAAU,EAAE,QAAQ,MAAM,OAAO,WAAW;AAC5C,UAAM,aAAa,IAAI,gBAAA;AAEvB,SAAK,cAAc,EAAE,MAAM,QAAQ,WAAW,QAAQ,WAAW,OAAA,CAAQ,EAAE;AAAA,MACzE,CAAC,eAAe;AACd,YAAI,WAAW,OAAO,QAAS;AAC/B,YAAI,WAAW,WAAW,SAAS;AACjC,oBAAU,EAAE,QAAQ,MAAM,OAAO,WAAW;AAC5C;AAAA,QACF;AACA,kBAAU,EAAE,QAAQ,WAAW,SAAS,OAAO,SAAS;AACxD,YAAI,CAAC,UAAU,WAAW,CAAC,WAAW,QAAQ,eAAgB;AAC9D,mBAAW,QAAQ,eAAe;AAAA,UAChC,OAAO;AAAA,UACP,QAAQ;AAAA,UACR,UAAU,qBAAqB,WAAW,OAAO,IAAI,SAAS;AAAA,QAAA,CAC/D;AAAA,MACH;AAAA,IAAA;AAGF,WAAO,MAAM,WAAW,MAAA;AAAA,EAI1B,GAAG,CAAC,KAAK,SAAS,CAAC;AAEnB,SAAO;AACT;"}

package/dist/overlay/use-tour-rect.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const react$1 = require("@floating-ui/react");
+const tourGeometry = require("./tour-geometry.cjs");
+function useTourRect(anchor, options) {
+  const { padding, radius } = options;
+  const [rect, setRect] = react.useState(null);
+  react.useEffect(() => {
+    if (!anchor) {
+      setRect(null);
+      return;
+    }
+    const view = anchor.ownerDocument.defaultView;
+    if (!view) return;
+    const measure = () => {
+      setRect(
+        tourGeometry.spotlightRect({
+          anchor: anchor.getBoundingClientRect(),
+          padding,
+          radius: radius ?? tourGeometry.anchorRadius(anchor) + padding,
+          viewport: { width: view.innerWidth, height: view.innerHeight }
+        })
+      );
+    };
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    return react$1.autoUpdate(anchor, anchor, measure);
+  }, [anchor, padding, radius]);
+  return rect;
+}
+exports.useTourRect = useTourRect;
+//# sourceMappingURL=use-tour-rect.cjs.map

package/dist/overlay/use-tour-rect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-rect.cjs","sources":["../../src/overlay/use-tour-rect.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { autoUpdate } from \"@floating-ui/react\";\nimport { anchorRadius, spotlightRect, type SpotlightRect } from \"./tour-geometry\";\n\n/**\n * Keeps the spotlight cutout locked to its anchor through scrolling, resizing,\n * and layout shifts. Separate from the card's own `autoUpdate` subscription:\n * both are cheap, and feeding floating-ui a virtual reference built from this\n * rect would still need its own update trigger.\n */\nexport function useTourRect(\n  anchor: HTMLElement | null,\n  options: { padding: number; radius?: number | undefined },\n): SpotlightRect | null {\n  const { padding, radius } = options;\n  const [rect, setRect] = useState<SpotlightRect | null>(null);\n\n  useEffect(() => {\n    if (!anchor) {\n      setRect(null);\n      return;\n    }\n    const view = anchor.ownerDocument.defaultView;\n    if (!view) return;\n\n    const measure = () => {\n      setRect(\n        spotlightRect({\n          anchor: anchor.getBoundingClientRect(),\n          padding,\n          radius: radius ?? anchorRadius(anchor) + padding,\n          viewport: { width: view.innerWidth, height: view.innerHeight },\n        }),\n      );\n    };\n\n    measure();\n    // jsdom has no ResizeObserver, and autoUpdate constructs one unconditionally.\n    if (typeof ResizeObserver === \"undefined\") return;\n    return autoUpdate(anchor, anchor, measure);\n  }, [anchor, padding, radius]);\n\n  return rect;\n}\n"],"names":["useState","useEffect","spotlightRect","anchorRadius","autoUpdate"],"mappings":";;;;;AAUO,SAAS,YACd,QACA,SACsB;AACtB,QAAM,EAAE,SAAS,OAAA,IAAW;AAC5B,QAAM,CAAC,MAAM,OAAO,IAAIA,MAAAA,SAA+B,IAAI;AAE3DC,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,QAAQ;AACX,cAAQ,IAAI;AACZ;AAAA,IACF;AACA,UAAM,OAAO,OAAO,cAAc;AAClC,QAAI,CAAC,KAAM;AAEX,UAAM,UAAU,MAAM;AACpB;AAAA,QACEC,2BAAc;AAAA,UACZ,QAAQ,OAAO,sBAAA;AAAA,UACf;AAAA,UACA,QAAQ,UAAUC,0BAAa,MAAM,IAAI;AAAA,UACzC,UAAU,EAAE,OAAO,KAAK,YAAY,QAAQ,KAAK,YAAA;AAAA,QAAY,CAC9D;AAAA,MAAA;AAAA,IAEL;AAEA,YAAA;AAEA,QAAI,OAAO,mBAAmB,YAAa;AAC3C,WAAOC,mBAAW,QAAQ,QAAQ,OAAO;AAAA,EAC3C,GAAG,CAAC,QAAQ,SAAS,MAAM,CAAC;AAE5B,SAAO;AACT;;"}

package/dist/overlay/use-tour-rect.d.ts

@@ -0,0 +1,12 @@
+import { SpotlightRect } from './tour-geometry';
+/**
+ * Keeps the spotlight cutout locked to its anchor through scrolling, resizing,
+ * and layout shifts. Separate from the card's own `autoUpdate` subscription:
+ * both are cheap, and feeding floating-ui a virtual reference built from this
+ * rect would still need its own update trigger.
+ */
+export declare function useTourRect(anchor: HTMLElement | null, options: {
+    padding: number;
+    radius?: number | undefined;
+}): SpotlightRect | null;
+//# sourceMappingURL=use-tour-rect.d.ts.map

package/dist/overlay/use-tour-rect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-rect.d.ts","sourceRoot":"","sources":["../../src/overlay/use-tour-rect.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACxD,aAAa,GAAG,IAAI,CA8BtB"}

package/dist/overlay/use-tour-rect.js

@@ -0,0 +1,33 @@
+import { useState, useEffect } from "react";
+import { autoUpdate } from "@floating-ui/react";
+import { spotlightRect, anchorRadius } from "./tour-geometry.js";
+function useTourRect(anchor, options) {
+  const { padding, radius } = options;
+  const [rect, setRect] = useState(null);
+  useEffect(() => {
+    if (!anchor) {
+      setRect(null);
+      return;
+    }
+    const view = anchor.ownerDocument.defaultView;
+    if (!view) return;
+    const measure = () => {
+      setRect(
+        spotlightRect({
+          anchor: anchor.getBoundingClientRect(),
+          padding,
+          radius: radius ?? anchorRadius(anchor) + padding,
+          viewport: { width: view.innerWidth, height: view.innerHeight }
+        })
+      );
+    };
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    return autoUpdate(anchor, anchor, measure);
+  }, [anchor, padding, radius]);
+  return rect;
+}
+export {
+  useTourRect
+};
+//# sourceMappingURL=use-tour-rect.js.map

package/dist/overlay/use-tour-rect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-rect.js","sources":["../../src/overlay/use-tour-rect.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { autoUpdate } from \"@floating-ui/react\";\nimport { anchorRadius, spotlightRect, type SpotlightRect } from \"./tour-geometry\";\n\n/**\n * Keeps the spotlight cutout locked to its anchor through scrolling, resizing,\n * and layout shifts. Separate from the card's own `autoUpdate` subscription:\n * both are cheap, and feeding floating-ui a virtual reference built from this\n * rect would still need its own update trigger.\n */\nexport function useTourRect(\n  anchor: HTMLElement | null,\n  options: { padding: number; radius?: number | undefined },\n): SpotlightRect | null {\n  const { padding, radius } = options;\n  const [rect, setRect] = useState<SpotlightRect | null>(null);\n\n  useEffect(() => {\n    if (!anchor) {\n      setRect(null);\n      return;\n    }\n    const view = anchor.ownerDocument.defaultView;\n    if (!view) return;\n\n    const measure = () => {\n      setRect(\n        spotlightRect({\n          anchor: anchor.getBoundingClientRect(),\n          padding,\n          radius: radius ?? anchorRadius(anchor) + padding,\n          viewport: { width: view.innerWidth, height: view.innerHeight },\n        }),\n      );\n    };\n\n    measure();\n    // jsdom has no ResizeObserver, and autoUpdate constructs one unconditionally.\n    if (typeof ResizeObserver === \"undefined\") return;\n    return autoUpdate(anchor, anchor, measure);\n  }, [anchor, padding, radius]);\n\n  return rect;\n}\n"],"names":[],"mappings":";;;AAUO,SAAS,YACd,QACA,SACsB;AACtB,QAAM,EAAE,SAAS,OAAA,IAAW;AAC5B,QAAM,CAAC,MAAM,OAAO,IAAI,SAA+B,IAAI;AAE3D,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ;AACX,cAAQ,IAAI;AACZ;AAAA,IACF;AACA,UAAM,OAAO,OAAO,cAAc;AAClC,QAAI,CAAC,KAAM;AAEX,UAAM,UAAU,MAAM;AACpB;AAAA,QACE,cAAc;AAAA,UACZ,QAAQ,OAAO,sBAAA;AAAA,UACf;AAAA,UACA,QAAQ,UAAU,aAAa,MAAM,IAAI;AAAA,UACzC,UAAU,EAAE,OAAO,KAAK,YAAY,QAAQ,KAAK,YAAA;AAAA,QAAY,CAC9D;AAAA,MAAA;AAAA,IAEL;AAEA,YAAA;AAEA,QAAI,OAAO,mBAAmB,YAAa;AAC3C,WAAO,WAAW,QAAQ,QAAQ,OAAO;AAAA,EAC3C,GAAG,CAAC,QAAQ,SAAS,MAAM,CAAC;AAE5B,SAAO;AACT;"}

package/dist/overlay/use-tour-step.cjs

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const tourModel = require("./tour-model.cjs");
+function useStepRoute(options) {
+  const { step, context, onNavigate } = options;
+  const routeRef = react.useRef(null);
+  const [navigating, setNavigating] = react.useState(false);
+  const contextRef = react.useRef(context);
+  contextRef.current = context;
+  const pendingRoute = (step == null ? void 0 : step.route) !== void 0 && step.route !== routeRef.current;
+  react.useEffect(() => {
+    if (!step || step.route === void 0 || step.route === routeRef.current) return;
+    const route = step.route;
+    routeRef.current = route;
+    const ctx = contextRef.current;
+    if (!onNavigate || !ctx) return;
+    setNavigating(true);
+    void Promise.resolve(onNavigate(route, ctx)).finally(() => setNavigating(false));
+  }, [step == null ? void 0 : step.id]);
+  return { navigating, pendingRoute };
+}
+function useMissingAnchorPolicy(options) {
+  const { definition, step, index, missing, policy, onStepError, onSkip } = options;
+  const skipRef = react.useRef(onSkip);
+  skipRef.current = onSkip;
+  react.useEffect(() => {
+    if (!missing || !step) return;
+    const target = tourModel.describeTarget(step.target);
+    const message = `Tour "${definition.id}" step "${step.id}": anchor ${target} never appeared`;
+    if (policy === "fail") throw new Error(message);
+    console.warn(`clicky-ui ${message}`);
+    onStepError == null ? void 0 : onStepError({ tourId: definition.id, step, index, reason: "anchor-timeout", target });
+    if (policy === "skip") skipRef.current(tourModel.nextStepIndex(definition.steps, index, "next"));
+  }, [missing, step == null ? void 0 : step.id, policy]);
+}
+function useActiveAnchorMarker(anchor) {
+  react.useEffect(() => {
+    if (!anchor) return;
+    anchor.dataset.tourActive = "true";
+    return () => {
+      delete anchor.dataset.tourActive;
+    };
+  }, [anchor]);
+}
+function useStepLifecycle(options) {
+  const { step, context, settled } = options;
+  const contextRef = react.useRef(context);
+  contextRef.current = context;
+  react.useEffect(() => {
+    var _a;
+    if (!step || !settled) return;
+    const ctx = contextRef.current;
+    if (!ctx) return;
+    void ((_a = step.onEnter) == null ? void 0 : _a.call(step, ctx));
+    return () => {
+      var _a2;
+      return (_a2 = step.onExit) == null ? void 0 : _a2.call(step, ctx);
+    };
+  }, [step == null ? void 0 : step.id, settled]);
+}
+exports.useActiveAnchorMarker = useActiveAnchorMarker;
+exports.useMissingAnchorPolicy = useMissingAnchorPolicy;
+exports.useStepLifecycle = useStepLifecycle;
+exports.useStepRoute = useStepRoute;
+//# sourceMappingURL=use-tour-step.cjs.map

package/dist/overlay/use-tour-step.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-step.cjs","sources":["../../src/overlay/use-tour-step.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { describeTarget, nextStepIndex } from \"./tour-model\";\nimport type {\n  TourDefinition,\n  TourMissingAnchor,\n  TourStep,\n  TourStepContext,\n  TourStepErrorInfo,\n} from \"./tour-types\";\n\n/**\n * The per-step effects of a running tour, kept out of the renderer: route\n * hand-off, the missing-anchor policy, `onEnter`/`onExit`, and the active-anchor\n * marker.\n */\n\n/**\n * Asks the host to navigate when the entered step lives on a different route.\n * The tour deliberately does NOT then wait on the route changing — the anchor\n * appearing is the only readiness signal, so one mechanism covers route change,\n * lazy chunk, and data fetch, and the same steps still run where there is no\n * router at all.\n */\nexport function useStepRoute(options: {\n  step: TourStep | undefined;\n  context: TourStepContext | null;\n  onNavigate: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;\n}): { navigating: boolean; pendingRoute: boolean } {\n  const { step, context, onNavigate } = options;\n  const routeRef = useRef<string | null>(null);\n  const [navigating, setNavigating] = useState(false);\n  const contextRef = useRef(context);\n  contextRef.current = context;\n\n  const pendingRoute = step?.route !== undefined && step.route !== routeRef.current;\n\n  useEffect(() => {\n    if (!step || step.route === undefined || step.route === routeRef.current) return;\n    const route = step.route;\n    routeRef.current = route;\n    const ctx = contextRef.current;\n    if (!onNavigate || !ctx) return;\n    setNavigating(true);\n    void Promise.resolve(onNavigate(route, ctx)).finally(() => setNavigating(false));\n    // Once per entered step whose route differs; the context object changes as\n    // the anchor resolves and must not retrigger navigation.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [step?.id]);\n\n  return { navigating, pendingRoute };\n}\n\n/**\n * Applies the missing-anchor policy. `\"center\"` (the default) keeps the step and\n * its counter but always warns and reports, so a broken anchor is loud without\n * being fatal in front of a user; `\"skip\"` silently rewrites the tour and is\n * opt-in; `\"fail\"` is for stories and tests.\n */\nexport function useMissingAnchorPolicy(options: {\n  definition: TourDefinition;\n  step: TourStep | undefined;\n  index: number;\n  missing: boolean;\n  policy: TourMissingAnchor;\n  onStepError: ((info: TourStepErrorInfo) => void) | undefined;\n  onSkip: (nextIndex: number | null) => void;\n}): void {\n  const { definition, step, index, missing, policy, onStepError, onSkip } = options;\n  const skipRef = useRef(onSkip);\n  skipRef.current = onSkip;\n\n  useEffect(() => {\n    if (!missing || !step) return;\n    const target = describeTarget(step.target);\n    const message = `Tour \"${definition.id}\" step \"${step.id}\": anchor ${target} never appeared`;\n    if (policy === \"fail\") throw new Error(message);\n\n    console.warn(`clicky-ui ${message}`);\n    onStepError?.({ tourId: definition.id, step, index, reason: \"anchor-timeout\", target });\n    if (policy === \"skip\") skipRef.current(nextStepIndex(definition.steps, index, \"next\"));\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [missing, step?.id, policy]);\n}\n\n/** Marks the spotlit element so styles and end-to-end tests can find it. */\nexport function useActiveAnchorMarker(anchor: HTMLElement | null): void {\n  useEffect(() => {\n    if (!anchor) return;\n    anchor.dataset.tourActive = \"true\";\n    return () => {\n      delete anchor.dataset.tourActive;\n    };\n  }, [anchor]);\n}\n\n/** Runs `onEnter` once the step has settled, and `onExit` when it is left. */\nexport function useStepLifecycle(options: {\n  step: TourStep | undefined;\n  context: TourStepContext | null;\n  settled: boolean;\n}): void {\n  const { step, context, settled } = options;\n  const contextRef = useRef(context);\n  contextRef.current = context;\n\n  useEffect(() => {\n    if (!step || !settled) return;\n    const ctx = contextRef.current;\n    if (!ctx) return;\n    void step.onEnter?.(ctx);\n    return () => step.onExit?.(ctx);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [step?.id, settled]);\n}\n"],"names":["useRef","useState","useEffect","describeTarget","nextStepIndex","_a"],"mappings":";;;;AAuBO,SAAS,aAAa,SAIsB;AACjD,QAAM,EAAE,MAAM,SAAS,WAAA,IAAe;AACtC,QAAM,WAAWA,MAAAA,OAAsB,IAAI;AAC3C,QAAM,CAAC,YAAY,aAAa,IAAIC,MAAAA,SAAS,KAAK;AAClD,QAAM,aAAaD,MAAAA,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,gBAAe,6BAAM,WAAU,UAAa,KAAK,UAAU,SAAS;AAE1EE,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,QAAQ,KAAK,UAAU,UAAa,KAAK,UAAU,SAAS,QAAS;AAC1E,UAAM,QAAQ,KAAK;AACnB,aAAS,UAAU;AACnB,UAAM,MAAM,WAAW;AACvB,QAAI,CAAC,cAAc,CAAC,IAAK;AACzB,kBAAc,IAAI;AAClB,SAAK,QAAQ,QAAQ,WAAW,OAAO,GAAG,CAAC,EAAE,QAAQ,MAAM,cAAc,KAAK,CAAC;AAAA,EAIjF,GAAG,CAAC,6BAAM,EAAE,CAAC;AAEb,SAAO,EAAE,YAAY,aAAA;AACvB;AAQO,SAAS,uBAAuB,SAQ9B;AACP,QAAM,EAAE,YAAY,MAAM,OAAO,SAAS,QAAQ,aAAa,WAAW;AAC1E,QAAM,UAAUF,MAAAA,OAAO,MAAM;AAC7B,UAAQ,UAAU;AAElBE,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,WAAW,CAAC,KAAM;AACvB,UAAM,SAASC,UAAAA,eAAe,KAAK,MAAM;AACzC,UAAM,UAAU,SAAS,WAAW,EAAE,WAAW,KAAK,EAAE,aAAa,MAAM;AAC3E,QAAI,WAAW,OAAQ,OAAM,IAAI,MAAM,OAAO;AAE9C,YAAQ,KAAK,aAAa,OAAO,EAAE;AACnC,+CAAc,EAAE,QAAQ,WAAW,IAAI,MAAM,OAAO,QAAQ,kBAAkB;AAC9E,QAAI,WAAW,OAAQ,SAAQ,QAAQC,wBAAc,WAAW,OAAO,OAAO,MAAM,CAAC;AAAA,EAEvF,GAAG,CAAC,SAAS,6BAAM,IAAI,MAAM,CAAC;AAChC;AAGO,SAAS,sBAAsB,QAAkC;AACtEF,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AACb,WAAO,QAAQ,aAAa;AAC5B,WAAO,MAAM;AACX,aAAO,OAAO,QAAQ;AAAA,IACxB;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AACb;AAGO,SAAS,iBAAiB,SAIxB;AACP,QAAM,EAAE,MAAM,SAAS,QAAA,IAAY;AACnC,QAAM,aAAaF,MAAAA,OAAO,OAAO;AACjC,aAAW,UAAU;AAErBE,QAAAA,UAAU,MAAM;;AACd,QAAI,CAAC,QAAQ,CAAC,QAAS;AACvB,UAAM,MAAM,WAAW;AACvB,QAAI,CAAC,IAAK;AACV,WAAK,UAAK,YAAL,8BAAe;AACpB,WAAO,MAAA;;AAAM,cAAAG,MAAA,KAAK,WAAL,gBAAAA,IAAA,WAAc;AAAA;AAAA,EAE7B,GAAG,CAAC,6BAAM,IAAI,OAAO,CAAC;AACxB;;;;;"}

package/dist/overlay/use-tour-step.d.ts

@@ -0,0 +1,45 @@
+import { TourDefinition, TourMissingAnchor, TourStep, TourStepContext, TourStepErrorInfo } from './tour-types';
+/**
+ * The per-step effects of a running tour, kept out of the renderer: route
+ * hand-off, the missing-anchor policy, `onEnter`/`onExit`, and the active-anchor
+ * marker.
+ */
+/**
+ * Asks the host to navigate when the entered step lives on a different route.
+ * The tour deliberately does NOT then wait on the route changing — the anchor
+ * appearing is the only readiness signal, so one mechanism covers route change,
+ * lazy chunk, and data fetch, and the same steps still run where there is no
+ * router at all.
+ */
+export declare function useStepRoute(options: {
+    step: TourStep | undefined;
+    context: TourStepContext | null;
+    onNavigate: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;
+}): {
+    navigating: boolean;
+    pendingRoute: boolean;
+};
+/**
+ * Applies the missing-anchor policy. `"center"` (the default) keeps the step and
+ * its counter but always warns and reports, so a broken anchor is loud without
+ * being fatal in front of a user; `"skip"` silently rewrites the tour and is
+ * opt-in; `"fail"` is for stories and tests.
+ */
+export declare function useMissingAnchorPolicy(options: {
+    definition: TourDefinition;
+    step: TourStep | undefined;
+    index: number;
+    missing: boolean;
+    policy: TourMissingAnchor;
+    onStepError: ((info: TourStepErrorInfo) => void) | undefined;
+    onSkip: (nextIndex: number | null) => void;
+}): void;
+/** Marks the spotlit element so styles and end-to-end tests can find it. */
+export declare function useActiveAnchorMarker(anchor: HTMLElement | null): void;
+/** Runs `onEnter` once the step has settled, and `onExit` when it is left. */
+export declare function useStepLifecycle(options: {
+    step: TourStep | undefined;
+    context: TourStepContext | null;
+    settled: boolean;
+}): void;
+//# sourceMappingURL=use-tour-step.d.ts.map

package/dist/overlay/use-tour-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-step.d.ts","sourceRoot":"","sources":["../../src/overlay/use-tour-step.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CACzF,GAAG;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAuBjD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,UAAU,EAAE,cAAc,CAAC;IAC3B,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC7D,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC5C,GAAG,IAAI,CAgBP;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAQtE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG,IAAI,CAaP"}

package/dist/overlay/use-tour-step.js

@@ -0,0 +1,66 @@
+import { useRef, useState, useEffect } from "react";
+import { describeTarget, nextStepIndex } from "./tour-model.js";
+function useStepRoute(options) {
+  const { step, context, onNavigate } = options;
+  const routeRef = useRef(null);
+  const [navigating, setNavigating] = useState(false);
+  const contextRef = useRef(context);
+  contextRef.current = context;
+  const pendingRoute = (step == null ? void 0 : step.route) !== void 0 && step.route !== routeRef.current;
+  useEffect(() => {
+    if (!step || step.route === void 0 || step.route === routeRef.current) return;
+    const route = step.route;
+    routeRef.current = route;
+    const ctx = contextRef.current;
+    if (!onNavigate || !ctx) return;
+    setNavigating(true);
+    void Promise.resolve(onNavigate(route, ctx)).finally(() => setNavigating(false));
+  }, [step == null ? void 0 : step.id]);
+  return { navigating, pendingRoute };
+}
+function useMissingAnchorPolicy(options) {
+  const { definition, step, index, missing, policy, onStepError, onSkip } = options;
+  const skipRef = useRef(onSkip);
+  skipRef.current = onSkip;
+  useEffect(() => {
+    if (!missing || !step) return;
+    const target = describeTarget(step.target);
+    const message = `Tour "${definition.id}" step "${step.id}": anchor ${target} never appeared`;
+    if (policy === "fail") throw new Error(message);
+    console.warn(`clicky-ui ${message}`);
+    onStepError == null ? void 0 : onStepError({ tourId: definition.id, step, index, reason: "anchor-timeout", target });
+    if (policy === "skip") skipRef.current(nextStepIndex(definition.steps, index, "next"));
+  }, [missing, step == null ? void 0 : step.id, policy]);
+}
+function useActiveAnchorMarker(anchor) {
+  useEffect(() => {
+    if (!anchor) return;
+    anchor.dataset.tourActive = "true";
+    return () => {
+      delete anchor.dataset.tourActive;
+    };
+  }, [anchor]);
+}
+function useStepLifecycle(options) {
+  const { step, context, settled } = options;
+  const contextRef = useRef(context);
+  contextRef.current = context;
+  useEffect(() => {
+    var _a;
+    if (!step || !settled) return;
+    const ctx = contextRef.current;
+    if (!ctx) return;
+    void ((_a = step.onEnter) == null ? void 0 : _a.call(step, ctx));
+    return () => {
+      var _a2;
+      return (_a2 = step.onExit) == null ? void 0 : _a2.call(step, ctx);
+    };
+  }, [step == null ? void 0 : step.id, settled]);
+}
+export {
+  useActiveAnchorMarker,
+  useMissingAnchorPolicy,
+  useStepLifecycle,
+  useStepRoute
+};
+//# sourceMappingURL=use-tour-step.js.map

package/dist/overlay/use-tour-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tour-step.js","sources":["../../src/overlay/use-tour-step.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport { describeTarget, nextStepIndex } from \"./tour-model\";\nimport type {\n  TourDefinition,\n  TourMissingAnchor,\n  TourStep,\n  TourStepContext,\n  TourStepErrorInfo,\n} from \"./tour-types\";\n\n/**\n * The per-step effects of a running tour, kept out of the renderer: route\n * hand-off, the missing-anchor policy, `onEnter`/`onExit`, and the active-anchor\n * marker.\n */\n\n/**\n * Asks the host to navigate when the entered step lives on a different route.\n * The tour deliberately does NOT then wait on the route changing — the anchor\n * appearing is the only readiness signal, so one mechanism covers route change,\n * lazy chunk, and data fetch, and the same steps still run where there is no\n * router at all.\n */\nexport function useStepRoute(options: {\n  step: TourStep | undefined;\n  context: TourStepContext | null;\n  onNavigate: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;\n}): { navigating: boolean; pendingRoute: boolean } {\n  const { step, context, onNavigate } = options;\n  const routeRef = useRef<string | null>(null);\n  const [navigating, setNavigating] = useState(false);\n  const contextRef = useRef(context);\n  contextRef.current = context;\n\n  const pendingRoute = step?.route !== undefined && step.route !== routeRef.current;\n\n  useEffect(() => {\n    if (!step || step.route === undefined || step.route === routeRef.current) return;\n    const route = step.route;\n    routeRef.current = route;\n    const ctx = contextRef.current;\n    if (!onNavigate || !ctx) return;\n    setNavigating(true);\n    void Promise.resolve(onNavigate(route, ctx)).finally(() => setNavigating(false));\n    // Once per entered step whose route differs; the context object changes as\n    // the anchor resolves and must not retrigger navigation.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [step?.id]);\n\n  return { navigating, pendingRoute };\n}\n\n/**\n * Applies the missing-anchor policy. `\"center\"` (the default) keeps the step and\n * its counter but always warns and reports, so a broken anchor is loud without\n * being fatal in front of a user; `\"skip\"` silently rewrites the tour and is\n * opt-in; `\"fail\"` is for stories and tests.\n */\nexport function useMissingAnchorPolicy(options: {\n  definition: TourDefinition;\n  step: TourStep | undefined;\n  index: number;\n  missing: boolean;\n  policy: TourMissingAnchor;\n  onStepError: ((info: TourStepErrorInfo) => void) | undefined;\n  onSkip: (nextIndex: number | null) => void;\n}): void {\n  const { definition, step, index, missing, policy, onStepError, onSkip } = options;\n  const skipRef = useRef(onSkip);\n  skipRef.current = onSkip;\n\n  useEffect(() => {\n    if (!missing || !step) return;\n    const target = describeTarget(step.target);\n    const message = `Tour \"${definition.id}\" step \"${step.id}\": anchor ${target} never appeared`;\n    if (policy === \"fail\") throw new Error(message);\n\n    console.warn(`clicky-ui ${message}`);\n    onStepError?.({ tourId: definition.id, step, index, reason: \"anchor-timeout\", target });\n    if (policy === \"skip\") skipRef.current(nextStepIndex(definition.steps, index, \"next\"));\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [missing, step?.id, policy]);\n}\n\n/** Marks the spotlit element so styles and end-to-end tests can find it. */\nexport function useActiveAnchorMarker(anchor: HTMLElement | null): void {\n  useEffect(() => {\n    if (!anchor) return;\n    anchor.dataset.tourActive = \"true\";\n    return () => {\n      delete anchor.dataset.tourActive;\n    };\n  }, [anchor]);\n}\n\n/** Runs `onEnter` once the step has settled, and `onExit` when it is left. */\nexport function useStepLifecycle(options: {\n  step: TourStep | undefined;\n  context: TourStepContext | null;\n  settled: boolean;\n}): void {\n  const { step, context, settled } = options;\n  const contextRef = useRef(context);\n  contextRef.current = context;\n\n  useEffect(() => {\n    if (!step || !settled) return;\n    const ctx = contextRef.current;\n    if (!ctx) return;\n    void step.onEnter?.(ctx);\n    return () => step.onExit?.(ctx);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [step?.id, settled]);\n}\n"],"names":["_a"],"mappings":";;AAuBO,SAAS,aAAa,SAIsB;AACjD,QAAM,EAAE,MAAM,SAAS,WAAA,IAAe;AACtC,QAAM,WAAW,OAAsB,IAAI;AAC3C,QAAM,CAAC,YAAY,aAAa,IAAI,SAAS,KAAK;AAClD,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,gBAAe,6BAAM,WAAU,UAAa,KAAK,UAAU,SAAS;AAE1E,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ,KAAK,UAAU,UAAa,KAAK,UAAU,SAAS,QAAS;AAC1E,UAAM,QAAQ,KAAK;AACnB,aAAS,UAAU;AACnB,UAAM,MAAM,WAAW;AACvB,QAAI,CAAC,cAAc,CAAC,IAAK;AACzB,kBAAc,IAAI;AAClB,SAAK,QAAQ,QAAQ,WAAW,OAAO,GAAG,CAAC,EAAE,QAAQ,MAAM,cAAc,KAAK,CAAC;AAAA,EAIjF,GAAG,CAAC,6BAAM,EAAE,CAAC;AAEb,SAAO,EAAE,YAAY,aAAA;AACvB;AAQO,SAAS,uBAAuB,SAQ9B;AACP,QAAM,EAAE,YAAY,MAAM,OAAO,SAAS,QAAQ,aAAa,WAAW;AAC1E,QAAM,UAAU,OAAO,MAAM;AAC7B,UAAQ,UAAU;AAElB,YAAU,MAAM;AACd,QAAI,CAAC,WAAW,CAAC,KAAM;AACvB,UAAM,SAAS,eAAe,KAAK,MAAM;AACzC,UAAM,UAAU,SAAS,WAAW,EAAE,WAAW,KAAK,EAAE,aAAa,MAAM;AAC3E,QAAI,WAAW,OAAQ,OAAM,IAAI,MAAM,OAAO;AAE9C,YAAQ,KAAK,aAAa,OAAO,EAAE;AACnC,+CAAc,EAAE,QAAQ,WAAW,IAAI,MAAM,OAAO,QAAQ,kBAAkB;AAC9E,QAAI,WAAW,OAAQ,SAAQ,QAAQ,cAAc,WAAW,OAAO,OAAO,MAAM,CAAC;AAAA,EAEvF,GAAG,CAAC,SAAS,6BAAM,IAAI,MAAM,CAAC;AAChC;AAGO,SAAS,sBAAsB,QAAkC;AACtE,YAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AACb,WAAO,QAAQ,aAAa;AAC5B,WAAO,MAAM;AACX,aAAO,OAAO,QAAQ;AAAA,IACxB;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AACb;AAGO,SAAS,iBAAiB,SAIxB;AACP,QAAM,EAAE,MAAM,SAAS,QAAA,IAAY;AACnC,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,YAAU,MAAM;;AACd,QAAI,CAAC,QAAQ,CAAC,QAAS;AACvB,UAAM,MAAM,WAAW;AACvB,QAAI,CAAC,IAAK;AACV,WAAK,UAAK,YAAL,8BAAe;AACpB,WAAO,MAAA;;AAAM,cAAAA,MAAA,KAAK,WAAL,gBAAAA,IAAA,WAAc;AAAA;AAAA,EAE7B,GAAG,CAAC,6BAAM,IAAI,OAAO,CAAC;AACxB;"}

package/dist/overlay/zIndex.cjs

@@ -15,6 +15,14 @@ const zIndex = {
   modalStep: 10,
   /** How far above the top modal floating content sits (below the next nest). */
   popoverOverModalOffset: 5,
+  /**
+   * Guided-tour dim/spotlight. Above every app overlay including a modal a step
+   * may point at, and below toasts. Floating content opened *during* a tour
+   * clears the dim via `useFloatingZIndex` (see ./modalStack).
+   */
+  tour: 5e4,
+  /** How far above the dim the tour's own step card sits. */
+  tourCardOffset: 10,
   /** Toasts / notifications — always the topmost layer. */
   toast: 1e5
 };

package/dist/overlay/zIndex.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"zIndex.cjs","sources":["../../src/overlay/zIndex.ts"],"sourcesContent":["/**\n * Centralized z-index scale for clicky-ui overlays — the single source of truth\n * so stacking conflicts (e.g. a dropdown opened inside a modal rendering behind\n * it) cannot recur.\n *\n * These are applied as inline `style={{ zIndex }}`, never as arbitrary `z-[N]`\n * Tailwind classes: a consumer's Tailwind build only generates the arbitrary\n * classes it can scan from clicky-ui's published dist, so a freshly chosen\n * `z-[N]` may silently emit no rule. Inline styles are immune to that.\n *\n * Floating, transient content (dropdown / combobox / menu / tooltip / popover)\n * must clear whatever modal is open, so its z-index is computed relative to the\n * active modal via `useFloatingZIndex` (see ./modalStack) rather than taken from\n * a constant here.\n *\n * Layers NOT listed here are intentionally local: they live inside their own\n * stacking context and never participate in the global ordering —\n * `Timeline` (`z-[1]`), `RangeSlider` thumbs (20/30), and `Modal`'s\n * `ConfirmClosePrompt` (`z-10`, relative to the modal panel).\n */\nexport const zIndex = {\n  /** In-flow raised affordances (sticky bits). */\n  raised: 30,\n  /** Persistent chat launcher. */\n  chatFab: 60,\n  /** Floating chat windows; `ChatWindowManager` increments from this base. */\n  chatWindow: 61,\n  /** Floating transient content when NO modal is open (above app chrome). */\n  popover: 9000,\n  /** Modal/dialog at depth 0; nested modals add `modalStep` per level. */\n  modal: 10000,\n  /** Per-level step between stacked modals. */\n  modalStep: 10,\n  /** How far above the top modal floating content sits (below the next nest). */\n  popoverOverModalOffset: 5,\n  /** Toasts / notifications — always the topmost layer. */\n  toast: 100000,\n} as const;\n"],"names":[],"mappings":";;AAoBO,MAAM,SAAS;AAAA;AAAA,EAEpB,QAAQ;AAAA;AAAA,EAER,SAAS;AAAA;AAAA,EAET,YAAY;AAAA;AAAA,EAEZ,SAAS;AAAA;AAAA,EAET,OAAO;AAAA;AAAA,EAEP,WAAW;AAAA;AAAA,EAEX,wBAAwB;AAAA;AAAA,EAExB,OAAO;AACT;;"}
+{"version":3,"file":"zIndex.cjs","sources":["../../src/overlay/zIndex.ts"],"sourcesContent":["/**\n * Centralized z-index scale for clicky-ui overlays — the single source of truth\n * so stacking conflicts (e.g. a dropdown opened inside a modal rendering behind\n * it) cannot recur.\n *\n * These are applied as inline `style={{ zIndex }}`, never as arbitrary `z-[N]`\n * Tailwind classes: a consumer's Tailwind build only generates the arbitrary\n * classes it can scan from clicky-ui's published dist, so a freshly chosen\n * `z-[N]` may silently emit no rule. Inline styles are immune to that.\n *\n * Floating, transient content (dropdown / combobox / menu / tooltip / popover)\n * must clear whatever modal is open, so its z-index is computed relative to the\n * active modal via `useFloatingZIndex` (see ./modalStack) rather than taken from\n * a constant here.\n *\n * Layers NOT listed here are intentionally local: they live inside their own\n * stacking context and never participate in the global ordering —\n * `Timeline` (`z-[1]`), `RangeSlider` thumbs (20/30), and `Modal`'s\n * `ConfirmClosePrompt` (`z-10`, relative to the modal panel).\n */\nexport const zIndex = {\n  /** In-flow raised affordances (sticky bits). */\n  raised: 30,\n  /** Persistent chat launcher. */\n  chatFab: 60,\n  /** Floating chat windows; `ChatWindowManager` increments from this base. */\n  chatWindow: 61,\n  /** Floating transient content when NO modal is open (above app chrome). */\n  popover: 9000,\n  /** Modal/dialog at depth 0; nested modals add `modalStep` per level. */\n  modal: 10000,\n  /** Per-level step between stacked modals. */\n  modalStep: 10,\n  /** How far above the top modal floating content sits (below the next nest). */\n  popoverOverModalOffset: 5,\n  /**\n   * Guided-tour dim/spotlight. Above every app overlay including a modal a step\n   * may point at, and below toasts. Floating content opened *during* a tour\n   * clears the dim via `useFloatingZIndex` (see ./modalStack).\n   */\n  tour: 50000,\n  /** How far above the dim the tour's own step card sits. */\n  tourCardOffset: 10,\n  /** Toasts / notifications — always the topmost layer. */\n  toast: 100000,\n} as const;\n"],"names":[],"mappings":";;AAoBO,MAAM,SAAS;AAAA;AAAA,EAEpB,QAAQ;AAAA;AAAA,EAER,SAAS;AAAA;AAAA,EAET,YAAY;AAAA;AAAA,EAEZ,SAAS;AAAA;AAAA,EAET,OAAO;AAAA;AAAA,EAEP,WAAW;AAAA;AAAA,EAEX,wBAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMxB,MAAM;AAAA;AAAA,EAEN,gBAAgB;AAAA;AAAA,EAEhB,OAAO;AACT;;"}