@classic-homes/theme-svelte 0.1.52 → 0.1.54

package/dist/lib/composables/useAnnounce.svelte.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Options for the useAnnounce composable
+ */
+export interface UseAnnounceOptions {
+    /**
+     * Politeness level for the announcement.
+     * - 'polite': Waits for the user to be idle before announcing (default)
+     * - 'assertive': Interrupts the user immediately
+     */
+    politeness?: 'polite' | 'assertive';
+    /**
+     * Delay in milliseconds before clearing the announcement.
+     * Set to 0 to never auto-clear. Default is 1000ms.
+     */
+    clearDelay?: number;
+}
+/**
+ * Return type for useAnnounce composable
+ */
+export interface UseAnnounceReturn {
+    /**
+     * Function to make an announcement to screen readers
+     */
+    announce: (message: string, options?: UseAnnounceOptions) => void;
+    /**
+     * Current announcement message (for rendering in a live region)
+     */
+    readonly message: string;
+    /**
+     * Current politeness level
+     */
+    readonly politeness: 'polite' | 'assertive';
+    /**
+     * Clear the current announcement
+     */
+    clear: () => void;
+}
+/**
+ * useAnnounce - Composable for imperative screen reader announcements
+ *
+ * Creates reactive state that can be used with a live region to announce
+ * dynamic content to screen reader users. Useful for status updates,
+ * form validation, and other dynamic content changes.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA22
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useAnnounce } from '@classic-homes/theme-svelte';
+ *   import LiveRegion from './LiveRegion.svelte';
+ *
+ *   const { announce, message, politeness } = useAnnounce();
+ *
+ *   async function handleSave() {
+ *     await saveData();
+ *     announce('Data saved successfully');
+ *   }
+ * </script>
+ *
+ * <button onclick={handleSave}>Save</button>
+ * <LiveRegion message={message} politeness={politeness} />
+ * ```
+ */
+export declare function useAnnounce(defaultOptions?: UseAnnounceOptions): UseAnnounceReturn;

package/dist/lib/composables/useAnnounce.svelte.js

@@ -0,0 +1,76 @@
+/**
+ * useAnnounce - Composable for imperative screen reader announcements
+ *
+ * Creates reactive state that can be used with a live region to announce
+ * dynamic content to screen reader users. Useful for status updates,
+ * form validation, and other dynamic content changes.
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA22
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useAnnounce } from '@classic-homes/theme-svelte';
+ *   import LiveRegion from './LiveRegion.svelte';
+ *
+ *   const { announce, message, politeness } = useAnnounce();
+ *
+ *   async function handleSave() {
+ *     await saveData();
+ *     announce('Data saved successfully');
+ *   }
+ * </script>
+ *
+ * <button onclick={handleSave}>Save</button>
+ * <LiveRegion message={message} politeness={politeness} />
+ * ```
+ */
+export function useAnnounce(defaultOptions) {
+    let message = $state('');
+    let politeness = $state(defaultOptions?.politeness ?? 'polite');
+    let clearTimeout = null;
+    function clear() {
+        message = '';
+        if (clearTimeout) {
+            globalThis.clearTimeout(clearTimeout);
+            clearTimeout = null;
+        }
+    }
+    function announce(newMessage, options) {
+        // Clear any pending timeout
+        if (clearTimeout) {
+            globalThis.clearTimeout(clearTimeout);
+        }
+        // Update politeness if provided
+        if (options?.politeness) {
+            politeness = options.politeness;
+        }
+        // Set the new message
+        message = newMessage;
+        // Set up auto-clear if delay > 0
+        const delay = options?.clearDelay ?? defaultOptions?.clearDelay ?? 1000;
+        if (delay > 0) {
+            clearTimeout = globalThis.setTimeout(() => {
+                message = '';
+            }, delay);
+        }
+    }
+    // Cleanup on destroy
+    $effect(() => {
+        return () => {
+            if (clearTimeout) {
+                globalThis.clearTimeout(clearTimeout);
+            }
+        };
+    });
+    return {
+        announce,
+        get message() {
+            return message;
+        },
+        get politeness() {
+            return politeness;
+        },
+        clear,
+    };
+}

