webdrive 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webdrive
+
+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/README.md

@@ -0,0 +1,620 @@
+# webdrive
+
+> **A production-ready, framework-agnostic TypeScript UI tour and onboarding walkthrough library with zero runtime dependencies.**
+
+[![npm version](https://img.shields.io/npm/v/webdrive.svg?style=flat-square)](https://www.npmjs.com/package/webdrive)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?style=flat-square)](https://www.typescriptlang.org/)
+
+`webdrive` provides guided, step-by-step product walkthroughs and feature tours for modern web applications. It works directly with browser DOM APIs and does not depend on React, Vue, Angular, Svelte, Tailwind CSS, or any other UI framework.
+
+---
+
+## ✨ Features
+
+- 🎯 **100% Framework-Agnostic** — Works seamlessly in Vanilla JavaScript, TypeScript, React, Next.js, Vue, Nuxt, Angular, Svelte, or any DOM environment.
+- 🪶 **Zero Dependencies** — Zero external runtime dependencies. Extremely lightweight and fast.
+- 🛡️ **Non-Destructive Highlighting** — Employs a full-screen SVG cutout mask to highlight elements without altering parent stacking contexts, `z-index`, `overflow`, or `transform` styles.
+- 📐 **Dedicated Positioning Engine** — Automatic viewport edge collision detection, intelligent flip fallbacks, coordinate clamping, and arrow alignment.
+- ♿ **Accessible by Design** — Proper dialog semantics (`role="dialog"`, `aria-modal="true"`, `aria-labelledby`, `aria-describedby`), focus trapping, automatic focus restoration, and keyboard navigation.
+- ⌨️ **Keyboard Support** — `ArrowRight` (Next), `ArrowLeft` (Previous), and `Escape` (Close).
+- 💾 **Persistent State** — Remember completed tours across sessions with namespaced localStorage support and custom storage adapters.
+- ⏳ **Dynamic Element Support** — Gracefully handles elements that load asynchronously (`missingElementBehavior: "skip" | "stop" | "wait"`).
+- 🌓 **Themeable & Dark Mode Ready** — Controlled entirely via CSS custom properties. Drop-in compatible with Tailwind CSS and shadcn/ui.
+- ⚡ **SSR Safe** — Zero access to `window`, `document`, or `localStorage` during module evaluation. Safe to import in Next.js Server Components and Node.js.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install webdrive
+```
+
+or with yarn / pnpm / bun:
+
+```bash
+pnpm add webdrive
+# or
+yarn add webdrive
+# or
+bun add webdrive
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import CSS & JavaScript
+
+```typescript
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+
+const tour = new WebDrive({
+  id: "dashboard-tour",
+  steps: [
+    {
+      element: "#sidebar",
+      title: "Navigation",
+      description: "Use the sidebar to navigate across the application.",
+      position: "right",
+    },
+    {
+      element: "#dashboard-stats",
+      title: "Dashboard Statistics",
+      description: "View real-time business metrics and transaction velocity.",
+      position: "bottom",
+    },
+    {
+      element: "#profile-menu",
+      title: "User Profile",
+      description: "Configure your personal preferences and organization settings.",
+      position: "left",
+    },
+  ],
+  showProgress: true,
+  animate: true,
+  smoothScroll: true,
+  remember: true,
+});
+
+tour.start();
+```
+
+---
+
+## 🛠️ Step Configuration (`WebDriveStep`)
+
+Each step in the `steps` array can be configured with the following properties:
+
+```typescript
+interface WebDriveStep {
+  /** Target element selector string (e.g., "#sidebar") or HTMLElement */
+  element: string | HTMLElement;
+
+  /** Title displayed in the popover header */
+  title?: string;
+
+  /** Plain text description rendered safely inside the content area */
+  description?: string;
+
+  /** Optional custom HTML content (used when rich HTML is required) */
+  content?: string;
+
+  /** Preferred placement: "top" | "right" | "bottom" | "left" (default: "bottom") */
+  position?: "top" | "right" | "bottom" | "left";
+
+  /** Alignment along target axis: "start" | "center" | "end" (default: "center") */
+  align?: "start" | "center" | "end";
+
+  /** Extra padding around the highlighted cutout in pixels (default: 8) */
+  padding?: number;
+
+  /** Spacing between target and popover in pixels (default: 12) */
+  offset?: number;
+
+  /** Show/hide next button for this step */
+  showNextButton?: boolean;
+
+  /** Show/hide previous button for this step */
+  showPreviousButton?: boolean;
+
+  /** Show/hide close button for this step */
+  showCloseButton?: boolean;
+
+  /** Custom label for Next button */
+  nextButtonText?: string;
+
+  /** Custom label for Previous button */
+  previousButtonText?: string;
+
+  /** Custom label for Done button (on final step) */
+  doneButtonText?: string;
+
+  /** Custom label for Close button */
+  closeButtonText?: string;
+
+  /** Hook called when entering this step */
+  onEnter?: () => void | Promise<void>;
+
+  /** Hook called when leaving this step */
+  onLeave?: () => void | Promise<void>;
+
+  /** Extensible custom properties */
+  [key: string]: unknown;
+}
+```
+
+---
+
+## ⚙️ WebDrive Configuration Options (`WebDriveOptions`)
+
+```typescript
+interface WebDriveOptions {
+  /** Unique ID for the tour (required for persistent completion tracking) */
+  id?: string;
+
+  /** Array of tour steps */
+  steps: WebDriveStep[];
+
+  /** Automatically start the tour on instantiation (if not already completed) */
+  autoStart?: boolean;
+
+  /** Show progress counter in popover footer (e.g. "2 / 5") (default: true) */
+  showProgress?: boolean;
+
+  /** Allow user to close the tour via close button or backdrop click (default: true) */
+  allowClose?: boolean;
+
+  /** Smooth animated transitions between steps and cutout bounds (default: true) */
+  animate?: boolean;
+
+  /** Smoothly scroll target element into viewport center before highlighting (default: true) */
+  smoothScroll?: boolean;
+
+  /** Display darkened backdrop overlay (default: true) */
+  overlay?: boolean;
+
+  /** Opacity of backdrop overlay (default: 0.6) */
+  overlayOpacity?: number;
+
+  /** Backdrop overlay color (default: "rgba(0, 0, 0, 0.6)") */
+  overlayColor?: string;
+
+  /** Base z-index for tour layers (default: 100000) */
+  zIndex?: number;
+
+  /** Default padding around highlighted targets (default: 8) */
+  stagePadding?: number;
+
+  /** Border radius of the cutout hole in pixels (default: 6) */
+  stageRadius?: number;
+
+  /** Enable keyboard navigation: Arrow keys & Escape (default: true) */
+  keyboardNavigation?: boolean;
+
+  /** Close tour when pressing Escape (default: true) */
+  closeOnEscape?: boolean;
+
+  /** Show navigation buttons in footer (default: true) */
+  showButtons?: boolean;
+
+  /** Global label for Next button (default: "Next") */
+  nextButtonText?: string;
+
+  /** Global label for Previous button (default: "Previous") */
+  previousButtonText?: string;
+
+  /** Global label for Done button (default: "Done") */
+  doneButtonText?: string;
+
+  /** Global label for Close button (default: "Close tour") */
+  closeButtonText?: string;
+
+  /** Remember completion status in storage so tour doesn't repeat (default: false) */
+  remember?: boolean;
+
+  /** Custom storage provider adapter (defaults to window.localStorage) */
+  storage?: WebDriveStorage;
+
+  /** Strategy when a step target element is not found: "skip" | "stop" | "wait" (default: "skip") */
+  missingElementBehavior?: "skip" | "stop" | "wait";
+
+  /** Maximum time in milliseconds to wait for a missing element if behavior is "wait" (default: 3000) */
+  missingElementWaitTimeout?: number;
+
+  /** Custom progress text formatter function (e.g. (cur, total) => `Step ${cur} of ${total}`) */
+  renderProgress?: (current: number, total: number) => string;
+
+  /** Callback invoked when tour starts */
+  onStart?: () => void;
+
+  /** Callback invoked when advancing or reversing steps */
+  onStepChange?: (step: WebDriveStep, index: number) => void;
+
+  /** Callback invoked when final step is finished */
+  onComplete?: () => void;
+
+  /** Callback invoked when tour is closed before completion */
+  onClose?: () => void;
+
+  /** Callback invoked when tour is destroyed */
+  onDestroy?: () => void;
+}
+```
+
+---
+
+## 🕹️ Public API Methods
+
+```typescript
+const tour = new WebDrive(options);
+
+// Starts the tour from the first step (or optional index)
+await tour.start(startIndex?: number);
+
+// Stops the active tour and cleans up UI
+await tour.stop();
+
+// Moves to the next step (or completes if on the final step)
+await tour.next();
+
+// Moves to the previous step
+await tour.previous();
+
+// Jumps directly to a specific step index
+await tour.goTo(index: number);
+
+// Recalculates positioning (call on window resize, layout shift, or dynamic content)
+tour.refresh();
+
+// Completely cleans up all DOM nodes, listeners, timers, and observers
+tour.destroy();
+
+// Returns true if the tour is currently active
+tour.isActive(): boolean;
+
+// Returns the current active step configuration object or null
+tour.getCurrentStep(): WebDriveStep | null;
+
+// Returns the zero-based index of the current step (-1 if inactive)
+tour.getCurrentStepIndex(): number;
+
+// Returns true if this tour has already been marked completed in storage
+await tour.hasCompleted(): Promise<boolean>;
+
+// Resets completion state for this tour ID
+await tour.reset(): Promise<void>;
+
+// Resets completion state for all WebDrive tours stored locally
+await tour.resetAll(): Promise<void>;
+```
+
+---
+
+## 📡 Event System
+
+In addition to configuration callbacks, `WebDrive` provides a type-safe pub/sub event system:
+
+```typescript
+tour.on("start", () => {
+  console.log("Tour started");
+});
+
+tour.on("stepChange", ({ step, index }) => {
+  console.log(`Current step index: ${index}, title: ${step.title}`);
+});
+
+tour.on("complete", () => {
+  console.log("Tour completed");
+});
+
+tour.on("close", () => {
+  console.log("Tour was dismissed");
+});
+
+tour.on("destroy", () => {
+  console.log("Tour was destroyed");
+});
+
+// Remove listeners with tour.off
+const handler = () => { /* ... */ };
+tour.on("stepChange", handler);
+tour.off("stepChange", handler);
+```
+
+---
+
+## 🏛️ DOM Architecture & Selectors
+
+WebDrive creates an isolated UI container with `data-webdrive-*` attributes and namespaced CSS classes:
+
+```html
+<div data-webdrive-root class="webdrive-root">
+  <!-- SVG Cutout Mask Overlay -->
+  <svg data-webdrive-overlay class="webdrive-overlay">
+    <defs>
+      <mask id="webdrive-mask-xyz">
+        <rect width="100%" height="100%" fill="#ffffff" />
+        <rect data-webdrive-cutout class="webdrive-cutout" rx="6" ry="6" fill="#000000" />
+      </mask>
+    </defs>
+    <rect width="100%" height="100%" mask="url(#webdrive-mask-xyz)" />
+  </svg>
+
+  <!-- Interactive Stage Boundary -->
+  <div data-webdrive-stage class="webdrive-stage"></div>
+
+  <!-- Popover Dialog Card -->
+  <div data-webdrive-popover class="webdrive-popover" role="dialog" aria-modal="true">
+    <div data-webdrive-header class="webdrive-header">
+      <h2 data-webdrive-title class="webdrive-title" id="webdrive-title"></h2>
+      <button data-webdrive-close class="webdrive-close" aria-label="Close tour">&times;</button>
+    </div>
+    <div data-webdrive-content class="webdrive-content" id="webdrive-description"></div>
+    <div data-webdrive-footer class="webdrive-footer">
+      <button data-webdrive-prev class="webdrive-button webdrive-prev"></button>
+      <div data-webdrive-progress class="webdrive-progress"></div>
+      <button data-webdrive-next class="webdrive-button webdrive-next"></button>
+    </div>
+    <div data-webdrive-arrow class="webdrive-arrow"></div>
+  </div>
+</div>
+```
+
+---
+
+## 🎨 Styling & CSS Theme Variables
+
+Override theme variables in your CSS to tailor WebDrive to your brand:
+
+```css
+:root {
+  --webdrive-background: #ffffff;
+  --webdrive-foreground: #111827;
+  --webdrive-border: #e5e7eb;
+  --webdrive-primary: #18181b;
+  --webdrive-primary-foreground: #ffffff;
+  --webdrive-muted: #6b7280;
+  --webdrive-overlay: rgba(0, 0, 0, 0.6);
+  --webdrive-overlay-opacity: 0.6;
+  --webdrive-radius: 0.5rem;
+  --webdrive-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
+  --webdrive-z-index: 100000;
+  --webdrive-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+```
+
+### Dark Mode
+
+WebDrive automatically responds to dark mode when `.dark` or `[data-theme="dark"]` is present on `<html>` or `<body>`, or via system `@media (prefers-color-scheme: dark)`:
+
+```css
+.dark {
+  --webdrive-background: #18181b;
+  --webdrive-foreground: #f4f4f5;
+  --webdrive-border: #27272a;
+  --webdrive-primary: #fafafa;
+  --webdrive-primary-foreground: #18181b;
+  --webdrive-muted: #a1a1aa;
+  --webdrive-overlay: rgba(0, 0, 0, 0.75);
+  --webdrive-shadow: 0 10px 30px rgba(0, 0, 0, 0.6);
+}
+```
+
+### Tailwind CSS & shadcn/ui Integration
+
+WebDrive does not bundle or require Tailwind CSS. You can easily style the exposed classes with `@apply` in your global CSS:
+
+```css
+.webdrive-popover {
+  @apply rounded-xl border border-border bg-card text-card-foreground shadow-2xl p-5;
+}
+
+.webdrive-title {
+  @apply text-base font-semibold text-foreground tracking-tight;
+}
+
+.webdrive-content {
+  @apply text-sm text-muted-foreground leading-relaxed;
+}
+
+.webdrive-next {
+  @apply rounded-md bg-primary px-3.5 py-2 text-sm font-medium text-primary-foreground shadow-sm hover:bg-primary/90;
+}
+
+.webdrive-prev {
+  @apply rounded-md border border-input bg-background px-3.5 py-2 text-sm font-medium text-foreground hover:bg-accent;
+}
+```
+
+---
+
+## 🌐 Framework Integrations
+
+### React
+
+```tsx
+import { useEffect, useRef } from "react";
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+
+export function AppTour() {
+  const tourRef = useRef<WebDrive | null>(null);
+
+  useEffect(() => {
+    tourRef.current = new WebDrive({
+      id: "react-app-tour",
+      remember: true,
+      steps: [
+        { element: "#sidebar", title: "Sidebar", description: "Quick navigation links." },
+        { element: "#search-bar", title: "Search", description: "Search across all assets." },
+      ],
+    });
+
+    tourRef.current.start();
+
+    return () => {
+      tourRef.current?.destroy();
+    };
+  }, []);
+
+  return null;
+}
+```
+
+### Next.js (App Router & Pages Router)
+
+`webdrive` is completely safe for Next.js Server Components. In the App Router, initialize WebDrive inside a client component with `"use client"`:
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+
+export function OnboardingTour() {
+  useEffect(() => {
+    const tour = new WebDrive({
+      id: "nextjs-onboarding",
+      steps: [
+        { element: "#hero", title: "Welcome", description: "Welcome to our Next.js app!" },
+      ],
+    });
+
+    tour.start();
+
+    return () => {
+      tour.destroy();
+    };
+  }, []);
+
+  return null;
+}
+```
+
+### Vue 3 / Nuxt
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from "vue";
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+
+let tour = null;
+
+onMounted(() => {
+  tour = new WebDrive({
+    steps: [
+      { element: "#vue-nav", title: "Navigation", description: "Explore the app." },
+      { element: "#vue-content", title: "Content", description: "Your main dashboard." },
+    ],
+  });
+  tour.start();
+});
+
+onUnmounted(() => {
+  tour?.destroy();
+});
+</script>
+```
+
+### Angular
+
+```typescript
+import { Component, OnInit, OnDestroy } from "@angular/core";
+import { WebDrive } from "webdrive";
+
+@Component({
+  selector: "app-tour",
+  template: "",
+  styleUrls: ["node_modules/webdrive/dist/webdrive.css"],
+})
+export class TourComponent implements OnInit, OnDestroy {
+  private tour?: WebDrive;
+
+  ngOnInit(): void {
+    this.tour = new WebDrive({
+      steps: [
+        { element: "#angular-header", title: "Header", description: "Main application header." },
+      ],
+    });
+    this.tour.start();
+  }
+
+  ngOnDestroy(): void {
+    this.tour?.destroy();
+  }
+}
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { onMount, onDestroy } from "svelte";
+  import { WebDrive } from "webdrive";
+  import "webdrive/styles.css";
+
+  let tour;
+
+  onMount(() => {
+    tour = new WebDrive({
+      steps: [
+        { element: "#svelte-intro", title: "Intro", description: "Welcome to Svelte!" }
+      ],
+    });
+    tour.start();
+  });
+
+  onDestroy(() => {
+    tour?.destroy();
+  });
+</script>
+```
+
+---
+
+## 🏃 Running the Demo & Tests
+
+### Run the Interactive Demo Locally
+
+To test WebDrive interactively in your browser:
+
+```bash
+# Start a local static web server
+npx serve .
+# Open http://localhost:3000/examples/ in your browser
+```
+
+### Run Automated Tests
+
+```bash
+npm test
+```
+
+### Typecheck
+
+```bash
+npm run typecheck
+```
+
+### Build Production Bundles
+
+```bash
+npm run build
+```
+
+Generates:
+- `dist/index.js` (ES Module)
+- `dist/index.cjs` (CommonJS)
+- `dist/index.d.ts` (TypeScript types)
+- `dist/webdrive.css` (Styles)
+
+---
+
+## 📄 License
+
+MIT © [webdrive](https://github.com/Abhi-6284/webdrive)