sv5ui 2.1.0 → 2.3.0

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

@@ -0,0 +1,62 @@
+type MaybeGetter<T> = T | (() => T);
+export interface UseIntervalOptions {
+    /**
+     * Whether the interval is paused. Accepts a value or a reactive getter.
+     * @default false
+     */
+    paused?: boolean | (() => boolean);
+}
+interface UseIntervalReturn {
+    /** Pause ticking. */
+    pause(): void;
+    /** Resume ticking. */
+    resume(): void;
+    /** Whether the interval is currently ticking. */
+    readonly active: boolean;
+}
+interface UseTimeoutReturn {
+    /** Cancel the pending timeout, then schedule a fresh one. */
+    restart(): void;
+    /** Cancel the pending timeout. */
+    cancel(): void;
+}
+/**
+ * Run a callback on an interval with proper runes teardown.
+ *
+ * The delay may be a value or a getter; changing it restarts the interval with
+ * the new period. A `null`/`undefined` or non-positive delay disables it, as
+ * does `pause()` or the `paused` option. SSR-safe: no timer runs on the server.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useInterval } from 'sv5ui'
+ *
+ *   let count = $state(0)
+ *   const timer = useInterval(() => count++, 1000)
+ * </script>
+ *
+ * <button onclick={timer.pause}>Pause</button>
+ * ```
+ */
+export declare function useInterval(callback: () => void, delay: MaybeGetter<number | null | undefined>, options?: UseIntervalOptions): UseIntervalReturn;
+/**
+ * Schedule a callback to run once after a delay, with proper runes teardown.
+ *
+ * Starts on mount. The delay may be a value or a getter; changing it restarts
+ * the timer. A `null`/`undefined` or negative delay schedules nothing. SSR-safe:
+ * no timer runs on the server.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTimeout } from 'sv5ui'
+ *
+ *   const timer = useTimeout(() => (visible = false), 3000)
+ * </script>
+ *
+ * <button onclick={timer.restart}>Reset</button>
+ * ```
+ */
+export declare function useTimeout(callback: () => void, delay: MaybeGetter<number | null | undefined>): UseTimeoutReturn;
+export {};

package/dist/hooks/useTimers/useTimers.svelte.js

@@ -0,0 +1,90 @@
+import { toGetter } from '../utils.js';
+/**
+ * Run a callback on an interval with proper runes teardown.
+ *
+ * The delay may be a value or a getter; changing it restarts the interval with
+ * the new period. A `null`/`undefined` or non-positive delay disables it, as
+ * does `pause()` or the `paused` option. SSR-safe: no timer runs on the server.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useInterval } from 'sv5ui'
+ *
+ *   let count = $state(0)
+ *   const timer = useInterval(() => count++, 1000)
+ * </script>
+ *
+ * <button onclick={timer.pause}>Pause</button>
+ * ```
+ */
+export function useInterval(callback, delay, options = {}) {
+    const resolveDelay = toGetter(delay);
+    const resolvePaused = toGetter(options.paused ?? false);
+    let manuallyPaused = $state(false);
+    const active = $derived.by(() => {
+        if (manuallyPaused || resolvePaused())
+            return false;
+        const ms = resolveDelay();
+        return typeof ms === 'number' && ms > 0;
+    });
+    $effect(() => {
+        if (!active)
+            return;
+        const ms = resolveDelay();
+        if (typeof ms !== 'number' || ms <= 0)
+            return;
+        const id = setInterval(callback, ms);
+        return () => clearInterval(id);
+    });
+    return {
+        pause() {
+            manuallyPaused = true;
+        },
+        resume() {
+            manuallyPaused = false;
+        },
+        get active() {
+            return active;
+        }
+    };
+}
+/**
+ * Schedule a callback to run once after a delay, with proper runes teardown.
+ *
+ * Starts on mount. The delay may be a value or a getter; changing it restarts
+ * the timer. A `null`/`undefined` or negative delay schedules nothing. SSR-safe:
+ * no timer runs on the server.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTimeout } from 'sv5ui'
+ *
+ *   const timer = useTimeout(() => (visible = false), 3000)
+ * </script>
+ *
+ * <button onclick={timer.restart}>Reset</button>
+ * ```
+ */
+export function useTimeout(callback, delay) {
+    const resolveDelay = toGetter(delay);
+    let timeoutId;
+    let restartToken = $state(0);
+    $effect(() => {
+        void restartToken;
+        const ms = resolveDelay();
+        if (typeof ms !== 'number' || ms < 0)
+            return;
+        timeoutId = setTimeout(callback, ms);
+        return () => clearTimeout(timeoutId);
+    });
+    return {
+        restart() {
+            restartToken++;
+        },
+        cancel() {
+            clearTimeout(timeoutId);
+        }
+    };
+}

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/hooks/utils.d.ts

