@trailguide/core 0.0.1

package/README.md

@@ -0,0 +1,125 @@
+# @trailguide/core
+
+Framework-agnostic product tours. Works with any web app - vanilla JS, React, Vue, Svelte, or anything else.
+
+## Installation
+
+```bash
+npm install @trailguide/core
+```
+
+## Quick Start
+
+```js
+import { start } from '@trailguide/core';
+import '@trailguide/core/styles.css';
+
+// Load your trail
+const trail = {
+  id: 'welcome',
+  title: 'Welcome Tour',
+  version: '1.0.0',
+  steps: [
+    {
+      id: 'step-1',
+      target: '#create-button',
+      placement: 'bottom',
+      title: 'Create something',
+      content: 'Click here to get started.'
+    }
+  ]
+};
+
+// Start the tour
+start(trail, {
+  onComplete: () => console.log('Tour completed!'),
+  onSkip: () => console.log('Tour skipped'),
+});
+```
+
+## CDN Usage (No Build Step)
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@trailguide/core/dist/trailguide.css">
+<script src="https://unpkg.com/@trailguide/core/dist/trailguide.umd.js"></script>
+<script>
+  Trailguide.start({
+    id: 'welcome',
+    title: 'Welcome',
+    version: '1.0.0',
+    steps: [
+      { id: '1', target: '#btn', placement: 'bottom', title: 'Click me', content: 'Start here' }
+    ]
+  });
+</script>
+```
+
+## API
+
+### Functions
+
+```js
+import { start, stop, next, prev, skip } from '@trailguide/core';
+
+start(trail, options)  // Start a tour
+stop()                 // Stop the current tour
+next()                 // Go to next step
+prev()                 // Go to previous step
+skip()                 // Skip/close the tour
+```
+
+### Class API
+
+```js
+import { Trailguide } from '@trailguide/core';
+
+const tour = new Trailguide({
+  onComplete: () => {},
+  onSkip: () => {},
+  onStepChange: (step, index) => {},
+});
+
+tour.start(trail);
+tour.next();
+tour.prev();
+tour.goToStep(2);
+tour.stop();
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onComplete` | `() => void` | Called when tour finishes |
+| `onSkip` | `() => void` | Called when user skips |
+| `onStepChange` | `(step, index) => void` | Called on each step change |
+
+## Trail Format
+
+```typescript
+interface Trail {
+  id: string;
+  title: string;
+  version: string;
+  steps: Step[];
+}
+
+interface Step {
+  id: string;
+  target: string;       // CSS selector
+  placement: 'top' | 'bottom' | 'left' | 'right';
+  title: string;
+  content: string;
+}
+```
+
+## Keyboard Shortcuts
+
+- `→` or `Enter` - Next step
+- `←` - Previous step
+- `Escape` - Skip tour
+
+## Framework Wrappers
+
+- **React**: Use `@trailguide/runtime` for hooks and components
+- **Vue/Svelte/etc**: Use this package directly

package/dist/dom.d.ts

@@ -0,0 +1,5 @@
+export declare function findElement(selector: string): HTMLElement | null;
+export declare function isElementVisible(element: HTMLElement): boolean;
+export declare function scrollToElement(element: HTMLElement): void;
+export declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, parent?: HTMLElement): HTMLElementTagNameMap[K];
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAOhE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAW9D;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAM1D;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACjE,GAAG,EAAE,CAAC,EACN,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,qBAAqB,CAAC,CAAC,CAAC,CAK1B"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+
+export { Trailguide, start, stop, next, prev, skip } from './trailguide';
+export type { Trail, Step, Placement, StepAction, NextTrigger, TrailguideOptions, TrailguideState, } from './types';
+export { findElement, isElementVisible, scrollToElement, } from './dom';
+//# 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":"AAAA,OAAO,cAAc,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzE,YAAY,EACV,KAAK,EACL,IAAI,EACJ,SAAS,EACT,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,GAChB,MAAM,OAAO,CAAC"}

package/dist/style.css

@@ -0,0 +1 @@
+.trailguide-overlay{position:fixed;top:0;right:0;bottom:0;left:0;z-index:9998;pointer-events:none}.trailguide-spotlight{position:absolute;top:0;right:0;bottom:0;left:0}.trailguide-spotlight svg{width:100%;height:100%}.trailguide-highlight{position:fixed;border-radius:4px;box-shadow:0 0 0 2px #3b82f6,0 0 0 4px #3b82f64d;transition:all .2s ease-out;pointer-events:none}.trailguide-tooltip{position:fixed;z-index:9999;pointer-events:auto;font-family:system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif}.trailguide-tooltip-content{background:#fff;border-radius:8px;box-shadow:0 10px 25px #00000026;max-width:320px;min-width:280px}.trailguide-tooltip-header{padding:12px 16px;border-bottom:1px solid #e5e7eb;display:flex;justify-content:space-between;align-items:center}.trailguide-tooltip-title{font-size:14px;font-weight:600;color:#111827;margin:0}.trailguide-tooltip-close{background:none;border:none;cursor:pointer;padding:4px;color:#6b7280;font-size:18px;line-height:1}.trailguide-tooltip-close:hover{color:#374151}.trailguide-tooltip-body{padding:16px;font-size:14px;line-height:1.5;color:#374151}.trailguide-tooltip-footer{padding:12px 16px;border-top:1px solid #e5e7eb;display:flex;justify-content:space-between;align-items:center}.trailguide-tooltip-progress{font-size:12px;color:#6b7280}.trailguide-tooltip-nav{display:flex;gap:8px}.trailguide-btn{padding:6px 12px;font-size:13px;font-weight:500;border-radius:6px;cursor:pointer;transition:all .15s ease}.trailguide-btn-secondary{border:1px solid #d1d5db;background:#fff;color:#374151}.trailguide-btn-secondary:hover{background:#f9fafb}.trailguide-btn-primary{border:none;background:#3b82f6;color:#fff}.trailguide-btn-primary:hover{background:#2563eb}.trailguide-tooltip-arrow{position:absolute;width:12px;height:12px;background:#fff;transform:rotate(45deg)}

package/dist/trailguide.d.ts

@@ -0,0 +1,32 @@
+import { Trail, TrailguideOptions } from './types';
+
+export declare class Trailguide {
+    private trail;
+    private currentStepIndex;
+    private isActive;
+    private options;
+    private overlay;
+    private tooltip;
+    private arrowEl;
+    private cleanupFns;
+    constructor(options?: TrailguideOptions);
+    start(trail: Trail): void;
+    stop(): void;
+    next(): void;
+    prev(): void;
+    skip(): void;
+    goToStep(index: number): void;
+    private complete;
+    private createOverlay;
+    private showStep;
+    private updateSpotlight;
+    private updateTooltip;
+    private bindKeyboard;
+    private cleanup;
+}
+export declare function start(trail: Trail, options?: TrailguideOptions): Trailguide;
+export declare function stop(): void;
+export declare function next(): void;
+export declare function prev(): void;
+export declare function skip(): void;
+//# sourceMappingURL=trailguide.d.ts.map

package/dist/trailguide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailguide.d.ts","sourceRoot":"","sources":["../src/trailguide.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAQ,iBAAiB,EAAa,MAAM,SAAS,CAAC;AAGzE,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAyB;IAGxC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAA4B;IAG3C,OAAO,CAAC,UAAU,CAAsB;gBAE5B,OAAO,GAAE,iBAAsB;IAI3C,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IASzB,IAAI,IAAI,IAAI;IAKZ,IAAI,IAAI,IAAI;IAWZ,IAAI,IAAI,IAAI;IASZ,IAAI,IAAI,IAAI;IAMZ,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ7B,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,aAAa;IAmDrB,OAAO,CAAC,QAAQ;IAwBhB,OAAO,CAAC,eAAe;YAkDT,aAAa;IAyC3B,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,OAAO;CAShB;AAKD,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAO3E;AAED,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,wBAAgB,IAAI,IAAI,IAAI,CAE3B"}