@classic-homes/theme-svelte 0.1.52 → 0.1.54

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

@@ -0,0 +1,92 @@
+/**
+ * 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 function useFocusRef(options = {}) {
+    let focusOnMount = $state(options.focusOnMount ?? false);
+    let preventScroll = $state(options.preventScroll ?? false);
+    let delay = $state(options.delay ?? 0);
+    let element = null;
+    let timeoutId = null;
+    let frameId = null;
+    function focus() {
+        if (element && typeof element.focus === 'function') {
+            element.focus({ preventScroll });
+        }
+    }
+    function scheduleFocus() {
+        if (!focusOnMount)
+            return;
+        if (delay > 0) {
+            timeoutId = setTimeout(focus, delay);
+        }
+        else {
+            // Use requestAnimationFrame to ensure element is rendered
+            frameId = requestAnimationFrame(focus);
+        }
+    }
+    function cleanup() {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
+        if (frameId !== null) {
+            cancelAnimationFrame(frameId);
+            frameId = null;
+        }
+    }
+    /**
+     * Svelte action to apply auto-focus to an element
+     */
+    function action(node) {
+        element = node;
+        scheduleFocus();
+        return {
+            update(newOptions) {
+                cleanup();
+                focusOnMount = newOptions.focusOnMount ?? false;
+                preventScroll = newOptions.preventScroll ?? false;
+                delay = newOptions.delay ?? 0;
+                scheduleFocus();
+            },
+            destroy() {
+                cleanup();
+                element = null;
+            },
+        };
+    }
+    /**
+     * Programmatically focus the element
+     */
+    function focusNow() {
+        focus();
+    }
+    return {
+        action,
+        focus: focusNow,
+    };
+}

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

@@ -0,0 +1,42 @@
+export interface UseFocusTrapOptions {
+    /** Whether the focus trap is active */
+    active?: boolean;
+    /** Element to return focus to when trap is deactivated */
+    returnFocusTo?: HTMLElement | null;
+    /** Selector for the element to focus initially (defaults to first focusable) */
+    initialFocus?: string;
+    /** Whether to prevent scrolling when focusing elements */
+    preventScroll?: boolean;
+}
+/**
+ * Creates a focus trap action for use with Svelte's use: directive.
+ *
+ * Traps focus within the container so Tab/Shift+Tab cycles through
+ * focusable elements without escaping. Useful for modals, dialogs,
+ * and dropdown menus.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFocusTrap } from '@classic-homes/theme-svelte';
+ *
+ *   const { action } = useFocusTrap({ active: isOpen });
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div use:action role="dialog">
+ *     <button>First</button>
+ *     <button>Second</button>
+ *     <button onclick={() => isOpen = false}>Close</button>
+ *   </div>
+ * {/if}
+ * ```
+ */
+export declare function useFocusTrap(options?: UseFocusTrapOptions): {
+    action: (node: HTMLElement) => {
+        update(newOptions: UseFocusTrapOptions): void;
+        destroy(): void;
+    };
+    activate: () => void;
+    deactivate: () => void;
+};

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