@@ -0,0 +1 @@
+export declare function toGetter<T>(value: T | (() => T)): () => T;

package/dist/hooks/utils.js

@@ -0,0 +1,3 @@
+export function toGetter(value) {
+    return typeof value === 'function' ? value : () => value;
+}

package/dist/index.d.ts

@@ -1,54 +1,59 @@
-export * from './Icon/index.js';
-export * from './Button/index.js';
-export * from './Avatar/index.js';
-export * from './AvatarGroup/index.js';
-export * from './Alert/index.js';
-export * from './Card/index.js';
-export * from './Link/index.js';
-export * from './Separator/index.js';
-export * from './Chip/index.js';
-export * from './Progress/index.js';
-export * from './Badge/index.js';
-export * from './Kbd/index.js';
-export * from './Container/index.js';
-export * from './Timeline/index.js';
-export * from './User/index.js';
-export * from './Empty/index.js';
-export * from './Skeleton/index.js';
-export * from './Drawer/index.js';
-export * from './Tooltip/index.js';
-export * from './Modal/index.js';
-export * from './Accordion/index.js';
-export * from './Collapsible/index.js';
-export * from './Command/index.js';
-export * from './Slideover/index.js';
-export * from './Popover/index.js';
-export * from './Breadcrumb/index.js';
-export * from './Calendar/index.js';
-export * from './DropdownMenu/index.js';
-export * from './ContextMenu/index.js';
-export * from './Tabs/index.js';
-export * from './Pagination/index.js';
-export * from './FieldGroup/index.js';
-export * from './FormField/index.js';
-export * from './Form/index.js';
-export * from './Input/index.js';
-export * from './Textarea/index.js';
-export * from './Select/index.js';
-export * from './SelectMenu/index.js';
-export * from './Switch/index.js';
-export * from './Checkbox/index.js';
-export * from './CheckboxGroup/index.js';
-export * from './RadioGroup/index.js';
-export * from './FileUpload/index.js';
-export * from './Slider/index.js';
-export * from './PinInput/index.js';
-export * from './ThemeModeButton/index.js';
-export * from './Table/index.js';
-export * from './Toast/index.js';
-export * from './Carousel/index.js';
-export * from './Banner/index.js';
-export * from './Stepper/index.js';
+export * from './components/Icon/index.js';
+export * from './components/Button/index.js';
+export * from './components/Avatar/index.js';
+export * from './components/AvatarGroup/index.js';
+export * from './components/Alert/index.js';
+export * from './components/Card/index.js';
+export * from './components/Link/index.js';
+export * from './components/Separator/index.js';
+export * from './components/Chip/index.js';
+export * from './components/Progress/index.js';
+export * from './components/Badge/index.js';
+export * from './components/Kbd/index.js';
+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';
+export * from './components/Modal/index.js';
+export * from './components/Accordion/index.js';
+export * from './components/Collapsible/index.js';
+export * from './components/Command/index.js';
+export * from './components/Slideover/index.js';
+export * from './components/Popover/index.js';
+export * from './components/Breadcrumb/index.js';
+export * from './components/Calendar/index.js';
+export * from './components/DropdownMenu/index.js';
+export * from './components/ContextMenu/index.js';
+export * from './components/Tabs/index.js';
+export * from './components/Pagination/index.js';
+export * from './components/FieldGroup/index.js';
+export * from './components/FormField/index.js';
+export * from './components/Form/index.js';
+export * from './components/Input/index.js';
+export * from './components/Textarea/index.js';
+export * from './components/Select/index.js';
+export * from './components/SelectMenu/index.js';
+export * from './components/Switch/index.js';
+export * from './components/Checkbox/index.js';
+export * from './components/CheckboxGroup/index.js';
+export * from './components/RadioGroup/index.js';
+export * from './components/FileUpload/index.js';
+export * from './components/Slider/index.js';
+export * from './components/PinInput/index.js';
+export * from './components/ThemeModeButton/index.js';
+export * from './components/Table/index.js';
+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

