@flanksource/clicky-ui 0.3.17 → 0.3.19

package/dist/overlay/Tour.js

@@ -0,0 +1,173 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useMemo, useRef, useEffect, useState } from "react";
+import { FloatingPortal } from "@floating-ui/react";
+import { useHotkey } from "../hooks/use-hotkey.js";
+import { useTourLayer, useEscapeLayer } from "./modalStack.js";
+import { TourCard } from "./TourCard.js";
+import { TourSpotlight } from "./TourSpotlight.js";
+import { validateTourDefinition, DEFAULT_TOUR_LABELS, activeSteps, nextStepIndex, displayPosition } from "./tour-model.js";
+import { useTourAnchor } from "./use-tour-anchor.js";
+import { useTourRect } from "./use-tour-rect.js";
+import { useStepRoute, useMissingAnchorPolicy, useActiveAnchorMarker, useStepLifecycle } from "./use-tour-step.js";
+const DEFAULT_ANCHOR_TIMEOUT_MS = 3e3;
+const DEFAULT_NAVIGATE_TIMEOUT_MS = 8e3;
+const DEFAULT_PADDING = 8;
+function viewOf(source) {
+  var _a;
+  const root = (typeof source === "function" ? source() : source) ?? null;
+  if (!root) return null;
+  if (root instanceof Document) return root.defaultView;
+  return ((_a = root.ownerDocument) == null ? void 0 : _a.defaultView) ?? null;
+}
+function useViewport(root) {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  useEffect(() => {
+    const view = viewOf(root);
+    if (!view) return;
+    const measure = () => setSize({ width: view.innerWidth, height: view.innerHeight });
+    measure();
+    view.addEventListener("resize", measure);
+    return () => view.removeEventListener("resize", measure);
+  }, [root]);
+  return size;
+}
+function Tour(props) {
+  const {
+    definition,
+    index,
+    onIndexChange,
+    onComplete,
+    onDismiss,
+    onNavigate,
+    portalContainer,
+    missingAnchor = "center",
+    anchorTimeoutMs = DEFAULT_ANCHOR_TIMEOUT_MS,
+    navigateTimeoutMs = DEFAULT_NAVIGATE_TIMEOUT_MS,
+    padding = DEFAULT_PADDING,
+    interaction = "allow-anchor",
+    keyboard = true,
+    closeOnEsc = true,
+    scrollIntoView = true,
+    onStepError
+  } = props;
+  const anchorRoot = useMemo(
+    () => props.anchorRoot ?? (() => typeof document === "undefined" ? null : document),
+    [props.anchorRoot]
+  );
+  const validated = useRef(null);
+  if (validated.current !== definition.id) {
+    validateTourDefinition(definition);
+    validated.current = definition.id;
+  }
+  const labels = useMemo(
+    () => ({ ...DEFAULT_TOUR_LABELS, ...props.labels }),
+    [props.labels]
+  );
+  const steps = definition.steps;
+  const step = steps[index];
+  const total = activeSteps(steps).length;
+  const viewport = useViewport(anchorRoot);
+  const contextSeed = useMemo(
+    () => step ? { step, index, total, anchor: null, direction: "jump" } : null,
+    [step, index, total]
+  );
+  const { navigating, pendingRoute } = useStepRoute({ step, context: contextSeed, onNavigate });
+  const anchorState = useTourAnchor({
+    root: anchorRoot,
+    target: step == null ? void 0 : step.target,
+    timeoutMs: pendingRoute || navigating ? navigateTimeoutMs : (step == null ? void 0 : step.timeoutMs) ?? anchorTimeoutMs,
+    scrollIntoView,
+    key: `${definition.id}:${(step == null ? void 0 : step.id) ?? ""}`
+  });
+  const context = useMemo(
+    () => step ? { step, index, total, anchor: anchorState.anchor, direction: "jump" } : null,
+    [step, index, total, anchorState.anchor]
+  );
+  const backIndex = nextStepIndex(steps, index, "back");
+  const forwardIndex = nextStepIndex(steps, index, "next");
+  const missing = anchorState.state === "missing";
+  const policy = (step == null ? void 0 : step.onMissing) ?? missingAnchor;
+  const waiting = missing && (step == null ? void 0 : step.hint) !== void 0 && step.hintOptional !== true;
+  const isLast = forwardIndex === null;
+  const blocked = waiting && !isLast;
+  const goNext = () => {
+    if (blocked) return;
+    if (forwardIndex === null) onComplete();
+    else onIndexChange(forwardIndex, "next");
+  };
+  const goBack = () => {
+    if (backIndex !== null) onIndexChange(backIndex, "back");
+  };
+  useMissingAnchorPolicy({
+    definition,
+    step,
+    index,
+    missing,
+    policy,
+    onStepError,
+    onSkip: (next) => next === null ? onComplete() : onIndexChange(next, "next")
+  });
+  useActiveAnchorMarker(anchorState.anchor);
+  useStepLifecycle({ step, context, settled: anchorState.state !== "waiting" });
+  useTourLayer(true);
+  useEscapeLayer(true, onDismiss, closeOnEsc);
+  useHotkey("arrowright", goNext, { enabled: keyboard, priority: 10 });
+  useHotkey("arrowleft", goBack, { enabled: keyboard, priority: 10 });
+  const anchored = anchorState.state === "found" ? anchorState.anchor : null;
+  const cutout = useTourRect(anchored, {
+    padding: (step == null ? void 0 : step.padding) ?? padding,
+    radius: step == null ? void 0 : step.radius
+  });
+  const liveStatus = navigating ? "navigating" : anchorState.state === "waiting" ? "waiting" : "active";
+  const { onStatusChange } = props;
+  useEffect(() => onStatusChange == null ? void 0 : onStatusChange(liveStatus), [liveStatus, onStatusChange]);
+  if (!step) return null;
+  if (missing && policy === "skip") return null;
+  return /* @__PURE__ */ jsx(FloatingPortal, { ...portalContainer ? { root: portalContainer } : {}, children: /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-tour-id": definition.id,
+      "data-tour-step": step.id,
+      "data-tour-state": navigating ? "navigating" : anchorState.state,
+      children: [
+        /* @__PURE__ */ jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: labels.announce(
+          displayPosition(steps, index),
+          total,
+          typeof step.title === "string" ? step.title : step.id
+        ) }),
+        anchored ? /* @__PURE__ */ jsx(
+          TourSpotlight,
+          {
+            cutout,
+            viewport,
+            interaction,
+            className: props.backdropClassName
+          }
+        ) : null,
+        /* @__PURE__ */ jsx(
+          TourCard,
+          {
+            step,
+            anchor: anchored,
+            current: displayPosition(steps, index),
+            total,
+            labels,
+            blockedHint: missing ? step.hint ?? null : null,
+            canGoBack: backIndex !== null,
+            canGoNext: !blocked,
+            isLast,
+            ...definition.footer ? { footer: definition.footer } : {},
+            onBack: goBack,
+            onNext: goNext,
+            onDismiss,
+            className: props.className
+          }
+        )
+      ]
+    }
+  ) });
+}
+export {
+  Tour
+};
+//# sourceMappingURL=Tour.js.map