@@ -0,0 +1,136 @@
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'button:not([disabled])',
+    'iframe',
+    'object',
+    'embed',
+    '[contenteditable]',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+function getFocusableElements(container) {
+    const elements = container.querySelectorAll(FOCUSABLE_SELECTOR);
+    return Array.from(elements).filter((el) => el.offsetParent !== null && getComputedStyle(el).visibility !== 'hidden');
+}
+/**
+ * Creates a focus trap action for use with Svelte's use: directive.
+ *
+ * Traps focus within the container so Tab/Shift+Tab cycles through
+ * focusable elements without escaping. Useful for modals, dialogs,
+ * and dropdown menus.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useFocusTrap } from '@classic-homes/theme-svelte';
+ *
+ *   const { action } = useFocusTrap({ active: isOpen });
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div use:action role="dialog">
+ *     <button>First</button>
+ *     <button>Second</button>
+ *     <button onclick={() => isOpen = false}>Close</button>
+ *   </div>
+ * {/if}
+ * ```
+ */
+export function useFocusTrap(options = {}) {
+    let active = $state(options.active ?? true);
+    let returnFocusTo = $state(options.returnFocusTo ?? null);
+    let initialFocus = $state(options.initialFocus);
+    let preventScroll = $state(options.preventScroll ?? false);
+    let container = null;
+    let previousActiveElement = null;
+    function handleKeyDown(event) {
+        if (!active || event.key !== 'Tab' || !container)
+            return;
+        const focusableElements = getFocusableElements(container);
+        if (focusableElements.length === 0)
+            return;
+        const firstElement = focusableElements[0];
+        const lastElement = focusableElements[focusableElements.length - 1];
+        if (event.shiftKey) {
+            // Shift + Tab: if on first element, move to last
+            if (document.activeElement === firstElement) {
+                event.preventDefault();
+                lastElement.focus({ preventScroll });
+            }
+        }
+        else {
+            // Tab: if on last element, move to first
+            if (document.activeElement === lastElement) {
+                event.preventDefault();
+                firstElement.focus({ preventScroll });
+            }
+        }
+    }
+    function activate() {
+        if (!container)
+            return;
+        // Save current active element to return focus later
+        previousActiveElement = document.activeElement;
+        // Focus initial element
+        const focusableElements = getFocusableElements(container);
+        if (focusableElements.length > 0) {
+            let elementToFocus = null;
+            if (initialFocus) {
+                elementToFocus = container.querySelector(initialFocus);
+            }
+            if (!elementToFocus) {
+                elementToFocus = focusableElements[0];
+            }
+            requestAnimationFrame(() => {
+                elementToFocus?.focus({ preventScroll });
+            });
+        }
+        document.addEventListener('keydown', handleKeyDown);
+    }
+    function deactivate() {
+        document.removeEventListener('keydown', handleKeyDown);
+        // Return focus when trap is deactivated
+        const elementToReturn = returnFocusTo ?? previousActiveElement;
+        if (elementToReturn && typeof elementToReturn.focus === 'function') {
+            elementToReturn.focus({ preventScroll });
+        }
+    }
+    /**
+     * Svelte action to apply focus trap to an element
+     */
+    function action(node) {
+        container = node;
+        if (active) {
+            activate();
+        }
+        return {
+            update(newOptions) {
+                const wasActive = active;
+                active = newOptions.active ?? true;
+                returnFocusTo = newOptions.returnFocusTo ?? null;
+                initialFocus = newOptions.initialFocus;
+                preventScroll = newOptions.preventScroll ?? false;
+                if (!wasActive && active) {
+                    activate();
+                }
+                else if (wasActive && !active) {
+                    deactivate();
+                }
+            },
+            destroy() {
+                if (active) {
+                    deactivate();
+                }
+                container = null;
+            },
+        };
+    }
+    return {
+        action,
+        activate,
+        deactivate,
+    };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Composable to detect user's reduced motion preference from system settings.
+ *
+ * Responds to the CSS media query `prefers-reduced-motion: reduce` which users
+ * can set in their operating system accessibility settings to indicate they
+ * prefer minimal motion/animation.
+ *
+ * Use this composable to disable or reduce animations for users who have this preference,
+ * which is important for accessibility (vestibular disorders, motion sensitivity, etc.).
+ *
+ * @returns Object with reactive `value` property - true if user prefers reduced motion
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useReducedMotion } from '@classic-homes/theme-svelte';
+ *
+ *   const reducedMotion = useReducedMotion();
+ * </script>
+ *
+ * <div
+ *   style:transition={$reducedMotion.value ? 'none' : 'transform 0.3s ease'}
+ * >
+ *   Content
+ * </div>
+ * ```
+ *
+ * @example with svelte/motion
+ * ```svelte
+ * <script>
+ *   import { fly } from 'svelte/transition';
+ *   import { useReducedMotion } from '@classic-homes/theme-svelte';
+ *
+ *   const reducedMotion = useReducedMotion();
+ *   const duration = $derived(reducedMotion.value ? 0 : 300);
+ * </script>
+ *
+ * <div
+ *   in:fly={{ y: reducedMotion.value ? 0 : 20, duration }}
+ * >
+ *   Content
+ * </div>
+ * ```
+ */
+export declare function useReducedMotion(): {
+    readonly value: boolean;
+};

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

@@ -0,0 +1,67 @@
+/**
+ * Composable to detect user's reduced motion preference from system settings.
+ *
+ * Responds to the CSS media query `prefers-reduced-motion: reduce` which users
+ * can set in their operating system accessibility settings to indicate they
+ * prefer minimal motion/animation.
+ *
+ * Use this composable to disable or reduce animations for users who have this preference,
+ * which is important for accessibility (vestibular disorders, motion sensitivity, etc.).
+ *
+ * @returns Object with reactive `value` property - true if user prefers reduced motion
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useReducedMotion } from '@classic-homes/theme-svelte';
+ *
+ *   const reducedMotion = useReducedMotion();
+ * </script>
+ *
+ * <div
+ *   style:transition={$reducedMotion.value ? 'none' : 'transform 0.3s ease'}
+ * >
+ *   Content
+ * </div>
+ * ```
+ *
+ * @example with svelte/motion
+ * ```svelte
+ * <script>
+ *   import { fly } from 'svelte/transition';
+ *   import { useReducedMotion } from '@classic-homes/theme-svelte';
+ *
+ *   const reducedMotion = useReducedMotion();
+ *   const duration = $derived(reducedMotion.value ? 0 : 300);
+ * </script>
+ *
+ * <div
+ *   in:fly={{ y: reducedMotion.value ? 0 : 20, duration }}
+ * >
+ *   Content
+ * </div>
+ * ```
+ */
+export function useReducedMotion() {
+    let reducedMotion = $state(false);
+    $effect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+        // Set initial value
+        reducedMotion = mediaQuery.matches;
+        // Listen for changes
+        const handleChange = (event) => {
+            reducedMotion = event.matches;
+        };
+        mediaQuery.addEventListener('change', handleChange);
+        return () => {
+            mediaQuery.removeEventListener('change', handleChange);
+        };
+    });
+    return {
+        get value() {
+            return reducedMotion;
+        },
+    };
+}

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

