sv5ui 2.2.0 → 2.3.0

package/dist/components/Tour/tour.variants.js

@@ -0,0 +1,56 @@
+import { tv } from 'tailwind-variants';
+export const tourVariants = tv({
+    slots: {
+        overlay: 'fixed inset-0 z-[var(--sv5ui-tour-overlay-z,100)]',
+        spotlight: [
+            'fixed top-0 left-0 z-[var(--sv5ui-tour-overlay-z,100)] pointer-events-none',
+            'shadow-[0_0_0_9999px_rgba(0,0,0,0.5)]'
+        ],
+        panel: [
+            'z-[var(--sv5ui-tour-panel-z,101)] flex flex-col',
+            'bg-surface-container-lowest text-on-surface ring ring-surface-container-highest',
+            'rounded-xl shadow-xl focus:outline-none',
+            'w-[var(--sv5ui-tour-w)] max-w-[calc(100vw-2rem)]'
+        ],
+        arrow: 'bg-surface-container-lowest border-surface-container-highest',
+        header: 'relative flex items-start justify-between gap-2 p-4 pb-0',
+        title: 'font-semibold text-sm leading-snug',
+        description: 'text-sm text-on-surface-variant',
+        body: 'px-4 py-3 text-sm text-on-surface-variant',
+        footer: 'flex items-center justify-between gap-3 p-4 pt-0',
+        progress: 'flex items-center gap-1.5',
+        progressDot: 'size-1.5 rounded-full bg-on-surface-variant/30 transition-colors',
+        nav: 'flex items-center gap-2 ml-auto',
+        prevButton: '',
+        nextButton: '',
+        skipButton: 'text-on-surface-variant',
+        closeButton: 'shrink-0 -mt-1 -mr-1'
+    },
+    variants: {
+        size: {
+            sm: { panel: '[--sv5ui-tour-w:280px]' },
+            md: { panel: '[--sv5ui-tour-w:340px]' },
+            lg: { panel: '[--sv5ui-tour-w:420px]' }
+        },
+        transition: {
+            true: {
+                panel: [
+                    'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+                    'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95'
+                ],
+                spotlight: 'transition-transform duration-300 ease-out'
+            }
+        },
+        active: {
+            true: { progressDot: 'bg-primary' }
+        }
+    },
+    defaultVariants: {
+        size: 'md',
+        transition: true
+    }
+});
+export const tourDefaults = {
+    defaultVariants: tourVariants.defaultVariants,
+    slots: {}
+};

package/dist/config.d.ts

