sv5ui 2.1.0 → 2.3.0

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

@@ -0,0 +1 @@
+export * from './useInfiniteScroll.svelte.js';

package/dist/hooks/useInfiniteScroll/index.js

@@ -0,0 +1 @@
+export * from './useInfiniteScroll.svelte.js';

package/dist/hooks/{useInfiniteScroll.svelte.d.ts → useInfiniteScroll/useInfiniteScroll.svelte.d.ts}

@@ -17,7 +17,7 @@ export interface UseInfiniteScrollOptions {
      */
     enabled?: boolean | (() => boolean);
 }
-export interface UseInfiniteScrollReturn {
+interface UseInfiniteScrollReturn {
     /** Whether an async onLoad is currently in progress */
     readonly loading: boolean;
 }
@@ -55,3 +55,4 @@ export interface UseInfiniteScrollReturn {
 export declare function useInfiniteScroll(options: UseInfiniteScrollOptions): UseInfiniteScrollReturn & {
     action: Action<HTMLElement>;
 };
+export {};

package/dist/hooks/{useInfiniteScroll.svelte.js → useInfiniteScroll/useInfiniteScroll.svelte.js}

@@ -1,3 +1,4 @@
+import { useEventListener } from '../useEventListener/index.js';
 /**
  * Reactive infinite scroll hook with Svelte action.
  *
@@ -50,15 +51,7 @@ export function useInfiniteScroll(options) {
         }
     }
     const action = (node) => {
-        function handleScroll() {
-            check(node);
-        }
-        node.addEventListener('scroll', handleScroll, { passive: true });
-        return {
-            destroy() {
-                node.removeEventListener('scroll', handleScroll);
-            }
-        };
+        useEventListener(() => node, 'scroll', () => check(node), { passive: true });
     };
     return {
         get loading() {

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

@@ -0,0 +1 @@
+export * from './useIntersectionObserver.svelte.js';

package/dist/hooks/useIntersectionObserver/index.js

@@ -0,0 +1 @@
+export * from './useIntersectionObserver.svelte.js';

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

@@ -0,0 +1,30 @@
+type ElementTarget = Element | null | undefined | (() => Element | null | undefined);
+export type UseIntersectionObserverOptions = IntersectionObserverInit;
+interface UseIntersectionObserverReturn {
+    /** Whether the target currently intersects the root, per the latest entry. */
+    readonly isIntersecting: boolean;
+}
+/**
+ * Observe an element's intersection with the viewport (or a root) via
+ * `IntersectionObserver`, with automatic cleanup.
+ *
+ * The target may be a value or a getter; when it is a getter that reads reactive
+ * state, the observer re-attaches as the target changes. SSR-safe: a nullish
+ * target is a no-op.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useIntersectionObserver } from 'sv5ui'
+ *
+ *   let el = $state<HTMLElement>()
+ *   const io = useIntersectionObserver(() => el, (entry) => {
+ *     if (entry.isIntersecting) loadImage()
+ *   }, { rootMargin: '200px' })
+ * </script>
+ *
+ * <div bind:this={el}>{io.isIntersecting ? 'visible' : 'hidden'}</div>
+ * ```
+ */
+export declare function useIntersectionObserver(target: ElementTarget, callback?: (entry: IntersectionObserverEntry) => void, options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn;
+export {};

package/dist/hooks/useIntersectionObserver/useIntersectionObserver.svelte.js

@@ -0,0 +1,46 @@
+import { toGetter } from '../utils.js';
+/**
+ * Observe an element's intersection with the viewport (or a root) via
+ * `IntersectionObserver`, with automatic cleanup.
+ *
+ * The target may be a value or a getter; when it is a getter that reads reactive
+ * state, the observer re-attaches as the target changes. SSR-safe: a nullish
+ * target is a no-op.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useIntersectionObserver } from 'sv5ui'
+ *
+ *   let el = $state<HTMLElement>()
+ *   const io = useIntersectionObserver(() => el, (entry) => {
+ *     if (entry.isIntersecting) loadImage()
+ *   }, { rootMargin: '200px' })
+ * </script>
+ *
+ * <div bind:this={el}>{io.isIntersecting ? 'visible' : 'hidden'}</div>
+ * ```
+ */
+export function useIntersectionObserver(target, callback, options) {
+    const resolveTarget = toGetter(target);
+    let isIntersecting = $state(false);
+    $effect(() => {
+        const el = resolveTarget();
+        if (!el)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            const entry = entries[entries.length - 1];
+            if (!entry)
+                return;
+            isIntersecting = entry.isIntersecting;
+            callback?.(entry);
+        }, options);
+        observer.observe(el);
+        return () => observer.disconnect();
+    });
+    return {
+        get isIntersecting() {
+            return isIntersecting;
+        }
+    };
+}

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