@@ -0,0 +1,54 @@
+export interface UseRovingTabindexOptions {
+    /** Whether navigation wraps from end to start */
+    loop?: boolean;
+    /** Selector for focusable items */
+    itemSelector?: string;
+    /** Initial focused index */
+    initialIndex?: number;
+    /** Callback when active index changes */
+    onIndexChange?: (index: number) => void;
+}
+/**
+ * Composable implementing roving tabindex pattern for composite widgets.
+ *
+ * Only one item in the group has tabindex="0" at a time, while
+ * others have tabindex="-1". Arrow keys move focus within the group.
+ *
+ * This is the recommended pattern for widgets like toolbars, menus,
+ * listboxes, tree views, and tabs.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useRovingTabindex } from '@classic-homes/theme-svelte';
+ *
+ *   const roving = useRovingTabindex();
+ * </script>
+ *
+ * <div role="toolbar" use:roving.action>
+ *   {#each tools as tool, i}
+ *     <button
+ *       data-roving-tabindex-item
+ *       tabindex={roving.activeIndex === i ? 0 : -1}
+ *       on:click={() => roving.setActiveIndex(i)}
+ *     >
+ *       {tool.label}
+ *     </button>
+ *   {/each}
+ * </div>
+ * ```
+ */
+export declare function useRovingTabindex(options?: UseRovingTabindexOptions): {
+    action: (node: HTMLElement) => {
+        update(newOptions: UseRovingTabindexOptions): void;
+        destroy(): void;
+    };
+    readonly activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    focusNext: () => void;
+    focusPrevious: () => void;
+    focusFirst: () => void;
+    focusLast: () => void;
+};

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