@@ -30,6 +30,8 @@ export declare const iconsDefaults: {
     chevronsRight: string;
     ellipsis: string;
     close: string;
+    menu: string;
+    external: string;
     check: string;
     light: string;
     dark: string;

package/dist/config.js

@@ -31,6 +31,8 @@ export const iconsDefaults = {
     chevronsRight: 'lucide:chevrons-right',
     ellipsis: 'lucide:ellipsis',
     close: 'lucide:x',
+    menu: 'lucide:menu',
+    external: 'lucide:arrow-up-right',
     check: 'lucide:check',
     light: 'lucide:sun',
     dark: 'lucide:moon',

package/dist/hooks/index.d.ts

@@ -14,3 +14,4 @@ export * from './useIntersectionObserver/index.js';
 export * from './useScrollLock/index.js';
 export * from './useFocusTrap/index.js';
 export * from './useLocalStorage/index.js';
+export * from './useTour/index.js';

package/dist/hooks/index.js

@@ -14,3 +14,4 @@ export * from './useIntersectionObserver/index.js';
 export * from './useScrollLock/index.js';
 export * from './useFocusTrap/index.js';
 export * from './useLocalStorage/index.js';
+export * from './useTour/index.js';

package/dist/hooks/useTour/index.d.ts

@@ -0,0 +1 @@
+export { useTour } from './useTour.svelte.js';

package/dist/hooks/useTour/index.js

@@ -0,0 +1 @@
+export { useTour } from './useTour.svelte.js';

package/dist/hooks/useTour/useTour.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { TourController, UseTourOptions } from '../../components/Tour/tour.types.js';
+/**
+ * Headless controller for the {@link import('../../components/Tour/tour.types.js').TourProps Tour}
+ * component. Pure reactive state — no `$effect` — so it is safe to create
+ * conditionally and renders nothing on the server.
+ *
+ * Drive the tour through the returned {@link TourController}, and pass it to
+ * `<Tour controller={tour} />`. Persistence (when enabled) keeps an in-progress
+ * tour alive across reloads and SPA navigations, which is what makes multi-page
+ * tours possible.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTour, Tour } from 'sv5ui'
+ *   import { goto } from '$app/navigation'
+ *
+ *   const tour = useTour({
+ *     steps,
+ *     persist: true,
+ *     onStepChange: (i) => { if (steps[i].route) goto(steps[i].route) }
+ *   })
+ * </script>
+ *
+ * <Button onclick={() => tour.start()}>Start</Button>
+ * <Tour {steps} controller={tour} />
+ * ```
+ */
+export declare function useTour(options: UseTourOptions): TourController;

package/dist/hooks/useTour/useTour.svelte.js

@@ -0,0 +1,194 @@
+function normalizePersist(persist) {
+    if (!persist)
+        return null;
+    const opts = persist === true ? {} : persist;
+    return { key: opts.key ?? 'sv5ui-tour', storage: opts.storage ?? 'local' };
+}
+/**
+ * Headless controller for the {@link import('../../components/Tour/tour.types.js').TourProps Tour}
+ * component. Pure reactive state — no `$effect` — so it is safe to create
+ * conditionally and renders nothing on the server.
+ *
+ * Drive the tour through the returned {@link TourController}, and pass it to
+ * `<Tour controller={tour} />`. Persistence (when enabled) keeps an in-progress
+ * tour alive across reloads and SPA navigations, which is what makes multi-page
+ * tours possible.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTour, Tour } from 'sv5ui'
+ *   import { goto } from '$app/navigation'
+ *
+ *   const tour = useTour({
+ *     steps,
+ *     persist: true,
+ *     onStepChange: (i) => { if (steps[i].route) goto(steps[i].route) }
+ *   })
+ * </script>
+ *
+ * <Button onclick={() => tour.start()}>Start</Button>
+ * <Tour {steps} controller={tour} />
+ * ```
+ */
+export function useTour(options) {
+    const defaultStep = options.defaultStep ?? 0;
+    const persist = normalizePersist(options.persist);
+    let open = $state(false);
+    let index = $state(defaultStep);
+    let completed = false;
+    function getSteps() {
+        return options.steps;
+    }
+    function clamp(i) {
+        const last = getSteps().length - 1;
+        if (last < 0)
+            return 0;
+        return Math.max(0, Math.min(i, last));
+    }
+    function resolveIndex(step) {
+        if (typeof step === 'number')
+            return clamp(step);
+        const found = getSteps().findIndex((s) => s.id === step);
+        return found >= 0 ? found : index;
+    }
+    function nextEnabled(from, dir) {
+        const steps = getSteps();
+        let i = from + dir;
+        while (i >= 0 && i < steps.length) {
+            if (!steps[i]?.disabled)
+                return i;
+            i += dir;
+        }
+        return null;
+    }
+    function firstEnabled(from) {
+        if (!getSteps()[from]?.disabled)
+            return from;
+        return nextEnabled(from, 1) ?? nextEnabled(from, -1) ?? from;
+    }
+    function persistSave() {
+        if (!persist || typeof window === 'undefined')
+            return;
+        try {
+            const store = persist.storage === 'session' ? sessionStorage : localStorage;
+            if (open) {
+                store.setItem(persist.key, JSON.stringify({ open: true, index }));
+            }
+            else {
+                store.removeItem(persist.key);
+            }
+        }
+        catch {
+            void 0;
+        }
+    }
+    if (persist && typeof window !== 'undefined') {
+        try {
+            const store = persist.storage === 'session' ? sessionStorage : localStorage;
+            const raw = store.getItem(persist.key);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (parsed?.open) {
+                    open = true;
+                    index = clamp(parsed.index ?? defaultStep);
+                }
+            }
+        }
+        catch {
+            void 0;
+        }
+    }
+    function changeIndex(target) {
+        const prev = index;
+        index = target;
+        persistSave();
+        if (target !== prev)
+            options.onStepChange?.(target, prev);
+    }
+    function start(step) {
+        const base = step !== undefined ? resolveIndex(step) : clamp(index);
+        const target = firstEnabled(base);
+        completed = false;
+        const prev = open ? index : -1;
+        index = target;
+        if (!open) {
+            open = true;
+            persistSave();
+            options.onStart?.();
+        }
+        else {
+            persistSave();
+        }
+        if (target !== prev)
+            options.onStepChange?.(target, prev);
+    }
+    function stop() {
+        if (!open)
+            return;
+        const at = index;
+        open = false;
+        persistSave();
+        if (!completed)
+            options.onSkip?.(at);
+    }
+    function next() {
+        if (!open)
+            return;
+        const ni = nextEnabled(index, 1);
+        if (ni === null) {
+            completed = true;
+            options.onComplete?.();
+            open = false;
+            persistSave();
+            return;
+        }
+        changeIndex(ni);
+    }
+    function prev() {
+        if (!open)
+            return;
+        const pi = nextEnabled(index, -1);
+        if (pi === null)
+            return;
+        changeIndex(pi);
+    }
+    function goTo(step) {
+        if (!open) {
+            start(step);
+            return;
+        }
+        changeIndex(firstEnabled(resolveIndex(step)));
+    }
+    return {
+        start,
+        stop,
+        next,
+        prev,
+        goTo,
+        get isActive() {
+            return open;
+        },
+        get currentIndex() {
+            return open ? index : -1;
+        },
+        get totalSteps() {
+            return getSteps().length;
+        },
+        get hasPrev() {
+            return open && nextEnabled(index, -1) !== null;
+        },
+        get hasNext() {
+            return open && nextEnabled(index, 1) !== null;
+        },
+        get isFirst() {
+            return nextEnabled(index, -1) === null;
+        },
+        get isLast() {
+            return nextEnabled(index, 1) === null;
+        },
+        get currentStepData() {
+            return open ? getSteps()[index] : undefined;
+        }
+    };
+}

package/dist/index.d.ts

@@ -14,6 +14,10 @@ export * from './components/Container/index.js';
 export * from './components/Timeline/index.js';
 export * from './components/User/index.js';
 export * from './components/Empty/index.js';
+export * from './components/Error/index.js';
+export * from './components/Footer/index.js';
+export * from './components/Header/index.js';
+export * from './components/Main/index.js';
 export * from './components/Skeleton/index.js';
 export * from './components/Drawer/index.js';
 export * from './components/Tooltip/index.js';
@@ -49,6 +53,7 @@ export * from './components/Toast/index.js';
 export * from './components/Carousel/index.js';
 export * from './components/Banner/index.js';
 export * from './components/Stepper/index.js';
+export * from './components/Tour/index.js';
 export * from './hooks/index.js';
 export { defineConfig } from './config.js';
 export type { UIConfig } from './config.js';

package/dist/index.js

@@ -15,6 +15,10 @@ export * from './components/Container/index.js';
 export * from './components/Timeline/index.js';
 export * from './components/User/index.js';
 export * from './components/Empty/index.js';
+export * from './components/Error/index.js';
+export * from './components/Footer/index.js';
+export * from './components/Header/index.js';
+export * from './components/Main/index.js';
 export * from './components/Skeleton/index.js';
 export * from './components/Drawer/index.js';
 export * from './components/Tooltip/index.js';
@@ -50,6 +54,7 @@ export * from './components/Toast/index.js';
 export * from './components/Carousel/index.js';
 export * from './components/Banner/index.js';
 export * from './components/Stepper/index.js';
+export * from './components/Tour/index.js';
 // Composables
 export * from './hooks/index.js';
 // Configuration

package/dist/theme.css

@@ -86,6 +86,9 @@
     --color-inverse-surface: oklch(0.208 0.042 265.75);
     --color-inverse-on-surface: oklch(0.929 0.013 255.51);
     --color-inverse-primary: oklch(0.707 0.165 254.62);
+
+    /* ========== LAYOUT ========== */
+    --ui-header-height: 4rem;
 }
 
 /* ============================================

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sv5ui",
-    "version": "2.2.0",
+    "version": "2.3.0",
     "description": "A modern Svelte 5 UI component library with Tailwind CSS",
     "author": "ndlabdev",
     "license": "MIT",