package/dist/lib/composables/useArrowNavigation.svelte.d.ts

@@ -0,0 +1,42 @@
+export type ArrowNavigationOrientation = 'horizontal' | 'vertical' | 'both';
+export interface UseArrowNavigationOptions {
+    /** Navigation orientation - determines which arrow keys work */
+    orientation?: ArrowNavigationOrientation;
+    /** Whether navigation wraps from end to start (and vice versa) */
+    loop?: boolean;
+    /** Selector for focusable items within the container */
+    itemSelector?: string;
+    /** Callback when focus changes */
+    onFocusChange?: (index: number, element: HTMLElement) => void;
+}
+/**
+ * Composable for arrow key navigation within a container of items.
+ *
+ * Implements keyboard navigation patterns for menus, listboxes, tabs,
+ * and other composite widgets per WAI-ARIA Authoring Practices.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useArrowNavigation } from '@classic-homes/theme-svelte';
+ *
+ *   const nav = useArrowNavigation({ orientation: 'vertical', loop: true });
+ * </script>
+ *
+ * <ul use:nav.action role="menu">
+ *   {#each items as item, i}
+ *     <li role="menuitem" tabindex={i === 0 ? 0 : -1}>
+ *       {item.label}
+ *     </li>
+ *   {/each}
+ * </ul>
+ * ```
+ */
+export declare function useArrowNavigation(options?: UseArrowNavigationOptions): {
+    action: (node: HTMLElement) => {
+        update(newOptions: UseArrowNavigationOptions): void;
+        destroy(): void;
+    };
+    focusItem: (index: number) => void;
+    readonly focusedIndex: number;
+};

package/dist/lib/composables/useArrowNavigation.svelte.js