package/dist/overlay/Tour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tour.js","sources":["../../src/overlay/Tour.tsx"],"sourcesContent":["import { useEffect, useMemo, useRef, useState } from \"react\";\nimport { FloatingPortal } from \"@floating-ui/react\";\nimport { useHotkey } from \"../hooks/use-hotkey\";\nimport { useEscapeLayer, useTourLayer } from \"./modalStack\";\nimport { TourCard } from \"./TourCard\";\nimport { TourSpotlight } from \"./TourSpotlight\";\nimport {\n  activeSteps,\n  DEFAULT_TOUR_LABELS,\n  displayPosition,\n  nextStepIndex,\n  validateTourDefinition,\n} from \"./tour-model\";\nimport type { TourStatus } from \"./tour-context\";\nimport { useTourAnchor } from \"./use-tour-anchor\";\nimport { useTourRect } from \"./use-tour-rect\";\nimport {\n  useActiveAnchorMarker,\n  useMissingAnchorPolicy,\n  useStepLifecycle,\n  useStepRoute,\n} from \"./use-tour-step\";\nimport type {\n  TourDefinition,\n  TourDirection,\n  TourInteraction,\n  TourLabels,\n  TourMissingAnchor,\n  TourRoot,\n  TourRootSource,\n  TourStepContext,\n  TourStepErrorInfo,\n} from \"./tour-types\";\n\n/**\n * Controlled renderer for one running tour: spotlight + step card + the step\n * lifecycle (exit -> navigate -> wait for anchor -> enter).\n *\n * It contains no `document` lookup of its own — every anchor query goes through\n * tour-anchor.ts against a configurable root, which is what lets the same steps\n * run over a mocked UI inside a shadow root.\n */\n\nconst DEFAULT_ANCHOR_TIMEOUT_MS = 3_000;\nconst DEFAULT_NAVIGATE_TIMEOUT_MS = 8_000;\nconst DEFAULT_PADDING = 8;\n\nexport type TourProps = {\n  /** The tour to render. Validated on first mount. */\n  definition: TourDefinition;\n  /** Zero-based index of the visible step, into `definition.steps`. */\n  index: number;\n  /** Requests a different step; the owner clamps and commits it. */\n  onIndexChange: (index: number, direction: TourDirection) => void;\n  /** The user reached the end. */\n  onComplete: () => void;\n  /** The user left early (Skip, Escape, close). */\n  onDismiss: () => void;\n  /**\n   * Called when the entered step's `route` differs from the route the tour is\n   * already on. The library never imports a router.\n   */\n  onNavigate?: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;\n  /** Where anchors are queried. Defaults to `document`. */\n  anchorRoot?: TourRootSource | undefined;\n  /**\n   * Element the overlay portals into. Defaults to `document.body`. Pass a node\n   * inside your shadow tree so the overlay is shadow-styled and scoped —\n   * `FloatingPortal` takes an HTMLElement, not a ShadowRoot, which is why this is\n   * a separate prop from `anchorRoot`. Note `position: fixed` resolves against a\n   * transformed ancestor, so a transformed container scopes the dim to itself\n   * (wanted for an embedded demo, surprising in an app).\n   */\n  portalContainer?: HTMLElement | null | undefined;\n  /** Policy when an anchor never appears. Defaults to `\"center\"`. */\n  missingAnchor?: TourMissingAnchor | undefined;\n  /** Anchor wait budget for a same-route step, in ms. */\n  anchorTimeoutMs?: number | undefined;\n  /** Anchor wait budget after `onNavigate`, in ms. */\n  navigateTimeoutMs?: number | undefined;\n  /** Default spotlight padding in px. */\n  padding?: number | undefined;\n  /** Pointer behaviour of the dim layer. */\n  interaction?: TourInteraction | undefined;\n  /**\n   * Bind arrow keys to Back/Next. Defaults to true. This preempts arrow-key page\n   * scrolling while the tour runs; set false to keep it.\n   */\n  keyboard?: boolean | undefined;\n  /** Dismiss on Escape. Defaults to true. */\n  closeOnEsc?: boolean | undefined;\n  /** Scroll each anchor into view on entry. Defaults to true. */\n  scrollIntoView?: boolean | undefined;\n  /** Copy overrides; unset keys fall back to `DEFAULT_TOUR_LABELS`. */\n  labels?: Partial<TourLabels> | undefined;\n  /** Reported on every anchor timeout, alongside a console warning. */\n  onStepError?: ((info: TourStepErrorInfo) => void) | undefined;\n  /** Reports the live step state, so a provider can expose it through `useTour()`. */\n  onStatusChange?: ((status: TourStatus) => void) | undefined;\n  /** Classes applied to the step card. */\n  className?: string | undefined;\n  /** Classes applied to the dim layer, e.g. `bg-black/60`. */\n  backdropClassName?: string | undefined;\n};\n\nfunction viewOf(source: TourRootSource): Window | null {\n  const root: TourRoot | null = (typeof source === \"function\" ? source() : source) ?? null;\n  if (!root) return null;\n  if (root instanceof Document) return root.defaultView;\n  return root.ownerDocument?.defaultView ?? null;\n}\n\nfunction useViewport(root: TourRootSource): { width: number; height: number } {\n  const [size, setSize] = useState({ width: 0, height: 0 });\n\n  useEffect(() => {\n    const view = viewOf(root);\n    if (!view) return;\n    const measure = () => setSize({ width: view.innerWidth, height: view.innerHeight });\n    measure();\n    view.addEventListener(\"resize\", measure);\n    return () => view.removeEventListener(\"resize\", measure);\n  }, [root]);\n\n  return size;\n}\n\nexport function Tour(props: TourProps) {\n  const {\n    definition,\n    index,\n    onIndexChange,\n    onComplete,\n    onDismiss,\n    onNavigate,\n    portalContainer,\n    missingAnchor = \"center\",\n    anchorTimeoutMs = DEFAULT_ANCHOR_TIMEOUT_MS,\n    navigateTimeoutMs = DEFAULT_NAVIGATE_TIMEOUT_MS,\n    padding = DEFAULT_PADDING,\n    interaction = \"allow-anchor\",\n    keyboard = true,\n    closeOnEsc = true,\n    scrollIntoView = true,\n    onStepError,\n  } = props;\n\n  // A getter rather than `document` directly, so the default is also safe under\n  // SSR where there is no document to reference at render time.\n  const anchorRoot: TourRootSource = useMemo(\n    () => props.anchorRoot ?? (() => (typeof document === \"undefined\" ? null : document)),\n    [props.anchorRoot],\n  );\n\n  const validated = useRef<string | null>(null);\n  if (validated.current !== definition.id) {\n    validateTourDefinition(definition);\n    validated.current = definition.id;\n  }\n\n  const labels: TourLabels = useMemo(\n    () => ({ ...DEFAULT_TOUR_LABELS, ...props.labels }),\n    [props.labels],\n  );\n\n  const steps = definition.steps;\n  const step = steps[index];\n  const total = activeSteps(steps).length;\n  const viewport = useViewport(anchorRoot);\n\n  const contextSeed = useMemo<TourStepContext | null>(\n    () => (step ? { step, index, total, anchor: null, direction: \"jump\" } : null),\n    [step, index, total],\n  );\n  const { navigating, pendingRoute } = useStepRoute({ step, context: contextSeed, onNavigate });\n\n  const anchorState = useTourAnchor({\n    root: anchorRoot,\n    target: step?.target,\n    timeoutMs:\n      pendingRoute || navigating ? navigateTimeoutMs : (step?.timeoutMs ?? anchorTimeoutMs),\n    scrollIntoView,\n    key: `${definition.id}:${step?.id ?? \"\"}`,\n  });\n\n  const context = useMemo<TourStepContext | null>(\n    () => (step ? { step, index, total, anchor: anchorState.anchor, direction: \"jump\" } : null),\n    [step, index, total, anchorState.anchor],\n  );\n\n  const backIndex = nextStepIndex(steps, index, \"back\");\n  const forwardIndex = nextStepIndex(steps, index, \"next\");\n  const missing = anchorState.state === \"missing\";\n  const policy = step?.onMissing ?? missingAnchor;\n\n  // A step that names what the operator must do is waiting on THEM, so Next stays\n  // shut until its anchor resolves. Advancing anyway would narrate a stop they\n  // never reached.\n  //\n  // The LAST step is exempt: there its button is Done, which ends the tour rather\n  // than moving to an unreachable stop. Blocking it would leave the only exit as\n  // abandoning a tour the operator has otherwise finished — so a tour ending on a\n  // waiting step could never be completed at all.\n  const waiting = missing && step?.hint !== undefined && step.hintOptional !== true;\n  const isLast = forwardIndex === null;\n  const blocked = waiting && !isLast;\n\n  const goNext = () => {\n    if (blocked) return;\n    if (forwardIndex === null) onComplete();\n    else onIndexChange(forwardIndex, \"next\");\n  };\n  const goBack = () => {\n    if (backIndex !== null) onIndexChange(backIndex, \"back\");\n  };\n\n  useMissingAnchorPolicy({\n    definition,\n    step,\n    index,\n    missing,\n    policy,\n    onStepError,\n    onSkip: (next) => (next === null ? onComplete() : onIndexChange(next, \"next\")),\n  });\n  useActiveAnchorMarker(anchorState.anchor);\n  useStepLifecycle({ step, context, settled: anchorState.state !== \"waiting\" });\n\n  useTourLayer(true);\n  useEscapeLayer(true, onDismiss, closeOnEsc);\n  // Lower-case combos: use-hotkey matches against `event.key.toLowerCase()`.\n  useHotkey(\"arrowright\", goNext, { enabled: keyboard, priority: 10 });\n  useHotkey(\"arrowleft\", goBack, { enabled: keyboard, priority: 10 });\n\n  const anchored = anchorState.state === \"found\" ? anchorState.anchor : null;\n  const cutout = useTourRect(anchored, {\n    padding: step?.padding ?? padding,\n    radius: step?.radius,\n  });\n\n  // \"missing\" still shows a card (centred), so it reads as active rather than\n  // leaving the provider stuck reporting a wait that already gave up.\n  const liveStatus: TourStatus = navigating\n    ? \"navigating\"\n    : anchorState.state === \"waiting\"\n      ? \"waiting\"\n      : \"active\";\n  const { onStatusChange } = props;\n  useEffect(() => onStatusChange?.(liveStatus), [liveStatus, onStatusChange]);\n\n  if (!step) return null;\n  if (missing && policy === \"skip\") return null;\n\n  return (\n    <FloatingPortal {...(portalContainer ? { root: portalContainer } : {})}>\n      <div\n        data-tour-id={definition.id}\n        data-tour-step={step.id}\n        data-tour-state={navigating ? \"navigating\" : anchorState.state}\n      >\n        <span role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n          {labels.announce(\n            displayPosition(steps, index),\n            total,\n            typeof step.title === \"string\" ? step.title : step.id,\n          )}\n        </span>\n\n        {anchored ? (\n          <TourSpotlight\n            cutout={cutout}\n            viewport={viewport}\n            interaction={interaction}\n            className={props.backdropClassName}\n          />\n        ) : null}\n\n        <TourCard\n          step={step}\n          anchor={anchored}\n          current={displayPosition(steps, index)}\n          total={total}\n          labels={labels}\n          blockedHint={missing ? (step.hint ?? null) : null}\n          canGoBack={backIndex !== null}\n          canGoNext={!blocked}\n          isLast={isLast}\n          {...(definition.footer ? { footer: definition.footer } : {})}\n          onBack={goBack}\n          onNext={goNext}\n          onDismiss={onDismiss}\n          className={props.className}\n        />\n      </div>\n    </FloatingPortal>\n  );\n}\n"],"names":[],"mappings":"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"}