@@ -1,55 +1,60 @@
 // Components
-export * from './Icon/index.js';
-export * from './Button/index.js';
-export * from './Avatar/index.js';
-export * from './AvatarGroup/index.js';
-export * from './Alert/index.js';
-export * from './Card/index.js';
-export * from './Link/index.js';
-export * from './Separator/index.js';
-export * from './Chip/index.js';
-export * from './Progress/index.js';
-export * from './Badge/index.js';
-export * from './Kbd/index.js';
-export * from './Container/index.js';
-export * from './Timeline/index.js';
-export * from './User/index.js';
-export * from './Empty/index.js';
-export * from './Skeleton/index.js';
-export * from './Drawer/index.js';
-export * from './Tooltip/index.js';
-export * from './Modal/index.js';
-export * from './Accordion/index.js';
-export * from './Collapsible/index.js';
-export * from './Command/index.js';
-export * from './Slideover/index.js';
-export * from './Popover/index.js';
-export * from './Breadcrumb/index.js';
-export * from './Calendar/index.js';
-export * from './DropdownMenu/index.js';
-export * from './ContextMenu/index.js';
-export * from './Tabs/index.js';
-export * from './Pagination/index.js';
-export * from './FieldGroup/index.js';
-export * from './FormField/index.js';
-export * from './Form/index.js';
-export * from './Input/index.js';
-export * from './Textarea/index.js';
-export * from './Select/index.js';
-export * from './SelectMenu/index.js';
-export * from './Switch/index.js';
-export * from './Checkbox/index.js';
-export * from './CheckboxGroup/index.js';
-export * from './RadioGroup/index.js';
-export * from './FileUpload/index.js';
-export * from './Slider/index.js';
-export * from './PinInput/index.js';
-export * from './ThemeModeButton/index.js';
-export * from './Table/index.js';
-export * from './Toast/index.js';
-export * from './Carousel/index.js';
-export * from './Banner/index.js';
-export * from './Stepper/index.js';
+export * from './components/Icon/index.js';
+export * from './components/Button/index.js';
+export * from './components/Avatar/index.js';
+export * from './components/AvatarGroup/index.js';
+export * from './components/Alert/index.js';
+export * from './components/Card/index.js';
+export * from './components/Link/index.js';
+export * from './components/Separator/index.js';
+export * from './components/Chip/index.js';
+export * from './components/Progress/index.js';
+export * from './components/Badge/index.js';
+export * from './components/Kbd/index.js';
+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';
+export * from './components/Modal/index.js';
+export * from './components/Accordion/index.js';
+export * from './components/Collapsible/index.js';
+export * from './components/Command/index.js';
+export * from './components/Slideover/index.js';
+export * from './components/Popover/index.js';
+export * from './components/Breadcrumb/index.js';
+export * from './components/Calendar/index.js';
+export * from './components/DropdownMenu/index.js';
+export * from './components/ContextMenu/index.js';
+export * from './components/Tabs/index.js';
+export * from './components/Pagination/index.js';
+export * from './components/FieldGroup/index.js';
+export * from './components/FormField/index.js';
+export * from './components/Form/index.js';
+export * from './components/Input/index.js';
+export * from './components/Textarea/index.js';
+export * from './components/Select/index.js';
+export * from './components/SelectMenu/index.js';
+export * from './components/Switch/index.js';
+export * from './components/Checkbox/index.js';
+export * from './components/CheckboxGroup/index.js';
+export * from './components/RadioGroup/index.js';
+export * from './components/FileUpload/index.js';
+export * from './components/Slider/index.js';
+export * from './components/PinInput/index.js';
+export * from './components/ThemeModeButton/index.js';
+export * from './components/Table/index.js';
+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.1.0",
+    "version": "2.3.0",
     "description": "A modern Svelte 5 UI component library with Tailwind CSS",
     "author": "ndlabdev",
     "license": "MIT",
@@ -43,9 +43,9 @@
             "default": "./dist/index.js"
         },
         "./editor": {
-            "types": "./dist/Editor/index.d.ts",
-            "svelte": "./dist/Editor/index.js",
-            "default": "./dist/Editor/index.js"
+            "types": "./dist/components/Editor/index.d.ts",
+            "svelte": "./dist/components/Editor/index.js",
+            "default": "./dist/components/Editor/index.js"
         },
         "./theme.css": {
             "import": "./dist/theme.css",