@trailguide/core 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/dist/analytics.d.ts

@@ -0,0 +1,15 @@
+import type { AnalyticsConfig } from './types';
+export type AnalyticsEventType = 'trail_started' | 'step_viewed' | 'step_completed' | 'trail_completed' | 'trail_skipped';
+export interface AnalyticsEvent {
+    event_type: AnalyticsEventType;
+    trail_id: string;
+    user_id: string;
+    session_id: string;
+    step_id?: string;
+    step_index?: number;
+    timestamp: string;
+}
+export type AnalyticsEventPayload = Omit<AnalyticsEvent, 'user_id' | 'session_id' | 'timestamp'>;
+export declare function sendEvent(config: AnalyticsConfig, event: AnalyticsEventPayload): Promise<void>;
+export declare function resetSession(): void;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAiBD,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC,CAAC;AAGjG,wBAAsB,SAAS,CAC7B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}

package/dist/dom.d.ts

@@ -1,5 +1,6 @@
 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 escapeHtml(str: string): string;
 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

@@ -1 +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"}
+{"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,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C;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

@@ -1,5 +1,9 @@
-
+import './styles.css';
 export { Trailguide, start, stop, next, prev, skip } from './trailguide';
-export type { Trail, Step, Placement, StepAction, NextTrigger, TrailguideOptions, TrailguideState, } from './types';
+export type { Trail, Step, Placement, TrailguideOptions, AnalyticsConfig, } from './types';
+export type { AnalyticsEvent, AnalyticsEventType, } from './analytics';
 export { findElement, isElementVisible, scrollToElement, } from './dom';
+export { theme } from './theme';
+export { validateTrail, logValidationResults, } from './validate';
+export type { ValidationResult, ValidationError, ValidationWarning, } from './validate';
 //# 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":"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"}
+{"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,iBAAiB,EACjB,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,cAAc,EACd,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,GAChB,MAAM,OAAO,CAAC;AAEf,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EACL,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/style.css

@@ -1 +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)}
+:root{--trailguide-accent: #1a91a2;--trailguide-accent-hover: #158292;--trailguide-bg: #ffffff;--trailguide-text: #374151;--trailguide-title: #111827;--trailguide-text-muted: #6b7280;--trailguide-border: #e5e7eb;--trailguide-btn-bg: #ffffff;--trailguide-btn-text: #374151;--trailguide-btn-border: #d1d5db;--trailguide-btn-hover: #f9fafb;--trailguide-radius: 8px;--trailguide-shadow: 0 10px 25px rgba(0, 0, 0, .15);--trailguide-overlay: rgba(0, 0, 0, .5);--trailguide-max-width: 320px;--trailguide-min-width: 280px;--trailguide-font: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif}.dark{--trailguide-bg: #1e293b;--trailguide-text: #cbd5e1;--trailguide-title: #f8fafc;--trailguide-text-muted: #94a3b8;--trailguide-border: rgba(255, 255, 255, .08);--trailguide-btn-bg: rgba(255, 255, 255, .06);--trailguide-btn-text: #e2e8f0;--trailguide-btn-border: rgba(255, 255, 255, .1);--trailguide-btn-hover: rgba(255, 255, 255, .1);--trailguide-shadow: 0 10px 25px rgba(0, 0, 0, .4)}.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-spotlight svg rect[mask]{fill:var(--trailguide-overlay)}.trailguide-highlight{position:fixed;border-radius:calc(var(--trailguide-radius) / 2);box-shadow:0 0 0 2px var(--trailguide-accent),0 0 0 4px color-mix(in srgb,var(--trailguide-accent) 30%,transparent);transition:all .2s ease-out;pointer-events:none}.trailguide-tooltip{position:fixed;z-index:9999;pointer-events:auto;font-family:var(--trailguide-font)}.trailguide-tooltip-content{background:var(--trailguide-bg);border-radius:var(--trailguide-radius);box-shadow:var(--trailguide-shadow);max-width:var(--trailguide-max-width);min-width:var(--trailguide-min-width)}.trailguide-tooltip-header{padding:12px 16px;border-bottom:1px solid var(--trailguide-border);display:flex;justify-content:space-between;align-items:center}.trailguide-tooltip-title{font-size:14px;font-weight:600;color:var(--trailguide-title);margin:0}.trailguide-tooltip-close{background:none;border:none;cursor:pointer;padding:4px;color:var(--trailguide-text-muted);font-size:18px;line-height:1}.trailguide-tooltip-close:hover{color:var(--trailguide-title)}.trailguide-tooltip-body{padding:16px;font-size:14px;line-height:1.5;color:var(--trailguide-text)}.trailguide-tooltip-footer{padding:12px 16px;border-top:1px solid var(--trailguide-border);display:flex;justify-content:space-between;align-items:center}.trailguide-tooltip-progress{font-size:12px;color:var(--trailguide-text-muted)}.trailguide-tooltip-nav{display:flex;gap:8px}.trailguide-btn{padding:6px 12px;font-size:13px;font-weight:500;border-radius:calc(var(--trailguide-radius) - 2px);cursor:pointer;transition:all .15s ease}.trailguide-btn-secondary{border:1px solid var(--trailguide-btn-border);background:var(--trailguide-btn-bg);color:var(--trailguide-btn-text)}.trailguide-btn-secondary:hover{background:var(--trailguide-btn-hover)}.trailguide-btn-primary{border:none;background:var(--trailguide-accent);color:#fff}.trailguide-btn-primary:hover{background:var(--trailguide-accent-hover)}.trailguide-tooltip-arrow{position:absolute;width:10px;height:10px;background:var(--trailguide-bg);transform:rotate(45deg);box-shadow:-1px -1px 1px #0000000d}.trailguide-tooltip[data-placement^=top] .trailguide-tooltip-arrow{bottom:-5px;box-shadow:1px 1px 1px #0000000d}.trailguide-tooltip[data-placement^=bottom] .trailguide-tooltip-arrow{top:-5px;box-shadow:-1px -1px 1px #0000000d}.trailguide-tooltip[data-placement^=left] .trailguide-tooltip-arrow{right:-5px;box-shadow:1px -1px 1px #0000000d}.trailguide-tooltip[data-placement^=right] .trailguide-tooltip-arrow{left:-5px;box-shadow:-1px 1px 1px #0000000d}

package/dist/theme.d.ts

@@ -0,0 +1,33 @@
+export declare const theme: {
+    readonly bgBase: "#0f172a";
+    readonly bgCard: "#1e293b";
+    readonly bgGlass: "rgba(255,255,255,0.06)";
+    readonly bgInput: "rgba(255,255,255,0.03)";
+    readonly textPrimary: "#f8fafc";
+    readonly textSecondary: "#e2e8f0";
+    readonly textTertiary: "#cbd5e1";
+    readonly textMuted: "#94a3b8";
+    readonly textFaint: "#64748b";
+    readonly borderSubtle: "rgba(255,255,255,0.06)";
+    readonly borderPanel: "rgba(255,255,255,0.08)";
+    readonly borderControl: "rgba(255,255,255,0.1)";
+    readonly accent: "#1a91a2";
+    readonly accentBg: "rgba(26,145,162,0.15)";
+    readonly accentBorder: "rgba(26,145,162,0.3)";
+    readonly error: "#ef4444";
+    readonly errorBg: "rgba(239,68,68,0.1)";
+    readonly errorBorder: "rgba(239,68,68,0.3)";
+    readonly errorLight: "rgba(248,113,113,0.1)";
+    readonly errorText: "#fca5a5";
+    readonly success: "#10b981";
+    readonly successBg: "rgba(16,185,129,0.1)";
+    readonly successBorder: "rgba(16,185,129,0.3)";
+    readonly successText: "#6ee7b7";
+    readonly warningBg: "rgba(234,179,8,0.1)";
+    readonly disabled: "#9ca3af";
+    readonly disabledBg: "#4b5563";
+    readonly shadowLight: "0 4px 12px rgba(0,0,0,0.15)";
+    readonly shadowMedium: "0 4px 20px rgba(0,0,0,0.4)";
+    readonly shadowOverlay: "rgba(0,0,0,0.3)";
+};
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDR,CAAA"}

package/dist/trailguide.d.ts

@@ -1,5 +1,4 @@
-import { Trail, TrailguideOptions } from './types';
-
+import type { Trail, TrailguideOptions } from './types';
 export declare class Trailguide {
     private trail;
     private currentStepIndex;
@@ -9,6 +8,8 @@ export declare class Trailguide {
     private tooltip;
     private arrowEl;
     private cleanupFns;
+    private stepCleanupFns;
+    private instanceId;
     constructor(options?: TrailguideOptions);
     start(trail: Trail): void;
     stop(): void;
@@ -19,10 +20,12 @@ export declare class Trailguide {
     private complete;
     private createOverlay;
     private showStep;
+    private showErrorState;
     private updateSpotlight;
     private updateTooltip;
     private bindKeyboard;
     private cleanup;
+    private emitAnalytics;
 }
 export declare function start(trail: Trail, options?: TrailguideOptions): Trailguide;
 export declare function stop(): void;

package/dist/trailguide.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"trailguide.d.ts","sourceRoot":"","sources":["../src/trailguide.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAQ,iBAAiB,EAAa,MAAM,SAAS,CAAC;AAIzE,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;IACxC,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,UAAU,CAAwE;gBAE9E,OAAO,GAAE,iBAAsB;IAI3C,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAUzB,IAAI,IAAI,IAAI;IAKZ,IAAI,IAAI,IAAI;IAcZ,IAAI,IAAI,IAAI;IASZ,IAAI,IAAI,IAAI;IAOZ,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ7B,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,aAAa;IAoDrB,OAAO,CAAC,QAAQ;IAuChB,OAAO,CAAC,cAAc;IAoCtB,OAAO,CAAC,eAAe;YAkDT,aAAa;IA0C3B,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,aAAa;CAetB;AAKD,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAO3E;AAED,wBAAgB,IAAI,IAAI,IAAI,CAG3B;AAED,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,wBAAgB,IAAI,IAAI,IAAI,CAG3B"}