Checklist, Hotspots & the Overlay

import { useTourChecklist } from '@absolutejs/tour';

const checklist = useTourChecklist({
	// Identity of this checklist — its persistence bucket in
	// localStorage (namespaced by storageKey, default 'absolute.tour').
	id: 'onboarding',
	// The tasks — a getter so the list can be reactive.
	items: () => [
		{ href: '/portal/intake', id: 'intake', title: 'Finish your intake' },
		// Completing this tutorial checks the task off (see
		// completeForTutorial below).
		{ id: 'tour', title: 'Take the tour', tutorialSlug: 'portal-intro' },
		{
			description: 'Get your first three matches reviewed.',
			href: '/portal/matches',
			id: 'matches',
			title: 'Review your matches'
		}
	]
});

// The host renders the panel:
// checklist.items.value    → [{ ...item, done }]
// checklist.progress.value → { done, total, percent }

// Wire tutorial completion into the checklist from the engine's funnel
// events — finishing 'portal-intro' checks off every task tied to it.
useSpotlight({
	controller,
	onClose,
	onEvent: (event) => {
		if (event.name === 'tour_completed') {
			checklist.completeForTutorial(event.tutorialSlug ?? '');
		}
	},
	steps: () => PORTAL_TOUR_STEPS,
	tutorialSlug: () => 'portal-intro'
});

// Manual task management:
checklist.complete('intake');
checklist.uncomplete('intake');
checklist.isDone('intake'); // boolean

// Dismissal persists (an ISO timestamp) until restored:
checklist.dismiss(); // checklist.dismissed.value → true
checklist.restore();

// Wipe completions AND the dismissal:
checklist.reset();

import { useTourController, useTourHotspots } from '@absolutejs/tour';

const tourController = useTourController('myapp.tour');

// Persistent pulsing beacons on tricky UI — independent of any linear
// tour — that open an explainer card on click.
const spots = useTourHotspots({
	// Master switch: hide beacons while a tour is playing. Default on.
	enabled: () => !tourController.active.value,
	// The hotspots for the current page — a getter so it can be reactive.
	hotspots: () => [
		{
			body: 'How aligned this investor is with your goals.',
			id: 'trust-fit',
			placement: 'right',
			target: "[data-tour='trust-fit']",
			title: 'Trust & Fit'
		},
		{
			body: 'Matches refresh every Monday morning.',
			id: 'refresh',
			// Hide the beacon permanently once it has been opened.
			once: true,
			target: "[data-tour='refresh']",
			title: 'Weekly refresh'
		}
	]
});

// spots.beacons.value → [{ hotspot, style }] — one beacon per target
// spots.card.value    → { hotspot, style } | null — the open card
// spots.open(id) / spots.close() / spots.dismiss(id) / spots.restoreAll()

<script setup lang="ts">
import { useSpotlight, useTourController } from '@absolutejs/tour';
import { PORTAL_TOUR_STEPS } from './steps';

const controller = useTourController('myapp.tour');
const emit = defineEmits<{ close: [] }>();

const t = useSpotlight({
	controller,
	// Below this query, steps' mobile blocks win. Default shown.
	mobileQuery: '(max-width: 640px)',
	onClose: () => emit('close'),
	// Hold positioning (and navigation!) until the host has resolved
	// WHICH steps to play — an async tutorial fetch on a cross-page
	// resume. The engine re-locates when this flips true.
	ready: () => tutorialLoaded.value,
	steps: () => PORTAL_TOUR_STEPS,
	// Per-tutorial theme → CSS custom properties on the overlay.
	theme: () => activeTutorial.value?.theme
});
</script>

<template>
	<Teleport to="body">
		<div
			v-if="t.active.value && t.step.value"
			class="tour-root"
			:style="t.themeVars.value"
		>
			<div class="tour-blocker" :class="{ dim: t.isCentered.value }"></div>
			<div class="tour-spotlight" :style="t.spotlightStyle.value"></div>
			<div
				class="tour-tooltip"
				:class="{ centered: t.isCentered.value }"
				:style="t.isCentered.value ? {} : t.tooltipStyle.value"
			>
				<p>Step {{ t.index.value + 1 }} of {{ t.stepCount.value }}</p>
				<h3>{{ t.step.value.title }}</h3>
				<p>{{ t.step.value.body }}</p>
				<button @click="t.skip">Skip</button>
				<button v-if="!t.isFirst.value" @click="t.back">Back</button>
				<button @click="t.next">
					{{ t.isLast.value ? 'Done' : 'Next' }}
				</button>
			</div>
		</div>
	</Teleport>
</template>