svelora 2.1.0

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

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const HookEmitProbe: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type HookEmitProbe = InstanceType<typeof HookEmitProbe>;
+export default HookEmitProbe;

package/dist/hooks/index.d.ts

@@ -0,0 +1,14 @@
+export type { UseClickOutsideOptions } from './useClickOutside.svelte.js';
+export { useClickOutside } from './useClickOutside.svelte.js';
+export type { UseClipboardOptions } from './useClipboard.svelte.js';
+export { useClipboard } from './useClipboard.svelte.js';
+export type { UseDebounceOptions } from './useDebounce.svelte.js';
+export { useDebounce } from './useDebounce.svelte.js';
+export type { UseEscapeKeydownOptions } from './useEscapeKeydown.svelte.js';
+export { useEscapeKeydown } from './useEscapeKeydown.svelte.js';
+export type { FormFieldContext } from './useFormField.svelte.js';
+export { FORM_FIELD_CONTEXT_KEY, useFormField, useFormFieldEmit } from './useFormField.svelte.js';
+export type { UseInfiniteScrollOptions } from './useInfiniteScroll.svelte.js';
+export { useInfiniteScroll } from './useInfiniteScroll.svelte.js';
+export type { UseMediaQueryOptions } from './useMediaQuery.svelte.js';
+export { useMediaQuery } from './useMediaQuery.svelte.js';

package/dist/hooks/index.js

@@ -0,0 +1,7 @@
+export { useClickOutside } from './useClickOutside.svelte.js';
+export { useClipboard } from './useClipboard.svelte.js';
+export { useDebounce } from './useDebounce.svelte.js';
+export { useEscapeKeydown } from './useEscapeKeydown.svelte.js';
+export { FORM_FIELD_CONTEXT_KEY, useFormField, useFormFieldEmit } from './useFormField.svelte.js';
+export { useInfiniteScroll } from './useInfiniteScroll.svelte.js';
+export { useMediaQuery } from './useMediaQuery.svelte.js';

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

@@ -0,0 +1,31 @@
+import type { Action } from 'svelte/action';
+export interface UseClickOutsideOptions {
+    /**
+     * Callback fired when a click occurs outside the element.
+     */
+    handler: (event: PointerEvent) => void;
+    /**
+     * Whether the listener is active.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Svelte action that detects clicks outside an element.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClickOutside } from 'svelora'
+ *
+ *   let open = $state(false)
+ * </script>
+ *
+ * {#if open}
+ *   <div use:useClickOutside={{ handler: () => (open = false) }}>
+ *     Dropdown content
+ *   </div>
+ * {/if}
+ * ```
+ */
+export declare const useClickOutside: Action<HTMLElement, UseClickOutsideOptions>;

package/dist/hooks/useClickOutside.svelte.js

@@ -0,0 +1,37 @@
+/**
+ * Svelte action that detects clicks outside an element.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClickOutside } from 'svelora'
+ *
+ *   let open = $state(false)
+ * </script>
+ *
+ * {#if open}
+ *   <div use:useClickOutside={{ handler: () => (open = false) }}>
+ *     Dropdown content
+ *   </div>
+ * {/if}
+ * ```
+ */
+export const useClickOutside = (node, initialOptions) => {
+    let currentOptions = initialOptions;
+    function handlePointerDown(event) {
+        if (currentOptions.enabled === false)
+            return;
+        if (!node.contains(event.target)) {
+            currentOptions.handler(event);
+        }
+    }
+    document.addEventListener('pointerdown', handlePointerDown, true);
+    return {
+        update(newOptions) {
+            currentOptions = newOptions;
+        },
+        destroy() {
+            document.removeEventListener('pointerdown', handlePointerDown, true);
+        }
+    };
+};

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

@@ -0,0 +1,30 @@
+export interface UseClipboardOptions {
+    /**
+     * Duration in milliseconds before `copied` resets to `false`.
+     * @default 2000
+     */
+    timeout?: number;
+}
+export interface UseClipboardReturn {
+    /** Whether text was recently copied (resets after timeout) */
+    readonly copied: boolean;
+    /** Copy text to clipboard */
+    copy: (text: string) => Promise<void>;
+}
+/**
+ * Reactive clipboard hook. Copies text and tracks copied state.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClipboard } from 'svelora'
+ *
+ *   const clipboard = useClipboard()
+ * </script>
+ *
+ * <Button onclick={() => clipboard.copy('Hello!')}>
+ *   {clipboard.copied ? 'Copied!' : 'Copy'}
+ * </Button>
+ * ```
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

package/dist/hooks/useClipboard.svelte.js

@@ -0,0 +1,45 @@
+/**
+ * Reactive clipboard hook. Copies text and tracks copied state.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClipboard } from 'svelora'
+ *
+ *   const clipboard = useClipboard()
+ * </script>
+ *
+ * <Button onclick={() => clipboard.copy('Hello!')}>
+ *   {clipboard.copied ? 'Copied!' : 'Copy'}
+ * </Button>
+ * ```
+ */
+export function useClipboard(options = {}) {
+    const { timeout = 2000 } = options;
+    let copied = $state(false);
+    let timeoutId;
+    async function copy(text) {
+        if (typeof navigator === 'undefined' || !navigator.clipboard)
+            return;
+        try {
+            await navigator.clipboard.writeText(text);
+            copied = true;
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => {
+                copied = false;
+            }, timeout);
+        }
+        catch {
+            copied = false;
+        }
+    }
+    $effect(() => {
+        return () => clearTimeout(timeoutId);
+    });
+    return {
+        get copied() {
+            return copied;
+        },
+        copy
+    };
+}

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

