--- # Just a Walkthrough

**Framework‑agnostic, zero‑dependency product tour / onboarding walkthrough with optional React helpers.** ## Features - Spotlight highlight & darkened backdrop (3 panel overlay + focus ring) - Accessible keyboard navigation (Esc / Enter / ← →) + focus trap - Auto scroll + responsive reposition on scroll/resize/mutations - Step hooks (beforeStep / afterStep) & lifecycle callbacks - Chain multiple tours with persistence-aware skipping - LocalStorage progress persistence & resume support - Optional once‑per‑session logic via orchestrator helper - Custom tooltip renderer + theming (default, tailwind, unstyled) - Works with any DOM (vanilla, React, shadcn, portals) - Tiny, tree‑shakeable (no external deps) ## Install ## Quick Start { const inst = startWalkthrough([ { selector: '#dash-metric', title: 'Metrics' }, { selector: '#create-btn', title: 'Create', content: 'Start something new' }, ], { persistProgress: true, tourId: 'main-onboarding' }); return () => inst.destroy(); }, []); return null; }`, label: 'React', language: 'tsx' }, ]} copyButton /> ## Orchestrator ## API Surface (Core) startWalkthrough(steps, options) – convenience wrapper returning a Walkthrough instance. Walkthrough key methods: - start(index?) – begin tour (auto called by helper) - next()/prev() - finish() – mark completed & cleanup - skip(reason?) - destroy() – cleanup without marking completed ## Theming Use theme: 'tailwind' to rely on your Tailwind stack (supply utility classes) or unstyled to supply all styling manually. ## Chain Multiple Tours Completed persistent tours are skipped automatically. ## Advanced Usage Notes - Use waitMs: 0 (or global stepWaitMs: 0) for elements that are guaranteed to be present to avoid unnecessary polling. - Prefer chaining tours when you have progressive disclosure flows; persistent tours auto-skip if already completed, keeping chains idempotent. - When dynamically removing highlighted elements mid-step (e.g. route transitions), the MutationObserver repositions but if the element disappears the next navigation call will resolve again. Consider guarding with required steps if element is critical. ## Accessibility Notes - Focus ring container traps tab order (unless disableFocusTrap: true) - Live region announces step titles (aria-live="polite") - Esc always available (when keyboard: true) ## Zero-Wait Configuration Specify stepWaitMs: 0 and/or per-step waitMs: 0 to disable polling for elements (single lookup). stepPollIntervalMs is clamped to a minimum of 1ms internally when waiting. --- Contributions welcome. Open an issue or PR with ideas / improvements.