@flanksource/clicky-ui 0.3.16 → 0.3.18

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

package/dist/overlay/TourProvider.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourProvider.cjs","sources":["../../src/overlay/TourProvider.tsx"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from \"react\";\nimport { Tour, type TourProps } from \"./Tour\";\nimport { TourContext, type TourContextValue, type TourStatus } from \"./tour-context\";\nimport { activeSteps, nextStepIndex, resolveStepIndex, validateTourDefinition } from \"./tour-model\";\nimport {\n  isTourFinished,\n  localStorageTourStorage,\n  type TourCompletion,\n  type TourCompletionStatus,\n  type TourStorage,\n} from \"./tour-progress\";\nimport type { TourDefinition, TourStepContext } from \"./tour-types\";\n\n/**\n * Registry + running state + completion persistence for guided tours. Renders at\n * most one `<Tour>`; everything else reaches it through `useTour()`.\n */\n\nexport type TourProviderProps = {\n  children: ReactNode;\n  /** Tours available to `start(id)`. Each is validated on registration. */\n  tours: TourDefinition[];\n  /** The app's current route. Used only for auto-start eligibility, never for step sequencing. */\n  currentRoute?: string | undefined;\n  /** Auto-start route matcher. Defaults to exact match with the trailing slash normalised. */\n  matchRoute?: ((tourRoute: string, currentRoute: string) => boolean) | undefined;\n  /** Navigation callback threaded into every tour. Required for multi-route tours. */\n  onNavigate?: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;\n  /** Completion persistence. Defaults to `localStorageTourStorage()`. */\n  storage?: TourStorage | undefined;\n  /** Fired when a tour ends, either way. */\n  onFinish?:\n    | ((result: { tourId: string; status: TourCompletionStatus; index: number }) => void)\n    | undefined;\n  /** Defaults shared by every tour; an explicit `<Tour>` prop still wins. */\n  defaults?:\n    | Pick<\n        TourProps,\n        | \"anchorRoot\"\n        | \"portalContainer\"\n        | \"missingAnchor\"\n        | \"anchorTimeoutMs\"\n        | \"navigateTimeoutMs\"\n        | \"padding\"\n        | \"interaction\"\n        | \"keyboard\"\n        | \"closeOnEsc\"\n        | \"scrollIntoView\"\n        | \"labels\"\n        | \"onStepError\"\n        | \"backdropClassName\"\n      >\n    | undefined;\n};\n\nfunction normalizeRoute(route: string): string {\n  return route.length > 1 && route.endsWith(\"/\") ? route.slice(0, -1) : route;\n}\n\nfunction defaultMatchRoute(tourRoute: string, currentRoute: string): boolean {\n  return normalizeRoute(tourRoute) === normalizeRoute(currentRoute);\n}\n\ntype Running = { tourId: string; index: number };\n\nexport function TourProvider(props: TourProviderProps) {\n  const {\n    children,\n    tours,\n    currentRoute,\n    matchRoute = defaultMatchRoute,\n    onNavigate,\n    onFinish,\n    defaults,\n  } = props;\n\n  const storage = useMemo(() => props.storage ?? localStorageTourStorage(), [props.storage]);\n  const [completions, setCompletions] = useState<TourCompletion[] | null>(null);\n  const [running, setRunning] = useState<Running | null>(null);\n  const [status, setStatus] = useState<TourStatus>(\"idle\");\n\n  for (const definition of tours) validateTourDefinition(definition);\n\n  // Auto-start is gated behind this read so a first-run tour never flashes before\n  // we know it was already seen.\n  useEffect(() => {\n    let cancelled = false;\n    void Promise.resolve(storage.read()).then((entries) => {\n      if (!cancelled) setCompletions(entries);\n    });\n    return () => {\n      cancelled = true;\n    };\n  }, [storage]);\n\n  const definitionOf = useCallback(\n    (tourId: string): TourDefinition => {\n      const found = tours.find((tour) => tour.id === tourId);\n      if (!found) throw new Error(`Unknown tour \"${tourId}\"`);\n      return found;\n    },\n    [tours],\n  );\n\n  const isFinished = useCallback(\n    (tourId: string) => isTourFinished(completions ?? [], definitionOf(tourId)),\n    [completions, definitionOf],\n  );\n\n  const start = useCallback<TourContextValue[\"start\"]>(\n    (tourId, options = {}) => {\n      const definition = definitionOf(tourId);\n      if (!options.force && isTourFinished(completions ?? [], definition)) return;\n      const index = options.at === undefined ? 0 : resolveStepIndex(definition.steps, options.at);\n      setRunning({ tourId, index });\n      setStatus(\"waiting\");\n    },\n    [completions, definitionOf],\n  );\n\n  const runningRef = useRef(running);\n  runningRef.current = running;\n\n  const finish = useCallback<TourContextValue[\"finish\"]>(\n    (completionStatus = \"dismissed\") => {\n      const current = runningRef.current;\n      if (!current) return;\n      const definition = definitionOf(current.tourId);\n      const entry: TourCompletion = {\n        tourId: current.tourId,\n        status: completionStatus,\n        version: definition.version ?? 1,\n        at: new Date().toISOString(),\n      };\n      void storage.write(entry);\n      setCompletions((prev) => [...(prev ?? []).filter((e) => e.tourId !== entry.tourId), entry]);\n      setRunning(null);\n      setStatus(\"idle\");\n      onFinish?.({ tourId: current.tourId, status: completionStatus, index: current.index });\n    },\n    [definitionOf, onFinish, storage],\n  );\n\n  const reset = useCallback<TourContextValue[\"reset\"]>(\n    (tourId) => {\n      void storage.clear(tourId);\n      setCompletions((prev) => (tourId ? (prev ?? []).filter((e) => e.tourId !== tourId) : []));\n    },\n    [storage],\n  );\n\n  // Honours `enabled()` so a programmatic next/back lands where the card's own\n  // buttons would, rather than on a step the tour is skipping.\n  const step = useCallback(\n    (direction: \"next\" | \"back\") => {\n      const current = runningRef.current;\n      if (!current) return;\n      const target = nextStepIndex(definitionOf(current.tourId).steps, current.index, direction);\n      if (target === null) {\n        if (direction === \"next\") finish(\"completed\");\n        return;\n      }\n      setRunning({ ...current, index: target });\n    },\n    [definitionOf, finish],\n  );\n\n  const goTo = useCallback<TourContextValue[\"goTo\"]>(\n    (step) => {\n      setRunning((current) => {\n        if (!current) return current;\n        return { ...current, index: resolveStepIndex(definitionOf(current.tourId).steps, step) };\n      });\n    },\n    [definitionOf],\n  );\n\n  // Auto-start: only on the declared route, only once the completions are known.\n  useEffect(() => {\n    if (completions === null || running || currentRoute === undefined) return;\n    for (const definition of tours) {\n      if (!definition.autoStart) continue;\n      const route = definition.autoStartRoute ?? definition.steps[0]?.route;\n      if (route === undefined || !matchRoute(route, currentRoute)) continue;\n      if (isTourFinished(completions, definition)) continue;\n      setRunning({ tourId: definition.id, index: 0 });\n      setStatus(\"waiting\");\n      return;\n    }\n  }, [completions, running, currentRoute, tours, matchRoute]);\n\n  const definition = running ? definitionOf(running.tourId) : null;\n\n  const value = useMemo<TourContextValue>(\n    () => ({\n      tourId: running?.tourId ?? null,\n      index: running?.index ?? 0,\n      total: definition ? activeSteps(definition.steps).length : 0,\n      status,\n      start,\n      next: () => step(\"next\"),\n      back: () => step(\"back\"),\n      goTo,\n      finish,\n      isFinished,\n      reset,\n      tours,\n    }),\n    [running, definition, status, start, step, goTo, finish, isFinished, reset, tours],\n  );\n\n  return (\n    <TourContext.Provider value={value}>\n      {children}\n      {definition && running ? (\n        <Tour\n          {...defaults}\n          definition={definition}\n          index={running.index}\n          onIndexChange={(index) => setRunning({ tourId: running.tourId, index })}\n          onComplete={() => finish(\"completed\")}\n          onDismiss={() => finish(\"dismissed\")}\n          onStatusChange={setStatus}\n          {...(onNavigate ? { onNavigate } : {})}\n        />\n      ) : null}\n    </TourContext.Provider>\n  );\n}\n"],"names":["useMemo","localStorageTourStorage","useState","definition","validateTourDefinition","useEffect","useCallback","isTourFinished","resolveStepIndex","useRef","nextStepIndex","step","activeSteps","jsxs","TourContext","jsx","Tour"],"mappings":"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"}

