torchlit 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <br />
-  <img src="https://em-content.zobj.net/source/apple/391/fire_1f525.png" width="80" />
+  <img src="assets/logo.svg" width="80" height="80" alt="Torchlit logo" />
   <br />
 </p>
 
@@ -12,10 +12,15 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/torchlit"><img src="https://img.shields.io/npm/v/torchlit?color=blue&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/barryking/torchlit/actions/workflows/ci.yml"><img src="https://github.com/barryking/torchlit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/torchlit"><img src="https://img.shields.io/npm/v/torchlit?color=F26122&label=npm" alt="npm version" /></a>
   <img src="https://img.shields.io/bundlephobia/minzip/torchlit?label=gzip" alt="bundle size" />
-  <img src="https://img.shields.io/badge/lit-%5E3.0-blue" alt="lit peer" />
-  <img src="https://img.shields.io/badge/license-MIT-green" alt="license" />
+  <img src="https://img.shields.io/badge/lit-%5E3.0-2F80ED" alt="lit peer" />
+  <img src="https://img.shields.io/badge/license-MIT-27AE60" alt="license" />
+</p>
+
+<p align="center">
+  <a href="https://barryking.github.io/torchlit/"><strong>Docs & Live Demo</strong></a>
 </p>
 
 ---
@@ -28,9 +33,11 @@ Most tour libraries break the moment your UI uses Shadow DOM. Torchlit was built
 |---|:---:|:---:|:---:|:---:|
 | Shadow DOM traversal | **Yes** | No | No | No |
 | Framework agnostic | **Yes** | Yes | Yes | React only |
-| Bundle size (gzip) | **~6 KB** | ~50 KB | ~15 KB | ~40 KB |
+| Bundle size (gzip) | **~9 KB** | ~50 KB | ~15 KB | ~40 KB |
 | Web Component | **Yes** | No | No | No |
+| Accessibility (ARIA + focus trap) | **Yes** | Partial | Partial | Yes |
 | CSS custom property theming | **Yes** | No | Partial | No |
+| Smart auto-positioning | **Yes** | Yes | No | Yes |
 | Async `beforeShow` hooks | **Yes** | Yes | No | Yes |
 | Zero runtime dependencies | **Yes** | Popper.js | No | React |
 
@@ -53,10 +60,8 @@ npm install torchlit lit
 import { createTourService } from 'torchlit';
 import 'torchlit/overlay'; // registers <torchlit-overlay>
 
-// 1. Create a service
 const tours = createTourService();
 
-// 2. Register a tour
 tours.register({
   id: 'welcome',
   name: 'Welcome',
@@ -74,26 +79,14 @@ tours.register({
       message: 'Use the sidebar to move between pages.',
       placement: 'right',
     },
-    {
-      target: 'search-bar',
-      title: 'Search',
-      message: 'Find anything instantly.',
-      placement: 'bottom',
-      beforeShow: async () => {
-        // Navigate, load data, or do any async prep work
-        await router.push('/search');
-      },
-    },
   ],
   onComplete: () => analytics.track('tour_finished'),
   onSkip: () => analytics.track('tour_skipped'),
 });
 
-// 3. Wire the overlay
 const overlay = document.querySelector('torchlit-overlay');
 overlay.service = tours;
 
-// 4. Auto-start on first visit
 if (tours.shouldAutoStart('welcome')) {
   setTimeout(() => tours.start('welcome'), 800);
 }
@@ -110,8 +103,6 @@ That's it. The spotlight finds elements even inside shadow roots.
 
 ## Tree-Shakeable Imports
 