@@ -0,0 +1,36 @@
+export interface UseDebounceOptions {
+    /**
+     * Delay in milliseconds before the callback is executed.
+     * @default 300
+     */
+    delay?: number;
+}
+/**
+ * Reactive debounce hook. Delays execution until a pause in calls.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useDebounce } from 'svelora'
+ *
+ *   const debounce = useDebounce({ delay: 500 })
+ *   let query = $state('')
+ *
+ *   function handleInput(e: Event) {
+ *     query = e.currentTarget.value
+ *     debounce.run(() => fetchResults(query))
+ *   }
+ * </script>
+ *
+ * <input oninput={handleInput} />
+ * {#if debounce.pending}
+ *   <Spinner />
+ * {/if}
+ * ```
+ */
+export declare function useDebounce(options?: UseDebounceOptions): {
+    readonly pending: boolean;
+    run: (callback: () => void) => void;
+    cancel: () => void;
+    flush: (callback: () => void) => void;
+};

package/dist/hooks/useDebounce.svelte.js

@@ -0,0 +1,56 @@
+/**
+ * Reactive debounce hook. Delays execution until a pause in calls.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useDebounce } from 'svelora'
+ *
+ *   const debounce = useDebounce({ delay: 500 })
+ *   let query = $state('')
+ *
+ *   function handleInput(e: Event) {
+ *     query = e.currentTarget.value
+ *     debounce.run(() => fetchResults(query))
+ *   }
+ * </script>
+ *
+ * <input oninput={handleInput} />
+ * {#if debounce.pending}
+ *   <Spinner />
+ * {/if}
+ * ```
+ */
+export function useDebounce(options = {}) {
+    const { delay = 300 } = options;
+    let pending = $state(false);
+    let timeoutId;
+    function run(callback) {
+        pending = true;
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => {
+            pending = false;
+            callback();
+        }, delay);
+    }
+    function cancel() {
+        clearTimeout(timeoutId);
+        pending = false;
+    }
+    function flush(callback) {
+        clearTimeout(timeoutId);
+        pending = false;
+        callback();
+    }
+    $effect(() => {
+        return () => clearTimeout(timeoutId);
+    });
+    return {
+        get pending() {
+            return pending;
+        },
+        run,
+        cancel,
+        flush
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { Action } from 'svelte/action';
+export interface UseEscapeKeydownOptions {
+    /**
+     * Callback fired when Escape is pressed.
+     */
+    handler: (event: KeyboardEvent) => void;
+    /**
+     * Whether the listener is active.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Svelte action that listens for Escape keydown on an element or the document.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEscapeKeydown } from 'svelora'
+ *
+ *   let open = $state(true)
+ * </script>
+ *
+ * {#if open}
+ *   <div use:useEscapeKeydown={{ handler: () => (open = false) }}>
+ *     Press Escape to close
+ *   </div>
+ * {/if}
+ * ```
+ */
+export declare const useEscapeKeydown: Action<HTMLElement, UseEscapeKeydownOptions>;

package/dist/hooks/useEscapeKeydown.svelte.js

@@ -0,0 +1,37 @@
+/**
+ * Svelte action that listens for Escape keydown on an element or the document.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEscapeKeydown } from 'svelora'
+ *
+ *   let open = $state(true)
+ * </script>
+ *
+ * {#if open}
+ *   <div use:useEscapeKeydown={{ handler: () => (open = false) }}>
+ *     Press Escape to close
+ *   </div>
+ * {/if}
+ * ```
+ */
+export const useEscapeKeydown = (_node, initialOptions) => {
+    let currentOptions = initialOptions;
+    function handleKeydown(event) {
+        if (currentOptions.enabled === false)
+            return;
+        if (event.key === 'Escape') {
+            currentOptions.handler(event);
+        }
+    }
+    document.addEventListener('keydown', handleKeydown);
+    return {
+        update(newOptions) {
+            currentOptions = newOptions;
+        },
+        destroy() {
+            document.removeEventListener('keydown', handleKeydown);
+        }
+    };
+};

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

@@ -0,0 +1,54 @@
+import type { FormFieldProps } from '../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
+ * user code or other libraries.
+ */
+export declare const FORM_FIELD_CONTEXT_KEY: unique symbol;
+export interface FormFieldContext {
+    name?: string;
+    size: NonNullable<FormFieldProps['size']>;
+    error?: string | boolean;
+    ariaId: string;
+    /** Whether input events should validate this field before first blur. */
+    eagerValidation?: boolean;
+    /** Per-field override for the input debounce delay. */
+    validateOnInputDelay?: number;
+    /** Regex pattern used to match form errors for this field (in addition to exact name). */
+    errorPattern?: RegExp;
+}
+/**
+ * Access the nearest FormField context. Returns `undefined` when used outside a FormField.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFormField } from 'svelora'
+ *
+ *   const formField = useFormField()
+ *   const hasError = $derived(formField?.error !== undefined && formField?.error !== false)
+ * </script>
+ * ```
+ */
+export declare function useFormField(): FormFieldContext | undefined;
+/**
+ * Event emitter helpers for inputs nested inside a `<FormField>` within a `<Form>`.
+ * Each returned function is a safe no-op when used outside a Form, so inputs can
+ * unconditionally wire them to their native events.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFormFieldEmit } from 'svelora'
+ *   const emit = useFormFieldEmit()
+ * </script>
+ *
+ * <input onblur={emit.onBlur} oninput={emit.onInput} onchange={emit.onChange} onfocus={emit.onFocus} />
+ * ```
+ */
+export declare function useFormFieldEmit(): {
+    onBlur(): void;
+    onFocus(): void;
+    onChange(): void;
+    onInput(): void;
+};

package/dist/hooks/useFormField.svelte.js

@@ -0,0 +1,65 @@
+import { getContext } from 'svelte';
+import { getFormContext } from '../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
+ * user code or other libraries.
+ */
+export const FORM_FIELD_CONTEXT_KEY = Symbol('svelora:form-field');
+/**
+ * Access the nearest FormField context. Returns `undefined` when used outside a FormField.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFormField } from 'svelora'
+ *
+ *   const formField = useFormField()
+ *   const hasError = $derived(formField?.error !== undefined && formField?.error !== false)
+ * </script>
+ * ```
+ */
+export function useFormField() {
+    return getContext(FORM_FIELD_CONTEXT_KEY);
+}
+/**
+ * Event emitter helpers for inputs nested inside a `<FormField>` within a `<Form>`.
+ * Each returned function is a safe no-op when used outside a Form, so inputs can
+ * unconditionally wire them to their native events.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFormFieldEmit } from 'svelora'
+ *   const emit = useFormFieldEmit()
+ * </script>
+ *
+ * <input onblur={emit.onBlur} oninput={emit.onInput} onchange={emit.onChange} onfocus={emit.onFocus} />
+ * ```
+ */
+export function useFormFieldEmit() {
+    const fieldCtx = getContext(FORM_FIELD_CONTEXT_KEY);
+    const formCtx = getFormContext();
+    return {
+        onBlur() {
+            const n = fieldCtx?.name;
+            if (n)
+                formCtx?.onBlur(n);
+        },
+        onFocus() {
+            const n = fieldCtx?.name;
+            if (n)
+                formCtx?.onFocus(n);
+        },
+        onChange() {
+            const n = fieldCtx?.name;
+            if (n)
+                formCtx?.onChange(n);
+        },
+        onInput() {
+            const n = fieldCtx?.name;
+            if (n)
+                formCtx?.onInput(n, fieldCtx?.eagerValidation);
+        }
+    };
+}

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

@@ -0,0 +1,57 @@
+import type { Action } from 'svelte/action';
+export interface UseInfiniteScrollOptions {
+    /**
+     * Callback fired when the user scrolls near the bottom.
+     * Return a promise to automatically manage the loading state.
+     */
+    onLoad: () => void | Promise<void>;
+    /**
+     * Distance in pixels from the bottom to trigger loading.
+     * @default 100
+     */
+    threshold?: number;
+    /**
+     * Whether the hook is active. Set to `false` when all data is loaded.
+     * Supports getter function for reactive control.
+     * @default true
+     */
+    enabled?: boolean | (() => boolean);
+}
+export interface UseInfiniteScrollReturn {
+    /** Whether an async onLoad is currently in progress */
+    readonly loading: boolean;
+}
+/**
+ * Reactive infinite scroll hook with Svelte action.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useInfiniteScroll } from 'svelora'
+ *
+ *   let items = $state([...])
+ *   let hasMore = $state(true)
+ *
+ *   const scroll = useInfiniteScroll({
+ *     onLoad: async () => {
+ *       const next = await fetchMore()
+ *       items.push(...next)
+ *       if (next.length === 0) hasMore = false
+ *     },
+ *     enabled: () => hasMore
+ *   })
+ * </script>
+ *
+ * <div use:scroll.action>
+ *   {#each items as item (item.id)}
+ *     <div>{item.name}</div>
+ *   {/each}
+ *   {#if scroll.loading}
+ *     <Spinner />
+ *   {/if}
+ * </div>
+ * ```
+ */
+export declare function useInfiniteScroll(options: UseInfiniteScrollOptions): UseInfiniteScrollReturn & {
+    action: Action<HTMLElement>;
+};

package/dist/hooks/useInfiniteScroll.svelte.js

@@ -0,0 +1,69 @@
+/**
+ * Reactive infinite scroll hook with Svelte action.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useInfiniteScroll } from 'svelora'
+ *
+ *   let items = $state([...])
+ *   let hasMore = $state(true)
+ *
+ *   const scroll = useInfiniteScroll({
+ *     onLoad: async () => {
+ *       const next = await fetchMore()
+ *       items.push(...next)
+ *       if (next.length === 0) hasMore = false
+ *     },
+ *     enabled: () => hasMore
+ *   })
+ * </script>
+ *
+ * <div use:scroll.action>
+ *   {#each items as item (item.id)}
+ *     <div>{item.name}</div>
+ *   {/each}
+ *   {#if scroll.loading}
+ *     <Spinner />
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function useInfiniteScroll(options) {
+    const { onLoad, threshold = 100 } = options;
+    let loading = $state(false);
+    function getEnabled() {
+        return typeof options.enabled === 'function' ? options.enabled() : (options.enabled ?? true);
+    }
+    async function check(el) {
+        if (loading || !getEnabled())
+            return;
+        const { scrollTop, scrollHeight, clientHeight } = el;
+        if (scrollHeight - scrollTop - clientHeight > threshold)
+            return;
+        loading = true;
+        try {
+            await onLoad();
+        }
+        finally {
+            loading = false;
+        }
+    }
+    const action = (node) => {
+        function handleScroll() {
+            check(node);
+        }
+        node.addEventListener('scroll', handleScroll, { passive: true });
+        return {
+            destroy() {
+                node.removeEventListener('scroll', handleScroll);
+            }
+        };
+    };
+    return {
+        get loading() {
+            return loading;
+        },
+        action
+    };
+}

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

@@ -0,0 +1,31 @@
+export interface UseMediaQueryOptions {
+    /**
+     * Initial value before the media query is evaluated (SSR-safe).
+     * @default false
+     */
+    initialValue?: boolean;
+}
+export interface UseMediaQueryReturn {
+    /** Whether the media query currently matches */
+    readonly matches: boolean;
+}
+/**
+ * Reactive media query hook. Tracks whether a CSS media query matches.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMediaQuery } from 'svelora'
+ *
+ *   const isMobile = useMediaQuery('(max-width: 640px)')
+ *   const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
+ * </script>
+ *
+ * {#if isMobile.matches}
+ *   <MobileLayout />
+ * {:else}
+ *   <DesktopLayout />
+ * {/if}
+ * ```
+ */
+export declare function useMediaQuery(query: string | (() => string), options?: UseMediaQueryOptions): UseMediaQueryReturn;

package/dist/hooks/useMediaQuery.svelte.js

@@ -0,0 +1,38 @@
+/**
+ * Reactive media query hook. Tracks whether a CSS media query matches.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useMediaQuery } from 'svelora'
+ *
+ *   const isMobile = useMediaQuery('(max-width: 640px)')
+ *   const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
+ * </script>
+ *
+ * {#if isMobile.matches}
+ *   <MobileLayout />
+ * {:else}
+ *   <DesktopLayout />
+ * {/if}
+ * ```
+ */
+export function useMediaQuery(query, options = {}) {
+    const { initialValue = false } = options;
+    const resolveQuery = typeof query === 'function' ? query : () => query;
+    let matches = $state(initialValue);
+    $effect(() => {
+        const mediaQuery = window.matchMedia(resolveQuery());
+        matches = mediaQuery.matches;
+        function handler(event) {
+            matches = event.matches;
+        }
+        mediaQuery.addEventListener('change', handler);
+        return () => mediaQuery.removeEventListener('change', handler);
+    });
+    return {
+        get matches() {
+            return matches;
+        }
+    };
+}