package/dist/overlay/TourProvider.d.ts

@@ -0,0 +1,31 @@
+import { ReactNode } from 'react';
+import { TourProps } from './Tour';
+import { TourCompletionStatus, TourStorage } from './tour-progress';
+import { TourDefinition, TourStepContext } from './tour-types';
+/**
+ * Registry + running state + completion persistence for guided tours. Renders at
+ * most one `<Tour>`; everything else reaches it through `useTour()`.
+ */
+export type TourProviderProps = {
+    children: ReactNode;
+    /** Tours available to `start(id)`. Each is validated on registration. */
+    tours: TourDefinition[];
+    /** The app's current route. Used only for auto-start eligibility, never for step sequencing. */
+    currentRoute?: string | undefined;
+    /** Auto-start route matcher. Defaults to exact match with the trailing slash normalised. */
+    matchRoute?: ((tourRoute: string, currentRoute: string) => boolean) | undefined;
+    /** Navigation callback threaded into every tour. Required for multi-route tours. */
+    onNavigate?: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;
+    /** Completion persistence. Defaults to `localStorageTourStorage()`. */
+    storage?: TourStorage | undefined;
+    /** Fired when a tour ends, either way. */
+    onFinish?: ((result: {
+        tourId: string;
+        status: TourCompletionStatus;
+        index: number;
+    }) => void) | undefined;
+    /** Defaults shared by every tour; an explicit `<Tour>` prop still wins. */
+    defaults?: Pick<TourProps, "anchorRoot" | "portalContainer" | "missingAnchor" | "anchorTimeoutMs" | "navigateTimeoutMs" | "padding" | "interaction" | "keyboard" | "closeOnEsc" | "scrollIntoView" | "labels" | "onStepError" | "backdropClassName"> | undefined;
+};
+export declare function TourProvider(props: TourProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=TourProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TourProvider.d.ts","sourceRoot":"","sources":["../../src/overlay/TourProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1F,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpE;;;GAGG;AAEH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,yEAAyE;IACzE,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4FAA4F;IAC5F,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChF,oFAAoF;IACpF,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IACzF,uEAAuE;IACvE,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,EACL,CAAC,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,oBAAoB,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GACnF,SAAS,CAAC;IACd,2EAA2E;IAC3E,QAAQ,CAAC,EACL,IAAI,CACF,SAAS,EACP,YAAY,GACZ,iBAAiB,GACjB,eAAe,GACf,iBAAiB,GACjB,mBAAmB,GACnB,SAAS,GACT,aAAa,GACb,UAAU,GACV,YAAY,GACZ,gBAAgB,GAChB,QAAQ,GACR,aAAa,GACb,mBAAmB,CACtB,GACD,SAAS,CAAC;CACf,CAAC;AAYF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,2CAmKpD"}

package/dist/overlay/TourProvider.js

@@ -0,0 +1,160 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import { useMemo, useState, useEffect, useCallback, useRef } from "react";
+import { Tour } from "./Tour.js";
+import { TourContext } from "./tour-context.js";
+import { validateTourDefinition, resolveStepIndex, nextStepIndex, activeSteps } from "./tour-model.js";
+import { localStorageTourStorage, isTourFinished } from "./tour-progress.js";
+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 = useMemo(() => props.storage ?? localStorageTourStorage(), [props.storage]);
+  const [completions, setCompletions] = useState(null);
+  const [running, setRunning] = useState(null);
+  const [status, setStatus] = useState("idle");
+  for (const definition2 of tours) validateTourDefinition(definition2);
+  useEffect(() => {
+    let cancelled = false;
+    void Promise.resolve(storage.read()).then((entries) => {
+      if (!cancelled) setCompletions(entries);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [storage]);
+  const definitionOf = useCallback(
+    (tourId) => {
+      const found = tours.find((tour) => tour.id === tourId);
+      if (!found) throw new Error(`Unknown tour "${tourId}"`);
+      return found;
+    },
+    [tours]
+  );
+  const isFinished = useCallback(
+    (tourId) => isTourFinished(completions ?? [], definitionOf(tourId)),
+    [completions, definitionOf]
+  );
+  const start = useCallback(
+    (tourId, options = {}) => {
+      const definition2 = definitionOf(tourId);
+      if (!options.force && isTourFinished(completions ?? [], definition2)) return;
+      const index = options.at === void 0 ? 0 : resolveStepIndex(definition2.steps, options.at);
+      setRunning({ tourId, index });
+      setStatus("waiting");
+    },
+    [completions, definitionOf]
+  );
+  const runningRef = useRef(running);
+  runningRef.current = running;
+  const finish = 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 = useCallback(
+    (tourId) => {
+      void storage.clear(tourId);
+      setCompletions((prev) => tourId ? (prev ?? []).filter((e) => e.tourId !== tourId) : []);
+    },
+    [storage]
+  );
+  const step = useCallback(
+    (direction) => {
+      const current = runningRef.current;
+      if (!current) return;
+      const target = 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 = useCallback(
+    (step2) => {
+      setRunning((current) => {
+        if (!current) return current;
+        return { ...current, index: resolveStepIndex(definitionOf(current.tourId).steps, step2) };
+      });
+    },
+    [definitionOf]
+  );
+  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 (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 = useMemo(
+    () => ({
+      tourId: (running == null ? void 0 : running.tourId) ?? null,
+      index: (running == null ? void 0 : running.index) ?? 0,
+      total: definition ? 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__ */ jsxs(TourContext.Provider, { value, children: [
+    children,
+    definition && running ? /* @__PURE__ */ jsx(
+      Tour,
+      {
+        ...defaults,
+        definition,
+        index: running.index,
+        onIndexChange: (index) => setRunning({ tourId: running.tourId, index }),
+        onComplete: () => finish("completed"),
+        onDismiss: () => finish("dismissed"),
+        onStatusChange: setStatus,
+        ...onNavigate ? { onNavigate } : {}
+      }
+    ) : null
+  ] });
+}
+export {
+  TourProvider
+};
+//# sourceMappingURL=TourProvider.js.map

package/dist/overlay/TourProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourProvider.js","sources":["../../src/overlay/TourProvider.tsx"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from \"react\";\nimport { Tour, type TourProps } from \"./Tour\";\nimport { TourContext, type TourContextValue, type TourStatus } from \"./tour-context\";\nimport { activeSteps, nextStepIndex, resolveStepIndex, validateTourDefinition } from \"./tour-model\";\nimport {\n  isTourFinished,\n  localStorageTourStorage,\n  type TourCompletion,\n  type TourCompletionStatus,\n  type TourStorage,\n} from \"./tour-progress\";\nimport type { TourDefinition, TourStepContext } from \"./tour-types\";\n\n/**\n * Registry + running state + completion persistence for guided tours. Renders at\n * most one `<Tour>`; everything else reaches it through `useTour()`.\n */\n\nexport type TourProviderProps = {\n  children: ReactNode;\n  /** Tours available to `start(id)`. Each is validated on registration. */\n  tours: TourDefinition[];\n  /** The app's current route. Used only for auto-start eligibility, never for step sequencing. */\n  currentRoute?: string | undefined;\n  /** Auto-start route matcher. Defaults to exact match with the trailing slash normalised. */\n  matchRoute?: ((tourRoute: string, currentRoute: string) => boolean) | undefined;\n  /** Navigation callback threaded into every tour. Required for multi-route tours. */\n  onNavigate?: ((route: string, ctx: TourStepContext) => void | Promise<void>) | undefined;\n  /** Completion persistence. Defaults to `localStorageTourStorage()`. */\n  storage?: TourStorage | undefined;\n  /** Fired when a tour ends, either way. */\n  onFinish?:\n    | ((result: { tourId: string; status: TourCompletionStatus; index: number }) => void)\n    | undefined;\n  /** Defaults shared by every tour; an explicit `<Tour>` prop still wins. */\n  defaults?:\n    | Pick<\n        TourProps,\n        | \"anchorRoot\"\n        | \"portalContainer\"\n        | \"missingAnchor\"\n        | \"anchorTimeoutMs\"\n        | \"navigateTimeoutMs\"\n        | \"padding\"\n        | \"interaction\"\n        | \"keyboard\"\n        | \"closeOnEsc\"\n        | \"scrollIntoView\"\n        | \"labels\"\n        | \"onStepError\"\n        | \"backdropClassName\"\n      >\n    | undefined;\n};\n\nfunction normalizeRoute(route: string): string {\n  return route.length > 1 && route.endsWith(\"/\") ? route.slice(0, -1) : route;\n}\n\nfunction defaultMatchRoute(tourRoute: string, currentRoute: string): boolean {\n  return normalizeRoute(tourRoute) === normalizeRoute(currentRoute);\n}\n\ntype Running = { tourId: string; index: number };\n\nexport function TourProvider(props: TourProviderProps) {\n  const {\n    children,\n    tours,\n    currentRoute,\n    matchRoute = defaultMatchRoute,\n    onNavigate,\n    onFinish,\n    defaults,\n  } = props;\n\n  const storage = useMemo(() => props.storage ?? localStorageTourStorage(), [props.storage]);\n  const [completions, setCompletions] = useState<TourCompletion[] | null>(null);\n  const [running, setRunning] = useState<Running | null>(null);\n  const [status, setStatus] = useState<TourStatus>(\"idle\");\n\n  for (const definition of tours) validateTourDefinition(definition);\n\n  // Auto-start is gated behind this read so a first-run tour never flashes before\n  // we know it was already seen.\n  useEffect(() => {\n    let cancelled = false;\n    void Promise.resolve(storage.read()).then((entries) => {\n      if (!cancelled) setCompletions(entries);\n    });\n    return () => {\n      cancelled = true;\n    };\n  }, [storage]);\n\n  const definitionOf = useCallback(\n    (tourId: string): TourDefinition => {\n      const found = tours.find((tour) => tour.id === tourId);\n      if (!found) throw new Error(`Unknown tour \"${tourId}\"`);\n      return found;\n    },\n    [tours],\n  );\n\n  const isFinished = useCallback(\n    (tourId: string) => isTourFinished(completions ?? [], definitionOf(tourId)),\n    [completions, definitionOf],\n  );\n\n  const start = useCallback<TourContextValue[\"start\"]>(\n    (tourId, options = {}) => {\n      const definition = definitionOf(tourId);\n      if (!options.force && isTourFinished(completions ?? [], definition)) return;\n      const index = options.at === undefined ? 0 : resolveStepIndex(definition.steps, options.at);\n      setRunning({ tourId, index });\n      setStatus(\"waiting\");\n    },\n    [completions, definitionOf],\n  );\n\n  const runningRef = useRef(running);\n  runningRef.current = running;\n\n  const finish = useCallback<TourContextValue[\"finish\"]>(\n    (completionStatus = \"dismissed\") => {\n      const current = runningRef.current;\n      if (!current) return;\n      const definition = definitionOf(current.tourId);\n      const entry: TourCompletion = {\n        tourId: current.tourId,\n        status: completionStatus,\n        version: definition.version ?? 1,\n        at: new Date().toISOString(),\n      };\n      void storage.write(entry);\n      setCompletions((prev) => [...(prev ?? []).filter((e) => e.tourId !== entry.tourId), entry]);\n      setRunning(null);\n      setStatus(\"idle\");\n      onFinish?.({ tourId: current.tourId, status: completionStatus, index: current.index });\n    },\n    [definitionOf, onFinish, storage],\n  );\n\n  const reset = useCallback<TourContextValue[\"reset\"]>(\n    (tourId) => {\n      void storage.clear(tourId);\n      setCompletions((prev) => (tourId ? (prev ?? []).filter((e) => e.tourId !== tourId) : []));\n    },\n    [storage],\n  );\n\n  // Honours `enabled()` so a programmatic next/back lands where the card's own\n  // buttons would, rather than on a step the tour is skipping.\n  const step = useCallback(\n    (direction: \"next\" | \"back\") => {\n      const current = runningRef.current;\n      if (!current) return;\n      const target = nextStepIndex(definitionOf(current.tourId).steps, current.index, direction);\n      if (target === null) {\n        if (direction === \"next\") finish(\"completed\");\n        return;\n      }\n      setRunning({ ...current, index: target });\n    },\n    [definitionOf, finish],\n  );\n\n  const goTo = useCallback<TourContextValue[\"goTo\"]>(\n    (step) => {\n      setRunning((current) => {\n        if (!current) return current;\n        return { ...current, index: resolveStepIndex(definitionOf(current.tourId).steps, step) };\n      });\n    },\n    [definitionOf],\n  );\n\n  // Auto-start: only on the declared route, only once the completions are known.\n  useEffect(() => {\n    if (completions === null || running || currentRoute === undefined) return;\n    for (const definition of tours) {\n      if (!definition.autoStart) continue;\n      const route = definition.autoStartRoute ?? definition.steps[0]?.route;\n      if (route === undefined || !matchRoute(route, currentRoute)) continue;\n      if (isTourFinished(completions, definition)) continue;\n      setRunning({ tourId: definition.id, index: 0 });\n      setStatus(\"waiting\");\n      return;\n    }\n  }, [completions, running, currentRoute, tours, matchRoute]);\n\n  const definition = running ? definitionOf(running.tourId) : null;\n\n  const value = useMemo<TourContextValue>(\n    () => ({\n      tourId: running?.tourId ?? null,\n      index: running?.index ?? 0,\n      total: definition ? activeSteps(definition.steps).length : 0,\n      status,\n      start,\n      next: () => step(\"next\"),\n      back: () => step(\"back\"),\n      goTo,\n      finish,\n      isFinished,\n      reset,\n      tours,\n    }),\n    [running, definition, status, start, step, goTo, finish, isFinished, reset, tours],\n  );\n\n  return (\n    <TourContext.Provider value={value}>\n      {children}\n      {definition && running ? (\n        <Tour\n          {...defaults}\n          definition={definition}\n          index={running.index}\n          onIndexChange={(index) => setRunning({ tourId: running.tourId, index })}\n          onComplete={() => finish(\"completed\")}\n          onDismiss={() => finish(\"dismissed\")}\n          onStatusChange={setStatus}\n          {...(onNavigate ? { onNavigate } : {})}\n        />\n      ) : null}\n    </TourContext.Provider>\n  );\n}\n"],"names":["definition","step"],"mappings":"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"}

package/dist/overlay/TourSpotlight.cjs

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const utils = require("../lib/utils.cjs");
+const tourGeometry = require("./tour-geometry.cjs");
+const zIndex = require("./zIndex.cjs");
+const SUPPORTS_CLIP_PATH = typeof CSS !== "undefined" && typeof CSS.supports === "function" ? CSS.supports("clip-path", "path('M0 0')") : false;
+function TourSpotlight({
+  cutout,
+  viewport,
+  interaction,
+  className
+}) {
+  if (!SUPPORTS_CLIP_PATH) return null;
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        "aria-hidden": "true",
+        "data-tour-spotlight": "",
+        className: utils.cn(
+          "fixed inset-0 bg-black/40 transition-[clip-path] duration-200 motion-reduce:transition-none",
+          interaction === "allow-all" ? "pointer-events-none" : "pointer-events-auto",
+          className
+        ),
+        style: {
+          zIndex: zIndex.zIndex.tour,
+          clipPath: tourGeometry.spotlightClipPath({ viewport, cutout })
+        }
+      }
+    ),
+    interaction === "block-all" && cutout ? (
+      // The cutout is a hole in the dim, so blocking the anchor too needs a
+      // second, unclipped layer above it.
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "div",
+        {
+          "aria-hidden": "true",
+          className: "fixed inset-0",
+          style: { zIndex: zIndex.zIndex.tour + 1 }
+        }
+      )
+    ) : null
+  ] });
+}
+exports.TourSpotlight = TourSpotlight;
+//# sourceMappingURL=TourSpotlight.cjs.map

package/dist/overlay/TourSpotlight.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourSpotlight.cjs","sources":["../../src/overlay/TourSpotlight.tsx"],"sourcesContent":["import { cn } from \"../lib/utils\";\nimport { spotlightClipPath, type SpotlightRect } from \"./tour-geometry\";\nimport type { TourInteraction } from \"./tour-types\";\nimport { zIndex } from \"./zIndex\";\n\n/**\n * The dim layer. One element clipped with `clip-path: path(evenodd, ...)`: the\n * clipped-away hole does not hit-test, so the dim swallows clicks while the\n * anchor underneath stays clickable and typable, with no extra blocker element\n * and no inverted pointer semantics.\n */\n\n// A browser that cannot clip would paint an uncut opaque sheet over the whole\n// app, which is far worse than simply having no dim.\nconst SUPPORTS_CLIP_PATH =\n  typeof CSS !== \"undefined\" && typeof CSS.supports === \"function\"\n    ? CSS.supports(\"clip-path\", \"path('M0 0')\")\n    : false;\n\nexport function TourSpotlight({\n  cutout,\n  viewport,\n  interaction,\n  className,\n}: {\n  cutout: SpotlightRect | null;\n  viewport: { width: number; height: number };\n  interaction: TourInteraction;\n  className?: string | undefined;\n}) {\n  if (!SUPPORTS_CLIP_PATH) return null;\n\n  return (\n    <>\n      <div\n        aria-hidden=\"true\"\n        data-tour-spotlight=\"\"\n        className={cn(\n          \"fixed inset-0 bg-black/40 transition-[clip-path] duration-200 motion-reduce:transition-none\",\n          interaction === \"allow-all\" ? \"pointer-events-none\" : \"pointer-events-auto\",\n          className,\n        )}\n        style={{\n          zIndex: zIndex.tour,\n          clipPath: spotlightClipPath({ viewport, cutout }),\n        }}\n      />\n      {interaction === \"block-all\" && cutout ? (\n        // The cutout is a hole in the dim, so blocking the anchor too needs a\n        // second, unclipped layer above it.\n        <div\n          aria-hidden=\"true\"\n          className=\"fixed inset-0\"\n          style={{ zIndex: zIndex.tour + 1 }}\n        />\n      ) : null}\n    </>\n  );\n}\n"],"names":["jsxs","Fragment","jsx","cn","zIndex","spotlightClipPath"],"mappings":";;;;;;AAcA,MAAM,qBACJ,OAAO,QAAQ,eAAe,OAAO,IAAI,aAAa,aAClD,IAAI,SAAS,aAAa,cAAc,IACxC;AAEC,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAKG;AACD,MAAI,CAAC,mBAAoB,QAAO;AAEhC,SACEA,2BAAAA,KAAAC,qBAAA,EACE,UAAA;AAAA,IAAAC,2BAAAA;AAAAA,MAAC;AAAA,MAAA;AAAA,QACC,eAAY;AAAA,QACZ,uBAAoB;AAAA,QACpB,WAAWC,MAAAA;AAAAA,UACT;AAAA,UACA,gBAAgB,cAAc,wBAAwB;AAAA,UACtD;AAAA,QAAA;AAAA,QAEF,OAAO;AAAA,UACL,QAAQC,OAAAA,OAAO;AAAA,UACf,UAAUC,aAAAA,kBAAkB,EAAE,UAAU,QAAQ;AAAA,QAAA;AAAA,MAClD;AAAA,IAAA;AAAA,IAED,gBAAgB,eAAe;AAAA;AAAA;AAAA,MAG9BH,2BAAAA;AAAAA,QAAC;AAAA,QAAA;AAAA,UACC,eAAY;AAAA,UACZ,WAAU;AAAA,UACV,OAAO,EAAE,QAAQE,OAAAA,OAAO,OAAO,EAAA;AAAA,QAAE;AAAA,MAAA;AAAA,QAEjC;AAAA,EAAA,GACN;AAEJ;;"}

