@trailguide/runtime 0.0.2 → 0.1.0

package/dist/context/TourRegistryContext.d.ts

@@ -0,0 +1,42 @@
+import { UseTrailManagerOptions, UseTrailManagerReturn } from '../hooks/useTrailManager';
+import { Trail } from '@trailguide/core';
+
+interface TourRegistryContextValue {
+    /**
+     * Trigger the tour for whatever page/view is currently mounted.
+     * Call this from a persistent help button, keyboard shortcut, etc.
+     */
+    startCurrentTour: () => void;
+    /**
+     * Register a tour start function for the currently active page.
+     * Returns a cleanup function that deregisters on unmount.
+     * You typically won't call this directly — use useRegisterTour instead.
+     */
+    registerTour: (startFn: () => void) => () => void;
+}
+/**
+ * Wrap your app's persistent layout (sidebar, navbar) with this provider.
+ * Wire your help button to `useTourRegistry().startCurrentTour()`.
+ * Each page uses `useRegisterTour()` to register itself.
+ */
+export declare function TourRegistryProvider({ children }: {
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Access the registry from a help button or keyboard shortcut handler */
+export declare function useTourRegistry(): TourRegistryContextValue;
+/**
+ * Drop-in replacement for useTrailManager that also registers the tour
+ * with the nearest TourRegistryProvider. The help menu will trigger
+ * this tour whenever this page/view is mounted.
+ *
+ * @example
+ * // In your page component:
+ * const { isActive, dismiss } = useRegisterTour(MY_TOUR, { once: true })
+ *
+ * // In your layout's help button:
+ * const { startCurrentTour } = useTourRegistry()
+ * <button onClick={startCurrentTour}>Quick Start Tour</button>
+ */
+export declare function useRegisterTour(trail: Trail, options?: UseTrailManagerOptions): UseTrailManagerReturn;
+export {};
+//# sourceMappingURL=TourRegistryContext.d.ts.map

package/dist/context/TourRegistryContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourRegistryContext.d.ts","sourceRoot":"","sources":["../../src/context/TourRegistryContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAE9F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,UAAU,wBAAwB;IAChC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B;;;;OAIG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CACnD;AAOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,2CAmB/E;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,6BAE9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,sBAAsB,GAC/B,qBAAqB,CAavB"}

package/dist/hooks/useTrailManager.d.ts

@@ -0,0 +1,54 @@
+import { Trail, Step, AnalyticsConfig } from '@trailguide/core';
+
+export interface UseTrailManagerOptions {
+    /**
+     * When true, the tour auto-shows on first visit and marks itself as seen
+     * on completion or skip so it never auto-shows again.
+     */
+    once?: boolean;
+    /**
+     * localStorage key used to track completion and progress.
+     * Defaults to `trailguide:managed:{trail.id}`.
+     */
+    storageKey?: string;
+    /**
+     * The tour only auto-shows when this is true.
+     * Use this to gate on loading state, user tier, feature flags, etc.
+     * The help menu can still trigger the tour regardless of this value.
+     * @default true
+     */
+    enabled?: boolean;
+    /** Delay in ms before the tour auto-shows on first visit. @default 500 */
+    delay?: number;
+    /**
+     * When true, saves the user's progress on each step so they resume
+     * where they left off if they navigate away mid-tour.
+     */
+    resumable?: boolean;
+    onComplete?: () => void;
+    onSkip?: () => void;
+    /** Fires when the tour is stopped programmatically (e.g. user navigates away) */
+    onAbandoned?: () => void;
+    onStepChange?: (step: Step, index: number) => void;
+    /** Fires when a step's target element is not found or not visible */
+    onError?: (step: Step, error: 'element_not_found' | 'element_not_visible') => void;
+    analytics?: AnalyticsConfig;
+}
+export interface UseTrailManagerReturn {
+    isActive: boolean;
+    currentStep: Step | null;
+    currentStepIndex: number;
+    totalSteps: number;
+    /** Show the tour (optionally resuming from saved progress) */
+    show: () => void;
+    /** Hide the tour and, if once:true, mark it as completed */
+    dismiss: () => void;
+    /** Clear all saved state for this tour so it will auto-show again */
+    reset: () => void;
+    next: () => void;
+    prev: () => void;
+    skip: () => void;
+    goToStep: (index: number) => void;
+}
+export declare function useTrailManager(trail: Trail, options?: UseTrailManagerOptions): UseTrailManagerReturn;
+//# sourceMappingURL=useTrailManager.d.ts.map

package/dist/hooks/useTrailManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTrailManager.d.ts","sourceRoot":"","sources":["../../src/hooks/useTrailManager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,mBAAmB,GAAG,qBAAqB,KAAK,IAAI,CAAC;IACnF,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAwHvB"}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export type { Trail, Step, Placement, TrailguideOptions, AnalyticsConfig, } from '@trailguide/core';
-export { findElement, isElementVisible, scrollToElement, } from '@trailguide/core';
+export { findElement, isElementVisible, scrollToElement, tourStorage, } from '@trailguide/core';
 export { Trailguide } from './components/Trailguide';
 export type { TrailguideProps } from './components/Trailguide';
 export { useTrail } from './hooks/useTrail';
 export type { UseTrailOptions, UseTrailReturn } from './hooks/useTrail';
+export { useTrailManager } from './hooks/useTrailManager';
+export type { UseTrailManagerOptions, UseTrailManagerReturn } from './hooks/useTrailManager';
+export { TourRegistryProvider, useTourRegistry, useRegisterTour, } from './context/TourRegistryContext';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,iBAAiB,EACjB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,iBAAiB,EACjB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAG7F,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,eAAe,GAChB,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -1,97 +1,204 @@
-import { Trailguide as I } from "@trailguide/core";
-import { findElement as J, isElementVisible as K, scrollToElement as L } from "@trailguide/core";
-import { useRef as c, useEffect as b, useState as E, useCallback as f } from "react";
-function D({
+import { Trailguide as M, tourStorage as v } from "@trailguide/core";
+import { findElement as F, isElementVisible as R, scrollToElement as rr, tourStorage as er } from "@trailguide/core";
+import { useRef as a, useEffect as P, useState as $, useCallback as p, createContext as D, useContext as G } from "react";
+import { jsx as H } from "react/jsx-runtime";
+function U({
   trail: n,
-  onComplete: i,
-  onStepChange: T,
-  onSkip: m,
-  analytics: a
+  onComplete: e,
+  onStepChange: u,
+  onSkip: g,
+  analytics: l
 }) {
-  const p = c(null), s = c(i), u = c(T), o = c(m);
-  return s.current = i, u.current = T, o.current = m, b(() => (p.current = new I({
+  const S = a(null), i = a(e), m = a(u), s = a(g);
+  return i.current = e, m.current = u, s.current = g, P(() => (S.current = new M({
     onComplete: () => {
-      var r;
-      return (r = s.current) == null ? void 0 : r.call(s);
+      var c;
+      return (c = i.current) == null ? void 0 : c.call(i);
     },
-    onStepChange: (r, e) => {
-      var l;
-      return (l = u.current) == null ? void 0 : l.call(u, r, e);
+    onStepChange: (c, o) => {
+      var d;
+      return (d = m.current) == null ? void 0 : d.call(m, c, o);
     },
     onSkip: () => {
-      var r;
-      return (r = o.current) == null ? void 0 : r.call(o);
+      var c;
+      return (c = s.current) == null ? void 0 : c.call(s);
     },
-    analytics: a
-  }), p.current.start(n), () => {
-    var r;
-    (r = p.current) == null || r.stop();
-  }), [n, a]), null;
+    analytics: l
+  }), S.current.start(n), () => {
+    var c;
+    (c = S.current) == null || c.stop();
+  }), [n, l]), null;
 }
-function F({
+function W({
   trail: n,
-  onComplete: i,
-  onStepChange: T,
-  onSkip: m,
-  autoStart: a = !1,
-  analytics: p
+  onComplete: e,
+  onStepChange: u,
+  onSkip: g,
+  autoStart: l = !1,
+  analytics: S
 }) {
-  const [s, u] = E(0), [o, r] = E(!1), e = c(null), l = c(i), x = c(T), g = c(m);
-  l.current = i, x.current = T, g.current = m;
-  const w = o && n.steps[s] ? n.steps[s] : null, A = n.steps.length;
-  b(() => (e.current = new I({
+  const [i, m] = $(0), [s, c] = $(!1), o = a(null), d = a(e), T = a(u), f = a(g);
+  d.current = e, T.current = u, f.current = g;
+  const h = s && n.steps[i] ? n.steps[i] : null, k = n.steps.length;
+  P(() => (o.current = new M({
     onComplete: () => {
       var t;
-      r(!1), (t = l.current) == null || t.call(l);
+      c(!1), (t = d.current) == null || t.call(d);
     },
-    onStepChange: (t, d) => {
-      var v;
-      u(d), (v = x.current) == null || v.call(x, t, d);
+    onStepChange: (t, C) => {
+      var K;
+      m(C), (K = T.current) == null || K.call(T, t, C);
     },
     onSkip: () => {
       var t;
-      r(!1), (t = g.current) == null || t.call(g);
+      c(!1), (t = f.current) == null || t.call(f);
     },
-    analytics: p
-  }), a && (e.current.start(n), r(!0)), () => {
+    analytics: S
+  }), l && (o.current.start(n), c(!0)), () => {
     var t;
-    (t = e.current) == null || t.stop();
-  }), [n, a, p]);
-  const S = f(() => {
-    e.current && (e.current.start(n), r(!0), u(0));
-  }, [n]), k = f(() => {
+    (t = o.current) == null || t.stop();
+  }), [n, l, S]);
+  const w = p(() => {
+    o.current && (o.current.start(n), c(!0), m(0));
+  }, [n]), I = p(() => {
     var t;
-    (t = e.current) == null || t.stop(), r(!1);
-  }, []), V = f(() => {
+    (t = o.current) == null || t.stop(), c(!1);
+  }, []), b = p(() => {
     var t;
-    (t = e.current) == null || t.next();
-  }, []), $ = f(() => {
+    (t = o.current) == null || t.next();
+  }, []), j = p(() => {
     var t;
-    (t = e.current) == null || t.prev();
-  }, []), j = f(() => {
+    (t = o.current) == null || t.prev();
+  }, []), A = p(() => {
     var t;
-    (t = e.current) == null || t.skip();
-  }, []), q = f((t) => {
-    var d;
-    (d = e.current) == null || d.goToStep(t);
+    (t = o.current) == null || t.skip();
+  }, []), y = p((t) => {
+    var C;
+    (C = o.current) == null || C.goToStep(t);
+  }, []);
+  return {
+    currentStep: h,
+    currentStepIndex: i,
+    totalSteps: k,
+    isActive: s,
+    next: b,
+    prev: j,
+    skip: A,
+    goToStep: y,
+    start: w,
+    stop: I
+  };
+}
+function J(n, e = {}) {
+  const {
+    once: u = !1,
+    storageKey: g,
+    enabled: l = !0,
+    delay: S = 500,
+    resumable: i = !1,
+    analytics: m
+  } = e, s = g ?? `trailguide:managed:${n.id}`, [c, o] = $(!1), [d, T] = $(0), f = a(null), h = a(e.onComplete), k = a(e.onSkip), w = a(e.onAbandoned), I = a(e.onStepChange), b = a(e.onError);
+  h.current = e.onComplete, k.current = e.onSkip, w.current = e.onAbandoned, I.current = e.onStepChange, b.current = e.onError;
+  const j = c && n.steps[d] ? n.steps[d] : null;
+  P(() => (f.current = new M({
+    onComplete: () => {
+      var r;
+      u && v.markCompleted(s), i && v.clearProgress(s), o(!1), T(0), (r = h.current) == null || r.call(h);
+    },
+    onSkip: () => {
+      var r;
+      u && v.markCompleted(s), i && v.clearProgress(s), o(!1), T(0), (r = k.current) == null || r.call(k);
+    },
+    onAbandoned: () => {
+      var r;
+      o(!1), (r = w.current) == null || r.call(w);
+    },
+    onStepChange: (r, x) => {
+      var E;
+      T(x), i && v.saveProgress(s, x), (E = I.current) == null || E.call(I, r, x);
+    },
+    onError: (r, x) => {
+      var E;
+      (E = b.current) == null || E.call(b, r, x);
+    },
+    analytics: m
+  }), () => {
+    var r;
+    (r = f.current) == null || r.stop();
+  }), [n, m, u, s, i]);
+  const A = p(() => {
+    if (!f.current) return;
+    const r = i ? v.getProgress(s) ?? 0 : 0;
+    f.current.start(n), r > 0 && f.current.goToStep(r), o(!0), T(r);
+  }, [n, i, s]), y = a(A);
+  y.current = A, P(() => {
+    if (!l || u && v.hasCompleted(s)) return;
+    const r = setTimeout(() => y.current(), S);
+    return () => clearTimeout(r);
+  }, [l, u, s, S]);
+  const t = p(() => {
+    var r;
+    u && v.markCompleted(s), (r = f.current) == null || r.stop(), o(!1), T(0);
+  }, [u, s]), C = p(() => {
+    v.reset(s);
+  }, [s]), K = p(() => {
+    var r;
+    return (r = f.current) == null ? void 0 : r.next();
+  }, []), q = p(() => {
+    var r;
+    return (r = f.current) == null ? void 0 : r.prev();
+  }, []), z = p(() => {
+    var r;
+    return (r = f.current) == null ? void 0 : r.skip();
+  }, []), B = p((r) => {
+    var x;
+    return (x = f.current) == null ? void 0 : x.goToStep(r);
   }, []);
   return {
-    currentStep: w,
-    currentStepIndex: s,
-    totalSteps: A,
-    isActive: o,
-    next: V,
-    prev: $,
-    skip: j,
-    goToStep: q,
-    start: S,
-    stop: k
+    isActive: c,
+    currentStep: j,
+    currentStepIndex: d,
+    totalSteps: n.steps.length,
+    show: A,
+    dismiss: t,
+    reset: C,
+    next: K,
+    prev: q,
+    skip: z,
+    goToStep: B
   };
 }
+const V = D({
+  startCurrentTour: () => {
+  },
+  registerTour: () => () => {
+  }
+});
+function X({ children: n }) {
+  const e = a(null), u = p((l) => (e.current = l, () => {
+    e.current === l && (e.current = null);
+  }), []), g = p(() => {
+    var l;
+    (l = e.current) == null || l.call(e);
+  }, []);
+  return /* @__PURE__ */ H(V.Provider, { value: { startCurrentTour: g, registerTour: u }, children: n });
+}
+function L() {
+  return G(V);
+}
+function Y(n, e) {
+  const { registerTour: u } = L(), g = J(n, e), l = a(g.show);
+  return l.current = g.show, P(() => u(() => l.current()), [u]), g;
+}
 export {
-  D as Trailguide,
-  J as findElement,
-  K as isElementVisible,
-  L as scrollToElement,
-  F as useTrail
+  X as TourRegistryProvider,
+  U as Trailguide,
+  F as findElement,
+  R as isElementVisible,
+  rr as scrollToElement,
+  er as tourStorage,
+  Y as useRegisterTour,
+  L as useTourRegistry,
+  W as useTrail,
+  J as useTrailManager
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trailguide/runtime",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "React hooks and components for Trailguide product tours.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,11 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit"
+  },
   "keywords": [
     "react",
     "product-tour",
@@ -39,7 +44,7 @@
     "react-dom": "^18.0.0"
   },
   "dependencies": {
-    "@trailguide/core": "0.0.3"
+    "@trailguide/core": "workspace:*"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",
@@ -50,10 +55,5 @@
     "typescript": "^5.4.0",
     "vite": "^5.2.0",
     "vite-plugin-dts": "^3.8.0"
-  },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly",
-    "typecheck": "tsc --noEmit"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Branden Langhals
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.