sv5ui 2.0.0 → 2.2.0

package/dist/hooks/useFocusTrap/useFocusTrap.svelte.js

@@ -0,0 +1,87 @@
+import { toGetter } from '../utils.js';
+import { useEventListener } from '../useEventListener/index.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 'sv5ui'
+ *
+ *   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/useFormField/HookContextProbe.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">import { useFormField } from "./useFormField.svelte.js";
+const ctx = useFormField();
+</script>
+
+<div data-name={ctx?.name ?? 'none'} data-has={String(!!ctx)}>probe</div>

package/dist/hooks/useFormField/HookContextProvider.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">import { setContext } from "svelte";
+import { FORM_FIELD_CONTEXT_KEY } from "./useFormField.svelte.js";
+import HookContextProbe from "./HookContextProbe.svelte";
+setContext(FORM_FIELD_CONTEXT_KEY, { name: "email", size: "md", ariaId: "ff" });
+</script>
+
+<HookContextProbe />

package/dist/hooks/useFormField/HookEmitProbe.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">import { useFormFieldEmit } from "./useFormField.svelte.js";
+const emit = useFormFieldEmit();
+function fireAll() {
+  emit.onBlur();
+  emit.onFocus();
+  emit.onChange();
+  emit.onInput();
+}
+</script>
+
+<button data-testid="fire" onclick={fireAll}>fire</button>

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

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

package/dist/hooks/useFormField/index.js

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

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

@@ -1,4 +1,4 @@
-import type { FormFieldProps } from '../FormField/form-field.types.js';
+import type { FormFieldProps } from '../../components/FormField/form-field.types.js';
 /**
  * Symbol key for the FormField context. Using a Symbol instead of a string
  * prevents collisions with unrelated `getContext('formField')` calls from

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

@@ -1,5 +1,5 @@
 import { getContext } from 'svelte';
-import { getFormContext } from '../Form/form.context.svelte.js';
+import { getFormContext } from '../../components/Form/form.context.svelte.js';
 /**
  * Symbol key for the FormField context. Using a Symbol instead of a string
  * prevents collisions with unrelated `getContext('formField')` calls from

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';