-Import only what you need:
-
 ```typescript
 // Full library (service + overlay + types + deepQuery)
 import { createTourService, TorchlitOverlay, deepQuery } from 'torchlit';
@@ -125,227 +116,22 @@ import { TorchlitOverlay } from 'torchlit/overlay';
 
 The `torchlit/service` entry point has **zero dependencies** and can be used with any rendering layer.
 
-## API Reference
-
-### `createTourService(config?)`
-
-Creates a new `TourService` instance.
-
-```typescript
-const tours = createTourService({
-  storageKey: 'my-app-tours',       // localStorage key (default: 'torchlit-state')
-  storage: sessionStorage,           // any { getItem, setItem } adapter
-  targetAttribute: 'data-tour-id',   // attribute for target lookup (default)
-  spotlightPadding: 10,              // px around spotlight cutout (default: 10)
-});
-```
-
-#### `TourConfig`
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `storageKey` | `string` | `'torchlit-state'` | Key for persisting completed/dismissed state |
-| `storage` | `StorageAdapter` | `localStorage` | Any object with `getItem` / `setItem` |
-| `targetAttribute` | `string` | `'data-tour-id'` | The data attribute used to locate targets |
-| `spotlightPadding` | `number` | `10` | Padding in pixels around the spotlight |
-
-### `TourService`
-
-| Method | Description |
-|---|---|
-| `register(tour)` | Register a single `TourDefinition` |
-| `register(tours[])` | Register multiple tours at once |
-| `start(tourId)` | Start a tour by ID |
-| `nextStep()` | Advance to the next step |
-| `prevStep()` | Go back to the previous step |
-| `skipTour()` | Dismiss the current tour |
-| `isActive()` | Whether a tour is currently running |
-| `shouldAutoStart(tourId)` | Whether a first-visit tour should start |
-| `getTour(tourId)` | Retrieve a registered tour |
-| `getAvailableTours()` | Get all registered tours |
-| `getSnapshot()` | Get the current step snapshot (or `null`) |
-| `findTarget(targetId)` | Find a DOM element by tour target ID |
-| `subscribe(listener)` | Subscribe to state changes; returns unsubscribe fn |
-| `resetAll()` | Clear all state (useful for testing and demos) |
-
-### `TourDefinition`
-
-```typescript
-interface TourDefinition {
-  id: string;
-  name: string;
-  trigger: 'first-visit' | 'manual';
-  steps: TourStep[];
-  onComplete?: () => void;
-  onSkip?: () => void;
-}
-```
-
-### `TourStep`
-
-```typescript
-interface TourStep {
-  target: string;            // data-tour-id value, or '_none_' for centered card
-  title: string;
-  message: string;
-  placement: 'top' | 'bottom' | 'left' | 'right';
-  route?: string;            // emits 'tour-route-change' event
-  beforeShow?: () => void | Promise<void>;
-}
-```
-
-### `<torchlit-overlay>`
-
-| Property | Type | Description |
-|---|---|---|
-| `service` | `TourService` | The service instance to subscribe to (required) |
-
-| Event | Detail | Description |
-|---|---|---|
-| `tour-route-change` | `{ route: string }` | Fired when a step has a `route` property |
-
-| CSS Part | Description |
-|---|---|
-| `backdrop` | The semi-transparent overlay |
-| `spotlight` | The cutout highlight |
-| `tooltip` | The floating tooltip card |
-| `center-card` | The centered card (no-target steps) |
-
-### `deepQuery(selector, root?)`
-
-Recursively searches the DOM including shadow roots. This is the utility that powers Torchlit's Shadow DOM support, exported for standalone use.
-
-```typescript
-import { deepQuery } from 'torchlit';
-
-const el = deepQuery('[data-tour-id="my-element"]');
-// Finds the element even if it's buried inside nested shadow DOMs
-```
-
-## Theming
-
-Torchlit adapts to your app's theme via CSS custom properties. Set them on `:root` or any ancestor:
-
-```css
-:root {
-  --primary: #6366f1;
-  --primary-foreground: #ffffff;
-  --card: #ffffff;
-  --border: #e5e5e5;
-  --foreground: #1a1a1a;
-  --muted-foreground: #737373;
-  --muted: #f5f5f5;
-  --background: #ffffff;
-  --radius-lg: 0.75rem;
-  --radius-md: 0.5rem;
-  --radius-xl: 1rem;
-}
-```
-
-For isolated theming (without affecting your app), use the `--tour-*` prefix:
-
-```css
-torchlit-overlay {
-  --tour-primary: #6366f1;
-  --tour-card: #1a1a2e;
-  --tour-foreground: #e5e5e5;
-  --tour-border: #333;
-  --tour-spotlight-radius: 1rem;
-  --tour-tooltip-radius: 0.75rem;
-  --tour-btn-radius: 0.5rem;
-}
-```
-
-### Dark Mode
-
-If your app already toggles CSS variables for dark mode, the tour overlay adapts automatically -- zero additional configuration.
-
-## Keyboard Navigation
-
-| Key | Action |
-|---|---|
-| `Arrow Right` / `Enter` | Next step |
-| `Arrow Left` | Previous step |
-| `Escape` | Skip / dismiss tour |
+## Features
 
-## Advanced Patterns
+- **Shadow DOM traversal** — finds targets inside nested shadow roots automatically
+- **Smart auto-positioning** — tooltip flips when it would clip the viewport; arrow tracks the target
+- **MutationObserver for lazy targets** — waits for elements to appear in the DOM (great for SPAs)
+- **Rich content** — step messages accept Lit `html` templates for bold, links, `<kbd>`, etc.
+- **Auto-advance / timed steps** — kiosk & demo modes with animated progress bar
+- **Looping tours** — set `loop: true` to restart from step 0 instead of completing
+- **Configurable spotlight shape** — circle, pill, or sharp corners per step
+- **Scroll tracking & restore** — repositions on scroll; restores scroll position when the tour ends
+- **Keyboard navigation** — Arrow Right / Enter (next), Arrow Left (back), Escape (skip)
+- **CSS custom property theming** — adapts to your app's design tokens, including dark mode
+- **`::part()` styling** — style `backdrop`, `spotlight`, `tooltip`, and `center-card` from the outside
+- **Accessible** — `role="dialog"`, `aria-modal`, `aria-live`, focus trap, focus restore
 
-### Route Changes During Tours
-
-Use `beforeShow` to navigate before a step renders:
-
-```typescript
-{
-  target: 'settings-panel',
-  title: 'Settings',
-  message: 'Configure your preferences here.',
-  placement: 'right',
-  beforeShow: async () => {
-    await router.push('/settings');
-    // Wait for the route transition to complete
-    await new Promise(r => setTimeout(r, 300));
-  },
-}
-```
-
-Or use the `route` property to emit a `tour-route-change` event that your app handles:
-
-```typescript
-{ target: 'dashboard-widget', title: '...', message: '...', placement: 'top', route: 'dashboard' }
-```
-
-```javascript
-overlay.addEventListener('tour-route-change', (e) => {
-  router.push(`/${e.detail.route}`);
-});
-```
-
-### Multiple Service Instances
-
-Each call to `createTourService()` creates an independent instance. This is useful for micro-frontends:
-
-```typescript
-const appTours = createTourService({ storageKey: 'app-tours' });
-const widgetTours = createTourService({ storageKey: 'widget-tours' });
-```
-
-### Custom Storage
-
-Persist tour state to an API instead of localStorage:
-
-```typescript
-const tours = createTourService({
-  storage: {
-    getItem: (key) => fetchFromAPI(key),
-    setItem: (key, value) => postToAPI(key, value),
-  },
-});
-```
-
-### Headless Mode (Custom UI)
-
-Use the service without the built-in overlay:
-
-```typescript
-import { createTourService } from 'torchlit/service';
-
-const tours = createTourService();
-tours.register([...]);
-
-tours.subscribe((snapshot) => {
-  if (!snapshot) {
-    // Tour ended
-    hideMyCustomUI();
-    return;
-  }
-  // Render your own tooltip using snapshot.step, snapshot.targetRect, etc.
-  renderMyCustomTooltip(snapshot);
-});
-
-tours.start('onboarding');
-```
-
-## Running the Demo
+> For the full API reference, theming guide, and advanced patterns, see the **[documentation site](https://barryking.github.io/torchlit/)**.
 
 ## Project Structure
 
@@ -360,31 +146,56 @@ torchlit/
       deep-query.ts       # Shadow DOM traversal utility
   test/
     tour-service.test.ts  # Service unit tests (Vitest)
+    tour-overlay.test.ts  # Overlay positioning & feature tests
     deep-query.test.ts    # Deep query unit tests
+  site/
+    index.html            # Docs site source (builds to docs/)
   examples/
-    index.html            # Interactive demo (no build step)
+    index.html            # Example listing page
+    basic.html            # Minimal tour setup
+    multi-page.html       # Tour spanning multiple views
+    custom-theme.html     # Custom brand theme & dark mode
+    kiosk.html            # Auto-advance + looping kiosk tour
+    smart-positioning.html # Smart auto-positioning demo
+    rich-content.html     # Rich HTML content in step messages
+  docs/                   # Built output for GitHub Pages
 ```
 