@@ -0,0 +1,138 @@
+const DEFAULT_SELECTOR = '[role="menuitem"], [role="option"], [role="tab"], button, a, [tabindex]:not([tabindex="-1"])';
+/**
+ * Composable for arrow key navigation within a container of items.
+ *
+ * Implements keyboard navigation patterns for menus, listboxes, tabs,
+ * and other composite widgets per WAI-ARIA Authoring Practices.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useArrowNavigation } from '@classic-homes/theme-svelte';
+ *
+ *   const nav = useArrowNavigation({ orientation: 'vertical', loop: true });
+ * </script>
+ *
+ * <ul use:nav.action role="menu">
+ *   {#each items as item, i}
+ *     <li role="menuitem" tabindex={i === 0 ? 0 : -1}>
+ *       {item.label}
+ *     </li>
+ *   {/each}
+ * </ul>
+ * ```
+ */
+export function useArrowNavigation(options = {}) {
+    let orientation = $state(options.orientation ?? 'vertical');
+    let loop = $state(options.loop ?? true);
+    let itemSelector = $state(options.itemSelector ?? DEFAULT_SELECTOR);
+    let onFocusChange = $state(options.onFocusChange);
+    let container = null;
+    let focusedIndex = $state(-1);
+    function getFocusableItems() {
+        if (!container)
+            return [];
+        return Array.from(container.querySelectorAll(itemSelector));
+    }
+    function focusItem(index) {
+        const items = getFocusableItems();
+        if (items.length === 0)
+            return;
+        let targetIndex = index;
+        // Handle wrapping
+        if (loop) {
+            if (targetIndex < 0)
+                targetIndex = items.length - 1;
+            if (targetIndex >= items.length)
+                targetIndex = 0;
+        }
+        else {
+            targetIndex = Math.max(0, Math.min(targetIndex, items.length - 1));
+        }
+        const element = items[targetIndex];
+        if (element) {
+            element.focus();
+            focusedIndex = targetIndex;
+            onFocusChange?.(targetIndex, element);
+        }
+    }
+    function handleKeyDown(event) {
+        const items = getFocusableItems();
+        if (items.length === 0)
+            return;
+        let handled = false;
+        switch (event.key) {
+            case 'ArrowUp':
+                if (orientation === 'vertical' || orientation === 'both') {
+                    focusItem(focusedIndex - 1);
+                    handled = true;
+                }
+                break;
+            case 'ArrowDown':
+                if (orientation === 'vertical' || orientation === 'both') {
+                    focusItem(focusedIndex + 1);
+                    handled = true;
+                }
+                break;
+            case 'ArrowLeft':
+                if (orientation === 'horizontal' || orientation === 'both') {
+                    focusItem(focusedIndex - 1);
+                    handled = true;
+                }
+                break;
+            case 'ArrowRight':
+                if (orientation === 'horizontal' || orientation === 'both') {
+                    focusItem(focusedIndex + 1);
+                    handled = true;
+                }
+                break;
+            case 'Home':
+                focusItem(0);
+                handled = true;
+                break;
+            case 'End':
+                focusItem(items.length - 1);
+                handled = true;
+                break;
+        }
+        if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    }
+    function handleFocus(event) {
+        const items = getFocusableItems();
+        const index = items.indexOf(event.target);
+        if (index !== -1) {
+            focusedIndex = index;
+        }
+    }
+    /**
+     * Svelte action to apply arrow navigation to a container
+     */
+    function action(node) {
+        container = node;
+        node.addEventListener('keydown', handleKeyDown);
+        node.addEventListener('focusin', handleFocus);
+        return {
+            update(newOptions) {
+                orientation = newOptions.orientation ?? 'vertical';
+                loop = newOptions.loop ?? true;
+                itemSelector = newOptions.itemSelector ?? DEFAULT_SELECTOR;
+                onFocusChange = newOptions.onFocusChange;
+            },
+            destroy() {
+                node.removeEventListener('keydown', handleKeyDown);
+                node.removeEventListener('focusin', handleFocus);
+                container = null;
+            },
+        };
+    }
+    return {
+        action,
+        focusItem,
+        get focusedIndex() {
+            return focusedIndex;
+        },
+    };
+}

package/dist/lib/composables/useClickOutside.svelte.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Options for the useClickOutside composable
+ */
+export interface UseClickOutsideOptions {
+    /**
+     * Whether the click outside handler is enabled.
+     * Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Event types to listen for.
+     * Default: ['mousedown', 'touchstart']
+     */
+    events?: ('mousedown' | 'mouseup' | 'touchstart' | 'touchend')[];
+    /**
+     * Additional elements that should be considered as "inside" even if not descendants.
+     * Useful for portaled elements like tooltips or dropdowns.
+     */
+    ignoreElements?: HTMLElement[];
+}
+/**
+ * useClickOutside - Composable for detecting clicks outside an element
+ *
+ * Useful for closing dropdowns, dialogs, and other overlay components
+ * when clicking outside of them.
+ *
+ * Accessibility note: This composable should be used in conjunction with
+ * keyboard escape handling for full accessibility. Users should be
+ * able to close overlays with both mouse clicks and the Escape key.
+ *
+ * @see useEscapeKey
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClickOutside, useEscapeKey } from '@classic-homes/theme-svelte';
+ *
+ *   let { isOpen = $bindable() } = $props();
+ *   let contentRef: HTMLDivElement;
+ *
+ *   function close() {
+ *     isOpen = false;
+ *   }
+ *
+ *   // Using $effect to set up handlers with the element reference
+ *   $effect(() => {
+ *     if (isOpen && contentRef) {
+ *       return useClickOutside(contentRef, close);
+ *     }
+ *   });
+ *
+ *   useEscapeKey(close, { enabled: isOpen });
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div bind:this={contentRef}>Dropdown content</div>
+ * {/if}
+ * ```
+ *
+ * @example Action-based usage
+ * ```svelte
+ * <script>
+ *   import { clickOutsideAction } from '@classic-homes/theme-svelte';
+ *
+ *   let isOpen = $state(true);
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div use:clickOutsideAction={() => isOpen = false}>
+ *     Dropdown content
+ *   </div>
+ * {/if}
+ * ```
+ */
+export declare function useClickOutside(element: HTMLElement, callback: (event: MouseEvent | TouchEvent) => void, options?: UseClickOutsideOptions): () => void;
+/**
+ * Svelte action for click outside detection.
+ *
+ * @example
+ * ```svelte
+ * <div use:clickOutsideAction={() => isOpen = false}>
+ *   Content
+ * </div>
+ * ```
+ */
+export declare function clickOutsideAction(node: HTMLElement, callback: (event: MouseEvent | TouchEvent) => void): {
+    destroy: () => void;
+};

