@trailguide/runtime 0.0.1

package/README.md

@@ -0,0 +1,105 @@
+# @trailguide/runtime
+
+React wrapper for Trailguide. Provides hooks and components for React apps.
+
+> **Note:** For non-React apps, use `@trailguide/core` directly.
+
+## Installation
+
+```bash
+npm install @trailguide/runtime @trailguide/core
+```
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { Trailguide } from '@trailguide/runtime';
+import '@trailguide/core/dist/style.css';
+import myTour from './tours/my-tour.json';
+
+function App() {
+  const [showTour, setShowTour] = useState(true);
+
+  return (
+    <>
+      <YourApp />
+      {showTour && (
+        <Trailguide
+          trail={myTour}
+          onComplete={() => setShowTour(false)}
+          onSkip={() => setShowTour(false)}
+          onStepChange={(step, index) => console.log(`Step ${index}:`, step)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+## API
+
+### `<Trailguide>`
+
+Main component that renders the tour.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `trail` | `Trail` | The trail JSON object |
+| `onComplete` | `() => void` | Called when user finishes all steps |
+| `onSkip` | `() => void` | Called when user skips the tour |
+| `onStepChange` | `(step, index) => void` | Called on each step change |
+
+### `useTrail(options)`
+
+Hook for programmatic control.
+
+```tsx
+import { useTrail } from '@trailguide/runtime';
+
+const {
+  currentStep,
+  currentStepIndex,
+  totalSteps,
+  isActive,
+  next,
+  prev,
+  skip,
+  goToStep,
+  start,
+  stop,
+} = useTrail({
+  trail,
+  onComplete,
+  onStepChange,
+  autoStart: false, // set true to start immediately
+});
+```
+
+## Types
+
+Types are re-exported from `@trailguide/core`:
+
+```typescript
+import type { Trail, Step, Placement } from '@trailguide/runtime';
+```
+
+## Keyboard Navigation
+
+- `→` or `Enter` - Next step
+- `←` - Previous step
+- `Escape` - Skip tour
+
+## Styling
+
+Import styles from the core package:
+
+```tsx
+import '@trailguide/core/dist/style.css';
+```
+
+CSS classes available for customization:
+- `.trailguide-overlay` - Main overlay container
+- `.trailguide-spotlight` - The darkened backdrop
+- `.trailguide-highlight` - Border around target element
+- `.trailguide-tooltip` - The tooltip container

package/dist/components/Trailguide.d.ts

@@ -0,0 +1,10 @@
+import { Trail, Step } from '@trailguide/core';
+
+export interface TrailguideProps {
+    trail: Trail;
+    onComplete?: () => void;
+    onStepChange?: (step: Step, index: number) => void;
+    onSkip?: () => void;
+}
+export declare function Trailguide({ trail, onComplete, onStepChange, onSkip, }: TrailguideProps): null;
+//# sourceMappingURL=Trailguide.d.ts.map

package/dist/components/Trailguide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Trailguide.d.ts","sourceRoot":"","sources":["../../src/components/Trailguide.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,UAAU,EACV,YAAY,EACZ,MAAM,GACP,EAAE,eAAe,QAqBjB"}

package/dist/hooks/useTrail.d.ts

@@ -0,0 +1,23 @@
+import { Trail, Step } from '@trailguide/core';
+
+export interface UseTrailOptions {
+    trail: Trail;
+    onComplete?: () => void;
+    onStepChange?: (step: Step, index: number) => void;
+    onSkip?: () => void;
+    autoStart?: boolean;
+}
+export interface UseTrailReturn {
+    currentStep: Step | null;
+    currentStepIndex: number;
+    totalSteps: number;
+    isActive: boolean;
+    next: () => void;
+    prev: () => void;
+    skip: () => void;
+    goToStep: (index: number) => void;
+    start: () => void;
+    stop: () => void;
+}
+export declare function useTrail({ trail, onComplete, onStepChange, onSkip, autoStart, }: UseTrailOptions): UseTrailReturn;
+//# sourceMappingURL=useTrail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useTrail.d.ts","sourceRoot":"","sources":["../../src/hooks/useTrail.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,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;IAClC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,UAAU,EACV,YAAY,EACZ,MAAM,EACN,SAAiB,GAClB,EAAE,eAAe,GAAG,cAAc,CA+ElC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Trail, Step, Placement, StepAction, NextTrigger, TrailguideOptions, } from '@trailguide/core';
+export { findElement, isElementVisible, scrollToElement, } 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,UAAU,EACV,WAAW,EACX,iBAAiB,GAClB,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"}

package/dist/index.js

@@ -0,0 +1,79 @@
+import { Trailguide as d } from "@trailguide/core";
+import { findElement as B, isElementVisible as D, scrollToElement as F } from "@trailguide/core";
+import { useRef as x, useEffect as v, useState as p, useCallback as l } from "react";
+function j({
+  trail: e,
+  onComplete: s,
+  onStepChange: c,
+  onSkip: u
+}) {
+  const n = x(null);
+  return v(() => (n.current = new d({
+    onComplete: s,
+    onStepChange: c,
+    onSkip: u
+  }), n.current.start(e), () => {
+    var f;
+    (f = n.current) == null || f.stop();
+  }), [e, s, c, u]), null;
+}
+function q({
+  trail: e,
+  onComplete: s,
+  onStepChange: c,
+  onSkip: u,
+  autoStart: n = !1
+}) {
+  const [f, T] = p(0), [a, i] = p(!1), r = x(null), E = a && e.steps[f] ? e.steps[f] : null, m = e.steps.length;
+  v(() => (r.current = new d({
+    onComplete: () => {
+      i(!1), s == null || s();
+    },
+    onStepChange: (t, o) => {
+      T(o), c == null || c(t, o);
+    },
+    onSkip: () => {
+      i(!1), u == null || u();
+    }
+  }), n && (r.current.start(e), i(!0)), () => {
+    var t;
+    (t = r.current) == null || t.stop();
+  }), [e, s, c, u, n]);
+  const I = l(() => {
+    r.current && (r.current.start(e), i(!0), T(0));
+  }, [e]), R = l(() => {
+    var t;
+    (t = r.current) == null || t.stop(), i(!1);
+  }, []), b = l(() => {
+    var t;
+    (t = r.current) == null || t.next();
+  }, []), w = l(() => {
+    var t;
+    (t = r.current) == null || t.prev();
+  }, []), A = l(() => {
+    var t;
+    (t = r.current) == null || t.skip();
+  }, []), g = l((t) => {
+    var o;
+    (o = r.current) == null || o.goToStep(t);
+  }, []);
+  return {
+    currentStep: E,
+    currentStepIndex: f,
+    totalSteps: m,
+    isActive: a,
+    next: b,
+    prev: w,
+    skip: A,
+    goToStep: g,
+    start: I,
+    stop: R
+  };
+}
+export {
+  j as Trailguide,
+  B as findElement,
+  D as isElementVisible,
+  F as scrollToElement,
+  q as useTrail
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@trailguide/runtime",
+  "version": "0.0.1",
+  "description": "React hooks and components for Trailguide product tours.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "react",
+    "product-tour",
+    "onboarding",
+    "walkthrough",
+    "tutorial",
+    "trailguide"
+  ],
+  "author": "Branden Langhals",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brandenlanghals/trailguide.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/brandenlanghals/trailguide#readme",
+  "bugs": {
+    "url": "https://github.com/brandenlanghals/trailguide/issues"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "dependencies": {
+    "@trailguide/core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0",
+    "vite-plugin-dts": "^3.8.0"
+  }
+}