package/dist/overlay/TourSpotlight.d.ts

@@ -0,0 +1,12 @@
+import { SpotlightRect } from './tour-geometry';
+import { TourInteraction } from './tour-types';
+export declare function TourSpotlight({ cutout, viewport, interaction, className, }: {
+    cutout: SpotlightRect | null;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    interaction: TourInteraction;
+    className?: string | undefined;
+}): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=TourSpotlight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TourSpotlight.d.ts","sourceRoot":"","sources":["../../src/overlay/TourSpotlight.tsx"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAiBpD,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,QAAQ,EACR,WAAW,EACX,SAAS,GACV,EAAE;IACD,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,WAAW,EAAE,eAAe,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,kDA6BA"}

package/dist/overlay/TourSpotlight.js

@@ -0,0 +1,47 @@
+import { jsxs, Fragment, jsx } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+import { spotlightClipPath } from "./tour-geometry.js";
+import { zIndex } from "./zIndex.js";
+const SUPPORTS_CLIP_PATH = typeof CSS !== "undefined" && typeof CSS.supports === "function" ? CSS.supports("clip-path", "path('M0 0')") : false;
+function TourSpotlight({
+  cutout,
+  viewport,
+  interaction,
+  className
+}) {
+  if (!SUPPORTS_CLIP_PATH) return null;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "aria-hidden": "true",
+        "data-tour-spotlight": "",
+        className: cn(
+          "fixed inset-0 bg-black/40 transition-[clip-path] duration-200 motion-reduce:transition-none",
+          interaction === "allow-all" ? "pointer-events-none" : "pointer-events-auto",
+          className
+        ),
+        style: {
+          zIndex: zIndex.tour,
+          clipPath: spotlightClipPath({ viewport, cutout })
+        }
+      }
+    ),
+    interaction === "block-all" && cutout ? (
+      // The cutout is a hole in the dim, so blocking the anchor too needs a
+      // second, unclipped layer above it.
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          "aria-hidden": "true",
+          className: "fixed inset-0",
+          style: { zIndex: zIndex.tour + 1 }
+        }
+      )
+    ) : null
+  ] });
+}
+export {
+  TourSpotlight
+};
+//# sourceMappingURL=TourSpotlight.js.map