package/dist/lib/composables/useClickOutside.svelte.js

@@ -0,0 +1,100 @@
+/**
+ * useClickOutside - Composable for detecting clicks outside an element
+ *
+ * Useful for closing dropdowns, dialogs, and other overlay components
+ * when clicking outside of them.
+ *
+ * Accessibility note: This composable should be used in conjunction with
+ * keyboard escape handling for full accessibility. Users should be
+ * able to close overlays with both mouse clicks and the Escape key.
+ *
+ * @see useEscapeKey
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useClickOutside, useEscapeKey } from '@classic-homes/theme-svelte';
+ *
+ *   let { isOpen = $bindable() } = $props();
+ *   let contentRef: HTMLDivElement;
+ *
+ *   function close() {
+ *     isOpen = false;
+ *   }
+ *
+ *   // Using $effect to set up handlers with the element reference
+ *   $effect(() => {
+ *     if (isOpen && contentRef) {
+ *       return useClickOutside(contentRef, close);
+ *     }
+ *   });
+ *
+ *   useEscapeKey(close, { enabled: isOpen });
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div bind:this={contentRef}>Dropdown content</div>
+ * {/if}
+ * ```
+ *
+ * @example Action-based usage
+ * ```svelte
+ * <script>
+ *   import { clickOutsideAction } from '@classic-homes/theme-svelte';
+ *
+ *   let isOpen = $state(true);
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div use:clickOutsideAction={() => isOpen = false}>
+ *     Dropdown content
+ *   </div>
+ * {/if}
+ * ```
+ */
+export function useClickOutside(element, callback, options) {
+    const { enabled = true, events = ['mousedown', 'touchstart'], ignoreElements = [], } = options ?? {};
+    if (!enabled) {
+        return () => { };
+    }
+    function handleEvent(event) {
+        const target = event.target;
+        // Check if click is inside the main element
+        if (element.contains(target)) {
+            return;
+        }
+        // Check if click is inside any of the ignored elements
+        for (const ignoreEl of ignoreElements) {
+            if (ignoreEl?.contains(target)) {
+                return;
+            }
+        }
+        callback(event);
+    }
+    // Add event listeners
+    events.forEach((eventType) => {
+        document.addEventListener(eventType, handleEvent);
+    });
+    // Return cleanup function
+    return () => {
+        events.forEach((eventType) => {
+            document.removeEventListener(eventType, handleEvent);
+        });
+    };
+}
+/**
+ * Svelte action for click outside detection.
+ *
+ * @example
+ * ```svelte
+ * <div use:clickOutsideAction={() => isOpen = false}>
+ *   Content
+ * </div>
+ * ```
+ */
+export function clickOutsideAction(node, callback) {
+    const cleanup = useClickOutside(node, callback);
+    return {
+        destroy: cleanup,
+    };
+}

