$ show nilbuild/driver.js
This repository is a monorepo for `driver.js`, a lightweight, zero-dependency JavaScript library for creating product tours, feature highlights, and contextual hints on web pages. The core library is in `packages/driver/` and exports two main factories: `driver()` for guided tours with an overlay cutout and popover, and `hints()` for persistent beacon-style hints. The architecture follows an instance-based pattern where each driver or hints instance owns its configuration, state, and event emitter, avoiding global state. Key modules include a pure-geometry positioning system (`position.ts`), an SVG overlay with animated stage transitions (`overlay.ts`, `stage.ts`), a popover renderer shared between tours and hints (`popover.ts`), and capture-phase click handling with `WeakMap`-based listeners (`click.ts`). The library has no runtime dependencies, comprehensive test coverage (vitest + jsdom), and supports keyboard navigation, animation, theming via CSS custom properties, and lifecycle hooks. The monorepo also includes two Astro-based applications: `apps/docs` (documentation site with live code samples) and `apps/playground` (interactive examples). The codebase demonstrates strong engineering practices with clean abstractions, instance isolation, and reusable primitives.
The LLM identified 4 files worth highlighting for reuse:
Provides a per-instance context object that holds configuration, state, and an event emitter. Each driver() or hints() call creates its own context, preventing global state pollution. This pattern is cleanly extractable for any library needing isolated instances with event-driven communication.
Implements pure functions for calculating popover placement relative to a target element, including arrow positioning and auto-flip to stay within the viewport. No internal dependencies; takes coordinates and dimensions as inputs and returns position data. Reusable in any UI library requiring smart positioning.
Handles click interception during tours by attaching a capture-phase listener on `document`. Uses a `WeakMap` to associate handlers with driver instances, preventing memory leaks. This pattern is reusable for any modal or overlay system that needs to block clicks outside its UI while allowing interaction with highlighted elements.
Generates SVG path strings for the overlay cutout (stage) that highlights a target element. Supports rounded rectangles and smooth transitions via `requestAnimationFrame` with easing. The path generation is a pure function of element bounding rect and padding, making it reusable for any spotlight or magnifier effect.