@heyramzi/ui 1.54.1 → 2.0.0

package/src/onboarding/demo.svelte

@@ -0,0 +1,86 @@
+<script lang="ts">
+	import { Button } from "../shadcn/button/index.js";
+	import { Badge } from "../shadcn/badge/index.js";
+	import { Plus } from "phosphor-svelte";
+	import OnboardingProvider from "./onboarding-provider.svelte";
+	import { defineTours } from "./define-tours.js";
+	import { memoryStore } from "./stores.js";
+	import type { Strings } from "./types.js";
+
+	const tours = defineTours([
+		{
+			id: "demo:intro",
+			route: "/demo/intro",
+			kind: "intro",
+			title: "The week in one place",
+			body: "Open work sits on the left. Anything late floats to the top.",
+		},
+		{
+			id: "demo:board",
+			route: "/demo/board",
+			kind: "steps",
+			steps: [
+				{ target: '[data-tour="demo-new"]', title: "Start here", body: "A new project takes a name and a client. That's all.", placement: "bottom-end" },
+				{ target: '[data-tour="demo-filter"]', title: "Narrow it down", body: "Late shows what slipped. Mine shows what's yours.", placement: "bottom-start" },
+				{ target: '[data-tour="demo-list"]', title: "Open a row", body: "Click a project to see its tasks, files and notes.", placement: "top" },
+			],
+		},
+	]);
+
+	const strings: Strings = {
+		next: "Next",
+		back: "Back",
+		done: "Got it",
+		skip: "Skip the tour",
+		progress: (n, total) => `Step ${n} of ${total}`,
+	};
+
+	const rows = [
+		{ name: "Brand refresh", client: "Northwind", tone: "success" as const, label: "On track" },
+		{ name: "Pricing page", client: "Acme", tone: "warning" as const, label: "Late" },
+		{ name: "Launch email", client: "Globex", tone: "neutral" as const, label: "Draft" },
+	];
+
+	let routeId = $state<string | null>(null);
+	let run = $state(0);
+	let store = $state(memoryStore());
+
+	// A fresh store each time, so the button always has an unseen tour to show.
+	function start(route: string) {
+		store = memoryStore();
+		routeId = route;
+		run += 1;
+	}
+</script>
+
+<div class="flex flex-col gap-4">
+	<div class="flex flex-wrap gap-2">
+		<Button variant="outline" size="sm" onclick={() => start("/demo/board")}>Show the page tour</Button>
+		<Button variant="outline" size="sm" onclick={() => start("/demo/intro")}>Show the intro card</Button>
+	</div>
+
+	<div class="bg-card ring-foreground/10 flex flex-col gap-4 rounded-xl p-4 ring-1">
+		<div class="flex items-center justify-between gap-3">
+			<h2 class="text-sm font-semibold">Projects</h2>
+			<Button size="sm" data-tour="demo-new"><Plus weight="bold" />New project</Button>
+		</div>
+		<div class="flex gap-1.5" data-tour="demo-filter">
+			<Badge variant="outline">All</Badge>
+			<Badge variant="outline">Late</Badge>
+			<Badge variant="outline">Mine</Badge>
+		</div>
+		<ul class="divide-border border-border divide-y rounded-lg border" data-tour="demo-list">
+			{#each rows as row (row.name)}
+				<li class="flex items-center justify-between gap-3 px-3 py-2.5 text-sm">
+					<span class="min-w-0 truncate font-medium">{row.name}</span>
+					<span class="text-muted-foreground hidden sm:block">{row.client}</span>
+					<Badge variant="outline">{row.label}</Badge>
+				</li>
+			{/each}
+		</ul>
+	</div>
+</div>
+
+{#key run}
+	<OnboardingProvider {tours} {store} {strings} {routeId} replayKey={false} />
+{/key}

package/src/onboarding/index.ts

@@ -0,0 +1,12 @@
+export { default as OnboardingProvider } from "./onboarding-provider.svelte";
+export { onboarding } from "./onboarding.svelte.js";
+export { defineTours } from "./define-tours.js";
+export { localStorageStore, memoryStore } from "./stores.js";
+export type {
+	Outcome,
+	Placement,
+	SeenStore,
+	Step,
+	Strings,
+	Tour,
+} from "./types.js";

package/src/onboarding/onboarding-provider.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+	import { tryCatchAsync } from "../lib/result.js";
+	import { untrack } from "svelte";
+	import { onboarding } from "./onboarding.svelte.js";
+	import { keepFoundSteps, pickForReplay, pickTour, toursForRoute, type SeenMap } from "./pick.js";
+	import TourRunner from "./tour-runner.svelte";
+	import type { Outcome, SeenStore, Step, Strings, Tour } from "./types.js";
+	import { waitForElement } from "./wait.js";
+
+	let {
+		tours,
+		store,
+		strings,
+		routeId,
+		enabled = true,
+		replayKey = true,
+		waitMs = 2000,
+	}: {
+		tours: readonly Tour[];
+		store: SeenStore;
+		strings: Strings;
+		/** `page.route.id`. A tour runs on the route it names. */
+		routeId: string | null | undefined;
+		/** False while signed out, or anywhere a tour has no business starting. */
+		enabled?: boolean;
+		/** Press `?` to replay this page's tour. */
+		replayKey?: boolean;
+		/** How long to wait for the first target before giving the tour up. */
+		waitMs?: number;
+	} = $props();
+
+	type Active = { tour: Tour; steps: Step[]; replay: boolean; run: number };
+
+	let active = $state<Active | null>(null);
+	let seen: SeenMap | null = null;
+	let loaded: Promise<SeenMap | null> | null = null;
+	let run = 0;
+
+	// One read per session. A failed read shows nothing: a tour repeating on every page is worse than none.
+	function loadSeen(): Promise<SeenMap | null> {
+		loaded ??= store.load().then(
+			(map) => (seen = map),
+			() => null,
+		);
+		return loaded;
+	}
+
+	async function launch(tour: Tour, replay: boolean, signal: AbortSignal): Promise<boolean> {
+		let steps: Step[] = [];
+		if (tour.kind === "steps") {
+			await waitForElement(tour.steps[0].target, waitMs, signal);
+			if (signal.aborted) return false;
+			steps = keepFoundSteps(tour.steps, (selector) => document.querySelector(selector) !== null);
+			if (steps.length === 0) return false;
+		}
+		if (active) return false;
+		active = { tour, steps, replay, run: ++run };
+		return true;
+	}
+
+	let controller: AbortController | null = null;
+
+	$effect(() => {
+		const id = routeId;
+		const list = tours;
+		const on = enabled;
+		onboarding.hasTour = on && toursForRoute(list, id).length > 0;
+		active = null;
+		if (!on || !id) return;
+		const mine = new AbortController();
+		controller = mine;
+		void loadSeen().then((map) => {
+			if (!map || mine.signal.aborted) return;
+			const tour = pickTour(untrack(() => tours), id, map);
+			if (tour) void launch(tour, false, mine.signal);
+		});
+		return () => mine.abort();
+	});
+
+	$effect(() => onboarding.bind(async (tourId) => {
+		const tour = pickForReplay(tours, routeId, tourId);
+		if (!tour || !controller || controller.signal.aborted) return false;
+		return launch(tour, true, controller.signal);
+	}));
+
+	$effect(() => {
+		onboarding.running = active !== null;
+		return () => {
+			onboarding.running = false;
+		};
+	});
+
+	async function finish(outcome: Outcome | null) {
+		const done = active;
+		active = null;
+		if (!done || done.replay || !outcome) return;
+		const version = done.tour.version ?? 1;
+		if (seen) seen = { ...seen, [done.tour.id]: version };
+		// A failed write shows the tour again next session, which beats an error toast.
+		await tryCatchAsync(() => store.markSeen(done.tour.id, version, outcome));
+	}
+
+	function onkeydown(event: KeyboardEvent) {
+		if (!replayKey || event.key !== "?" || event.ctrlKey || event.metaKey || event.altKey) return;
+		const el = event.target instanceof HTMLElement ? event.target : null;
+		if (el?.closest("input, textarea, select, [contenteditable]")) return;
+		if (el?.isContentEditable) return;
+		if (!onboarding.hasTour || active) return;
+		event.preventDefault();
+		void onboarding.replay();
+	}
+</script>
+
+<svelte:window {onkeydown} />
+
+{#if active}
+	{#key active.run}
+		<TourRunner tour={active.tour} steps={active.steps} {strings} onfinish={finish} />
+	{/key}
+{/if}

package/src/onboarding/onboarding.svelte.ts

@@ -0,0 +1,24 @@
+type Replay = (tourId?: string) => Promise<boolean>;
+
+class Onboarding {
+	/** True when the current page has a tour, so a menu item can hide itself. */
+	hasTour = $state(false);
+	/** True while a tour is on screen. */
+	running = $state(false);
+	#replay: Replay | null = null;
+
+	/** The provider registers itself here. Returns the undo for cleanup. */
+	bind(replay: Replay): () => void {
+		this.#replay = replay;
+		return () => {
+			if (this.#replay === replay) this.#replay = null;
+		};
+	}
+
+	/** Restarts this page's tour, or the one named. Writes no seen-state. False when nothing started. */
+	replay(tourId?: string): Promise<boolean> {
+		return this.#replay ? this.#replay(tourId) : Promise.resolve(false);
+	}
+}
+
+export const onboarding = new Onboarding();

package/src/onboarding/pick.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vite-plus/test";
+import { isSeen, keepFoundSteps, pickForReplay, pickTour, toursForRoute } from "./pick.js";
+import type { Tour } from "./types.js";
+
+const step = { target: "#a", title: "A", body: "a" };
+const tours: Tour[] = [
+	{ id: "home", route: "/(app)", kind: "intro", title: "Hi", body: "Welcome." },
+	{ id: "board", route: "/(app)/projects", kind: "steps", steps: [step] },
+	{ id: "board-extra", route: "/(app)/projects", kind: "steps", steps: [step], version: 2 },
+	{ id: "record", route: "/(app)/projects/[id]", kind: "steps", steps: [step] },
+];
+
+describe("isSeen", () => {
+	it("counts a tour as seen once the stored version reaches its own", () => {
+		expect(isSeen(tours[1], {})).toBe(false);
+		expect(isSeen(tours[1], { board: 1 })).toBe(true);
+		expect(isSeen(tours[2], { "board-extra": 1 })).toBe(false);
+		expect(isSeen(tours[2], { "board-extra": 2 })).toBe(true);
+	});
+
+	it("shows a tour again after its version is bumped", () => {
+		const v1: Tour = { id: "t", route: "/", kind: "steps", steps: [step] };
+		const v2: Tour = { ...v1, version: 2 };
+		expect(isSeen(v1, { t: 1 })).toBe(true);
+		expect(isSeen(v2, { t: 1 })).toBe(false);
+	});
+});
+
+describe("pickTour", () => {
+	it("matches the route id exactly, so a params route never borrows its parent's tour", () => {
+		expect(pickTour(tours, "/(app)", {})?.id).toBe("home");
+		expect(pickTour(tours, "/(app)/projects/[id]", {})?.id).toBe("record");
+		expect(pickTour(tours, "/(app)/settings", {})).toBeUndefined();
+	});
+
+	it("takes the first unseen tour on a route, one at a time", () => {
+		expect(pickTour(tours, "/(app)/projects", {})?.id).toBe("board");
+		expect(pickTour(tours, "/(app)/projects", { board: 1 })?.id).toBe("board-extra");
+		expect(pickTour(tours, "/(app)/projects", { board: 1, "board-extra": 2 })).toBeUndefined();
+	});
+
+	it("picks nothing without a route", () => {
+		expect(pickTour(tours, null, {})).toBeUndefined();
+		expect(pickTour(tours, undefined, {})).toBeUndefined();
+	});
+});
+
+describe("toursForRoute", () => {
+	it("lists every tour on the route in definition order", () => {
+		expect(toursForRoute(tours, "/(app)/projects").map((t) => t.id)).toEqual(["board", "board-extra"]);
+	});
+});
+
+describe("pickForReplay", () => {
+	it("restarts the page's first tour even when it was seen", () => {
+		expect(pickForReplay(tours, "/(app)/projects")?.id).toBe("board");
+	});
+
+	it("finds a tour by id on any route", () => {
+		expect(pickForReplay(tours, "/(app)", "record")?.id).toBe("record");
+		expect(pickForReplay(tours, "/(app)", "missing")).toBeUndefined();
+	});
+});
+
+describe("keepFoundSteps", () => {
+	const steps = [
+		{ ...step, target: "#a" },
+		{ ...step, target: "#b" },
+		{ ...step, target: "#c" },
+	];
+
+	it("drops the steps whose target isn't on the page", () => {
+		expect(keepFoundSteps(steps, (s) => s !== "#b").map((s) => s.target)).toEqual(["#a", "#c"]);
+	});
+
+	it("returns nothing when no target is found, so no empty spotlight starts", () => {
+		expect(keepFoundSteps(steps, () => false)).toEqual([]);
+	});
+});

package/src/onboarding/pick.ts

@@ -0,0 +1,36 @@
+import type { Step, Tour } from "./types.js";
+
+export type SeenMap = Record<string, number>;
+
+/** The seen version has to reach the tour's own, so bumping `version` shows it again. */
+export function isSeen(tour: Tour, seen: SeenMap): boolean {
+	return (seen[tour.id] ?? 0) >= (tour.version ?? 1);
+}
+
+export function toursForRoute(tours: readonly Tour[], routeId: string | null | undefined): Tour[] {
+	return routeId ? tours.filter((tour) => tour.route === routeId) : [];
+}
+
+/** The first unseen tour on a route, in the order they were defined. One per page view. */
+export function pickTour(
+	tours: readonly Tour[],
+	routeId: string | null | undefined,
+	seen: SeenMap,
+): Tour | undefined {
+	return toursForRoute(tours, routeId).find((tour) => !isSeen(tour, seen));
+}
+
+/** What replay starts: a named tour, or the page's first one whether or not it was seen. */
+export function pickForReplay(
+	tours: readonly Tour[],
+	routeId: string | null | undefined,
+	tourId?: string,
+): Tour | undefined {
+	if (tourId) return tours.find((tour) => tour.id === tourId);
+	return toursForRoute(tours, routeId)[0];
+}
+
+/** Keeps the steps whose target is on the page. A tour with none left starts nothing. */
+export function keepFoundSteps(steps: readonly Step[], exists: (selector: string) => boolean): Step[] {
+	return steps.filter((step) => exists(step.target));
+}

package/src/onboarding/stores.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import { localStorageStore, memoryStore } from "./stores.js";
+import type { SeenStore } from "./types.js";
+
+function fakeStorage(): Storage {
+	const data = new Map<string, string>();
+	return {
+		get length() {
+			return data.size;
+		},
+		clear: () => data.clear(),
+		getItem: (key) => data.get(key) ?? null,
+		key: (i) => [...data.keys()][i] ?? null,
+		removeItem: (key) => void data.delete(key),
+		setItem: (key, value) => void data.set(key, String(value)),
+	};
+}
+
+function behavesLikeAStore(make: () => SeenStore) {
+	it("starts empty", async () => {
+		expect(await make().load()).toEqual({});
+	});
+
+	it("remembers the version it saw", async () => {
+		const store = make();
+		await store.markSeen("home", 1, "completed");
+		await store.markSeen("board", 2, "dismissed");
+		expect(await store.load()).toEqual({ home: 1, board: 2 });
+	});
+
+	it("never goes back to an older version", async () => {
+		const store = make();
+		await store.markSeen("home", 3, "completed");
+		await store.markSeen("home", 2, "completed");
+		expect((await store.load()).home).toBe(3);
+	});
+
+	it("resets one tour or all of them", async () => {
+		const store = make();
+		await store.markSeen("home", 1, "completed");
+		await store.markSeen("board", 1, "completed");
+		await store.reset("home");
+		expect(await store.load()).toEqual({ board: 1 });
+		await store.reset();
+		expect(await store.load()).toEqual({});
+	});
+}
+
+describe("memoryStore", () => {
+	behavesLikeAStore(() => memoryStore());
+
+	it("takes a starting state and keeps its own copy", async () => {
+		const initial = { home: 1 };
+		const store = memoryStore(initial);
+		await store.markSeen("board", 1, "completed");
+		expect(initial).toEqual({ home: 1 });
+		expect(await store.load()).toEqual({ home: 1, board: 1 });
+	});
+});
+
+describe("localStorageStore", () => {
+	beforeEach(() => {
+		vi.stubGlobal("localStorage", fakeStorage());
+	});
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	behavesLikeAStore(() => localStorageStore());
+
+	it("shares state between two stores on one key and keeps keys apart", async () => {
+		await localStorageStore("a").markSeen("home", 1, "completed");
+		expect(await localStorageStore("a").load()).toEqual({ home: 1 });
+		expect(await localStorageStore("b").load()).toEqual({});
+	});
+
+	it("reads corrupt or foreign data as empty", async () => {
+		localStorage.setItem("heyramzi:onboarding", "{nope");
+		expect(await localStorageStore().load()).toEqual({});
+		localStorage.setItem("heyramzi:onboarding", JSON.stringify(["x"]));
+		expect(await localStorageStore().load()).toEqual({});
+		localStorage.setItem("heyramzi:onboarding", JSON.stringify({ home: 1, bad: "yes" }));
+		expect(await localStorageStore().load()).toEqual({ home: 1 });
+	});
+
+	it("doesn't throw when storage is blocked", async () => {
+		vi.stubGlobal("localStorage", {
+			getItem: () => {
+				throw new Error("blocked");
+			},
+			setItem: () => {
+				throw new Error("blocked");
+			},
+			removeItem: () => {
+				throw new Error("blocked");
+			},
+		});
+		const store = localStorageStore();
+		expect(await store.load()).toEqual({});
+		await expect(store.markSeen("home", 1, "completed")).resolves.toBeUndefined();
+		await expect(store.reset()).resolves.toBeUndefined();
+	});
+});

package/src/onboarding/stores.ts

@@ -0,0 +1,58 @@
+import { tryCatch } from "../lib/result.js";
+import type { Outcome, SeenStore } from "./types.js";
+
+type Seen = Record<string, number>;
+
+/** Holds seen-state in memory. Tests and previews. */
+export function memoryStore(initial: Seen = {}): SeenStore {
+	let seen: Seen = { ...initial };
+	return {
+		async load() {
+			return { ...seen };
+		},
+		async markSeen(tourId, version, _outcome: Outcome) {
+			seen[tourId] = Math.max(seen[tourId] ?? 0, version);
+		},
+		async reset(tourId) {
+			if (tourId === undefined) seen = {};
+			else delete seen[tourId];
+		},
+	};
+}
+
+function readSeen(key: string): Seen {
+	const read = tryCatch(() => JSON.parse(localStorage.getItem(key) ?? "{}") as unknown);
+	const parsed = read.ok ? read.value : null;
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+	return Object.fromEntries(
+		Object.entries(parsed).filter((entry): entry is [string, number] => typeof entry[1] === "number"),
+	);
+}
+
+// Blocked storage (private mode, a full disk) means the tour shows again next visit, which beats an error.
+function writeSeen(key: string, seen: Seen): void {
+	tryCatch(() => localStorage.setItem(key, JSON.stringify(seen)));
+}
+
+/** Keeps seen-state in this browser. Demos and signed-out pages. */
+export function localStorageStore(key = "heyramzi:onboarding"): SeenStore {
+	return {
+		async load() {
+			return readSeen(key);
+		},
+		async markSeen(tourId, version, _outcome: Outcome) {
+			const seen = readSeen(key);
+			seen[tourId] = Math.max(seen[tourId] ?? 0, version);
+			writeSeen(key, seen);
+		},
+		async reset(tourId) {
+			if (tourId === undefined) {
+				tryCatch(() => localStorage.removeItem(key));
+				return;
+			}
+			const seen = readSeen(key);
+			delete seen[tourId];
+			writeSeen(key, seen);
+		},
+	};
+}

package/src/onboarding/tour-card.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+	import { Button } from "../shadcn/button/index.js";
+	import { X } from "phosphor-svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Strings } from "./types.js";
+
+	type Attrs = HTMLAttributes<HTMLElement>;
+
+	// The card is plain markup. The engine hands it the attribute bags that wire it to the machine.
+	let {
+		title,
+		body,
+		image,
+		intro = false,
+		index,
+		total,
+		strings,
+		titleAttrs,
+		bodyAttrs,
+		onclose,
+		onprev,
+		onnext,
+	}: {
+		title: string;
+		body: string;
+		image?: string;
+		intro?: boolean;
+		index: number;
+		total: number;
+		strings: Strings;
+		titleAttrs: Attrs;
+		bodyAttrs: Attrs;
+		onclose: () => void;
+		onprev: () => void;
+		/** The last step's button reads "done", and this closes the tour. */
+		onnext: () => void;
+	} = $props();
+
+	const last = $derived(index === total - 1);
+</script>
+
+{#if image}
+	<img src={image} alt="" class="aspect-video w-full rounded-t-[inherit] object-cover outline -outline-offset-1 outline-black/10 dark:outline-white/10" />
+{/if}
+<div class="flex flex-col gap-1.5 p-4 pb-3">
+	<div class="flex items-start justify-between gap-3">
+		<h2 {...titleAttrs} class={["font-semibold leading-snug text-balance", intro ? "text-base" : "text-sm"]}>{title}</h2>
+		<Button onclick={onclose} variant="ghost" size="sm" icon class="-mt-1 -mr-1.5 text-muted-foreground" aria-label={strings.skip}>
+			<X weight="bold" />
+		</Button>
+	</div>
+	<p {...bodyAttrs} class="text-muted-foreground text-sm text-pretty">{body}</p>
+</div>
+<div class="flex items-center justify-between gap-3 px-4 pb-4">
+	{#if total > 1}
+		<div role="img" aria-label={strings.progress(index + 1, total)} class="flex items-center gap-1.5">
+			{#each { length: total } as _, i (i)}
+				<span class={["h-1.5 rounded-full transition-[width,background-color] duration-(--duration-fast) ease-(--ease-smooth-out) motion-reduce:transition-none", i === index ? "bg-foreground w-4" : "bg-border w-1.5"]}></span>
+			{/each}
+		</div>
+	{:else}
+		<span></span>
+	{/if}
+	<div class="flex items-center gap-2">
+		{#if index > 0}
+			<Button onclick={onprev} variant="ghost" size="sm">{strings.back}</Button>
+		{/if}
+		<Button onclick={onnext} size="sm">{last ? strings.done : strings.next}</Button>
+	</div>
+</div>