-## Running the Demo
+## Running Locally
 
 ```bash
 git clone https://github.com/barryking/torchlit.git
 cd torchlit
-npm install
-npm run dev
+pnpm install
+```
+
+### Docs site
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:5173` to see the full documentation site with an onboarding tour, contextual help, API reference, and theme switching.
+
+### Examples
+
+```bash
+pnpm dev:examples
 ```
 
-Open `http://localhost:5173` to see the interactive demo with an onboarding tour, contextual help, and theme switching.
+Open `http://localhost:5173` to browse standalone examples -- basic tour, multi-page tour, custom theming, kiosk mode, and more. Each is a self-contained HTML file you can copy and adapt.
 
 ## Contributing
 
 Contributions are welcome! Please open an issue first to discuss what you'd like to change.
 
 ```bash
-npm install     # install dependencies
-npm test        # run tests
-npm run build   # build the library
-npm run dev     # start the demo dev server
+pnpm install          # install dependencies
+pnpm test             # run tests
+pnpm run build        # build the library
+pnpm dev              # start the docs site dev server
+pnpm dev:examples     # start the examples dev server
+pnpm run build:demo   # build the docs site to docs/ for GitHub Pages
 ```
 
 ## License

package/dist/deep-query-vkmcq1Dw.js

@@ -0,0 +1,16 @@
+function deepQuery(selector, root = document.body) {
+  const found = root.querySelector(selector);
+  if (found) return found;
+  const children = root.querySelectorAll("*");
+  for (const el of children) {
+    if (el.shadowRoot) {
+      const shadowResult = deepQuery(selector, el.shadowRoot);
+      if (shadowResult) return shadowResult;
+    }
+  }
+  return null;
+}
+export {
+  deepQuery as d
+};
+//# sourceMappingURL=deep-query-vkmcq1Dw.js.map

