@marianmeres/stuic 3.65.0 → 3.66.1

package/API.md

@@ -1482,6 +1482,7 @@ Multi-step onboarding tour built on the spotlight primitive. Define steps centra
 | `borderRadius`| `number`            | Cutout border radius (px)                 |
 | `onEnter`     | `() => void`        | Called when entering step                  |
 | `onLeave`     | `() => void`        | Called when leaving step                   |
+| `selector`    | `string`            | CSS selector to find the target element (alternative to `use:tourStep`) |
 
 **`tourStep` action:** `use:tourStep={[tour, stepId]}`
 
@@ -1504,6 +1505,29 @@ Multi-step onboarding tour built on the spotlight primitive. Define steps centra
 <button onclick={tour.start}>Start Tour</button>
 ```
 
+**Selector-based targeting:** Steps can target elements by CSS selector instead of `use:tourStep`. Useful when the target lives inside a reusable component that shouldn't know about the tour:
+
+```svelte
+<!-- ReusableComponent.svelte — no tour knowledge -->
+<button data-tour-id="download">Download</button>
+
+<!-- Tour config -->
+<script>
+	const tour = createTour({
+		steps: [
+			{
+				id: "dl-step",
+				title: "Download",
+				content: "Click here to download.",
+				selector: '[data-tour-id="download"]',
+			},
+		],
+	});
+</script>
+```
+
+When a step has `selector`, the tour uses `document.querySelector(selector)` to find the target element. If the element isn't in the DOM yet, the tour polls periodically until `waitForElement` ms elapse (same timeout as `use:tourStep`). Steps without `selector` continue to use `use:tourStep` as before — both mechanisms coexist freely.
+
 ---
 
 ## Utilities

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

@@ -30,6 +30,12 @@ export interface TourStepDef {
     onEnter?: () => void;
     /** Called when tour leaves this step */
     onLeave?: () => void;
+    /**
+     * CSS selector to find the target element in the DOM.
+     * If provided, the tour will use `document.querySelector(selector)`
+     * instead of waiting for a `use:tourStep` registration.
+     */
+    selector?: string;
 }
 /**
  * Default label overrides for the navigation shell buttons.
@@ -147,6 +153,7 @@ export declare function createTour(options: TourOptions): {
     reset: () => void;
     _register: (id: string, el: HTMLElement) => void;
     _unregister: (id: string) => void;
+    _registerAction: (id: string) => void;
     _isCurrentStep: (id: string) => boolean;
     _getShellContent: (id: string) => THC;
 };

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

@@ -36,6 +36,8 @@ export function createTour(options) {
         : null;
     // Element registry: stepId -> HTMLElement
     const registry = new Map();
+    // Steps registered via use:tourStep action (to prevent double-spotlight with selector)
+    const actionRegistered = new Set();
     // Wait-for-element mechanism (one pending wait at a time)
     let pendingStepId = null;
     let pendingResolve = null;
@@ -63,7 +65,34 @@ export function createTour(options) {
             return () => document.removeEventListener("keydown", handler);
         }
     });
+    // Spotlight for selector-based steps (no use:tourStep action to manage it)
+    $effect(() => {
+        const step = currentStep;
+        if (!active || !step?.selector)
+            return;
+        // If this step was registered via use:tourStep, let the action handle spotlight
+        if (actionRegistered.has(step.id))
+            return;
+        const el = registry.get(step.id);
+        if (!el)
+            return;
+        // spotlight() creates inner $effects; Svelte cleans them up
+        // when this outer effect re-runs (step change) or is destroyed (tour end)
+        spotlight(el, () => ({
+            open: true,
+            content: _getShellContent(step.id),
+            position: step.position ?? "bottom",
+            padding: step.padding,
+            borderRadius: step.borderRadius,
+            closeOnEscape: false,
+            closeOnBackdropClick: false,
+            scrollIntoView: true,
+        }));
+    });
     // -- Internal API (used by tourStep action) -----------------------------------------
+    function _registerAction(id) {
+        actionRegistered.add(id);
+    }
     function _register(id, el) {
         registry.set(id, el);
         // If we were waiting for this element, resolve immediately
@@ -119,10 +148,25 @@ export function createTour(options) {
             pendingResolve = null;
             pendingStepId = null;
         }
+        const step = options.steps.find((s) => s.id === id);
+        const selector = step?.selector;
         return new Promise((resolve) => {
             pendingStepId = id;
             pendingResolve = resolve;
+            // For selector-based steps, poll the DOM periodically
+            let pollInterval = null;
+            if (selector) {
+                pollInterval = setInterval(() => {
+                    const el = document.querySelector(selector);
+                    if (el && pendingStepId === id) {
+                        _register(id, el);
+                        // _register() resolves the promise via pendingResolve
+                    }
+                }, 50);
+            }
             setTimeout(() => {
+                if (pollInterval)
+                    clearInterval(pollInterval);
                 if (pendingStepId === id) {
                     console.warn(`[createTour] Step "${id}" element not found after ${options.waitForElement ?? 500}ms — skipping`);
                     pendingStepId = null;
@@ -144,6 +188,13 @@ export function createTour(options) {
             // Find the nearest available step in the direction of travel
             while (index >= 0 && index < options.steps.length) {
                 const step = options.steps[index];
+                // For selector-based steps, try to find the element in the DOM
+                if (step.selector && !registry.has(step.id)) {
+                    const el = document.querySelector(step.selector);
+                    if (el) {
+                        _register(step.id, el);
+                    }
+                }
                 if (!registry.has(step.id)) {
                     const found = await waitForElement(step.id);
                     if (!found) {
@@ -216,6 +267,7 @@ export function createTour(options) {
         // Internal — used by tourStep action
         _register,
         _unregister,
+        _registerAction,
         _isCurrentStep,
         _getShellContent,
     };
@@ -235,6 +287,7 @@ export function tourStep(el, args) {
     const [tour, id] = args;
     if (!tour)
         return;
+    tour._registerAction(id);
     tour._register(id, el);
     spotlight(el, () => {
         const isActive = tour._isCurrentStep(id);

package/docs/domains/actions.md

@@ -136,7 +136,17 @@ Actions using `$effect()` accept a function returning options:
 <button onclick={tour.start}>Start Tour</button>
 ```
 