package/dist/overlay/TourSpotlight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourSpotlight.js","sources":["../../src/overlay/TourSpotlight.tsx"],"sourcesContent":["import { cn } from \"../lib/utils\";\nimport { spotlightClipPath, type SpotlightRect } from \"./tour-geometry\";\nimport type { TourInteraction } from \"./tour-types\";\nimport { zIndex } from \"./zIndex\";\n\n/**\n * The dim layer. One element clipped with `clip-path: path(evenodd, ...)`: the\n * clipped-away hole does not hit-test, so the dim swallows clicks while the\n * anchor underneath stays clickable and typable, with no extra blocker element\n * and no inverted pointer semantics.\n */\n\n// A browser that cannot clip would paint an uncut opaque sheet over the whole\n// app, which is far worse than simply having no dim.\nconst SUPPORTS_CLIP_PATH =\n  typeof CSS !== \"undefined\" && typeof CSS.supports === \"function\"\n    ? CSS.supports(\"clip-path\", \"path('M0 0')\")\n    : false;\n\nexport function TourSpotlight({\n  cutout,\n  viewport,\n  interaction,\n  className,\n}: {\n  cutout: SpotlightRect | null;\n  viewport: { width: number; height: number };\n  interaction: TourInteraction;\n  className?: string | undefined;\n}) {\n  if (!SUPPORTS_CLIP_PATH) return null;\n\n  return (\n    <>\n      <div\n        aria-hidden=\"true\"\n        data-tour-spotlight=\"\"\n        className={cn(\n          \"fixed inset-0 bg-black/40 transition-[clip-path] duration-200 motion-reduce:transition-none\",\n          interaction === \"allow-all\" ? \"pointer-events-none\" : \"pointer-events-auto\",\n          className,\n        )}\n        style={{\n          zIndex: zIndex.tour,\n          clipPath: spotlightClipPath({ viewport, cutout }),\n        }}\n      />\n      {interaction === \"block-all\" && cutout ? (\n        // The cutout is a hole in the dim, so blocking the anchor too needs a\n        // second, unclipped layer above it.\n        <div\n          aria-hidden=\"true\"\n          className=\"fixed inset-0\"\n          style={{ zIndex: zIndex.tour + 1 }}\n        />\n      ) : null}\n    </>\n  );\n}\n"],"names":[],"mappings":";;;;AAcA,MAAM,qBACJ,OAAO,QAAQ,eAAe,OAAO,IAAI,aAAa,aAClD,IAAI,SAAS,aAAa,cAAc,IACxC;AAEC,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAKG;AACD,MAAI,CAAC,mBAAoB,QAAO;AAEhC,SACE,qBAAA,UAAA,EACE,UAAA;AAAA,IAAA;AAAA,MAAC;AAAA,MAAA;AAAA,QACC,eAAY;AAAA,QACZ,uBAAoB;AAAA,QACpB,WAAW;AAAA,UACT;AAAA,UACA,gBAAgB,cAAc,wBAAwB;AAAA,UACtD;AAAA,QAAA;AAAA,QAEF,OAAO;AAAA,UACL,QAAQ,OAAO;AAAA,UACf,UAAU,kBAAkB,EAAE,UAAU,QAAQ;AAAA,QAAA;AAAA,MAClD;AAAA,IAAA;AAAA,IAED,gBAAgB,eAAe;AAAA;AAAA;AAAA,MAG9B;AAAA,QAAC;AAAA,QAAA;AAAA,UACC,eAAY;AAAA,UACZ,WAAU;AAAA,UACV,OAAO,EAAE,QAAQ,OAAO,OAAO,EAAA;AAAA,QAAE;AAAA,MAAA;AAAA,QAEjC;AAAA,EAAA,GACN;AAEJ;"}