package/dist/deep-query-vkmcq1Dw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-query-vkmcq1Dw.js","sources":["../src/utils/deep-query.ts"],"sourcesContent":["/**\n * Recursively search the DOM — including shadow roots — for an element\n * matching the given CSS selector.\n *\n * This is the key differentiator vs. libraries like Shepherd.js or Intro.js\n * which cannot pierce shadow DOM boundaries.\n *\n * @param selector  A valid CSS selector string.\n * @param root      The root element (or Document) to start searching from.\n *                  Defaults to `document.body`.\n * @returns         The first matching `Element`, or `null`.\n *\n * @example\n * ```ts\n * import { deepQuery } from 'torchlit';\n *\n * const el = deepQuery('[data-tour-id=\"sidebar-nav\"]');\n * ```\n */\nexport function deepQuery(\n  selector: string,\n  root: Element | Document = document.body,\n): Element | null {\n  // Try light DOM first (fast path)\n  const found = root.querySelector(selector);\n  if (found) return found;\n\n  // Walk children that expose a shadowRoot\n  const children = root.querySelectorAll('*');\n  for (const el of children) {\n    if (el.shadowRoot) {\n      const shadowResult = deepQuery(selector, el.shadowRoot as unknown as Document);\n      if (shadowResult) return shadowResult;\n    }\n  }\n\n  return null;\n}\n"],"names":[],"mappings":"AAmBO,SAAS,UACd,UACA,OAA2B,SAAS,MACpB;AAEhB,QAAM,QAAQ,KAAK,cAAc,QAAQ;AACzC,MAAI,MAAO,QAAO;AAGlB,QAAM,WAAW,KAAK,iBAAiB,GAAG;AAC1C,aAAW,MAAM,UAAU;AACzB,QAAI,GAAG,YAAY;AACjB,YAAM,eAAe,UAAU,UAAU,GAAG,UAAiC;AAC7E,UAAI,aAAc,QAAO;AAAA,IAC3B;AAAA,EACF;AAEA,SAAO;AACT;"}

package/dist/index.js

@@ -1,9 +1,10 @@
-import { T, c, d } from "./tour-service-BKz7eeWb.js";
+import { TourService, createTourService } from "./tour-service.js";
 import { TorchlitOverlay } from "./tour-overlay.js";
+import { d } from "./deep-query-vkmcq1Dw.js";
 export {
   TorchlitOverlay,
-  T as TourService,
-  c as createTourService,
+  TourService,
+  createTourService,
   d as deepQuery
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/tour-overlay.d.ts

@@ -32,19 +32,57 @@ export declare class TorchlitOverlay extends LitElement {
     private snapshot;
     private visible;
     private unsubscribe?;
+    private previouslyFocused;
+    private autoAdvanceTimer;
+    private lastResolvedPlacement;
+    private scrollRafId;
+    private savedScrollY;
+    private activeTourId;
     connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changed: Map<string, unknown>): void;
+    /**
+     * After rendering, measure the tooltip's actual height and correct
+     * its position for 'top' placement (the only one that depends on
+     * tooltip height). This eliminates hardcoded height estimates.
+     */
+    private adjustTooltipPosition;
     private attachService;
+    private clearAutoAdvance;
+    private startAutoAdvance;
+    /**
+     * Wait for a target element to appear in the DOM using a MutationObserver.
+     * Resolves as soon as `deepQuery` finds the target, or after `timeout` ms.
+     */
+    private waitForTarget;
     private handleTourChange;
-    private scrollTargetIntoView;
+    /**
+     * Scroll an element into view and wait for the scroll to finish.
+     * For tall elements (> 60% of viewport), scrolls to the top so the user
+     * sees the start of the element plus the tooltip. For smaller elements,
+     * centers them in the viewport.
+     */
+    private scrollAndSettle;
     private handleResize;
+    /** Throttled scroll handler — refreshes the snapshot once per frame. */
+    private handleScroll;
     private handleKeydown;
     private handleBackdropClick;
+    private trapFocus;
+    /**
+     * Determine the best placement for the tooltip, flipping when the preferred
+     * placement would clip the viewport. Tries: preferred → opposite → perpendicular.
+     */
+    private bestPlacement;
     private getTooltipPosition;
     private clampToViewport;
     private getArrowClass;
-    render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Compute the arrow's offset along the tooltip edge so it points at
+     * the center of the target element, clamped to stay within the tooltip.
+     */
+    private getArrowOffset;
+    render(): import("lit").TemplateResult<1>;
     private renderProgressDots;
     private renderCenteredStep;
 }

package/dist/tour-overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tour-overlay.d.ts","sourceRoot":"","sources":["../src/tour-overlay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,KAAK,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACa,eAAgB,SAAQ,UAAU;IAG7C,OAAgB,MAAM,0BA+QpB;IAIF;;;OAGG;IAEH,OAAO,EAAG,WAAW,CAAC;IAEb,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,OAAO,CAAS;IAEjC,OAAO,CAAC,WAAW,CAAC,CAAa;IAIxB,iBAAiB;IASjB,oBAAoB;IAOpB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAO,CAAC,aAAa;YAMP,gBAAgB;IAmC9B,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,YAAY,CAIlB;IAEF,OAAO,CAAC,aAAa,CAYnB;IAEF,OAAO,CAAC,mBAAmB,CAEzB;IAIF,OAAO,CAAC,kBAAkB;IA+B1B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,aAAa;IAYZ,MAAM;IAgFf,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,kBAAkB;CA2C3B;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,kBAAkB,EAAE,eAAe,CAAC;KACrC;CACF"}
+{"version":3,"file":"tour-overlay.d.ts","sourceRoot":"","sources":["../src/tour-overlay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,MAAM,KAAK,CAAC;AAIrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAWrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACa,eAAgB,SAAQ,UAAU;IAG7C,OAAgB,MAAM,0BAkUpB;IAIF;;;OAGG;IAEH,OAAO,EAAG,WAAW,CAAC;IAEb,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,OAAO,CAAS;IAEjC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,qBAAqB,CAA2B;IACxD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAuB;IAIlC,iBAAiB;IAUjB,oBAAoB;IAUpB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAoB9C;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAe7B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,OAAO,CAAC,aAAa;YAsCP,gBAAgB;IAwF9B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAmCvB,OAAO,CAAC,YAAY,CAIlB;IAEF,wEAAwE;IACxE,OAAO,CAAC,YAAY,CAQlB;IAEF,OAAO,CAAC,aAAa,CAmBnB;IAEF,OAAO,CAAC,mBAAmB,CAGzB;IAIF,OAAO,CAAC,SAAS;IA6BjB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAsCrB,OAAO,CAAC,kBAAkB;IAqC1B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,aAAa;IAUrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA2Bb,MAAM;IA+Hf,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,kBAAkB;CA8E3B;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,kBAAkB,EAAE,eAAe,CAAC;KACrC;CACF"}