@@ -0,0 +1 @@
+export * from './useLocalStorage.svelte.js';

package/dist/hooks/useLocalStorage/index.js

@@ -0,0 +1 @@
+export * from './useLocalStorage.svelte.js';

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

@@ -0,0 +1,39 @@
+export interface UseLocalStorageSerializer<T> {
+    parse: (raw: string) => T;
+    stringify: (value: T) => string;
+}
+export interface UseLocalStorageOptions<T> {
+    /**
+     * Custom serializer. Defaults to JSON.
+     */
+    serializer?: UseLocalStorageSerializer<T>;
+    /**
+     * Update the value when another tab changes the same key (via the `storage` event).
+     * @default true
+     */
+    syncTabs?: boolean;
+}
+export interface UseLocalStorageReturn<T> {
+    /** The persisted value. Read it, or assign to write through to `localStorage`. */
+    current: T;
+}
+/**
+ * Reactive `localStorage`-backed value with cross-tab sync.
+ *
+ * Reads the stored value on mount (falling back to `initial`), writes through to
+ * `localStorage` whenever `.current` changes, and — when `syncTabs` is on — updates
+ * when another tab changes the same key. SSR-safe: renders `initial` on the server
+ * and hydrates on mount; parse/quota errors are tolerated.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useLocalStorage } from 'sv5ui'
+ *
+ *   const theme = useLocalStorage('theme', 'system')
+ * </script>
+ *
+ * <button onclick={() => (theme.current = 'dark')}>{theme.current}</button>
+ * ```
+ */
+export declare function useLocalStorage<T>(key: string, initial: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;

package/dist/hooks/useLocalStorage/useLocalStorage.svelte.js

@@ -0,0 +1,73 @@
+import { useEventListener } from '../useEventListener/index.js';
+const jsonSerializer = {
+    parse: (raw) => JSON.parse(raw),
+    stringify: (value) => JSON.stringify(value)
+};
+/**
+ * Reactive `localStorage`-backed value with cross-tab sync.
+ *
+ * Reads the stored value on mount (falling back to `initial`), writes through to
+ * `localStorage` whenever `.current` changes, and — when `syncTabs` is on — updates
+ * when another tab changes the same key. SSR-safe: renders `initial` on the server
+ * and hydrates on mount; parse/quota errors are tolerated.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useLocalStorage } from 'sv5ui'
+ *
+ *   const theme = useLocalStorage('theme', 'system')
+ * </script>
+ *
+ * <button onclick={() => (theme.current = 'dark')}>{theme.current}</button>
+ * ```
+ */
+export function useLocalStorage(key, initial, options = {}) {
+    const serializer = options.serializer ?? jsonSerializer;
+    const { syncTabs = true } = options;
+    let value = $state(initial);
+    $effect(() => {
+        const raw = localStorage.getItem(key);
+        if (raw !== null) {
+            try {
+                value = serializer.parse(raw);
+            }
+            catch {
+                value = initial;
+            }
+        }
+    });
+    $effect(() => {
+        try {
+            const serialized = serializer.stringify(value);
+            if (localStorage.getItem(key) !== serialized) {
+                localStorage.setItem(key, serialized);
+            }
+        }
+        catch {
+            // ignore serialization / quota errors
+        }
+    });
+    useEventListener(() => (syncTabs ? window : null), 'storage', (event) => {
+        if (event.key !== key || event.storageArea !== localStorage)
+            return;
+        if (event.newValue === null) {
+            value = initial;
+            return;
+        }
+        try {
+            value = serializer.parse(event.newValue);
+        }
+        catch {
+            // ignore malformed external writes
+        }
+    });
+    return {
+        get current() {
+            return value;
+        },
+        set current(next) {
+            value = next;
+        }
+    };
+}

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

@@ -0,0 +1 @@
+export * from './useMediaQuery.svelte.js';

package/dist/hooks/useMediaQuery/index.js

@@ -0,0 +1 @@
+export * from './useMediaQuery.svelte.js';

package/dist/hooks/{useMediaQuery.svelte.d.ts → useMediaQuery/useMediaQuery.svelte.d.ts}

@@ -5,7 +5,7 @@ export interface UseMediaQueryOptions {
      */
     initialValue?: boolean;
 }
-export interface UseMediaQueryReturn {
+interface UseMediaQueryReturn {
     /** Whether the media query currently matches */
     readonly matches: boolean;
 }
@@ -29,3 +29,4 @@ export interface UseMediaQueryReturn {
  * ```
  */
 export declare function useMediaQuery(query: string | (() => string), options?: UseMediaQueryOptions): UseMediaQueryReturn;
+export {};

package/dist/hooks/{useMediaQuery.svelte.js → useMediaQuery/useMediaQuery.svelte.js}

@@ -1,3 +1,4 @@
+import { toGetter } from '../utils.js';
 /**
  * Reactive media query hook. Tracks whether a CSS media query matches.
  *
@@ -19,7 +20,7 @@
  */
 export function useMediaQuery(query, options = {}) {
     const { initialValue = false } = options;
-    const resolveQuery = typeof query === 'function' ? query : () => query;
+    const resolveQuery = toGetter(query);
     let matches = $state(initialValue);
     $effect(() => {
         const mediaQuery = window.matchMedia(resolveQuery());

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

@@ -0,0 +1 @@
+export * from './useResizeObserver.svelte.js';

package/dist/hooks/useResizeObserver/index.js

@@ -0,0 +1 @@
+export * from './useResizeObserver.svelte.js';

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

@@ -0,0 +1,50 @@
+type ElementTarget = HTMLElement | null | undefined | (() => HTMLElement | null | undefined);
+/**
+ * Observe an element's size changes with a `ResizeObserver` and automatic cleanup.
+ *
+ * The target may be a value or a getter; when it is a getter that reads reactive
+ * state, the observer re-attaches as the target changes. SSR-safe: a nullish
+ * target is a no-op.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useResizeObserver } from 'sv5ui'
+ *
+ *   let el = $state<HTMLElement>()
+ *   useResizeObserver(() => el, ([entry]) => {
+ *     console.log(entry.contentRect.width)
+ *   })
+ * </script>
+ *
+ * <div bind:this={el}>resize me</div>
+ * ```
+ */
+export declare function useResizeObserver(target: ElementTarget, callback: ResizeObserverCallback, options?: ResizeObserverOptions): void;
+interface UseElementSizeReturn {
+    /** Current content-box width in pixels. */
+    readonly width: number;
+    /** Current content-box height in pixels. */
+    readonly height: number;
+}
+/**
+ * Track an element's content-box size reactively.
+ *
+ * Built on `useResizeObserver`. The size starts at `0` and updates on the
+ * observer's initial callback and on every subsequent resize. SSR-safe.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useElementSize } from 'sv5ui'
+ *
+ *   let el = $state<HTMLElement>()
+ *   const size = useElementSize(() => el)
+ * </script>
+ *
+ * <div bind:this={el}>...</div>
+ * <p>{size.width} × {size.height}</p>
+ * ```
+ */
+export declare function useElementSize(target: ElementTarget): UseElementSizeReturn;
+export {};

package/dist/hooks/useResizeObserver/useResizeObserver.svelte.js

@@ -0,0 +1,71 @@
+import { toGetter } from '../utils.js';
+/**
+ * Observe an element's size changes with a `ResizeObserver` and automatic cleanup.
+ *
+ * The target may be a value or a getter; when it is a getter that reads reactive
+ * state, the observer re-attaches as the target changes. SSR-safe: a nullish
+ * target is a no-op.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useResizeObserver } from 'sv5ui'
+ *
+ *   let el = $state<HTMLElement>()
+ *   useResizeObserver(() => el, ([entry]) => {
+ *     console.log(entry.contentRect.width)
+ *   })
+ * </script>
+ *
+ * <div bind:this={el}>resize me</div>
+ * ```
+ */
+export function useResizeObserver(target, callback, options) {
+    const resolveTarget = toGetter(target);
+    $effect(() => {
+        const el = resolveTarget();
+        if (!el)
+            return;
+        const observer = new ResizeObserver(callback);
+        observer.observe(el, options);
+        return () => observer.disconnect();
+    });
+}
+/**
+ * Track an element's content-box size reactively.
+ *
+ * Built on `useResizeObserver`. The size starts at `0` and updates on the
+ * observer's initial callback and on every subsequent resize. SSR-safe.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useElementSize } from 'sv5ui'
+ *
+ *   let el = $state<HTMLElement>()
+ *   const size = useElementSize(() => el)
+ * </script>
+ *
+ * <div bind:this={el}>...</div>
+ * <p>{size.width} × {size.height}</p>
+ * ```
+ */
+export function useElementSize(target) {
+    let width = $state(0);
+    let height = $state(0);
+    useResizeObserver(target, (entries) => {
+        const entry = entries[0];
+        if (!entry)
+            return;
+        width = entry.contentRect.width;
+        height = entry.contentRect.height;
+    });
+    return {
+        get width() {
+            return width;
+        },
+        get height() {
+            return height;
+        }
+    };
+}

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

@@ -0,0 +1 @@
+export * from './useScrollLock.svelte.js';

package/dist/hooks/useScrollLock/index.js

@@ -0,0 +1 @@
+export * from './useScrollLock.svelte.js';

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

@@ -0,0 +1,28 @@
+type ElementTarget = HTMLElement | null | undefined | (() => HTMLElement | null | undefined);
+interface UseScrollLockReturn {
+    lock: () => void;
+    unlock: () => void;
+}
+/**
+ * Lock scroll on an element (default `document.body`) while `locked` is true.
+ *
+ * Sets `overflow: hidden` and compensates for the scrollbar width to avoid a
+ * layout jump. Reference-counted per target, so nested overlays locking the same
+ * element do not unlock it prematurely. Original styles are restored when the
+ * last lock releases or on teardown. SSR-safe: a nullish target is a no-op.
+ *
+ * Pass a reactive `() => open` getter for the common case, or use the returned
+ * `lock` / `unlock` for imperative control (do not mix both on one instance).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScrollLock } from 'sv5ui'
+ *
+ *   let open = $state(false)
+ *   useScrollLock(() => open)
+ * </script>
+ * ```
+ */
+export declare function useScrollLock(locked: boolean | (() => boolean), target?: ElementTarget): UseScrollLockReturn;
+export {};

package/dist/hooks/useScrollLock/useScrollLock.svelte.js

@@ -0,0 +1,79 @@
+import { toGetter } from '../utils.js';
+const registry = new WeakMap();
+function scrollbarWidth(el) {
+    if (el === document.body || el === document.documentElement) {
+        return window.innerWidth - document.documentElement.clientWidth;
+    }
+    return el.offsetWidth - el.clientWidth;
+}
+function acquire(el) {
+    let state = registry.get(el);
+    if (!state) {
+        state = { count: 0, overflow: el.style.overflow, paddingRight: el.style.paddingRight };
+        registry.set(el, state);
+    }
+    if (state.count === 0) {
+        const gap = scrollbarWidth(el);
+        el.style.overflow = 'hidden';
+        if (gap > 0) {
+            const current = parseFloat(getComputedStyle(el).paddingRight) || 0;
+            el.style.paddingRight = `${current + gap}px`;
+        }
+    }
+    state.count++;
+}
+function release(el) {
+    const state = registry.get(el);
+    if (!state)
+        return;
+    state.count--;
+    if (state.count <= 0) {
+        el.style.overflow = state.overflow;
+        el.style.paddingRight = state.paddingRight;
+        registry.delete(el);
+    }
+}
+/**
+ * Lock scroll on an element (default `document.body`) while `locked` is true.
+ *
+ * Sets `overflow: hidden` and compensates for the scrollbar width to avoid a
+ * layout jump. Reference-counted per target, so nested overlays locking the same
+ * element do not unlock it prematurely. Original styles are restored when the
+ * last lock releases or on teardown. SSR-safe: a nullish target is a no-op.
+ *
+ * Pass a reactive `() => open` getter for the common case, or use the returned
+ * `lock` / `unlock` for imperative control (do not mix both on one instance).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useScrollLock } from 'sv5ui'
+ *
+ *   let open = $state(false)
+ *   useScrollLock(() => open)
+ * </script>
+ * ```
+ */
+export function useScrollLock(locked, target) {
+    const resolveLocked = toGetter(locked);
+    const resolveTarget = typeof target === 'function' ? target : () => target ?? document.body;
+    let manual = $state(null);
+    const isLocked = $derived(manual ?? resolveLocked());
+    $effect(() => {
+        if (!isLocked)
+            return;
+        const el = resolveTarget();
+        if (!el)
+            return;
+        acquire(el);
+        return () => release(el);
+    });
+    return {
+        lock() {
+            manual = true;
+        },
+        unlock() {
+            manual = false;
+        }
+    };
+}

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

@@ -0,0 +1 @@
+export * from './useThrottle.svelte.js';

package/dist/hooks/useThrottle/index.js

@@ -0,0 +1 @@
+export * from './useThrottle.svelte.js';

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

@@ -0,0 +1,37 @@
+export interface UseThrottleOptions {
+    /**
+     * Minimum time in milliseconds between invocations.
+     * @default 200
+     */
+    delay?: number;
+}
+/**
+ * Reactive throttle hook. Caps how often a callback runs to at most once per
+ * `delay`, with leading and trailing invocation.
+ *
+ * The companion to `useDebounce`: debounce waits for a pause, throttle
+ * guarantees a steady maximum rate — ideal for scroll, resize, mousemove, and
+ * drag handlers. The first call runs immediately; calls during the cooldown
+ * window are coalesced into a single trailing call (latest wins). Any pending
+ * timer is cleared on teardown.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useThrottle } from 'sv5ui'
+ *
+ *   const throttle = useThrottle({ delay: 100 })
+ *
+ *   function onScroll() {
+ *     throttle.run(() => updatePosition(window.scrollY))
+ *   }
+ * </script>
+ *
+ * <svelte:window onscroll={onScroll} />
+ * ```
+ */
+export declare function useThrottle(options?: UseThrottleOptions): {
+    readonly pending: boolean;
+    run: (callback: () => void) => void;
+    cancel: () => void;
+};

package/dist/hooks/useThrottle/useThrottle.svelte.js

@@ -0,0 +1,72 @@
+/**
+ * Reactive throttle hook. Caps how often a callback runs to at most once per
+ * `delay`, with leading and trailing invocation.
+ *
+ * The companion to `useDebounce`: debounce waits for a pause, throttle
+ * guarantees a steady maximum rate — ideal for scroll, resize, mousemove, and
+ * drag handlers. The first call runs immediately; calls during the cooldown
+ * window are coalesced into a single trailing call (latest wins). Any pending
+ * timer is cleared on teardown.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useThrottle } from 'sv5ui'
+ *
+ *   const throttle = useThrottle({ delay: 100 })
+ *
+ *   function onScroll() {
+ *     throttle.run(() => updatePosition(window.scrollY))
+ *   }
+ * </script>
+ *
+ * <svelte:window onscroll={onScroll} />
+ * ```
+ */
+export function useThrottle(options = {}) {
+    const { delay = 200 } = options;
+    let pending = $state(false);
+    let timeoutId;
+    let trailing;
+    function start() {
+        timeoutId = setTimeout(() => {
+            if (trailing) {
+                const callback = trailing;
+                trailing = undefined;
+                pending = false;
+                callback();
+                start();
+            }
+            else {
+                timeoutId = undefined;
+                pending = false;
+            }
+        }, delay);
+    }
+    function run(callback) {
+        if (timeoutId === undefined) {
+            callback();
+            start();
+        }
+        else {
+            trailing = callback;
+            pending = true;
+        }
+    }
+    function cancel() {
+        clearTimeout(timeoutId);
+        timeoutId = undefined;
+        trailing = undefined;
+        pending = false;
+    }
+    $effect(() => {
+        return () => clearTimeout(timeoutId);
+    });
+    return {
+        get pending() {
+            return pending;
+        },
+        run,
+        cancel
+    };
+}

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

@@ -0,0 +1 @@
+export * from './useTimers.svelte.js';

package/dist/hooks/useTimers/index.js

@@ -0,0 +1 @@
+export * from './useTimers.svelte.js';