package/dist/overlay/TourCard.cjs

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const react = require("react");
+const react$1 = require("@floating-ui/react");
+const utils = require("../lib/utils.cjs");
+const button = require("../components/button.cjs");
+const Icon = require("../data/Icon.cjs");
+const zIndex = require("./zIndex.cjs");
+const UiClose = require("../icons/components/UiClose.cjs");
+const UiArrowLeft = require("../icons/components/UiArrowLeft.cjs");
+const UiArrowRight = require("../icons/components/UiArrowRight.cjs");
+const Markdown = react.lazy(
+  () => Promise.resolve().then(() => require("../data/Markdown.cjs")).then((module2) => ({ default: module2.Markdown }))
+);
+const CENTERED_STYLE = {
+  position: "fixed",
+  top: "50%",
+  left: "50%",
+  transform: "translate(-50%, -50%)"
+};
+function StepBody({ step }) {
+  if (step.markdown !== void 0) {
+    return /* @__PURE__ */ jsxRuntime.jsx(react.Suspense, { fallback: /* @__PURE__ */ jsxRuntime.jsx("p", { className: "whitespace-pre-wrap text-sm", children: step.markdown }), children: /* @__PURE__ */ jsxRuntime.jsx(Markdown, { text: step.markdown, className: "text-sm" }) });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "text-sm text-muted-foreground", children: step.body });
+}
+function TourCard(props) {
+  const { step, anchor, current, total, labels, blockedHint, isLast } = props;
+  const titleId = react.useId();
+  const bodyId = react.useId();
+  const placement = step.placement ?? "bottom";
+  const { refs, floatingStyles, context } = react$1.useFloating({
+    open: true,
+    placement,
+    middleware: [react$1.offset(12), react$1.flip(), react$1.shift({ padding: 8 })],
+    whileElementsMounted: react$1.autoUpdate
+  });
+  const { getFloatingProps } = react$1.useInteractions([react$1.useRole(context, { role: "dialog" })]);
+  react.useEffect(() => {
+    if (anchor) refs.setPositionReference(anchor);
+  }, [anchor, refs]);
+  const card = /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      ref: refs.setFloating,
+      role: "dialog",
+      "aria-labelledby": titleId,
+      "aria-describedby": bodyId,
+      "data-tour-card": "",
+      className: utils.cn(
+        "w-[min(22rem,calc(100vw-2rem))] rounded-lg border border-border bg-popover p-density-4 text-popover-foreground shadow-xl",
+        props.className,
+        step.cardClassName
+      ),
+      style: {
+        ...anchor ? floatingStyles : CENTERED_STYLE,
+        zIndex: zIndex.zIndex.tour + zIndex.zIndex.tourCardOffset
+      },
+      ...getFloatingProps(),
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-start justify-between gap-density-2", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { id: titleId, className: "text-sm font-semibold", children: step.title }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            button.Button,
+            {
+              variant: "ghost",
+              size: "icon",
+              className: "-mr-1 -mt-1 size-7",
+              "aria-label": labels.close,
+              onClick: props.onDismiss,
+              children: /* @__PURE__ */ jsxRuntime.jsx(Icon.Icon, { icon: UiClose.UiClose, className: "size-4" })
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsx("div", { id: bodyId, className: "mt-density-2", children: /* @__PURE__ */ jsxRuntime.jsx(StepBody, { step }) }),
+        blockedHint ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-density-2 rounded-md border border-border bg-muted/50 p-density-2 text-xs text-muted-foreground", children: blockedHint }) : null,
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "mt-density-4 flex items-center justify-between gap-density-2", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-xs tabular-nums text-muted-foreground", children: labels.counter(current, total) }),
+          /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-density-2", children: [
+            /* @__PURE__ */ jsxRuntime.jsx(button.Button, { variant: "ghost", size: "sm", onClick: props.onDismiss, children: labels.skip }),
+            /* @__PURE__ */ jsxRuntime.jsxs(
+              button.Button,
+              {
+                variant: "outline",
+                size: "sm",
+                disabled: !props.canGoBack,
+                onClick: props.onBack,
+                children: [
+                  /* @__PURE__ */ jsxRuntime.jsx(Icon.Icon, { icon: UiArrowLeft.UiArrowLeft, className: "size-3.5" }),
+                  labels.back
+                ]
+              }
+            ),
+            /* @__PURE__ */ jsxRuntime.jsxs(button.Button, { size: "sm", disabled: !props.canGoNext, onClick: props.onNext, children: [
+              isLast ? labels.done : labels.next,
+              isLast ? null : /* @__PURE__ */ jsxRuntime.jsx(Icon.Icon, { icon: UiArrowRight.UiArrowRight, className: "size-3.5" })
+            ] })
+          ] })
+        ] }),
+        props.footer ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mt-density-2 border-t border-border pt-density-2 text-xs text-muted-foreground", children: props.footer }) : null
+      ]
+    }
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(react$1.FloatingFocusManager, { context, modal: false, returnFocus: true, initialFocus: -1, children: card });
+}
+exports.TourCard = TourCard;
+//# sourceMappingURL=TourCard.cjs.map