@@ -0,0 +1,128 @@
+const DEFAULT_SELECTOR = '[data-roving-tabindex-item]';
+/**
+ * Composable implementing roving tabindex pattern for composite widgets.
+ *
+ * Only one item in the group has tabindex="0" at a time, while
+ * others have tabindex="-1". Arrow keys move focus within the group.
+ *
+ * This is the recommended pattern for widgets like toolbars, menus,
+ * listboxes, tree views, and tabs.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useRovingTabindex } from '@classic-homes/theme-svelte';
+ *
+ *   const roving = useRovingTabindex();
+ * </script>
+ *
+ * <div role="toolbar" use:roving.action>
+ *   {#each tools as tool, i}
+ *     <button
+ *       data-roving-tabindex-item
+ *       tabindex={roving.activeIndex === i ? 0 : -1}
+ *       on:click={() => roving.setActiveIndex(i)}
+ *     >
+ *       {tool.label}
+ *     </button>
+ *   {/each}
+ * </div>
+ * ```
+ */
+export function useRovingTabindex(options = {}) {
+    let loop = $state(options.loop ?? true);
+    let itemSelector = $state(options.itemSelector ?? DEFAULT_SELECTOR);
+    let activeIndex = $state(options.initialIndex ?? 0);
+    let onIndexChange = $state(options.onIndexChange);
+    let container = null;
+    function getItems() {
+        if (!container)
+            return [];
+        return Array.from(container.querySelectorAll(itemSelector));
+    }
+    function focusIndex(index) {
+        const items = getItems();
+        if (items.length === 0)
+            return;
+        let targetIndex = index;
+        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));
+        }
+        activeIndex = targetIndex;
+        onIndexChange?.(targetIndex);
+        const element = items[targetIndex];
+        if (element) {
+            element.focus();
+        }
+    }
+    function handleKeyDown(event) {
+        const items = getItems();
+        if (items.length === 0)
+            return;
+        let handled = false;
+        switch (event.key) {
+            case 'ArrowUp':
+            case 'ArrowLeft':
+                focusIndex(activeIndex - 1);
+                handled = true;
+                break;
+            case 'ArrowDown':
+            case 'ArrowRight':
+                focusIndex(activeIndex + 1);
+                handled = true;
+                break;
+            case 'Home':
+                focusIndex(0);
+                handled = true;
+                break;
+            case 'End':
+                focusIndex(items.length - 1);
+                handled = true;
+                break;
+        }
+        if (handled) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    }
+    /**
+     * Svelte action to apply roving tabindex to a container
+     */
+    function action(node) {
+        container = node;
+        node.addEventListener('keydown', handleKeyDown);
+        return {
+            update(newOptions) {
+                loop = newOptions.loop ?? true;
+                itemSelector = newOptions.itemSelector ?? DEFAULT_SELECTOR;
+                if (newOptions.initialIndex !== undefined && newOptions.initialIndex !== activeIndex) {
+                    activeIndex = newOptions.initialIndex;
+                }
+                onIndexChange = newOptions.onIndexChange;
+            },
+            destroy() {
+                node.removeEventListener('keydown', handleKeyDown);
+                container = null;
+            },
+        };
+    }
+    return {
+        action,
+        get activeIndex() {
+            return activeIndex;
+        },
+        setActiveIndex: focusIndex,
+        focusNext: () => focusIndex(activeIndex + 1),
+        focusPrevious: () => focusIndex(activeIndex - 1),
+        focusFirst: () => focusIndex(0),
+        focusLast: () => focusIndex(getItems().length - 1),
+    };
+}

package/dist/lib/index.d.ts