-Features: step navigation (next/prev/skip), persistent state via `storageKey`, custom shell snippets, `confirmSkip` callback, wait-for-element mechanism, Escape key support, step lifecycle callbacks (`onEnter`/`onLeave`).
+Steps can also target elements by CSS **selector** instead of `use:tourStep` — useful when the target lives inside a reusable component:
+
+```svelte
+<!-- Component adds a stable data attribute (no tour knowledge) -->
+<button data-tour-id="download">Download</button>
+
+<!-- Tour config references it by selector -->
+{ id: "dl-step", title: "Download", content: "...", selector: '[data-tour-id="download"]' }
+```
+
+Features: step navigation (next/prev/skip), selector-based step targeting, persistent state via `storageKey`, custom shell snippets, `confirmSkip` callback, wait-for-element mechanism, Escape key support, step lifecycle callbacks (`onEnter`/`onLeave`).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "3.65.0",
+  "version": "3.66.1",
   "files": [
     "dist",
     "!dist/**/*.test.*",
@@ -35,35 +35,35 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
-    "@marianmeres/random-human-readable": "^1.8.2",
+    "@marianmeres/random-human-readable": "^1.8.3",
     "@sveltejs/adapter-auto": "^4.0.0",
-    "@sveltejs/kit": "^2.55.0",
+    "@sveltejs/kit": "^2.57.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@tailwindcss/cli": "^4.2.2",
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "dotenv": "^16.6.1",
     "eslint": "^9.39.4",
     "globals": "^16.5.0",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.2",
     "prettier-plugin-svelte": "^3.5.1",
     "publint": "^0.3.18",
-    "svelte": "^5.55.0",
-    "svelte-check": "^4.4.5",
+    "svelte": "^5.55.3",
+    "svelte-check": "^4.4.6",
     "tailwindcss": "^4.2.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.2",
-    "vite": "^7.3.1",
+    "typescript-eslint": "^8.58.2",
+    "vite": "^7.3.2",
     "vitest": "^3.2.4"
   },
   "dependencies": {
     "@marianmeres/clog": "^3.15.2",
     "@marianmeres/cron": "^1.1.0",
-    "@marianmeres/design-tokens": "^1.3.0",
+    "@marianmeres/design-tokens": "^1.3.1",
     "@marianmeres/icons-fns": "^5.0.0",
     "@marianmeres/item-collection": "^1.3.5",
     "@marianmeres/paging-store": "^2.0.2",
@@ -71,7 +71,7 @@
     "@marianmeres/ticker": "^1.16.5",
     "@marianmeres/tree": "^2.2.5",
     "esm-env": "^1.2.2",
-    "libphonenumber-js": "^1.12.40",
+    "libphonenumber-js": "^1.12.41",
     "runed": "^0.23.4",
     "tailwind-merge": "^3.5.0"
   },