package/dist/overlay/TourCard.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourCard.cjs","sources":["../../src/overlay/TourCard.tsx"],"sourcesContent":["import { lazy, Suspense, useEffect, useId, type ReactNode } from \"react\";\nimport {\n  autoUpdate,\n  flip,\n  FloatingFocusManager,\n  offset,\n  shift,\n  useFloating,\n  useInteractions,\n  useRole,\n} from \"@floating-ui/react\";\nimport type { Placement } from \"@floating-ui/react\";\nimport { cn } from \"../lib/utils\";\nimport { Button } from \"../components/button\";\nimport { Icon } from \"../data/Icon\";\nimport { UiArrowLeft, UiArrowRight, UiClose } from \"../icons\";\nimport type { TourLabels, TourStep } from \"./tour-types\";\nimport { zIndex } from \"./zIndex\";\n\n// `Markdown` pulls in CodeBlock -> shiki/marked. A tour card body is a\n// paragraph, so a consumer with no markdown steps should not carry that graph.\nconst Markdown = lazy(() =>\n  import(\"../data/Markdown\").then((module) => ({ default: module.Markdown })),\n);\n\n/** Where an anchorless step's card sits — the same slot the spotlight would centre on. */\nconst CENTERED_STYLE = {\n  position: \"fixed\",\n  top: \"50%\",\n  left: \"50%\",\n  transform: \"translate(-50%, -50%)\",\n} as const;\n\nexport type TourCardProps = {\n  step: TourStep;\n  anchor: HTMLElement | null;\n  /** 1-based position among enabled steps. */\n  current: number;\n  total: number;\n  labels: TourLabels;\n  /** Shown instead of the nav hint when the step is waiting on the operator. */\n  blockedHint: ReactNode | null;\n  canGoBack: boolean;\n  canGoNext: boolean;\n  isLast: boolean;\n  /** Rendered under the nav row; the tour's link back to its written guide. */\n  footer?: ReactNode;\n  onBack: () => void;\n  onNext: () => void;\n  onDismiss: () => void;\n  className?: string | undefined;\n};\n\nfunction StepBody({ step }: { step: TourStep }) {\n  if (step.markdown !== undefined) {\n    return (\n      <Suspense fallback={<p className=\"whitespace-pre-wrap text-sm\">{step.markdown}</p>}>\n        <Markdown text={step.markdown} className=\"text-sm\" />\n      </Suspense>\n    );\n  }\n  return <div className=\"text-sm text-muted-foreground\">{step.body}</div>;\n}\n\nexport function TourCard(props: TourCardProps) {\n  const { step, anchor, current, total, labels, blockedHint, isLast } = props;\n  const titleId = useId();\n  const bodyId = useId();\n  const placement: Placement = step.placement ?? \"bottom\";\n\n  const { refs, floatingStyles, context } = useFloating({\n    open: true,\n    placement,\n    middleware: [offset(12), flip(), shift({ padding: 8 })],\n    whileElementsMounted: autoUpdate,\n  });\n  const { getFloatingProps } = useInteractions([useRole(context, { role: \"dialog\" })]);\n\n  // In an effect, not during render: setPositionReference schedules a state\n  // update, so calling it inline re-renders forever.\n  useEffect(() => {\n    if (anchor) refs.setPositionReference(anchor);\n  }, [anchor, refs]);\n\n  const card = (\n    <div\n      // Always the floating element so FloatingFocusManager has a node to manage;\n      // only an anchored card takes floating-ui's computed position.\n      ref={refs.setFloating}\n      // No `aria-modal`: it hides the rest of the document from assistive tech,\n      // which would hide the very element the step is describing.\n      role=\"dialog\"\n      aria-labelledby={titleId}\n      aria-describedby={bodyId}\n      data-tour-card=\"\"\n      className={cn(\n        \"w-[min(22rem,calc(100vw-2rem))] rounded-lg border border-border bg-popover p-density-4 text-popover-foreground shadow-xl\",\n        props.className,\n        step.cardClassName,\n      )}\n      // One element in one tree position whether or not there is an anchor: a\n      // structural switch here would unmount and remount the card the moment a\n      // waited-for anchor resolves, losing focus and any in-flight transition.\n      style={{\n        ...(anchor ? floatingStyles : CENTERED_STYLE),\n        zIndex: zIndex.tour + zIndex.tourCardOffset,\n      }}\n      {...getFloatingProps()}\n    >\n      <div className=\"flex items-start justify-between gap-density-2\">\n        <h2 id={titleId} className=\"text-sm font-semibold\">\n          {step.title}\n        </h2>\n        <Button\n          variant=\"ghost\"\n          size=\"icon\"\n          className=\"-mr-1 -mt-1 size-7\"\n          aria-label={labels.close}\n          onClick={props.onDismiss}\n        >\n          <Icon icon={UiClose} className=\"size-4\" />\n        </Button>\n      </div>\n\n      <div id={bodyId} className=\"mt-density-2\">\n        <StepBody step={step} />\n      </div>\n\n      {blockedHint ? (\n        <p className=\"mt-density-2 rounded-md border border-border bg-muted/50 p-density-2 text-xs text-muted-foreground\">\n          {blockedHint}\n        </p>\n      ) : null}\n\n      <div className=\"mt-density-4 flex items-center justify-between gap-density-2\">\n        <span className=\"text-xs tabular-nums text-muted-foreground\">\n          {labels.counter(current, total)}\n        </span>\n        <div className=\"flex items-center gap-density-2\">\n          <Button variant=\"ghost\" size=\"sm\" onClick={props.onDismiss}>\n            {labels.skip}\n          </Button>\n          <Button\n            variant=\"outline\"\n            size=\"sm\"\n            disabled={!props.canGoBack}\n            onClick={props.onBack}\n          >\n            <Icon icon={UiArrowLeft} className=\"size-3.5\" />\n            {labels.back}\n          </Button>\n          <Button size=\"sm\" disabled={!props.canGoNext} onClick={props.onNext}>\n            {isLast ? labels.done : labels.next}\n            {isLast ? null : <Icon icon={UiArrowRight} className=\"size-3.5\" />}\n          </Button>\n        </div>\n      </div>\n\n      {props.footer ? (\n        <div className=\"mt-density-2 border-t border-border pt-density-2 text-xs text-muted-foreground\">\n          {props.footer}\n        </div>\n      ) : null}\n    </div>\n  );\n\n  return (\n    <FloatingFocusManager context={context} modal={false} returnFocus initialFocus={-1}>\n      {card}\n    </FloatingFocusManager>\n  );\n}\n"],"names":["lazy","module","Suspense","jsx","useId","useFloating","offset","flip","shift","autoUpdate","useInteractions","useRole","useEffect","jsxs","cn","zIndex","Button","Icon","UiClose","UiArrowLeft","UiArrowRight","FloatingFocusManager"],"mappings":"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"}

