webdrive 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Placement options for the popover relative to the target element.
+ */
+type Position = "top" | "right" | "bottom" | "left";
+/**
+ * Alignment of the popover along the target element's axis.
+ */
+type Alignment = "start" | "center" | "end";
+/**
+ * Strategy to use when a target element is not immediately present in the DOM.
+ * - "skip": skips the step and advances to the next available step.
+ * - "stop": halts the tour safely.
+ * - "wait": observes DOM mutations until the element appears or timeout expires.
+ */
+type MissingElementBehavior = "skip" | "stop" | "wait";
+/**
+ * Step configuration interface for WebDrive.
+ */
+interface WebDriveStep {
+    /** Target element selector or DOM HTMLElement */
+    element: string | HTMLElement;
+    /** Title displayed in the popover header */
+    title?: string;
+    /** Plain text description rendered inside the popover content */
+    description?: string;
+    /** Optional HTML content for rich formatting */
+    content?: string;
+    /** Preferred popover position relative to target */
+    position?: Position;
+    /** Popover alignment relative to target */
+    align?: Alignment;
+    /** Padding around the highlighted element in pixels */
+    padding?: number;
+    /** Distance between the popover and the highlighted target in pixels */
+    offset?: number;
+    /** Whether to show the Next / Finish button on this step */
+    showNextButton?: boolean;
+    /** Whether to show the Previous button on this step */
+    showPreviousButton?: boolean;
+    /** Whether to show the Close button on this step */
+    showCloseButton?: boolean;
+    /** Custom text for Next button on this step */
+    nextButtonText?: string;
+    /** Custom text for Previous button on this step */
+    previousButtonText?: string;
+    /** Custom text for Done/Finish button on this step */
+    doneButtonText?: string;
+    /** Custom text for Close button on this step */
+    closeButtonText?: string;
+    /** Callback invoked when entering this step */
+    onEnter?: () => void | Promise<void>;
+    /** Callback invoked when leaving this step */
+    onLeave?: () => void | Promise<void>;
+    /** Allows future extensibility without breaking the public API */
+    [key: string]: unknown;
+}
+/**
+ * Custom storage adapter interface for tour completion persistence.
+ */
+interface WebDriveStorage {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+}
+/**
+ * Global configuration options for WebDrive.
+ */
+interface WebDriveOptions {
+    /** Unique ID for the tour (used for storage persistence) */
+    id?: string;
+    /** Sequence of tour steps */
+    steps: WebDriveStep[];
+    /** Automatically start the tour upon instantiation if not already completed */
+    autoStart?: boolean;
+    /** Show step counter progress indicator (e.g., "2 / 5") */
+    showProgress?: boolean;
+    /** Allow user to close the tour via close button or backdrop click */
+    allowClose?: boolean;
+    /** Animate transitions between steps */
+    animate?: boolean;
+    /** Smoothly scroll target elements into view */
+    smoothScroll?: boolean;
+    /** Display darkened backdrop overlay */
+    overlay?: boolean;
+    /** Opacity of the backdrop overlay (0.0 to 1.0) */
+    overlayOpacity?: number;
+    /** Color of the backdrop overlay (CSS color string) */
+    overlayColor?: string;
+    /** Custom base z-index for the tour overlay and popover */
+    zIndex?: number;
+    /** Default padding around highlighted elements in pixels */
+    stagePadding?: number;
+    /** Border radius for the highlighted cutout area in pixels */
+    stageRadius?: number;
+    /** Enable keyboard navigation (ArrowRight, ArrowLeft, Escape) */
+    keyboardNavigation?: boolean;
+    /** Close tour when pressing Escape key */
+    closeOnEscape?: boolean;
+    /** Show navigation buttons in popover footer */
+    showButtons?: boolean;
+    /** Text for Next button */
+    nextButtonText?: string;
+    /** Text for Previous button */
+    previousButtonText?: string;
+    /** Text for Done/Finish button */
+    doneButtonText?: string;
+    /** Text for Close button */
+    closeButtonText?: string;
+    /** Persist completed state in storage so tour doesn't repeat */
+    remember?: boolean;
+    /** Custom storage provider (defaults to window.localStorage with memory fallback) */
+    storage?: WebDriveStorage;
+    /** Behavior when a target element is not found */
+    missingElementBehavior?: MissingElementBehavior;
+    /** Maximum time in milliseconds to wait for a missing element if behavior is "wait" */
+    missingElementWaitTimeout?: number;
+    /** Custom renderer for progress text */
+    renderProgress?: (current: number, total: number) => string;
+    /** Callback invoked when the tour starts */
+    onStart?: () => void;
+    /** Callback invoked when moving to a new step */
+    onStepChange?: (step: WebDriveStep, index: number) => void;
+    /** Callback invoked when the tour completes the final step */
+    onComplete?: () => void;
+    /** Callback invoked when the tour is closed before completion or via close button */
+    onClose?: () => void;
+    /** Callback invoked when the tour is destroyed */
+    onDestroy?: () => void;
+}
+/**
+ * Event map for strongly typed WebDrive event emitter.
+ */
+interface WebDriveEvents {
+    start: void;
+    stepChange: {
+        step: WebDriveStep;
+        index: number;
+    };
+    complete: void;
+    close: void;
+    destroy: void;
+}
+/**
+ * Result returned by the positioning calculation engine.
+ */
+interface PopoverPositionResult {
+    top: number;
+    left: number;
+    placement: Position;
+    alignment: Alignment;
+    arrowTop?: number;
+    arrowLeft?: number;
+    arrowPlacement?: Position;
+}
+/**
+ * Parameters for the popover positioning calculation.
+ */
+interface CalculatePositionParams {
+    targetRect: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+        right?: number;
+        bottom?: number;
+    };
+    popoverRect: {
+        width: number;
+        height: number;
+    };
+    placement?: Position;
+    alignment?: Alignment;
+    offset?: number;
+    viewportPadding?: number;
+    arrowSize?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+}
+
+declare class WebDrive {
+    private options;
+    private emitter;
+    private storage;
+    private controller;
+    constructor(options: WebDriveOptions);
+    private ensureController;
+    start(startIndex?: number): Promise<void>;
+    stop(): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    goTo(index: number): Promise<void>;
+    refresh(): void;
+    destroy(): void;
+    isActive(): boolean;
+    getCurrentStep(): WebDriveStep | null;
+    getCurrentStepIndex(): number;
+    hasCompleted(): Promise<boolean>;
+    reset(): Promise<void>;
+    resetAll(): Promise<void>;
+    on<K extends keyof WebDriveEvents>(event: K, callback: (data: WebDriveEvents[K]) => void): this;
+    off<K extends keyof WebDriveEvents>(event: K, callback: (data: WebDriveEvents[K]) => void): this;
+}
+
+declare class EventEmitter {
+    private events;
+    on<K extends keyof WebDriveEvents>(event: K, handler: (data: WebDriveEvents[K]) => void): void;
+    off<K extends keyof WebDriveEvents>(event: K, handler: (data: WebDriveEvents[K]) => void): void;
+    emit<K extends keyof WebDriveEvents>(event: K, ...args: WebDriveEvents[K] extends void ? [] : [WebDriveEvents[K]]): void;
+    removeAllListeners(): void;
+}
+
+declare class StorageManager {
+    private storage;
+    private readonly prefix;
+    constructor(customStorage?: WebDriveStorage);
+    private getKey;
+    isCompleted(id: string): Promise<boolean>;
+    markCompleted(id: string): Promise<void>;
+    reset(id: string): Promise<void>;
+    resetAll(): Promise<void>;
+}
+
+declare class TourController {
+    private options;
+    private emitter;
+    private storage;
+    private overlay;
+    private popover;
+    private highlight;
+    private accessibility;
+    private currentStepIndex;
+    private tourActive;
+    private destroyed;
+    private resizeListener;
+    private scrollListener;
+    private rafId;
+    private waitObserver;
+    private waitTimeoutId;
+    constructor(options: WebDriveOptions, emitter: EventEmitter, storage: StorageManager);
+    start(startIndex?: number): Promise<void>;
+    stop(): Promise<void>;
+    complete(): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    goTo(index: number, direction?: "forward" | "backward"): Promise<void>;
+    refresh(): void;
+    destroy(): void;
+    isActive(): boolean;
+    getCurrentStep(): WebDriveStep | null;
+    getCurrentStepIndex(): number;
+    private syncUI;
+    private updatePosition;
+    private triggerStepLeave;
+    private advanceFromMissing;
+    private waitForElement;
+    private cleanupWaiting;
+    private setupViewportListeners;
+    private removeViewportListeners;
+}
+
+/**
+ * Computes optimal popover position, handles viewport collision, fallback, clamping,
+ * and arrow positioning.
+ */
+declare function calculatePopoverPosition(params: CalculatePositionParams): PopoverPositionResult;
+
+export { type Alignment, type CalculatePositionParams, EventEmitter, type MissingElementBehavior, type PopoverPositionResult, type Position, StorageManager, TourController, WebDrive, type WebDriveEvents, type WebDriveOptions, type WebDriveStep, type WebDriveStorage, calculatePopoverPosition, WebDrive as default };