@@ -29,6 +29,12 @@ export { default as Spinner } from './components/Spinner.svelte';
 export { default as Skeleton } from './components/Skeleton.svelte';
 export { default as Toast } from './components/Toast.svelte';
 export { default as ToastContainer } from './components/ToastContainer.svelte';
+export { default as ProgressBar } from './components/ProgressBar.svelte';
+export { default as LoadingOverlay } from './components/LoadingOverlay.svelte';
+export { default as LoadingPage } from './components/LoadingPage.svelte';
+export { default as LoadingSection } from './components/LoadingSection.svelte';
+export { default as LiveRegion } from './components/LiveRegion.svelte';
+export { default as SkipLink } from './components/SkipLink.svelte';
 export { default as Dialog } from './components/Dialog.svelte';
 export { default as AlertDialog } from './components/AlertDialog.svelte';
 export { default as Tooltip } from './components/Tooltip.svelte';
@@ -85,6 +91,6 @@ export { generateId, computeDescribedBy } from './utils/form.js';
 export { tv, type VariantProps } from 'tailwind-variants';
 export { validateNonEmptyArray, validateRequired, validateOneOf, validateRange, validateProps, createValidator, type ValidationResult, } from './validation.js';
 export { perfStart, perfEnd, measure, measureAsync, getPerformanceEntries, clearPerformanceEntries, createPerfMonitor, type PerformanceMark, } from './performance.js';
-export { useForm, useAsync, runAsync, usePersistedForm, type UseFormOptions, type UseFormReturn, type FieldError, type FormState, type InferFormData, type UseAsyncOptions, type UseAsyncReturn, type UsePersistedFormOptions, type UsePersistedFormReturn, type InferPersistedFormData, } from './composables/index.js';
+export { useForm, useAsync, runAsync, usePersistedForm, useFocusTrap, useFocusRef, useReducedMotion, useArrowNavigation, useRovingTabindex, useAnnounce, useEscapeKey, useClickOutside, clickOutsideAction, type UseFormOptions, type UseFormReturn, type FieldError, type FormState, type InferFormData, type UseAsyncOptions, type UseAsyncReturn, type UsePersistedFormOptions, type UsePersistedFormReturn, type InferPersistedFormData, type UseFocusTrapOptions, type UseFocusRefOptions, type UseArrowNavigationOptions, type ArrowNavigationOrientation, type UseRovingTabindexOptions, type UseAnnounceOptions, type UseAnnounceReturn, type UseEscapeKeyOptions, type UseClickOutsideOptions, } from './composables/index.js';
 export * from './schemas/index.js';
 export { type Notice, type NoticeConfig, type NoticeLocation, type NoticeVariant, type NoticePage, type ActiveNotice, NoticeSchema, NoticeLinkSchema, validateNotice, validateNotices, initializeNotices, setCurrentPath, dismissNotice, clearDismissedNotices, isNoticeDismissed, activeNotices, bannerNotices, cardNotices, getNoticesForPage, refreshNotices, cleanupDismissedNotices, isNoticeActive, isNoticeForPage, isNoticeForLocation, sanitizeHtml, initSanitizer, NoticeBanner, NoticeCard, } from './notices/index.js';

package/dist/lib/index.js

@@ -34,6 +34,14 @@ export { default as Spinner } from './components/Spinner.svelte';
 export { default as Skeleton } from './components/Skeleton.svelte';
 export { default as Toast } from './components/Toast.svelte';
 export { default as ToastContainer } from './components/ToastContainer.svelte';
+// Loading Components
+export { default as ProgressBar } from './components/ProgressBar.svelte';
+export { default as LoadingOverlay } from './components/LoadingOverlay.svelte';
+export { default as LoadingPage } from './components/LoadingPage.svelte';
+export { default as LoadingSection } from './components/LoadingSection.svelte';
+// Accessibility Components
+export { default as LiveRegion } from './components/LiveRegion.svelte';
+export { default as SkipLink } from './components/SkipLink.svelte';
 // Overlay Components (using Bits UI)
 export { default as Dialog } from './components/Dialog.svelte';
 export { default as AlertDialog } from './components/AlertDialog.svelte';
