@marianmeres/stuic 3.35.1 → 3.37.0

package/dist/actions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./autogrow.svelte.js";
+export * from "./onboarding/onboarding.svelte.js";
 export * from "./autoscroll.js";
 export * from "./dim-behind/dim-behind.svelte.js";
 export * from "./file-dropzone.svelte.js";

package/dist/actions/index.js

@@ -1,4 +1,5 @@
 export * from "./autogrow.svelte.js";
+export * from "./onboarding/onboarding.svelte.js";
 export * from "./autoscroll.js";
 export * from "./dim-behind/dim-behind.svelte.js";
 export * from "./file-dropzone.svelte.js";

package/dist/actions/onboarding/OnboardingShell.svelte

@@ -0,0 +1,71 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { TourStepDef, TourLabels, TourShellContext } from "./onboarding.svelte.js";
+
+	export interface Props {
+		step: TourStepDef;
+		/** 0-based index of this step */
+		index: number;
+		total: number;
+		isFirst: boolean;
+		isLast: boolean;
+		labels: Required<TourLabels>;
+		/** Optional custom shell snippet — replaces the entire default layout */
+		shell?: Snippet<[TourShellContext]>;
+		next: () => void;
+		prev: () => void;
+		skip: () => void;
+	}
+</script>
+
+<script lang="ts">
+	import Thc from "../../components/Thc/Thc.svelte";
+
+	let { step, index, total, isFirst, isLast, labels, shell, next, prev, skip }: Props = $props();
+
+	const context: TourShellContext = $derived({
+		step,
+		index,
+		total,
+		isFirst,
+		isLast,
+		next,
+		prev,
+		skip,
+	});
+</script>
+
+{#if shell}
+	{@render shell(context)}
+{:else}
+	<div class="stuic-onboarding-shell">
+		{#if step.title}
+			<div class="stuic-onboarding-title">{step.title}</div>
+		{/if}
+		{#if step.content}
+			<div class="stuic-onboarding-content">
+				<Thc thc={step.content} />
+			</div>
+		{/if}
+		<div class="stuic-onboarding-footer">
+			<span class="stuic-onboarding-steps">{index + 1} / {total}</span>
+			<div class="stuic-onboarding-actions">
+				{#if !isLast}
+					<button class="stuic-onboarding-btn-skip" onclick={skip}>
+						{step.skipLabel ?? labels.skip}
+					</button>
+				{/if}
+				{#if !isFirst}
+					<button class="stuic-onboarding-btn-prev" onclick={prev}>
+						{step.prevLabel ?? labels.prev}
+					</button>
+				{/if}
+				<button class="stuic-onboarding-btn-next" onclick={next}>
+					{isLast
+						? (step.finishLabel ?? labels.finish)
+						: (step.nextLabel ?? labels.next)}
+				</button>
+			</div>
+		</div>
+	</div>
+{/if}

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

@@ -0,0 +1,19 @@
+import type { Snippet } from "svelte";
+import type { TourStepDef, TourLabels, TourShellContext } from "./onboarding.svelte.js";
+export interface Props {
+    step: TourStepDef;
+    /** 0-based index of this step */
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    labels: Required<TourLabels>;
+    /** Optional custom shell snippet — replaces the entire default layout */
+    shell?: Snippet<[TourShellContext]>;
+    next: () => void;
+    prev: () => void;
+    skip: () => void;
+}
+declare const OnboardingShell: import("svelte").Component<Props, {}, "">;
+type OnboardingShell = ReturnType<typeof OnboardingShell>;
+export default OnboardingShell;

package/dist/actions/onboarding/index.css

@@ -0,0 +1,93 @@
+/* Onboarding shell tokens */
+:root {
+	--stuic-onboarding-shell-padding: calc(var(--spacing) * 3);
+	--stuic-onboarding-shell-gap: calc(var(--spacing) * 2);
+	--stuic-onboarding-shell-min-width: 200px;
+	--stuic-onboarding-shell-max-width: 320px;
+	--stuic-onboarding-title-size: var(--text-base);
+	--stuic-onboarding-content-size: var(--text-sm);
+	--stuic-onboarding-footer-gap: calc(var(--spacing) * 1.5);
+	--stuic-onboarding-steps-size: var(--text-xs);
+	--stuic-onboarding-btn-padding-x: calc(var(--spacing) * 2.5);
+	--stuic-onboarding-btn-padding-y: calc(var(--spacing) * 1);
+	--stuic-onboarding-btn-radius: calc(var(--spacing) * 1);
+	--stuic-onboarding-btn-font-size: var(--text-xs);
+	--stuic-onboarding-btn-primary-bg: var(--stuic-color-primary, #737373);
+	--stuic-onboarding-btn-primary-fg: var(--stuic-color-primary-foreground, #fff);
+	--stuic-onboarding-btn-secondary-bg: oklch(from currentColor l c h / 0.08);
+}
+
+.stuic-onboarding-shell {
+	display: flex;
+	flex-direction: column;
+	gap: var(--stuic-onboarding-shell-gap);
+	padding: var(--stuic-onboarding-shell-padding);
+	min-width: var(--stuic-onboarding-shell-min-width);
+	max-width: var(--stuic-onboarding-shell-max-width);
+}
+
+.stuic-onboarding-title {
+	font-weight: 600;
+	font-size: var(--stuic-onboarding-title-size);
+}
+
+.stuic-onboarding-content {
+	font-size: var(--stuic-onboarding-content-size);
+	opacity: 0.85;
+}
+
+.stuic-onboarding-footer {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: calc(var(--spacing) * 2);
+	padding-top: calc(var(--spacing) * 2);
+	margin-top: calc(var(--spacing) * 1);
+	border-top: 1px solid var(--stuic-spotlight-annotation-border, rgba(0, 0, 0, 0.1));
+}
+
+.stuic-onboarding-steps {
+	font-size: var(--stuic-onboarding-steps-size);
+	opacity: 0.5;
+}
+
+.stuic-onboarding-actions {
+	display: flex;
+	align-items: center;
+	gap: var(--stuic-onboarding-footer-gap);
+}
+
+/* Shared button base */
+.stuic-onboarding-btn-skip,
+.stuic-onboarding-btn-prev,
+.stuic-onboarding-btn-next {
+	font-size: var(--stuic-onboarding-btn-font-size);
+	padding: var(--stuic-onboarding-btn-padding-y) var(--stuic-onboarding-btn-padding-x);
+	border-radius: var(--stuic-onboarding-btn-radius);
+	line-height: 1.5;
+	transition:
+		opacity 0.15s,
+		filter 0.15s;
+}
+
+.stuic-onboarding-btn-skip {
+	opacity: 0.45;
+	&:hover {
+		opacity: 0.85;
+	}
+}
+
+.stuic-onboarding-btn-prev {
+	background: var(--stuic-onboarding-btn-secondary-bg);
+	&:hover {
+		filter: brightness(0.9);
+	}
+}
+
+.stuic-onboarding-btn-next {
+	background: var(--stuic-onboarding-btn-primary-bg);
+	color: var(--stuic-onboarding-btn-primary-fg);
+	&:hover {
+		filter: brightness(0.9);
+	}
+}

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

@@ -0,0 +1,148 @@
+import type { Snippet } from "svelte";
+import type { SpotlightPosition } from "../spotlight/spotlight.svelte.js";
+import type { THC } from "../../components/Thc/Thc.svelte";
+/**
+ * Definition of a single step in an onboarding tour.
+ */
+export interface TourStepDef {
+    /** Unique identifier — must match the `id` passed to `use:tourStep` */
+    id: string;
+    /** Short title shown in the default shell header */
+    title?: string;
+    /** Rich step description (any THC value: string, html, component, snippet) */
+    content?: THC;
+    /** Spotlight annotation position relative to the target element */
+    position?: SpotlightPosition;
+    /** Spotlight cutout padding in px */
+    padding?: number;
+    /** Spotlight cutout border radius in px */
+    borderRadius?: number;
+    /** Override "Next" button label for this step */
+    nextLabel?: string;
+    /** Override "Back" button label for this step */
+    prevLabel?: string;
+    /** Override "Skip" button label for this step */
+    skipLabel?: string;
+    /** Override "Finish" button label for the last step */
+    finishLabel?: string;
+    /** Called when tour enters this step */
+    onEnter?: () => void;
+    /** Called when tour leaves this step */
+    onLeave?: () => void;
+}
+/**
+ * Default label overrides for the navigation shell buttons.
+ */
+export interface TourLabels {
+    next?: string;
+    prev?: string;
+    skip?: string;
+    finish?: string;
+}
+/**
+ * Context passed to a custom `shell` snippet.
+ */
+export interface TourShellContext {
+    step: TourStepDef;
+    /** 0-based index of the current step */
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    prev: () => void;
+    skip: () => void | Promise<void>;
+}
+/**
+ * Options for `createTour`.
+ */
+export interface TourOptions {
+    steps: TourStepDef[];
+    /** How long to wait (ms) for a step's element to appear before skipping it. Default: 500 */
+    waitForElement?: number;
+    /** Default button labels (per-step overrides take precedence) */
+    labels?: TourLabels;
+    /** Replace the entire default shell with a custom Svelte snippet */
+    shell?: Snippet<[TourShellContext]>;
+    /** Press Escape to skip the tour. Default: true */
+    closeOnEscape?: boolean;
+    /** Called when tour starts */
+    onStart?: () => void;
+    /** Called when tour reaches the end naturally (after last step) */
+    onEnd?: () => void;
+    /** Called when tour is skipped by the user */
+    onSkip?: () => void;
+    /**
+     * If provided, called before skipping. Return (or resolve) `false` to cancel the skip.
+     * Works for both the Skip button and Escape key.
+     * @example
+     * ```ts
+     * // with createConfirm helper
+     * confirmSkip: () => confirm("Are you sure you want to skip the tutorial?")
+     * ```
+     */
+    confirmSkip?: () => boolean | Promise<boolean>;
+    /** Called on every step change */
+    onStepChange?: (step: TourStepDef, index: number) => void;
+    /**
+     * If set, the tour result ('completed' or 'skipped') is persisted under this key.
+     * On subsequent `start()` calls, the tour will silently skip if the key exists.
+     * Use `tour.reset()` to clear the persisted state and allow the tour to run again.
+     */
+    storageKey?: string;
+    /** Storage backend for persistence. Default: 'local' */
+    storage?: "local" | "session";
+}
+/**
+ * Creates a multi-step onboarding tour on top of the spotlight primitive.
+ *
+ * Define all steps centrally here, then attach `use:tourStep={[tour, stepId]}`
+ * to each target element in your markup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createTour, tourStep } from '../..';
+ *
+ *   const tour = createTour({
+ *     steps: [
+ *       { id: 'header', title: 'Welcome', content: 'This is the top of the page.' },
+ *       { id: 'save-btn', title: 'Save your work', content: 'Click here to save.' },
+ *     ],
+ *     onEnd: () => console.log('Tour complete!'),
+ *   });
+ * </script>
+ *
+ * <header use:tourStep={[tour, 'header']}>...</header>
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * <button onclick={tour.start}>Start Tour</button>
+ * ```
+ */
+export declare function createTour(options: TourOptions): {
+    readonly active: boolean;
+    readonly currentStep: TourStepDef;
+    readonly currentIndex: number;
+    readonly seen: boolean;
+    start: () => void;
+    next: () => void;
+    prev: () => void;
+    skip: () => Promise<void>;
+    reset: () => void;
+    _register: (id: string, el: HTMLElement) => void;
+    _unregister: (id: string) => void;
+    _isCurrentStep: (id: string) => boolean;
+    _getShellContent: (id: string) => THC;
+};
+export type TourInstance = ReturnType<typeof createTour>;
+/**
+ * Svelte action that registers a DOM element as the target for a specific tour step.
+ *
+ * @param el - The target element
+ * @param args - Tuple of `[TourInstance, stepId]`
+ *
+ * @example
+ * ```svelte
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * ```
+ */
+export declare function tourStep(el: HTMLElement, args: [TourInstance, string]): void;

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

@@ -0,0 +1,249 @@
+import { spotlight } from "../spotlight/spotlight.svelte.js";
+import OnboardingShell from "./OnboardingShell.svelte";
+import { StorageAbstraction } from "../../utils/storage-abstraction.js";
+/**
+ * Creates a multi-step onboarding tour on top of the spotlight primitive.
+ *
+ * Define all steps centrally here, then attach `use:tourStep={[tour, stepId]}`
+ * to each target element in your markup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createTour, tourStep } from '../..';
+ *
+ *   const tour = createTour({
+ *     steps: [
+ *       { id: 'header', title: 'Welcome', content: 'This is the top of the page.' },
+ *       { id: 'save-btn', title: 'Save your work', content: 'Click here to save.' },
+ *     ],
+ *     onEnd: () => console.log('Tour complete!'),
+ *   });
+ * </script>
+ *
+ * <header use:tourStep={[tour, 'header']}>...</header>
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * <button onclick={tour.start}>Start Tour</button>
+ * ```
+ */
+export function createTour(options) {
+    let currentIndex = $state(-1);
+    const active = $derived(currentIndex >= 0);
+    const currentStep = $derived(options.steps[currentIndex] ?? null);
+    // Optional persistence store
+    const store = options.storageKey
+        ? new StorageAbstraction(options.storage ?? "local")
+        : null;
+    // Element registry: stepId -> HTMLElement
+    const registry = new Map();
+    // Wait-for-element mechanism (one pending wait at a time)
+    let pendingStepId = null;
+    let pendingResolve = null;
+    // Guard against concurrent navigation calls
+    let advancing = false;
+    const resolvedLabels = {
+        next: "Next",
+        prev: "Back",
+        skip: "Skip",
+        finish: "Finish",
+        ...options.labels,
+    };
+    // Escape key listener — active only while tour is running
+    $effect(() => {
+        if (active && options.closeOnEscape !== false) {
+            const handler = async (e) => {
+                if (e.key === "Escape") {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    e.stopImmediatePropagation();
+                    await skip();
+                }
+            };
+            document.addEventListener("keydown", handler);
+            return () => document.removeEventListener("keydown", handler);
+        }
+    });
+    // -- Internal API (used by tourStep action) -----------------------------------------
+    function _register(id, el) {
+        registry.set(id, el);
+        // If we were waiting for this element, resolve immediately
+        if (pendingStepId === id && pendingResolve) {
+            pendingResolve(true);
+            pendingStepId = null;
+            pendingResolve = null;
+        }
+    }
+    function _unregister(id) {
+        registry.delete(id);
+        // If the active step's element unmounts mid-tour, end gracefully
+        if (active && currentStep?.id === id) {
+            console.warn(`[createTour] Active step "${id}" element unmounted — ending tour`);
+            _end();
+        }
+    }
+    function _isCurrentStep(id) {
+        return active && currentStep?.id === id;
+    }
+    function _getShellContent(id) {
+        const step = options.steps.find((s) => s.id === id);
+        const index = options.steps.indexOf(step);
+        const total = options.steps.length;
+        return {
+            component: OnboardingShell,
+            props: {
+                step,
+                index,
+                total,
+                isFirst: index === 0,
+                isLast: index === total - 1,
+                labels: resolvedLabels,
+                shell: options.shell,
+                next,
+                prev,
+                skip,
+            },
+        };
+    }
+    // -- Navigation ---------------------------------------------------------------------
+    function waitForElement(id) {
+        // Cancel any previous pending wait
+        if (pendingResolve) {
+            pendingResolve(false);
+            pendingResolve = null;
+            pendingStepId = null;
+        }
+        return new Promise((resolve) => {
+            pendingStepId = id;
+            pendingResolve = resolve;
+            setTimeout(() => {
+                if (pendingStepId === id) {
+                    console.warn(`[createTour] Step "${id}" element not found after ${options.waitForElement ?? 500}ms — skipping`);
+                    pendingStepId = null;
+                    pendingResolve = null;
+                    resolve(false);
+                }
+            }, options.waitForElement ?? 500);
+        });
+    }
+    async function advanceTo(targetIndex) {
+        if (advancing)
+            return;
+        advancing = true;
+        try {
+            // Call onLeave for the step we're leaving
+            currentStep?.onLeave?.();
+            const direction = targetIndex >= currentIndex ? 1 : -1;
+            let index = targetIndex;
+            // Find the nearest available step in the direction of travel
+            while (index >= 0 && index < options.steps.length) {
+                const step = options.steps[index];
+                if (!registry.has(step.id)) {
+                    const found = await waitForElement(step.id);
+                    if (!found) {
+                        index += direction;
+                        continue;
+                    }
+                }
+                // Step element is available — navigate here
+                currentIndex = index;
+                step.onEnter?.();
+                options.onStepChange?.(step, index);
+                return;
+            }
+            // Exhausted all steps in the direction of travel
+            _end();
+        }
+        finally {
+            advancing = false;
+        }
+    }
+    function _end() {
+        currentIndex = -1;
+        store?.set(options.storageKey, "completed");
+        options.onEnd?.();
+    }
+    // -- Public API ---------------------------------------------------------------------
+    function start() {
+        if (store && store.has(options.storageKey))
+            return;
+        options.onStart?.();
+        advanceTo(0);
+    }
+    function next() {
+        advanceTo(currentIndex + 1);
+    }
+    function prev() {
+        if (currentIndex > 0)
+            advanceTo(currentIndex - 1);
+    }
+    async function skip() {
+        if (options.confirmSkip && !(await options.confirmSkip()))
+            return;
+        currentIndex = -1;
+        store?.set(options.storageKey, "skipped");
+        options.onSkip?.();
+    }
+    function reset() {
+        store?.remove(options.storageKey);
+    }
+    return {
+        get active() {
+            return active;
+        },
+        get currentStep() {
+            return currentStep;
+        },
+        get currentIndex() {
+            return currentIndex;
+        },
+        get seen() {
+            return store ? store.has(options.storageKey) : false;
+        },
+        start,
+        next,
+        prev,
+        skip,
+        reset,
+        // Internal — used by tourStep action
+        _register,
+        _unregister,
+        _isCurrentStep,
+        _getShellContent,
+    };
+}
+/**
+ * Svelte action that registers a DOM element as the target for a specific tour step.
+ *
+ * @param el - The target element
+ * @param args - Tuple of `[TourInstance, stepId]`
+ *
+ * @example
+ * ```svelte
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * ```
+ */
+export function tourStep(el, args) {
+    const [tour, id] = args;
+    tour._register(id, el);
+    spotlight(el, () => {
+        const isActive = tour._isCurrentStep(id);
+        if (!isActive) {
+            return { open: false };
+        }
+        return {
+            open: true,
+            content: tour._getShellContent(id),
+            position: tour.currentStep?.position ?? "bottom",
+            padding: tour.currentStep?.padding,
+            borderRadius: tour.currentStep?.borderRadius,
+            closeOnEscape: false,
+            closeOnBackdropClick: false,
+            scrollIntoView: true,
+        };
+    });
+    $effect(() => {
+        return () => {
+            tour._unregister(id);
+        };
+    });
+}

package/dist/index.css

@@ -62,6 +62,7 @@ In practice:
 
 /* Action CSS */
 @import "./actions/dim-behind/index.css";
+@import "./actions/onboarding/index.css";
 @import "./actions/popover/index.css";
 @import "./actions/spotlight/index.css";
 @import "./actions/tooltip/index.css";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "3.35.1",
+  "version": "3.37.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",