package/dist/overlay/TourCard.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+import { TourLabels, TourStep } from './tour-types';
+export type TourCardProps = {
+    step: TourStep;
+    anchor: HTMLElement | null;
+    /** 1-based position among enabled steps. */
+    current: number;
+    total: number;
+    labels: TourLabels;
+    /** Shown instead of the nav hint when the step is waiting on the operator. */
+    blockedHint: ReactNode | null;
+    canGoBack: boolean;
+    canGoNext: boolean;
+    isLast: boolean;
+    /** Rendered under the nav row; the tour's link back to its written guide. */
+    footer?: ReactNode;
+    onBack: () => void;
+    onNext: () => void;
+    onDismiss: () => void;
+    className?: string | undefined;
+};
+export declare function TourCard(props: TourCardProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=TourCard.d.ts.map

package/dist/overlay/TourCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourCard.d.ts","sourceRoot":"","sources":["../../src/overlay/TourCard.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAgBzE,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAiBzD,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,8EAA8E;IAC9E,WAAW,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAaF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,2CA2G5C"}

package/dist/overlay/TourCard.js

@@ -0,0 +1,108 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import { useId, useEffect, Suspense, lazy } from "react";
+import { useFloating, autoUpdate, offset, flip, shift, useInteractions, useRole, FloatingFocusManager } from "@floating-ui/react";
+import { cn } from "../lib/utils.js";
+import { Button } from "../components/button.js";
+import { Icon } from "../data/Icon.js";
+import { zIndex } from "./zIndex.js";
+import { UiClose } from "../icons/components/UiClose.js";
+import { UiArrowLeft } from "../icons/components/UiArrowLeft.js";
+import { UiArrowRight } from "../icons/components/UiArrowRight.js";
+const Markdown = lazy(
+  () => import("../data/Markdown.js").then((module) => ({ default: module.Markdown }))
+);
+const CENTERED_STYLE = {
+  position: "fixed",
+  top: "50%",
+  left: "50%",
+  transform: "translate(-50%, -50%)"
+};
+function StepBody({ step }) {
+  if (step.markdown !== void 0) {
+    return /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx("p", { className: "whitespace-pre-wrap text-sm", children: step.markdown }), children: /* @__PURE__ */ jsx(Markdown, { text: step.markdown, className: "text-sm" }) });
+  }
+  return /* @__PURE__ */ jsx("div", { className: "text-sm text-muted-foreground", children: step.body });
+}
+function TourCard(props) {
+  const { step, anchor, current, total, labels, blockedHint, isLast } = props;
+  const titleId = useId();
+  const bodyId = useId();
+  const placement = step.placement ?? "bottom";
+  const { refs, floatingStyles, context } = useFloating({
+    open: true,
+    placement,
+    middleware: [offset(12), flip(), shift({ padding: 8 })],
+    whileElementsMounted: autoUpdate
+  });
+  const { getFloatingProps } = useInteractions([useRole(context, { role: "dialog" })]);
+  useEffect(() => {
+    if (anchor) refs.setPositionReference(anchor);
+  }, [anchor, refs]);
+  const card = /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: refs.setFloating,
+      role: "dialog",
+      "aria-labelledby": titleId,
+      "aria-describedby": bodyId,
+      "data-tour-card": "",
+      className: cn(
+        "w-[min(22rem,calc(100vw-2rem))] rounded-lg border border-border bg-popover p-density-4 text-popover-foreground shadow-xl",
+        props.className,
+        step.cardClassName
+      ),
+      style: {
+        ...anchor ? floatingStyles : CENTERED_STYLE,
+        zIndex: zIndex.tour + zIndex.tourCardOffset
+      },
+      ...getFloatingProps(),
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: "flex items-start justify-between gap-density-2", children: [
+          /* @__PURE__ */ jsx("h2", { id: titleId, className: "text-sm font-semibold", children: step.title }),
+          /* @__PURE__ */ jsx(
+            Button,
+            {
+              variant: "ghost",
+              size: "icon",
+              className: "-mr-1 -mt-1 size-7",
+              "aria-label": labels.close,
+              onClick: props.onDismiss,
+              children: /* @__PURE__ */ jsx(Icon, { icon: UiClose, className: "size-4" })
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsx("div", { id: bodyId, className: "mt-density-2", children: /* @__PURE__ */ jsx(StepBody, { step }) }),
+        blockedHint ? /* @__PURE__ */ jsx("p", { className: "mt-density-2 rounded-md border border-border bg-muted/50 p-density-2 text-xs text-muted-foreground", children: blockedHint }) : null,
+        /* @__PURE__ */ jsxs("div", { className: "mt-density-4 flex items-center justify-between gap-density-2", children: [
+          /* @__PURE__ */ jsx("span", { className: "text-xs tabular-nums text-muted-foreground", children: labels.counter(current, total) }),
+          /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-density-2", children: [
+            /* @__PURE__ */ jsx(Button, { variant: "ghost", size: "sm", onClick: props.onDismiss, children: labels.skip }),
+            /* @__PURE__ */ jsxs(
+              Button,
+              {
+                variant: "outline",
+                size: "sm",
+                disabled: !props.canGoBack,
+                onClick: props.onBack,
+                children: [
+                  /* @__PURE__ */ jsx(Icon, { icon: UiArrowLeft, className: "size-3.5" }),
+                  labels.back
+                ]
+              }
+            ),
+            /* @__PURE__ */ jsxs(Button, { size: "sm", disabled: !props.canGoNext, onClick: props.onNext, children: [
+              isLast ? labels.done : labels.next,
+              isLast ? null : /* @__PURE__ */ jsx(Icon, { icon: UiArrowRight, className: "size-3.5" })
+            ] })
+          ] })
+        ] }),
+        props.footer ? /* @__PURE__ */ jsx("div", { className: "mt-density-2 border-t border-border pt-density-2 text-xs text-muted-foreground", children: props.footer }) : null
+      ]
+    }
+  );
+  return /* @__PURE__ */ jsx(FloatingFocusManager, { context, modal: false, returnFocus: true, initialFocus: -1, children: card });
+}
+export {
+  TourCard
+};
+//# sourceMappingURL=TourCard.js.map

