diff --git a/llm.txt b/llm.txt new file mode 100644 index 00000000..91b58049 --- /dev/null +++ b/llm.txt @@ -0,0 +1,191 @@ +# Driver.js + +Driver.js is a lightweight (~5kb gzipped), vanilla TypeScript library for creating overlays, highlights, tours, and focus shifters on web pages. It has zero external dependencies. + +**Website**: https://driverjs.com +**Repository**: https://github.com/kamranahmedse/driver.js +**Version**: 1.4.0 +**License**: MIT + +## Project Structure + +``` +src/ + config.ts - Configuration types and defaults + driver.ts - Main Driver class - the public API + emitter.ts - Event emitter for publishing/subscribing to events + events.ts - Event type definitions + highlight.ts - Highlight element functionality + overlay.ts - Overlay rendering and management + popover.ts - Popover/tooltip rendering + state.ts - Application state management + utils.ts - Utility functions +``` + +## Installation + +```bash +npm install driver.js +# or +pnpm install driver.js +# or +yarn add driver.js +``` + +Or via CDN: +```html + + +``` + +## Basic Usage + +```javascript +import { driver } from "driver.js"; +import "driver.js/dist/driver.css"; + +const driverObj = driver(); +driverObj.highlight({ + element: "#some-element", + popover: { + title: "Title", + description: "Description" + } +}); +``` + +For tours with multiple steps: +```javascript +const driverObj = driver({ + showProgress: true, + steps: [ + { element: '.page-header', popover: { title: 'Title', description: 'Description' } }, + { element: '.top-nav', popover: { title: 'Title', description: 'Description' } }, + ] +}); +driverObj.drive(); +``` + +## Configuration + +### Config Type + +```typescript +type Config = { + // Array of steps for product tour + steps?: DriveStep[]; + + // Animation (default: true) + animate?: boolean; + // Overlay color (default: black) + overlayColor?: string; + // Smooth scroll to element (default: false) + smoothScroll?: boolean; + // Allow closing popover by clicking backdrop (default: true) + allowClose?: boolean; + // Backdrop opacity (default: 0.5) + overlayOpacity?: number; + // Overlay click behavior: 'close', 'nextStep', or function + overlayClickBehavior?: "close" | "nextStep" | ((element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void); + // Distance between highlighted element and cutout (default: 10) + stagePadding?: number; + // Radius of cutout (default: 5) + stageRadius?: number; + // Allow keyboard navigation (default: true) + allowKeyboardControl?: boolean; + // Disable interaction with highlighted element (default: false) + disableActiveInteraction?: boolean; + // Custom class for popover + popoverClass?: string; + // Distance between popover and highlighted element (default: 10) + popoverOffset?: number; + // Buttons to show (default: ["next", "previous", "close"] for tours, [] for single highlight) + showButtons?: AllowedButtons[]; + // Buttons to disable + disableButtons?: AllowedButtons[]; + // Show progress text (default: false) + showProgress?: boolean; + // Progress text template: {{current}}, {{total}} + progressText?: string; + // Button texts + nextBtnText?: string; + prevBtnText?: string; + doneBtnText?: string; + + // Hooks + onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State, driver: Driver }) => void; + onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onDestroyStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onDestroyed?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; +}; +``` + +### Popover Type + +```typescript +type Popover = { + title?: string; + description?: string; + // Position relative to target element + side?: "top" | "right" | "bottom" | "left"; + align?: "start" | "center" | "end"; + showButtons?: ("next" | "previous" | "close")[]; + disableButtons?: ("next" | "previous" | "close")[]; + nextBtnText?: string; + prevBtnText?: string; + doneBtnText?: string; + showProgress?: boolean; + progressText?: string; + popoverClass?: string; + onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State, driver: Driver }) => void; + onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; +} +``` + +### DriveStep Type + +```typescript +type DriveStep = { + // DOM element, CSS selector, or function returning Element + element?: Element | string | (() => Element); + popover?: Popover; + disableActiveInteraction?: boolean; + onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; + onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State, driver: Driver }) => void; +} +``` + +### State Type + +```typescript +type State = { + isInitialized?: boolean; + activeIndex?: number; + activeElement?: Element; + activeStep?: DriveStep; + previousElement?: Element; + previousStep?: DriveStep; + popover?: PopoverDOM; +} +``` + +## Build Commands + +- `npm run dev` - Start dev server with Vite +- `npm run build` - Build for production (TypeScript + Vite + dts-bundle-generator) +- `npm run test` - Run tests with Vitest +- `npm run format` - Format code with Prettier + +## Entry Points + +- Main export: `./dist/driver.js.cjs` (CommonJS) and `./dist/driver.js.mjs` (ESM) +- CSS: `./dist/driver.css` +- Types: `./dist/driver.js.d.ts`