@marianmeres/stuic 3.64.1 → 3.66.0

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/dist/components/TabbedMenu/TabbedMenu.svelte

@@ -19,6 +19,7 @@
 		value?: string | number;
 		disabled?: boolean;
 		onSelect?: (item: TabbedMenuItem) => void;
+		orientation?: "horizontal" | "vertical";
 		//
 		class?: string;
 		classItem?: string;
@@ -39,6 +40,7 @@
 		value = $bindable(),
 		disabled,
 		onSelect,
+		orientation = "horizontal",
 		//
 		class: classProp,
 		classItem,
@@ -114,6 +116,8 @@
 		bind:this={el}
 		class={twMerge(!unstyled && "stuic-tabbed-menu", classProp)}
 		role="tablist"
+		aria-orientation={orientation}
+		data-orientation={orientation}
 		{...rest}
 	>
 		{#each items as item (item.id)}

package/dist/components/TabbedMenu/TabbedMenu.svelte.d.ts

@@ -14,6 +14,7 @@ export interface Props extends Omit<HTMLAttributes<HTMLUListElement>, "children"
     value?: string | number;
     disabled?: boolean;
     onSelect?: (item: TabbedMenuItem) => void;
+    orientation?: "horizontal" | "vertical";
     class?: string;
     classItem?: string;
     classButton?: string;

package/dist/components/TabbedMenu/index.css

@@ -86,4 +86,29 @@
 		outline: 2px solid var(--stuic-color-ring);
 		outline-offset: 2px;
 	}
+
+	/* ============================================================================
+	   VERTICAL ORIENTATION
+	   ============================================================================ */
+
+	.stuic-tabbed-menu[data-orientation="vertical"] {
+		flex-direction: column;
+	}
+
+	.stuic-tabbed-menu[data-orientation="vertical"] .stuic-tabbed-menu-item {
+		max-width: none;
+		flex: none;
+		width: var(--stuic-tabbed-menu-item-max-width);
+	}
+
+	.stuic-tabbed-menu[data-orientation="vertical"] .stuic-tabbed-menu-tab {
+		border-radius: var(--stuic-tabbed-menu-radius, var(--stuic-radius)) 0 0 var(--stuic-tabbed-menu-radius, var(--stuic-radius));
+		border: 1px solid var(--stuic-tabbed-menu-border);
+		border-right: 0;
+		text-align: left;
+	}
+
+	.stuic-tabbed-menu[data-orientation="vertical"] .stuic-tabbed-menu-tab[aria-selected="true"] {
+		border-color: var(--stuic-tabbed-menu-border-active);
+	}
 }

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.64.1",
+  "version": "3.66.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",