package/dist/overlay/TourCard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourCard.js","sources":["../../src/overlay/TourCard.tsx"],"sourcesContent":["import { lazy, Suspense, useEffect, useId, type ReactNode } from \"react\";\nimport {\n  autoUpdate,\n  flip,\n  FloatingFocusManager,\n  offset,\n  shift,\n  useFloating,\n  useInteractions,\n  useRole,\n} from \"@floating-ui/react\";\nimport type { Placement } from \"@floating-ui/react\";\nimport { cn } from \"../lib/utils\";\nimport { Button } from \"../components/button\";\nimport { Icon } from \"../data/Icon\";\nimport { UiArrowLeft, UiArrowRight, UiClose } from \"../icons\";\nimport type { TourLabels, TourStep } from \"./tour-types\";\nimport { zIndex } from \"./zIndex\";\n\n// `Markdown` pulls in CodeBlock -> shiki/marked. A tour card body is a\n// paragraph, so a consumer with no markdown steps should not carry that graph.\nconst Markdown = lazy(() =>\n  import(\"../data/Markdown\").then((module) => ({ default: module.Markdown })),\n);\n\n/** Where an anchorless step's card sits — the same slot the spotlight would centre on. */\nconst CENTERED_STYLE = {\n  position: \"fixed\",\n  top: \"50%\",\n  left: \"50%\",\n  transform: \"translate(-50%, -50%)\",\n} as const;\n\nexport type TourCardProps = {\n  step: TourStep;\n  anchor: HTMLElement | null;\n  /** 1-based position among enabled steps. */\n  current: number;\n  total: number;\n  labels: TourLabels;\n  /** Shown instead of the nav hint when the step is waiting on the operator. */\n  blockedHint: ReactNode | null;\n  canGoBack: boolean;\n  canGoNext: boolean;\n  isLast: boolean;\n  /** Rendered under the nav row; the tour's link back to its written guide. */\n  footer?: ReactNode;\n  onBack: () => void;\n  onNext: () => void;\n  onDismiss: () => void;\n  className?: string | undefined;\n};\n\nfunction StepBody({ step }: { step: TourStep }) {\n  if (step.markdown !== undefined) {\n    return (\n      <Suspense fallback={<p className=\"whitespace-pre-wrap text-sm\">{step.markdown}</p>}>\n        <Markdown text={step.markdown} className=\"text-sm\" />\n      </Suspense>\n    );\n  }\n  return <div className=\"text-sm text-muted-foreground\">{step.body}</div>;\n}\n\nexport function TourCard(props: TourCardProps) {\n  const { step, anchor, current, total, labels, blockedHint, isLast } = props;\n  const titleId = useId();\n  const bodyId = useId();\n  const placement: Placement = step.placement ?? \"bottom\";\n\n  const { refs, floatingStyles, context } = useFloating({\n    open: true,\n    placement,\n    middleware: [offset(12), flip(), shift({ padding: 8 })],\n    whileElementsMounted: autoUpdate,\n  });\n  const { getFloatingProps } = useInteractions([useRole(context, { role: \"dialog\" })]);\n\n  // In an effect, not during render: setPositionReference schedules a state\n  // update, so calling it inline re-renders forever.\n  useEffect(() => {\n    if (anchor) refs.setPositionReference(anchor);\n  }, [anchor, refs]);\n\n  const card = (\n    <div\n      // Always the floating element so FloatingFocusManager has a node to manage;\n      // only an anchored card takes floating-ui's computed position.\n      ref={refs.setFloating}\n      // No `aria-modal`: it hides the rest of the document from assistive tech,\n      // which would hide the very element the step is describing.\n      role=\"dialog\"\n      aria-labelledby={titleId}\n      aria-describedby={bodyId}\n      data-tour-card=\"\"\n      className={cn(\n        \"w-[min(22rem,calc(100vw-2rem))] rounded-lg border border-border bg-popover p-density-4 text-popover-foreground shadow-xl\",\n        props.className,\n        step.cardClassName,\n      )}\n      // One element in one tree position whether or not there is an anchor: a\n      // structural switch here would unmount and remount the card the moment a\n      // waited-for anchor resolves, losing focus and any in-flight transition.\n      style={{\n        ...(anchor ? floatingStyles : CENTERED_STYLE),\n        zIndex: zIndex.tour + zIndex.tourCardOffset,\n      }}\n      {...getFloatingProps()}\n    >\n      <div className=\"flex items-start justify-between gap-density-2\">\n        <h2 id={titleId} className=\"text-sm font-semibold\">\n          {step.title}\n        </h2>\n        <Button\n          variant=\"ghost\"\n          size=\"icon\"\n          className=\"-mr-1 -mt-1 size-7\"\n          aria-label={labels.close}\n          onClick={props.onDismiss}\n        >\n          <Icon icon={UiClose} className=\"size-4\" />\n        </Button>\n      </div>\n\n      <div id={bodyId} className=\"mt-density-2\">\n        <StepBody step={step} />\n      </div>\n\n      {blockedHint ? (\n        <p className=\"mt-density-2 rounded-md border border-border bg-muted/50 p-density-2 text-xs text-muted-foreground\">\n          {blockedHint}\n        </p>\n      ) : null}\n\n      <div className=\"mt-density-4 flex items-center justify-between gap-density-2\">\n        <span className=\"text-xs tabular-nums text-muted-foreground\">\n          {labels.counter(current, total)}\n        </span>\n        <div className=\"flex items-center gap-density-2\">\n          <Button variant=\"ghost\" size=\"sm\" onClick={props.onDismiss}>\n            {labels.skip}\n          </Button>\n          <Button\n            variant=\"outline\"\n            size=\"sm\"\n            disabled={!props.canGoBack}\n            onClick={props.onBack}\n          >\n            <Icon icon={UiArrowLeft} className=\"size-3.5\" />\n            {labels.back}\n          </Button>\n          <Button size=\"sm\" disabled={!props.canGoNext} onClick={props.onNext}>\n            {isLast ? labels.done : labels.next}\n            {isLast ? null : <Icon icon={UiArrowRight} className=\"size-3.5\" />}\n          </Button>\n        </div>\n      </div>\n\n      {props.footer ? (\n        <div className=\"mt-density-2 border-t border-border pt-density-2 text-xs text-muted-foreground\">\n          {props.footer}\n        </div>\n      ) : null}\n    </div>\n  );\n\n  return (\n    <FloatingFocusManager context={context} modal={false} returnFocus initialFocus={-1}>\n      {card}\n    </FloatingFocusManager>\n  );\n}\n"],"names":[],"mappings":";;;;;;;;;;AAqBA,MAAM,WAAW;AAAA,EAAK,MACpB,OAAO,qBAAkB,EAAE,KAAK,CAAC,YAAY,EAAE,SAAS,OAAO,WAAW;AAC5E;AAGA,MAAM,iBAAiB;AAAA,EACrB,UAAU;AAAA,EACV,KAAK;AAAA,EACL,MAAM;AAAA,EACN,WAAW;AACb;AAsBA,SAAS,SAAS,EAAE,QAA4B;AAC9C,MAAI,KAAK,aAAa,QAAW;AAC/B,+BACG,UAAA,EAAS,UAAU,oBAAC,KAAA,EAAE,WAAU,+BAA+B,UAAA,KAAK,UAAS,GAC5E,8BAAC,UAAA,EAAS,MAAM,KAAK,UAAU,WAAU,WAAU,GACrD;AAAA,EAEJ;AACA,SAAO,oBAAC,OAAA,EAAI,WAAU,iCAAiC,eAAK,MAAK;AACnE;AAEO,SAAS,SAAS,OAAsB;AAC7C,QAAM,EAAE,MAAM,QAAQ,SAAS,OAAO,QAAQ,aAAa,WAAW;AACtE,QAAM,UAAU,MAAA;AAChB,QAAM,SAAS,MAAA;AACf,QAAM,YAAuB,KAAK,aAAa;AAE/C,QAAM,EAAE,MAAM,gBAAgB,QAAA,IAAY,YAAY;AAAA,IACpD,MAAM;AAAA,IACN;AAAA,IACA,YAAY,CAAC,OAAO,EAAE,GAAG,QAAQ,MAAM,EAAE,SAAS,EAAA,CAAG,CAAC;AAAA,IACtD,sBAAsB;AAAA,EAAA,CACvB;AACD,QAAM,EAAE,qBAAqB,gBAAgB,CAAC,QAAQ,SAAS,EAAE,MAAM,SAAA,CAAU,CAAC,CAAC;AAInF,YAAU,MAAM;AACd,QAAI,OAAQ,MAAK,qBAAqB,MAAM;AAAA,EAC9C,GAAG,CAAC,QAAQ,IAAI,CAAC;AAEjB,QAAM,OACJ;AAAA,IAAC;AAAA,IAAA;AAAA,MAGC,KAAK,KAAK;AAAA,MAGV,MAAK;AAAA,MACL,mBAAiB;AAAA,MACjB,oBAAkB;AAAA,MAClB,kBAAe;AAAA,MACf,WAAW;AAAA,QACT;AAAA,QACA,MAAM;AAAA,QACN,KAAK;AAAA,MAAA;AAAA,MAKP,OAAO;AAAA,QACL,GAAI,SAAS,iBAAiB;AAAA,QAC9B,QAAQ,OAAO,OAAO,OAAO;AAAA,MAAA;AAAA,MAE9B,GAAG,iBAAA;AAAA,MAEJ,UAAA;AAAA,QAAA,qBAAC,OAAA,EAAI,WAAU,kDACb,UAAA;AAAA,UAAA,oBAAC,QAAG,IAAI,SAAS,WAAU,yBACxB,eAAK,OACR;AAAA,UACA;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,SAAQ;AAAA,cACR,MAAK;AAAA,cACL,WAAU;AAAA,cACV,cAAY,OAAO;AAAA,cACnB,SAAS,MAAM;AAAA,cAEf,UAAA,oBAAC,MAAA,EAAK,MAAM,SAAS,WAAU,SAAA,CAAS;AAAA,YAAA;AAAA,UAAA;AAAA,QAC1C,GACF;AAAA,QAEA,oBAAC,SAAI,IAAI,QAAQ,WAAU,gBACzB,UAAA,oBAAC,UAAA,EAAS,KAAA,CAAY,EAAA,CACxB;AAAA,QAEC,cACC,oBAAC,KAAA,EAAE,WAAU,sGACV,uBACH,IACE;AAAA,QAEJ,qBAAC,OAAA,EAAI,WAAU,gEACb,UAAA;AAAA,UAAA,oBAAC,UAAK,WAAU,8CACb,iBAAO,QAAQ,SAAS,KAAK,GAChC;AAAA,UACA,qBAAC,OAAA,EAAI,WAAU,mCACb,UAAA;AAAA,YAAA,oBAAC,QAAA,EAAO,SAAQ,SAAQ,MAAK,MAAK,SAAS,MAAM,WAC9C,UAAA,OAAO,KAAA,CACV;AAAA,YACA;AAAA,cAAC;AAAA,cAAA;AAAA,gBACC,SAAQ;AAAA,gBACR,MAAK;AAAA,gBACL,UAAU,CAAC,MAAM;AAAA,gBACjB,SAAS,MAAM;AAAA,gBAEf,UAAA;AAAA,kBAAA,oBAAC,MAAA,EAAK,MAAM,aAAa,WAAU,YAAW;AAAA,kBAC7C,OAAO;AAAA,gBAAA;AAAA,cAAA;AAAA,YAAA;AAAA,YAEV,qBAAC,QAAA,EAAO,MAAK,MAAK,UAAU,CAAC,MAAM,WAAW,SAAS,MAAM,QAC1D,UAAA;AAAA,cAAA,SAAS,OAAO,OAAO,OAAO;AAAA,cAC9B,SAAS,OAAO,oBAAC,QAAK,MAAM,cAAc,WAAU,WAAA,CAAW;AAAA,YAAA,EAAA,CAClE;AAAA,UAAA,EAAA,CACF;AAAA,QAAA,GACF;AAAA,QAEC,MAAM,SACL,oBAAC,OAAA,EAAI,WAAU,kFACZ,UAAA,MAAM,QACT,IACE;AAAA,MAAA;AAAA,IAAA;AAAA,EAAA;AAIR,SACE,oBAAC,wBAAqB,SAAkB,OAAO,OAAO,aAAW,MAAC,cAAc,IAC7E,UAAA,KAAA,CACH;AAEJ;"}