package/dist/overlay/modalStack.cjs

@@ -6,6 +6,7 @@ const stack = [];
 const listeners = /* @__PURE__ */ new Set();
 const escapeStack = [];
 let escapeDocument = null;
+let tourLayers = 0;
 function emit() {
   for (const listener of listeners) listener();
 }
@@ -16,7 +17,7 @@ function subscribe(listener) {
   };
 }
 function getSnapshot() {
-  return stack.join("\0");
+  return `${tourLayers}:` + stack.join("\0");
 }
 function onEscapeKeyDown(event) {
   if (event.defaultPrevented || event.key !== "Escape" || event.isComposing || event.keyCode === 229) {
@@ -75,13 +76,26 @@ function useEscapeLayer(open, onEscape, enabled = true) {
     return () => removeEscapeLayer(id);
   }, [enabled, id, open]);
 }
+function useTourLayer(active) {
+  react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  react.useEffect(() => {
+    if (!active) return;
+    tourLayers += 1;
+    emit();
+    return () => {
+      tourLayers -= 1;
+      emit();
+    };
+  }, [active]);
+}
 function useFloatingZIndex() {
   react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-  if (stack.length === 0) return zIndex.zIndex.popover;
-  const topModalZ = zIndex.zIndex.modal + (stack.length - 1) * zIndex.zIndex.modalStep;
-  return topModalZ + zIndex.zIndex.popoverOverModalOffset;
+  const base = stack.length === 0 ? zIndex.zIndex.popover : zIndex.zIndex.modal + (stack.length - 1) * zIndex.zIndex.modalStep + zIndex.zIndex.popoverOverModalOffset;
+  if (tourLayers === 0) return base;
+  return Math.max(base, zIndex.zIndex.tour + zIndex.zIndex.tourCardOffset + zIndex.zIndex.popoverOverModalOffset);
 }
 exports.useEscapeLayer = useEscapeLayer;
 exports.useFloatingZIndex = useFloatingZIndex;
 exports.useModalStack = useModalStack;