@@ -112,7 +120,9 @@ export { validateNonEmptyArray, validateRequired, validateOneOf, validateRange,
 // Performance monitoring utilities (dev-only, tree-shaken in production)
 export { perfStart, perfEnd, measure, measureAsync, getPerformanceEntries, clearPerformanceEntries, createPerfMonitor, } from './performance.js';
 // Composables - reusable Svelte 5 state management patterns
-export { useForm, useAsync, runAsync, usePersistedForm, } from './composables/index.js';
+export { useForm, useAsync, runAsync, usePersistedForm, 
+// Accessibility composables
+useFocusTrap, useFocusRef, useReducedMotion, useArrowNavigation, useRovingTabindex, useAnnounce, useEscapeKey, useClickOutside, clickOutsideAction, } from './composables/index.js';
 // Validation schemas - Zod schemas for forms and data validation
 export * from './schemas/index.js';
 // Notice System - Scheduled, page-specific, dismissible announcements

package/dist/lib/stores/theme.svelte.d.ts

@@ -30,7 +30,7 @@ declare class ThemeStore {
     /** Current theme mode setting (light, dark, or system) */
     mode: ThemeMode;
     /** Resolved theme (accounts for system preference when mode is 'system') */
-    resolvedTheme: "dark" | "light";
+    resolvedTheme: "light" | "dark";
     /** Whether we're on the client (not SSR) */
     private isClient;
     /** Media query for system dark mode preference */

package/dist/lib/utils.d.ts

@@ -6,9 +6,11 @@ import { type ClassValue } from 'clsx';
 export declare function cn(...inputs: ClassValue[]): string;
 /**
  * Generate a unique ID with an optional prefix.
- * IDs are sequential and stable, preventing SSR hydration mismatches.
+ * Uses crypto.randomUUID() to avoid SSR hydration mismatches caused by
+ * sequential counters (where server and client counts can diverge).
+ * The short suffix is derived from the UUID for compact, readable IDs.
  *
  * @param prefix - Optional prefix for the ID (e.g., 'checkbox', 'tabs')
- * @returns A unique ID string like 'checkbox-1' or 'ct-1' (ct = classic-theme)
+ * @returns A unique ID string like 'checkbox-a1b2c3d4' or 'ct-a1b2c3d4'
  */
 export declare function useId(prefix?: string): string;

package/dist/lib/utils.js

@@ -7,22 +7,16 @@ import { twMerge } from 'tailwind-merge';
 export function cn(...inputs) {
     return twMerge(clsx(inputs));
 }
-/**
- * Counter for generating unique sequential IDs.
- * Uses a sequential counter instead of Math.random() to ensure:
- * - Deterministic IDs that match between SSR and hydration
- * - Stable IDs across component re-renders
- * - Accessibility-friendly ID associations
- */
-let idCounter = 0;
 /**
  * Generate a unique ID with an optional prefix.
- * IDs are sequential and stable, preventing SSR hydration mismatches.
+ * Uses crypto.randomUUID() to avoid SSR hydration mismatches caused by
+ * sequential counters (where server and client counts can diverge).
+ * The short suffix is derived from the UUID for compact, readable IDs.
  *
  * @param prefix - Optional prefix for the ID (e.g., 'checkbox', 'tabs')
- * @returns A unique ID string like 'checkbox-1' or 'ct-1' (ct = classic-theme)
+ * @returns A unique ID string like 'checkbox-a1b2c3d4' or 'ct-a1b2c3d4'
  */
 export function useId(prefix) {
-    const id = ++idCounter;
+    const id = crypto.randomUUID().slice(0, 8);
     return prefix ? `${prefix}-${id}` : `ct-${id}`;
 }