package/dist/overlay/TourProvider.cjs

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const react = require("react");
+const Tour = require("./Tour.cjs");
+const tourContext = require("./tour-context.cjs");
+const tourModel = require("./tour-model.cjs");
+const tourProgress = require("./tour-progress.cjs");
+function normalizeRoute(route) {
+  return route.length > 1 && route.endsWith("/") ? route.slice(0, -1) : route;
+}
+function defaultMatchRoute(tourRoute, currentRoute) {
+  return normalizeRoute(tourRoute) === normalizeRoute(currentRoute);
+}
+function TourProvider(props) {
+  const {
+    children,
+    tours,
+    currentRoute,
+    matchRoute = defaultMatchRoute,
+    onNavigate,
+    onFinish,
+    defaults
+  } = props;
+  const storage = react.useMemo(() => props.storage ?? tourProgress.localStorageTourStorage(), [props.storage]);
+  const [completions, setCompletions] = react.useState(null);
+  const [running, setRunning] = react.useState(null);
+  const [status, setStatus] = react.useState("idle");
+  for (const definition2 of tours) tourModel.validateTourDefinition(definition2);
+  react.useEffect(() => {
+    let cancelled = false;
+    void Promise.resolve(storage.read()).then((entries) => {
+      if (!cancelled) setCompletions(entries);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [storage]);
+  const definitionOf = react.useCallback(
+    (tourId) => {
+      const found = tours.find((tour) => tour.id === tourId);
+      if (!found) throw new Error(`Unknown tour "${tourId}"`);
+      return found;
+    },
+    [tours]
+  );
+  const isFinished = react.useCallback(
+    (tourId) => tourProgress.isTourFinished(completions ?? [], definitionOf(tourId)),
+    [completions, definitionOf]
+  );
+  const start = react.useCallback(
+    (tourId, options = {}) => {
+      const definition2 = definitionOf(tourId);
+      if (!options.force && tourProgress.isTourFinished(completions ?? [], definition2)) return;
+      const index = options.at === void 0 ? 0 : tourModel.resolveStepIndex(definition2.steps, options.at);
+      setRunning({ tourId, index });
+      setStatus("waiting");
+    },
+    [completions, definitionOf]
+  );
+  const runningRef = react.useRef(running);
+  runningRef.current = running;
+  const finish = react.useCallback(
+    (completionStatus = "dismissed") => {
+      const current = runningRef.current;
+      if (!current) return;
+      const definition2 = definitionOf(current.tourId);
+      const entry = {
+        tourId: current.tourId,
+        status: completionStatus,
+        version: definition2.version ?? 1,
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      void storage.write(entry);
+      setCompletions((prev) => [...(prev ?? []).filter((e) => e.tourId !== entry.tourId), entry]);
+      setRunning(null);
+      setStatus("idle");
+      onFinish == null ? void 0 : onFinish({ tourId: current.tourId, status: completionStatus, index: current.index });
+    },
+    [definitionOf, onFinish, storage]
+  );
+  const reset = react.useCallback(
+    (tourId) => {
+      void storage.clear(tourId);
+      setCompletions((prev) => tourId ? (prev ?? []).filter((e) => e.tourId !== tourId) : []);
+    },
+    [storage]
+  );
+  const step = react.useCallback(
+    (direction) => {
+      const current = runningRef.current;
+      if (!current) return;
+      const target = tourModel.nextStepIndex(definitionOf(current.tourId).steps, current.index, direction);
+      if (target === null) {
+        if (direction === "next") finish("completed");
+        return;
+      }
+      setRunning({ ...current, index: target });
+    },
+    [definitionOf, finish]
+  );
+  const goTo = react.useCallback(
+    (step2) => {
+      setRunning((current) => {
+        if (!current) return current;
+        return { ...current, index: tourModel.resolveStepIndex(definitionOf(current.tourId).steps, step2) };
+      });
+    },
+    [definitionOf]
+  );
+  react.useEffect(() => {
+    var _a;
+    if (completions === null || running || currentRoute === void 0) return;
+    for (const definition2 of tours) {
+      if (!definition2.autoStart) continue;
+      const route = definition2.autoStartRoute ?? ((_a = definition2.steps[0]) == null ? void 0 : _a.route);
+      if (route === void 0 || !matchRoute(route, currentRoute)) continue;
+      if (tourProgress.isTourFinished(completions, definition2)) continue;
+      setRunning({ tourId: definition2.id, index: 0 });
+      setStatus("waiting");
+      return;
+    }
+  }, [completions, running, currentRoute, tours, matchRoute]);
+  const definition = running ? definitionOf(running.tourId) : null;
+  const value = react.useMemo(
+    () => ({
+      tourId: (running == null ? void 0 : running.tourId) ?? null,
+      index: (running == null ? void 0 : running.index) ?? 0,
+      total: definition ? tourModel.activeSteps(definition.steps).length : 0,
+      status,
+      start,
+      next: () => step("next"),
+      back: () => step("back"),
+      goTo,
+      finish,
+      isFinished,
+      reset,
+      tours
+    }),
+    [running, definition, status, start, step, goTo, finish, isFinished, reset, tours]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsxs(tourContext.TourContext.Provider, { value, children: [
+    children,
+    definition && running ? /* @__PURE__ */ jsxRuntime.jsx(
+      Tour.Tour,
+      {
+        ...defaults,
+        definition,
+        index: running.index,
+        onIndexChange: (index) => setRunning({ tourId: running.tourId, index }),
+        onComplete: () => finish("completed"),
+        onDismiss: () => finish("dismissed"),
+        onStatusChange: setStatus,
+        ...onNavigate ? { onNavigate } : {}
+      }
+    ) : null
+  ] });
+}
+exports.TourProvider = TourProvider;
+//# sourceMappingURL=TourProvider.cjs.map