+exports.useTourLayer = useTourLayer;
 //# sourceMappingURL=modalStack.cjs.map

package/dist/overlay/modalStack.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"modalStack.cjs","sources":["../../src/overlay/modalStack.ts"],"sourcesContent":["import { useEffect, useId, useRef, useSyncExternalStore } from \"react\";\nimport { zIndex } from \"./zIndex\";\n\n// A process-wide stack of the currently open modals, topmost last. Modals mount\n// independently (no shared provider), so the stack lives at module scope and is\n// shared through useSyncExternalStore. It lets nested modals cooperate: only the\n// topmost reacts to Escape, and each renders above the one it opened over.\nconst stack: string[] = [];\nconst listeners = new Set<() => void>();\nconst escapeStack: Array<{ id: string; onEscape: () => void }> = [];\nlet escapeDocument: Document | null = null;\n\nfunction emit() {\n  for (const listener of listeners) listener();\n}\n\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n// The snapshot is the stack identity; it only changes when an entry is pushed or\n// popped, so subscribers re-render exactly when their position could have moved.\nfunction getSnapshot() {\n  return stack.join(\"\\u0000\");\n}\n\nfunction onEscapeKeyDown(event: KeyboardEvent) {\n  if (\n    event.defaultPrevented ||\n    event.key !== \"Escape\" ||\n    event.isComposing ||\n    (event as KeyboardEvent & { keyCode?: number }).keyCode === 229\n  ) {\n    return;\n  }\n\n  const top = escapeStack[escapeStack.length - 1];\n  if (!top) return;\n\n  event.preventDefault();\n  event.stopPropagation();\n  event.stopImmediatePropagation();\n  top.onEscape();\n}\n\nfunction ensureEscapeListener() {\n  if (escapeDocument || typeof document === \"undefined\") return;\n  escapeDocument = document;\n  escapeDocument.addEventListener(\"keydown\", onEscapeKeyDown);\n}\n\nfunction removeEscapeLayer(id: string) {\n  const index = escapeStack.findIndex((entry) => entry.id === id);\n  if (index !== -1) escapeStack.splice(index, 1);\n\n  if (escapeStack.length === 0 && escapeDocument) {\n    escapeDocument.removeEventListener(\"keydown\", onEscapeKeyDown);\n    escapeDocument = null;\n  }\n}\n\nexport type ModalStackPosition = {\n  /** Whether this modal is the topmost open one and should own global affordances. */\n  isTop: boolean;\n  /** Zero-based depth in the stack; drives the stacking order of nested modals. */\n  depth: number;\n};\n\n/**\n * Registers a modal in the global stack while `open`, returning its live\n * position. Used so a nested modal sits above its opener and only the topmost\n * modal closes on Escape.\n */\nexport function useModalStack(open: boolean): ModalStackPosition {\n  const id = useId();\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  useEffect(() => {\n    if (!open) return;\n    stack.push(id);\n    emit();\n    return () => {\n      const index = stack.indexOf(id);\n      if (index !== -1) stack.splice(index, 1);\n      emit();\n    };\n  }, [open, id]);\n\n  const depth = stack.indexOf(id);\n  return {\n    isTop: depth !== -1 && depth === stack.length - 1,\n    depth: depth === -1 ? 0 : depth,\n  };\n}\n\n/**\n * Registers an Escape-closeable overlay while `open`. The topmost registered\n * layer owns Escape, so a keypress dismisses one dialog/menu layer at a time.\n */\nexport function useEscapeLayer(open: boolean, onEscape: () => void, enabled = true) {\n  const id = useId();\n  const onEscapeRef = useRef(onEscape);\n  onEscapeRef.current = onEscape;\n\n  useEffect(() => {\n    if (!open || !enabled) return;\n\n    ensureEscapeListener();\n    escapeStack.push({\n      id,\n      onEscape: () => onEscapeRef.current(),\n    });\n\n    return () => removeEscapeLayer(id);\n  }, [enabled, id, open]);\n}\n\n/**\n * z-index a floating layer (dropdown / combobox / tooltip / popover) should use\n * so it renders above any open modal — and below the next nested modal — or at\n * the popover floor when no modal is open. Subscribes to the modal stack so the\n * value tracks modals opening and closing.\n */\nexport function useFloatingZIndex(): number {\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  if (stack.length === 0) return zIndex.popover;\n  const topModalZ = zIndex.modal + (stack.length - 1) * zIndex.modalStep;\n  return topModalZ + zIndex.popoverOverModalOffset;\n}\n"],"names":["useId","useSyncExternalStore","useEffect","useRef","zIndex"],"mappings":";;;;AAOA,MAAM,QAAkB,CAAA;AACxB,MAAM,gCAAgB,IAAA;AACtB,MAAM,cAA2D,CAAA;AACjE,IAAI,iBAAkC;AAEtC,SAAS,OAAO;AACd,aAAW,YAAY,UAAW,UAAA;AACpC;AAEA,SAAS,UAAU,UAAsB;AACvC,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAIA,SAAS,cAAc;AACrB,SAAO,MAAM,KAAK,IAAQ;AAC5B;AAEA,SAAS,gBAAgB,OAAsB;AAC7C,MACE,MAAM,oBACN,MAAM,QAAQ,YACd,MAAM,eACL,MAA+C,YAAY,KAC5D;AACA;AAAA,EACF;AAEA,QAAM,MAAM,YAAY,YAAY,SAAS,CAAC;AAC9C,MAAI,CAAC,IAAK;AAEV,QAAM,eAAA;AACN,QAAM,gBAAA;AACN,QAAM,yBAAA;AACN,MAAI,SAAA;AACN;AAEA,SAAS,uBAAuB;AAC9B,MAAI,kBAAkB,OAAO,aAAa,YAAa;AACvD,mBAAiB;AACjB,iBAAe,iBAAiB,WAAW,eAAe;AAC5D;AAEA,SAAS,kBAAkB,IAAY;AACrC,QAAM,QAAQ,YAAY,UAAU,CAAC,UAAU,MAAM,OAAO,EAAE;AAC9D,MAAI,UAAU,GAAI,aAAY,OAAO,OAAO,CAAC;AAE7C,MAAI,YAAY,WAAW,KAAK,gBAAgB;AAC9C,mBAAe,oBAAoB,WAAW,eAAe;AAC7D,qBAAiB;AAAA,EACnB;AACF;AAcO,SAAS,cAAc,MAAmC;AAC/D,QAAM,KAAKA,MAAAA,MAAA;AACXC,6BAAqB,WAAW,aAAa,WAAW;AAExDC,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,KAAM;AACX,UAAM,KAAK,EAAE;AACb,SAAA;AACA,WAAO,MAAM;AACX,YAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,UAAI,UAAU,GAAI,OAAM,OAAO,OAAO,CAAC;AACvC,WAAA;AAAA,IACF;AAAA,EACF,GAAG,CAAC,MAAM,EAAE,CAAC;AAEb,QAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,SAAO;AAAA,IACL,OAAO,UAAU,MAAM,UAAU,MAAM,SAAS;AAAA,IAChD,OAAO,UAAU,KAAK,IAAI;AAAA,EAAA;AAE9B;AAMO,SAAS,eAAe,MAAe,UAAsB,UAAU,MAAM;AAClF,QAAM,KAAKF,MAAAA,MAAA;AACX,QAAM,cAAcG,MAAAA,OAAO,QAAQ;AACnC,cAAY,UAAU;AAEtBD,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,QAAQ,CAAC,QAAS;AAEvB,yBAAA;AACA,gBAAY,KAAK;AAAA,MACf;AAAA,MACA,UAAU,MAAM,YAAY,QAAA;AAAA,IAAQ,CACrC;AAED,WAAO,MAAM,kBAAkB,EAAE;AAAA,EACnC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;AACxB;AAQO,SAAS,oBAA4B;AAC1CD,6BAAqB,WAAW,aAAa,WAAW;AACxD,MAAI,MAAM,WAAW,EAAG,QAAOG,OAAAA,OAAO;AACtC,QAAM,YAAYA,OAAAA,OAAO,SAAS,MAAM,SAAS,KAAKA,OAAAA,OAAO;AAC7D,SAAO,YAAYA,OAAAA,OAAO;AAC5B;;;;"}
+{"version":3,"file":"modalStack.cjs","sources":["../../src/overlay/modalStack.ts"],"sourcesContent":["import { useEffect, useId, useRef, useSyncExternalStore } from \"react\";\nimport { zIndex } from \"./zIndex\";\n\n// A process-wide stack of the currently open modals, topmost last. Modals mount\n// independently (no shared provider), so the stack lives at module scope and is\n// shared through useSyncExternalStore. It lets nested modals cooperate: only the\n// topmost reacts to Escape, and each renders above the one it opened over.\nconst stack: string[] = [];\nconst listeners = new Set<() => void>();\nconst escapeStack: Array<{ id: string; onEscape: () => void }> = [];\nlet escapeDocument: Document | null = null;\n// Running guided tours. A tour dims the page from `zIndex.tour`, far above the\n// modal band, so floating content opened *during* a tour (the menu a step tells\n// the user to open) has to clear that dim or it renders invisibly underneath.\nlet tourLayers = 0;\n\nfunction emit() {\n  for (const listener of listeners) listener();\n}\n\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n// The snapshot is the stack identity plus the tour-layer count; it only changes\n// when an entry is pushed or popped, so subscribers re-render exactly when their\n// position could have moved.\nfunction getSnapshot() {\n  return `${tourLayers}:` + stack.join(\"\\u0000\");\n}\n\nfunction onEscapeKeyDown(event: KeyboardEvent) {\n  if (\n    event.defaultPrevented ||\n    event.key !== \"Escape\" ||\n    event.isComposing ||\n    (event as KeyboardEvent & { keyCode?: number }).keyCode === 229\n  ) {\n    return;\n  }\n\n  const top = escapeStack[escapeStack.length - 1];\n  if (!top) return;\n\n  event.preventDefault();\n  event.stopPropagation();\n  event.stopImmediatePropagation();\n  top.onEscape();\n}\n\nfunction ensureEscapeListener() {\n  if (escapeDocument || typeof document === \"undefined\") return;\n  escapeDocument = document;\n  escapeDocument.addEventListener(\"keydown\", onEscapeKeyDown);\n}\n\nfunction removeEscapeLayer(id: string) {\n  const index = escapeStack.findIndex((entry) => entry.id === id);\n  if (index !== -1) escapeStack.splice(index, 1);\n\n  if (escapeStack.length === 0 && escapeDocument) {\n    escapeDocument.removeEventListener(\"keydown\", onEscapeKeyDown);\n    escapeDocument = null;\n  }\n}\n\nexport type ModalStackPosition = {\n  /** Whether this modal is the topmost open one and should own global affordances. */\n  isTop: boolean;\n  /** Zero-based depth in the stack; drives the stacking order of nested modals. */\n  depth: number;\n};\n\n/**\n * Registers a modal in the global stack while `open`, returning its live\n * position. Used so a nested modal sits above its opener and only the topmost\n * modal closes on Escape.\n */\nexport function useModalStack(open: boolean): ModalStackPosition {\n  const id = useId();\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  useEffect(() => {\n    if (!open) return;\n    stack.push(id);\n    emit();\n    return () => {\n      const index = stack.indexOf(id);\n      if (index !== -1) stack.splice(index, 1);\n      emit();\n    };\n  }, [open, id]);\n\n  const depth = stack.indexOf(id);\n  return {\n    isTop: depth !== -1 && depth === stack.length - 1,\n    depth: depth === -1 ? 0 : depth,\n  };\n}\n\n/**\n * Registers an Escape-closeable overlay while `open`. The topmost registered\n * layer owns Escape, so a keypress dismisses one dialog/menu layer at a time.\n */\nexport function useEscapeLayer(open: boolean, onEscape: () => void, enabled = true) {\n  const id = useId();\n  const onEscapeRef = useRef(onEscape);\n  onEscapeRef.current = onEscape;\n\n  useEffect(() => {\n    if (!open || !enabled) return;\n\n    ensureEscapeListener();\n    escapeStack.push({\n      id,\n      onEscape: () => onEscapeRef.current(),\n    });\n\n    return () => removeEscapeLayer(id);\n  }, [enabled, id, open]);\n}\n\n/**\n * Registers a running guided tour while `active`, so floating layers lift above\n * its dim. Symmetric with `useModalStack`, but a count rather than a stack: the\n * tour overlay does not nest.\n */\nexport function useTourLayer(active: boolean): void {\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  useEffect(() => {\n    if (!active) return;\n    tourLayers += 1;\n    emit();\n    return () => {\n      tourLayers -= 1;\n      emit();\n    };\n  }, [active]);\n}\n\n/**\n * z-index a floating layer (dropdown / combobox / tooltip / popover) should use\n * so it renders above any open modal — and below the next nested modal — or at\n * the popover floor when no modal is open. While a guided tour runs, the value\n * also clears the tour's dim and step card, so a step that says \"open this menu\"\n * shows the menu rather than hiding it under the overlay. Subscribes to the\n * modal stack so the value tracks modals and tours opening and closing.\n */\nexport function useFloatingZIndex(): number {\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  const base =\n    stack.length === 0\n      ? zIndex.popover\n      : zIndex.modal + (stack.length - 1) * zIndex.modalStep + zIndex.popoverOverModalOffset;\n  if (tourLayers === 0) return base;\n  return Math.max(base, zIndex.tour + zIndex.tourCardOffset + zIndex.popoverOverModalOffset);\n}\n"],"names":["useId","useSyncExternalStore","useEffect","useRef","zIndex"],"mappings":"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"}