svelora 3.0.5 → 3.0.7

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

@@ -0,0 +1,30 @@
+type MaybeGetter<T> = T | (() => T);
+/**
+ * Attach event listener(s) to a target with automatic cleanup.
+ *
+ * Binds inside an `$effect` and removes the listener(s) on teardown. The target
+ * may be a value or a getter; when it is a getter that reads reactive state, the
+ * listener re-binds as the target changes. SSR-safe: a nullish target is a no-op.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEventListener } from 'svelora'
+ *
+ *   let el = $state<HTMLElement>()
+ *
+ *   // Window target (static)
+ *   useEventListener(window, 'resize', () => console.log('resized'))
+ *
+ *   // Element target (reactive getter) + multiple event types
+ *   useEventListener(() => el, ['pointerenter', 'focus'], () => console.log('active'))
+ * </script>
+ *
+ * <div bind:this={el}>hover or focus me</div>
+ * ```
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(target: MaybeGetter<Window | null | undefined>, type: K | K[], handler: (this: Window, event: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof DocumentEventMap>(target: MaybeGetter<Document | null | undefined>, type: K | K[], handler: (this: Document, event: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener<K extends keyof HTMLElementEventMap>(target: MaybeGetter<HTMLElement | null | undefined>, type: K | K[], handler: (this: HTMLElement, event: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener(target: MaybeGetter<EventTarget | null | undefined>, type: string | string[], handler: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+export {};

package/dist/hooks/useEventListener.svelte.js

@@ -0,0 +1,16 @@
+import { toGetter } from './utils.js';
+export function useEventListener(target, type, handler, options) {
+    const resolveTarget = toGetter(target);
+    const types = Array.isArray(type) ? type : [type];
+    $effect(() => {
+        const el = resolveTarget();
+        if (!el)
+            return;
+        for (const t of types)
+            el.addEventListener(t, handler, options);
+        return () => {
+            for (const t of types)
+                el.removeEventListener(t, handler, options);
+        };
+    });
+}

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

@@ -0,0 +1,42 @@
+type ElementTarget = HTMLElement | null | undefined | (() => HTMLElement | null | undefined);
+export interface UseFocusTrapOptions {
+    /**
+     * Whether the trap is active. Accepts a value or a reactive getter.
+     * @default true
+     */
+    active?: boolean | (() => boolean);
+    /**
+     * Element to focus when the trap activates. A getter is resolved on activate.
+     * Pass `false` to skip auto-focus. Defaults to the first focusable element.
+     */
+    initialFocus?: HTMLElement | (() => HTMLElement | null) | false;
+    /**
+     * Restore focus to the previously focused element when the trap deactivates.
+     * @default true
+     */
+    restoreFocus?: boolean;
+}
+/**
+ * Trap keyboard focus within an element while active, and restore focus on exit.
+ *
+ * Cycles Tab / Shift+Tab among the focusable descendants of `target`, focuses an
+ * initial element on activation, and (by default) returns focus to the previously
+ * focused element when it deactivates or unmounts. The target and `active` may be
+ * values or reactive getters. SSR-safe: a nullish/inactive target is a no-op.
+ *
+ * Intended for custom focus-scoped UI. Components built on bits-ui primitives
+ * (Modal, Slideover, Drawer, Popover) already trap focus — do not double-wrap them.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFocusTrap } from 'svelora'
+ *
+ *   let open = $state(false)
+ *   let panel = $state<HTMLElement>()
+ *   useFocusTrap(() => panel, { active: () => open })
+ * </script>
+ * ```
+ */
+export declare function useFocusTrap(target: ElementTarget, options?: UseFocusTrapOptions): void;
+export {};

package/dist/hooks/useFocusTrap.svelte.js

@@ -0,0 +1,87 @@
+import { toGetter } from './utils.js';
+import { useEventListener } from './useEventListener.svelte.js';
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+    'audio[controls]',
+    'video[controls]',
+    '[contenteditable]:not([contenteditable="false"])',
+    'details > summary:first-of-type'
+].join(',');
+function getFocusable(container) {
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => el.offsetWidth > 0 || el.offsetHeight > 0 || el === document.activeElement);
+}
+/**
+ * Trap keyboard focus within an element while active, and restore focus on exit.
+ *
+ * Cycles Tab / Shift+Tab among the focusable descendants of `target`, focuses an
+ * initial element on activation, and (by default) returns focus to the previously
+ * focused element when it deactivates or unmounts. The target and `active` may be
+ * values or reactive getters. SSR-safe: a nullish/inactive target is a no-op.
+ *
+ * Intended for custom focus-scoped UI. Components built on bits-ui primitives
+ * (Modal, Slideover, Drawer, Popover) already trap focus — do not double-wrap them.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFocusTrap } from 'svelora'
+ *
+ *   let open = $state(false)
+ *   let panel = $state<HTMLElement>()
+ *   useFocusTrap(() => panel, { active: () => open })
+ * </script>
+ * ```
+ */
+export function useFocusTrap(target, options = {}) {
+    const resolveTarget = toGetter(target);
+    const resolveActive = toGetter(options.active ?? true);
+    const { initialFocus, restoreFocus = true } = options;
+    $effect(() => {
+        if (!resolveActive())
+            return;
+        const resolved = resolveTarget();
+        if (!resolved)
+            return;
+        const el = resolved;
+        const previouslyFocused = document.activeElement;
+        if (initialFocus !== false) {
+            const initial = typeof initialFocus === 'function' ? initialFocus() : initialFocus;
+            (initial ?? getFocusable(el)[0] ?? el).focus();
+        }
+        return () => {
+            if (restoreFocus && previouslyFocused && document.contains(previouslyFocused)) {
+                previouslyFocused.focus();
+            }
+        };
+    });
+    useEventListener(() => (resolveActive() && resolveTarget() ? document : null), 'keydown', (event) => {
+        if (event.key !== 'Tab')
+            return;
+        const el = resolveTarget();
+        if (!el)
+            return;
+        const focusable = getFocusable(el);
+        if (focusable.length === 0) {
+            event.preventDefault();
+            return;
+        }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const active = document.activeElement;
+        if (event.shiftKey) {
+            if (active === first || !el.contains(active)) {
+                event.preventDefault();
+                last.focus();
+            }
+        }
+        else if (active === last || !el.contains(active)) {
+            event.preventDefault();
+            first.focus();
+        }
+    }, true);
+}

package/dist/hooks/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 'svelora'
+ *
+ *   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.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 'svelora'
+ *
+ *   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.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 'svelora'
+ *
+ *   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.svelte.js

@@ -0,0 +1,73 @@
+import { useEventListener } from './useEventListener.svelte.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 'svelora'
+ *
+ *   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/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 'svelora'
+ *
+ *   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 'svelora'
+ *
+ *   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.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 'svelora'
+ *
+ *   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 'svelora'
+ *
+ *   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.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 'svelora'
+ *
+ *   let open = $state(false)
+ *   useScrollLock(() => open)
+ * </script>
+ * ```
+ */
+export declare function useScrollLock(locked: boolean | (() => boolean), target?: ElementTarget): UseScrollLockReturn;
+export {};

package/dist/hooks/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 'svelora'
+ *
+ *   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.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 'svelora'
+ *
+ *   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;
+};