@marianmeres/stuic 3.155.0 → 3.157.0

package/API.md

@@ -1629,10 +1629,12 @@ Multi-step onboarding tour built on the spotlight primitive. Define steps centra
 | `onSkip`         | `() => void`                        | —         | Called when tour is skipped                      |
 | `onStepChange`   | `(step, index) => void`             | —         | Called on every step change                      |
 
-**Returns:** `{ start(), stop(), next(), prev(), skip(), reset(), reposition(), active, currentStep, currentIndex }`
+**Returns:** `{ start(), next(), prev(), skip(), reset(), reposition(), active, currentStep, currentIndex, seen }`
 
 `reposition()` forces the active step's spotlight to re-measure its target and re-apply the cutout/anchor. Useful after a layout shift the spotlight's auto-tracking can't observe (or when a step opted out of it).
 
+`reset()` clears the `storageKey` result so `start()` will run the tour again; `seen` is that flag read back. Every `start()` re-resolves `selector` steps against the current DOM, so a tour whose targets remount between runs (a lazy tab, a route, a keyed block) points at the nodes that are on screen now. Targets registered through `use:tourStep` are left to the action, which already tracks their mount and unmount.
+
 **`TourStepDef`:**
 
 | Field          | Type                | Description                                                             |

package/dist/actions/onboarding/onboarding.container.fixture.svelte

@@ -0,0 +1,76 @@
+<script lang="ts">
+	import { untrack } from "svelte";
+	import { createTour, tourStep } from "./onboarding.svelte.js";
+
+	let {
+		/** Register the target through `use:tourStep` instead of a `selector`. */
+		useAction = false,
+		/** Re-keys the target, i.e. destroys the node and mounts a fresh one at
+		 *  different coordinates — what a lazy tab or a keyed block does between
+		 *  two runs of the same tour. */
+		swapped = false,
+		storageKey = undefined,
+	}: {
+		useAction?: boolean;
+		swapped?: boolean;
+		storageKey?: string;
+	} = $props();
+
+	const tour = createTour({
+		steps: [
+			{
+				id: "one",
+				title: "Step one",
+				content: "the only step",
+				position: "bottom",
+				padding: 0,
+				borderRadius: 0,
+				// The whole point of the two modes: an action-registered step has
+				// no selector to be re-resolved from. untracked for the same reason
+				// as `storageKey` below.
+				selector: untrack(() => (useAction ? undefined : "[data-testid='target']")),
+			},
+		],
+		// Short: the action test asserts a step is NOT skipped, and a skip costs
+		// this whole wait before it can be observed.
+		waitForElement: 300,
+		// untrack: read once at init, which is when `createTour` needs it — a
+		// tracked read here would be a reactivity warning for a prop that never
+		// changes after mount.
+		storageKey: untrack(() => storageKey),
+		storage: "session",
+		showSteps: false,
+	});
+</script>
+
+<!-- Above the spotlight backdrop (z-index 50), which would otherwise swallow
+every click the test makes while a tour is running. -->
+<div style="position: relative; z-index: 100;">
+	<button data-testid="start" onclick={() => tour.start()}>start</button>
+	<button data-testid="reset" onclick={() => tour.reset()}>reset</button>
+	<button data-testid="skip" onclick={() => void tour.skip()}>skip</button>
+	<div data-testid="active">{tour.active ? "yes" : "no"}</div>
+</div>
+
+{#key swapped}
+	{#if useAction}
+		<div
+			data-testid="target"
+			use:tourStep={[tour, "one"]}
+			style="position: absolute; left: {swapped ? 160 : 40}px; top: {swapped
+				? 130
+				: 30}px; width: 60px; height: 20px;"
+		>
+			t
+		</div>
+	{:else}
+		<div
+			data-testid="target"
+			style="position: absolute; left: {swapped ? 160 : 40}px; top: {swapped
+				? 130
+				: 30}px; width: 60px; height: 20px;"
+		>
+			t
+		</div>
+	{/if}
+{/key}

package/dist/actions/onboarding/onboarding.container.fixture.svelte.d.ts

@@ -0,0 +1,8 @@
+type $$ComponentProps = {
+    useAction?: boolean;
+    swapped?: boolean;
+    storageKey?: string;
+};
+declare const Onboarding: import("svelte").Component<$$ComponentProps, {}, "">;
+type Onboarding = ReturnType<typeof Onboarding>;
+export default Onboarding;

package/dist/actions/onboarding/onboarding.svelte.js

@@ -225,12 +225,51 @@ export function createTour(options) {
         store?.set(options.storageKey, "completed");
         options.onEnd?.();
     }
