Repository navigation
v0.3.0
Pre-1.0 reminder: this is a MINOR release, and in this package a minor may
carry breaking changes. This one carries one behaviour change (see Changed);
no API was removed or renamed.
Added
- Chained walkthroughs (#2).
WalkthroughDocument.nextnames the
walkthrough to start when this one completes (skipping never chains).
Give one<Walkthrough>a library withwalkthroughs={[...docs]}and the
next one starts in place; ifnextis not in the library it is handed over
through the storage adapter to whichever<Walkthrough>has that id, already
mounted on the page or mounted on a later one. - The active walkthrough is controlled state:
walkthrough+
onWalkthroughChange, or uncontrolled withdefaultWalkthrough.
useWalkthrough()gainswalkthrough(the active id) and
start(at?, walkthrough?). - Steps on another page.
step.route+<Walkthrough onNavigate>: when
a step starts and the host is elsewhere,onNavigate(step, { walkthrough, index })is called once and the HOST navigates (Inertia'srouter.visit, its
own page transition). The package never navigates and depends on no router.
The card waits for the target to register on the new page, and the step's
whenMissingpolicy is held off until the host has arrived. Pass
currentRoute(compared by string equality) so the package knows where
the host is; without it,window.location.pathnameis read in an effect. - Resume across navigation and reloads through a storage adapter, per the
design record's 2026-09-22 decision:storage={{ load, save }}, where
load()returnsWalkthroughProgress | null(or a Promise of it) and
save(progress | null)stores it.WalkthroughProgressis
{ walkthrough, step?, index }; resume finds the step by id first, so
reordering steps does not resume on the wrong one. An optionalsubscribe
lets a hand-over reach a<Walkthrough>already on the page. The default is
createLocalStorageAdapter(key = "fancy-walkthrough"), which is SSR-safe
(nothing toucheswindowat import or render) and degrades to remembering
nothing when storage is disabled or full. - Events:
walkthrough:chained { walkthrough, from, to }when one hands
over to the next;walkthrough:resumed { walkthrough, step, index }instead
ofstartedwhen progress is read back (sostartedstays an honest
denominator);walkthrough:completednow carriesnextwhen there is one. - Handles: the card carries
data-walkthrough-id(the active walkthrough)
and, while the host is navigating to its page,data-walkthrough-navigating
(the route). - Types:
WalkthroughStorage,WalkthroughProgress,
WalkthroughNavigateContext.
Changed
- In-progress walkthroughs now persist to localStorage by default. A tour
that was running when the page reloaded resumes on the step it was on.
Finishing or skipping clears it. To keep 0.2's behaviour, pass
storage={null}. Nothing else to do:idandstepsare now optional
(they may come fromwalkthroughsinstead), which accepts everything that
compiled before. - Nothing runs or reports until the store has been read, so a resumed
walkthrough does not first reportstartedatdefaultStep. With a sync
store this happens in the mount effect, before anything is painted.