package/dist/lib/composables/useEscapeKey.svelte.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Options for the useEscapeKey composable
+ */
+export interface UseEscapeKeyOptions {
+    /**
+     * Whether the escape key handler is enabled.
+     * Useful for conditionally enabling based on component state (e.g., dialog open).
+     * Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to prevent default behavior when Escape is pressed.
+     * Default: true
+     */
+    preventDefault?: boolean;
+    /**
+     * Whether to stop propagation when Escape is pressed.
+     * Default: false
+     */
+    stopPropagation?: boolean;
+}
+/**
+ * useEscapeKey - Composable for handling Escape key press
+ *
+ * Registers a global keydown listener for the Escape key.
+ * Useful for closing modals, dialogs, dropdowns, etc.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEscapeKey } from '@classic-homes/theme-svelte';
+ *
+ *   let { isOpen = $bindable(), onClose } = $props();
+ *
+ *   useEscapeKey(() => {
+ *     isOpen = false;
+ *     onClose?.();
+ *   }, { enabled: isOpen });
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div>Modal content</div>
+ * {/if}
+ * ```
+ */
+export declare function useEscapeKey(callback: (event: KeyboardEvent) => void, options?: UseEscapeKeyOptions): void;

package/dist/lib/composables/useEscapeKey.svelte.js

@@ -0,0 +1,50 @@
+/**
+ * useEscapeKey - Composable for handling Escape key press
+ *
+ * Registers a global keydown listener for the Escape key.
+ * Useful for closing modals, dialogs, dropdowns, etc.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useEscapeKey } from '@classic-homes/theme-svelte';
+ *
+ *   let { isOpen = $bindable(), onClose } = $props();
+ *
+ *   useEscapeKey(() => {
+ *     isOpen = false;
+ *     onClose?.();
+ *   }, { enabled: isOpen });
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div>Modal content</div>
+ * {/if}
+ * ```
+ */
+export function useEscapeKey(callback, options) {
+    const enabled = $derived(options?.enabled ?? true);
+    const preventDefault = options?.preventDefault ?? true;
+    const stopPropagation = options?.stopPropagation ?? false;
+    $effect(() => {
+        if (!enabled)
+            return;
+        function handleKeyDown(event) {
+            if (event.key === 'Escape') {
+                if (preventDefault) {
+                    event.preventDefault();
+                }
+                if (stopPropagation) {
+                    event.stopPropagation();
+                }
+                callback(event);
+            }
+        }
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    });
+}

package/dist/lib/composables/useFocusRef.svelte.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Options for the useFocusRef composable
+ */
+export interface UseFocusRefOptions {
+    /** Whether to focus the element on mount */
+    focusOnMount?: boolean;
+    /** Whether to prevent scroll when focusing */
+    preventScroll?: boolean;
+    /** Delay in ms before focusing (useful for animations) */
+    delay?: number;
+}
+/**
+ * Creates a focus action for use with Svelte's use: directive.
+ *
+ * Useful for focusing form fields, dialog close buttons, or other
+ * elements that should receive focus when they appear.
+ *
+ * @example Basic usage
+ * ```svelte
+ * <script>
+ *   import { useFocusRef } from '@classic-homes/theme-svelte';
+ *
+ *   const { action } = useFocusRef({ focusOnMount: true });
+ * </script>
+ *
+ * <input use:action type="search" />
+ * ```
+ *
+ * @example With delay (for animations)
+ * ```svelte
+ * <script>
+ *   import { useFocusRef } from '@classic-homes/theme-svelte';
+ *
+ *   const { action } = useFocusRef({ focusOnMount: true, delay: 200 });
+ * </script>
+ *
+ * <button use:action>Close</button>
+ * ```
+ */
+export declare function useFocusRef(options?: UseFocusRefOptions): {
+    action: (node: HTMLElement) => {
+        update(newOptions: UseFocusRefOptions): void;
+        destroy(): void;
+    };
+    focus: () => void;
+};