+    /**
+     * Drop every SELECTOR-resolved target, so the next run resolves them against
+     * the DOM as it is now.
+     *
+     * The registry is a cache and `advanceTo` only queries the DOM for a step it
+     * does not already hold, so without this a second run re-uses the first
+     * run's nodes. For a tour whose targets all sit in one stable subtree that
+     * is harmless. For one that crosses a lazy tab, a route or a keyed block it
+     * is fatal, and silently: a detached node's `getBoundingClientRect()` is all
+     * zeroes, so the cutout collapses to 0x0 in the top-left corner and the
+     * annotation follows it there. Nothing throws and nothing warns.
+     *
+     * Steps registered through `use:tourStep` are deliberately SPARED. The
+     * action owns their lifetime — it registers on mount and unregisters on
+     * destroy — so their entries are never stale, and such a step has no
+     * `selector` to be re-resolved from: dropping one whose element is still on
+     * screen would leave `advanceTo` nothing to find, and it would skip the step
+     * after waiting `waitForElement` ms for a registration that already
+     * happened. `actionRegistered` is exactly the set to spare.
+     */
+    function clearResolvedTargets() {
+        for (const id of registry.keys()) {
+            if (!actionRegistered.has(id))
+                registry.delete(id);
+        }
+    }
     // -- Public API ---------------------------------------------------------------------
+    /**
+     * Begin the tour at its first available step.
+     *
+     * No-op while a tour is already running, and — if `storageKey` is set — for
+     * anyone who has already completed or skipped it. Use {@link reset} to
+     * clear that.
+     *
+     * Resolved targets are cleared HERE rather than in `reset()`, because the
+     * staleness is per-RUN and not per-persisted-flag: a tour with no
+     * `storageKey` is re-startable without ever calling `reset()`, and would
+     * otherwise walk the previous run's nodes. See {@link clearResolvedTargets}.
+     */
     function start() {
         if (active)
             return;
         if (store && store.has(options.storageKey))
             return;
+        clearResolvedTargets();
         options.onStart?.();
         advanceTo(0);
     }
@@ -248,6 +287,13 @@ export function createTour(options) {
         store?.set(options.storageKey, "skipped");
         options.onSkip?.();
     }
+    /**
+     * Forget that this tour was completed or skipped, so {@link start} runs it
+     * again. A no-op without `storageKey` — there is nothing persisted to clear.
+     *
+     * It does NOT touch the resolved-target cache; `start()` does, on every run.
+     * See {@link clearResolvedTargets} for why that is the right boundary.
+     */
     function reset() {
         store?.remove(options.storageKey);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.155.0",
+	"version": "3.157.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -128,12 +128,12 @@
 		}
 	},
 	"devDependencies": {
-		"@codemirror/commands": "^6.10.4",
+		"@codemirror/commands": "^6.11.0",
 		"@codemirror/lang-markdown": "^6.5.2",
 		"@codemirror/language": "^6.12.4",
 		"@codemirror/language-data": "^6.5.2",
 		"@codemirror/state": "^6.7.1",
-		"@codemirror/view": "^6.43.8",
+		"@codemirror/view": "^6.43.9",
 		"@eslint/js": "^9.39.5",
 		"@marianmeres/random-human-readable": "^1.10.2",
 		"@milkdown/core": "^7.22.1",
@@ -146,7 +146,7 @@
 		"@milkdown/transformer": "^7.22.1",
 		"@milkdown/utils": "^7.22.1",
 		"@sveltejs/adapter-auto": "^4.0.0",
-		"@sveltejs/kit": "^2.70.2",
+		"@sveltejs/kit": "^2.70.3",
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^6.2.4",
 		"@tailwindcss/cli": "^4.3.3",
@@ -154,14 +154,14 @@
 		"@tailwindcss/typography": "^0.5.20",
 		"@tailwindcss/vite": "^4.3.3",
 		"@types/node": "^25.9.5",
-		"@vitest/browser-playwright": "^4.1.10",
+		"@vitest/browser-playwright": "^4.1.11",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.5",
 		"globals": "^16.5.0",
 		"playwright": "^1.62.1",
 		"prettier": "^3.9.6",
 		"prettier-plugin-svelte": "^3.5.2",
-		"publint": "^0.3.23",
+		"publint": "^0.3.24",
 		"svelte": "^5.56.9",
 		"svelte-check": "^4.7.6",
 		"tailwindcss": "^4.3.3",
@@ -169,7 +169,7 @@
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.67.0",
 		"vite": "^7.3.6",
-		"vitest": "^4.1.10",
+		"vitest": "^4.1.11",
 		"vitest-browser-svelte": "^2.2.1"
 	},
 	"dependencies": {
@@ -177,13 +177,13 @@
 		"@marianmeres/countries": "^1.1.0",
 		"@marianmeres/cron-parser": "^1.0.1",
 		"@marianmeres/design-tokens": "^1.17.0",
-		"@marianmeres/icons-fns": "^5.0.0",
+		"@marianmeres/icons-fns": "^6.0.0",
 		"@marianmeres/item-collection": "^1.4.2",
 		"@marianmeres/paging-store": "^2.1.1",
 		"@marianmeres/parse-boolean": "^2.1.0",
 		"@marianmeres/ticker": "^1.17.1",
 		"@marianmeres/tree": "^2.3.0",
-		"libphonenumber-js": "^1.13.10",
+		"libphonenumber-js": "^1.13.11",
 		"runed": "^0.23.4",
 		"tailwind-merge": "^3.6.0"
 	}