@object-ui/react 0.5.0 → 3.0.0

package/dist/hooks/useETagCache.js

@@ -0,0 +1,306 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULTS = {
+    enabled: true,
+    storage: 'memory',
+    storagePrefix: 'oui-etag',
+    maxEntries: 1000,
+    ttl: 3600000, // 1 hour
+    useServiceWorker: false,
+    serviceWorkerUrl: '/service-worker.js',
+};
+// ---------------------------------------------------------------------------
+// LRU cache implementation (module-scoped, shared across instances)
+// ---------------------------------------------------------------------------
+const memoryCache = new Map();
+/** Access order tracking for LRU eviction — most recently used at the end. */
+const accessOrder = [];
+function touchAccessOrder(url) {
+    const idx = accessOrder.indexOf(url);
+    if (idx !== -1)
+        accessOrder.splice(idx, 1);
+    accessOrder.push(url);
+}
+function evictLRU(maxEntries) {
+    while (memoryCache.size > maxEntries && accessOrder.length > 0) {
+        const oldest = accessOrder.shift();
+        if (oldest)
+            memoryCache.delete(oldest);
+    }
+}
+// ---------------------------------------------------------------------------
+// localStorage helpers (SSR-safe)
+// ---------------------------------------------------------------------------
+function loadFromLocalStorage(prefix) {
+    if (typeof localStorage === 'undefined')
+        return new Map();
+    const entries = new Map();
+    try {
+        const raw = localStorage.getItem(`${prefix}:index`);
+        if (!raw)
+            return entries;
+        const keys = JSON.parse(raw);
+        for (const key of keys) {
+            const item = localStorage.getItem(`${prefix}:${key}`);
+            if (item) {
+                entries.set(key, JSON.parse(item));
+            }
+        }
+    }
+    catch {
+        // corrupted storage — ignore
+    }
+    return entries;
+}
+function persistToLocalStorage(prefix, cache) {
+    if (typeof localStorage === 'undefined')
+        return;
+    try {
+        const keys = Array.from(cache.keys());
+        localStorage.setItem(`${prefix}:index`, JSON.stringify(keys));
+        for (const [key, entry] of cache) {
+            localStorage.setItem(`${prefix}:${key}`, JSON.stringify(entry));
+        }
+    }
+    catch {
+        // localStorage full or unavailable — silently ignore
+    }
+}
+function clearLocalStorage(prefix) {
+    if (typeof localStorage === 'undefined')
+        return;
+    try {
+        const raw = localStorage.getItem(`${prefix}:index`);
+        if (raw) {
+            const keys = JSON.parse(raw);
+            for (const key of keys) {
+                localStorage.removeItem(`${prefix}:${key}`);
+            }
+        }
+        localStorage.removeItem(`${prefix}:index`);
+    }
+    catch {
+        // ignore
+    }
+}
+function removeFromLocalStorage(prefix, url) {
+    if (typeof localStorage === 'undefined')
+        return;
+    try {
+        localStorage.removeItem(`${prefix}:${url}`);
+        const raw = localStorage.getItem(`${prefix}:index`);
+        if (raw) {
+            const keys = JSON.parse(raw).filter((k) => k !== url);
+            localStorage.setItem(`${prefix}:index`, JSON.stringify(keys));
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+// ---------------------------------------------------------------------------
+// useETagCache hook
+// ---------------------------------------------------------------------------
+/**
+ * Hook for ETag-based HTTP caching with optional Service Worker support.
+ * Integrates with @objectstack/client ETag caching for efficient data fetching.
+ * When the server responds with 304 Not Modified, cached data is reused.
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const cache = useETagCache({ storage: 'localStorage', ttl: 60_000 });
+ *
+ *   useEffect(() => {
+ *     cache.fetchWithETag<User>(`/api/users/${userId}`).then(({ data, fromCache }) => {
+ *       console.log(fromCache ? 'Served from cache' : 'Fresh data');
+ *       setUser(data);
+ *     });
+ *   }, [userId]);
+ *
+ *   return <div>Cache entries: {cache.cacheSize}</div>;
+ * }
+ * ```
+ */
+export function useETagCache(userConfig = {}) {
+    const enabled = userConfig.enabled ?? DEFAULTS.enabled;
+    const storage = userConfig.storage ?? DEFAULTS.storage;
+    const storagePrefix = userConfig.storagePrefix ?? DEFAULTS.storagePrefix;
+    const maxEntries = userConfig.maxEntries ?? DEFAULTS.maxEntries;
+    const ttl = userConfig.ttl ?? DEFAULTS.ttl;
+    const useSW = userConfig.useServiceWorker ?? DEFAULTS.useServiceWorker;
+    const swUrl = userConfig.serviceWorkerUrl ?? DEFAULTS.serviceWorkerUrl;
+    const [cacheSize, setCacheSize] = useState(0);
+    const [serviceWorkerActive, setServiceWorkerActive] = useState(false);
+    // Keep config in a ref so callbacks always see latest values
+    const configRef = useRef({ enabled, storage, storagePrefix, maxEntries, ttl });
+    configRef.current = { enabled, storage, storagePrefix, maxEntries, ttl };
+    // Hydrate memory cache from localStorage on mount
+    useEffect(() => {
+        if (storage === 'localStorage') {
+            const persisted = loadFromLocalStorage(storagePrefix);
+            for (const [key, entry] of persisted) {
+                if (!memoryCache.has(key)) {
+                    memoryCache.set(key, entry);
+                    touchAccessOrder(key);
+                }
+            }
+            evictLRU(maxEntries);
+            setCacheSize(memoryCache.size);
+        }
+        // Only run on mount
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Auto-register Service Worker when enabled
+    useEffect(() => {
+        if (!useSW)
+            return;
+        if (typeof navigator === 'undefined' || !('serviceWorker' in navigator))
+            return;
+        navigator.serviceWorker
+            .register(swUrl, { scope: '/' })
+            .then((registration) => {
+            const worker = registration.active ?? registration.installing ?? registration.waiting;
+            setServiceWorkerActive(worker?.state === 'activated');
+            registration.onupdatefound = () => {
+                const installing = registration.installing;
+                if (!installing)
+                    return;
+                installing.onstatechange = () => {
+                    if (installing.state === 'activated') {
+                        setServiceWorkerActive(true);
+                    }
+                };
+            };
+        })
+            .catch(() => {
+            setServiceWorkerActive(false);
+        });
+    }, [useSW, swUrl]);
+    // ----- Helpers that read/write the shared cache -----
+    const isExpired = useCallback((entry) => {
+        return Date.now() - entry.timestamp > configRef.current.ttl;
+    }, []);
+    const setEntry = useCallback((url, entry) => {
+        memoryCache.set(url, entry);
+        touchAccessOrder(url);
+        evictLRU(configRef.current.maxEntries);
+        if (configRef.current.storage === 'localStorage') {
+            persistToLocalStorage(configRef.current.storagePrefix, memoryCache);
+        }
+        setCacheSize(memoryCache.size);
+    }, []);
+    const removeEntry = useCallback((url) => {
+        memoryCache.delete(url);
+        const idx = accessOrder.indexOf(url);
+        if (idx !== -1)
+            accessOrder.splice(idx, 1);
+        if (configRef.current.storage === 'localStorage') {
+            removeFromLocalStorage(configRef.current.storagePrefix, url);
+        }
+        setCacheSize(memoryCache.size);
+    }, []);
+    // ----- Public API -----
+    const fetchWithETag = useCallback(async (url, options) => {
+        // Validate URL: only allow http(s) or relative URLs
+        if (url.includes('://')) {
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+                    throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
+                }
+            }
+            catch (e) {
+                if (e instanceof Error && e.message.startsWith('Unsupported'))
+                    throw e;
+                throw new Error('Invalid URL');
+            }
+        }
+        if (!configRef.current.enabled) {
+            const res = await fetch(url, options);
+            const data = (await res.json());
+            return { data, fromCache: false, etag: res.headers.get('etag') ?? undefined };
+        }
+        const cached = memoryCache.get(url);
+        const headers = new Headers(options?.headers);
+        if (cached && !isExpired(cached)) {
+            if (cached.etag) {
+                headers.set('If-None-Match', cached.etag);
+            }
+            if (cached.lastModified) {
+                headers.set('If-Modified-Since', cached.lastModified);
+            }
+        }
+        const res = await fetch(url, { ...options, headers });
+        // 304 Not Modified — serve from cache
+        if (res.status === 304 && cached) {
+            touchAccessOrder(url);
+            return { data: cached.data, fromCache: true, etag: cached.etag };
+        }
+        const data = (await res.json());
+        const etag = res.headers.get('etag') ?? undefined;
+        const lastModified = res.headers.get('last-modified') ?? undefined;
+        if (etag || lastModified) {
+            setEntry(url, {
+                data,
+                etag: etag ?? '',
+                url,
+                timestamp: Date.now(),
+                lastModified,
+            });
+        }
+        return { data, fromCache: false, etag };
+    }, [isExpired, setEntry]);
+    const invalidate = useCallback((url) => {
+        removeEntry(url);
+    }, [removeEntry]);
+    const invalidatePattern = useCallback((pattern) => {
+        const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+        const keysToRemove = Array.from(memoryCache.keys()).filter((key) => regex.test(key));
+        for (const key of keysToRemove) {
+            removeEntry(key);
+        }
+    }, [removeEntry]);
+    const clearCache = useCallback(() => {
+        memoryCache.clear();
+        accessOrder.length = 0;
+        if (configRef.current.storage === 'localStorage') {
+            clearLocalStorage(configRef.current.storagePrefix);
+        }
+        setCacheSize(0);
+    }, []);
+    const registerSW = useCallback(async () => {
+        if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
+            return false;
+        }
+        try {
+            const registration = await navigator.serviceWorker.register(swUrl, { scope: '/' });
+            const worker = registration.active ?? registration.installing ?? registration.waiting;
+            const active = worker?.state === 'activated';
+            setServiceWorkerActive(active);
+            return active;
+        }
+        catch {
+            setServiceWorkerActive(false);
+            return false;
+        }
+    }, [swUrl]);
+    return useMemo(() => ({
+        fetchWithETag,
+        invalidate,
+        invalidatePattern,
+        clearCache,
+        cacheSize,
+        serviceWorkerActive,
+        registerServiceWorker: registerSW,
+    }), [fetchWithETag, invalidate, invalidatePattern, clearCache, cacheSize, serviceWorkerActive, registerSW]);
+}

package/dist/hooks/useFocusManagement.d.ts

@@ -0,0 +1,89 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface FocusReturnOptions {
+    /** Whether focus restoration is enabled. @default true */
+    enabled?: boolean;
+    /** Whether to focus the previously active element on unmount. @default true */
+    restoreOnUnmount?: boolean;
+}
+/**
+ * Hook that captures the currently focused element on mount and restores
+ * focus to it when the component unmounts. Useful for modals, drawers,
+ * and overlays that temporarily steal focus.
+ *
+ * @example
+ * ```tsx
+ * function Drawer({ onClose }: { onClose: () => void }) {
+ *   const { returnFocus } = useFocusReturn();
+ *
+ *   const handleClose = () => {
+ *     returnFocus();
+ *     onClose();
+ *   };
+ *
+ *   return <aside>...</aside>;
+ * }
+ * ```
+ */
+export declare function useFocusReturn(options?: FocusReturnOptions): {
+    /** Manually restore focus to the previously focused element. */
+    returnFocus: () => void;
+};
+export type RovingOrientation = 'horizontal' | 'vertical' | 'both';
+export interface RovingFocusOptions {
+    /** Whether roving focus is enabled. @default true */
+    enabled?: boolean;
+    /** Navigation orientation. @default 'vertical' */
+    orientation?: RovingOrientation;
+    /** Whether focus wraps from last to first item and vice-versa. @default true */
+    loop?: boolean;
+    /** Callback fired when the focused index changes. */
+    onFocusChange?: (index: number) => void;
+}
+export interface RovingFocusReturn<T extends HTMLElement> {
+    /** Ref to attach to the container element. */
+    containerRef: React.RefObject<T | null>;
+    /** The index of the currently focused item (-1 if none). */
+    focusedIndex: number;
+    /** Programmatically focus a specific item by index. */
+    setFocusedIndex: (index: number) => void;
+}
+/**
+ * Hook that implements roving tabindex / arrow-key navigation for a list of
+ * focusable items inside a container (sidebar items, tab lists, menu items).
+ *
+ * Only the currently active item participates in the tab order (tabindex 0);
+ * all other items are removed from the tab order (tabindex -1). Arrow keys
+ * move focus between items.
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav({ items }: { items: string[] }) {
+ *   const { containerRef, focusedIndex } = useRovingFocus<HTMLUListElement>({
+ *     orientation: 'vertical',
+ *     loop: true,
+ *   });
+ *
+ *   return (
+ *     <ul ref={containerRef} role="tablist">
+ *       {items.map((item, i) => (
+ *         <li
+ *           key={item}
+ *           role="tab"
+ *           tabIndex={i === focusedIndex ? 0 : -1}
+ *           data-roving-item
+ *         >
+ *           {item}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRovingFocus<T extends HTMLElement = HTMLDivElement>(options?: RovingFocusOptions): RovingFocusReturn<T>;

package/dist/hooks/useFocusManagement.js

@@ -0,0 +1,188 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useEffect, useRef, useCallback, useState } from 'react';
+/**
+ * Hook that captures the currently focused element on mount and restores
+ * focus to it when the component unmounts. Useful for modals, drawers,
+ * and overlays that temporarily steal focus.
+ *
+ * @example
+ * ```tsx
+ * function Drawer({ onClose }: { onClose: () => void }) {
+ *   const { returnFocus } = useFocusReturn();
+ *
+ *   const handleClose = () => {
+ *     returnFocus();
+ *     onClose();
+ *   };
+ *
+ *   return <aside>...</aside>;
+ * }
+ * ```
+ */
+export function useFocusReturn(options = {}) {
+    const { enabled = true, restoreOnUnmount = true } = options;
+    const previousFocusRef = useRef(null);
+    // Capture focused element on mount
+    useEffect(() => {
+        if (!enabled)
+            return;
+        previousFocusRef.current = document.activeElement;
+    }, [enabled]);
+    const returnFocus = useCallback(() => {
+        if (!enabled)
+            return;
+        const el = previousFocusRef.current;
+        if (el && typeof el.focus === 'function' && document.body.contains(el)) {
+            el.focus();
+        }
+    }, [enabled]);
+    // Restore on unmount
+    useEffect(() => {
+        if (!enabled || !restoreOnUnmount)
+            return;
+        return () => {
+            const el = previousFocusRef.current;
+            if (el && typeof el.focus === 'function' && document.body.contains(el)) {
+                el.focus();
+            }
+        };
+        // Only run cleanup on unmount — intentionally stable deps
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return { returnFocus };
+}
+/**
+ * Hook that implements roving tabindex / arrow-key navigation for a list of
+ * focusable items inside a container (sidebar items, tab lists, menu items).
+ *
+ * Only the currently active item participates in the tab order (tabindex 0);
+ * all other items are removed from the tab order (tabindex -1). Arrow keys
+ * move focus between items.
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav({ items }: { items: string[] }) {
+ *   const { containerRef, focusedIndex } = useRovingFocus<HTMLUListElement>({
+ *     orientation: 'vertical',
+ *     loop: true,
+ *   });
+ *
+ *   return (
+ *     <ul ref={containerRef} role="tablist">
+ *       {items.map((item, i) => (
+ *         <li
+ *           key={item}
+ *           role="tab"
+ *           tabIndex={i === focusedIndex ? 0 : -1}
+ *           data-roving-item
+ *         >
+ *           {item}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useRovingFocus(options = {}) {
+    const { enabled = true, orientation = 'vertical', loop = true, onFocusChange, } = options;
+    const containerRef = useRef(null);
+    const [focusedIndex, setFocusedIndexState] = useState(-1);
+    const onFocusChangeRef = useRef(onFocusChange);
+    useEffect(() => {
+        onFocusChangeRef.current = onFocusChange;
+    }, [onFocusChange]);
+    const getItems = useCallback(() => {
+        if (!containerRef.current)
+            return [];
+        return Array.from(containerRef.current.querySelectorAll('[data-roving-item]')).filter((el) => {
+            // Exclude hidden or disabled elements
+            if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') {
+                return false;
+            }
+            return el.offsetParent !== null; // visible check
+        });
+    }, []);
+    const setFocusedIndex = useCallback((index) => {
+        const items = getItems();
+        if (items.length === 0)
+            return;
+        const clamped = Math.max(0, Math.min(index, items.length - 1));
+        setFocusedIndexState(clamped);
+        items[clamped]?.focus();
+        onFocusChangeRef.current?.(clamped);
+    }, [getItems]);
+    useEffect(() => {
+        if (!enabled || !containerRef.current)
+            return;
+        const handleKeyDown = (event) => {
+            const items = getItems();
+            if (items.length === 0)
+                return;
+            const currentIndex = items.findIndex((el) => el === document.activeElement);
+            if (currentIndex === -1)
+                return;
+            const prevKeys = orientation === 'horizontal' ? ['ArrowLeft'] :
+                orientation === 'vertical' ? ['ArrowUp'] :
+                    ['ArrowUp', 'ArrowLeft'];
+            const nextKeys = orientation === 'horizontal' ? ['ArrowRight'] :
+                orientation === 'vertical' ? ['ArrowDown'] :
+                    ['ArrowDown', 'ArrowRight'];
+            let nextIndex = null;
+            if (prevKeys.includes(event.key)) {
+                event.preventDefault();
+                if (currentIndex > 0) {
+                    nextIndex = currentIndex - 1;
+                }
+                else if (loop) {
+                    nextIndex = items.length - 1;
+                }
+            }
+            else if (nextKeys.includes(event.key)) {
+                event.preventDefault();
+                if (currentIndex < items.length - 1) {
+                    nextIndex = currentIndex + 1;
+                }
+                else if (loop) {
+                    nextIndex = 0;
+                }
+            }
+            else if (event.key === 'Home') {
+                event.preventDefault();
+                nextIndex = 0;
+            }
+            else if (event.key === 'End') {
+                event.preventDefault();
+                nextIndex = items.length - 1;
+            }
+            if (nextIndex !== null) {
+                setFocusedIndexState(nextIndex);
+                items[nextIndex].focus();
+                onFocusChangeRef.current?.(nextIndex);
+            }
+        };
+        // When an item receives focus (e.g. via click), sync the index
+        const handleFocusIn = (event) => {
+            const items = getItems();
+            const index = items.findIndex((el) => el === event.target);
+            if (index !== -1) {
+                setFocusedIndexState(index);
+                onFocusChangeRef.current?.(index);
+            }
+        };
+        const container = containerRef.current;
+        container.addEventListener('keydown', handleKeyDown);
+        container.addEventListener('focusin', handleFocusIn);
+        return () => {
+            container.removeEventListener('keydown', handleKeyDown);
+            container.removeEventListener('focusin', handleFocusIn);
+        };
+    }, [enabled, orientation, loop, getItems]);
+    return { containerRef, focusedIndex, setFocusedIndex };
+}

package/dist/hooks/useFocusTrap.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface FocusTrapOptions {
+    /** Whether the focus trap is currently active */
+    enabled?: boolean;
+    /** Whether to auto-focus the first focusable element on mount */
+    autoFocus?: boolean;
+    /** Whether to restore focus to the previously focused element on unmount */
+    restoreFocus?: boolean;
+    /** Whether to release the trap on Escape key */
+    escapeDeactivates?: boolean;
+    /** Callback when Escape is pressed (if escapeDeactivates is true) */
+    onEscape?: () => void;
+    /** Initial element to focus (CSS selector) */
+    initialFocus?: string;
+}
+/**
+ * Hook that traps focus within a container element.
+ * Implements FocusTrapConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * function Modal({ onClose }: { onClose: () => void }) {
+ *   const trapRef = useFocusTrap({
+ *     enabled: true,
+ *     autoFocus: true,
+ *     restoreFocus: true,
+ *     escapeDeactivates: true,
+ *     onEscape: onClose,
+ *   });
+ *
+ *   return <div ref={trapRef}>...</div>;
+ * }
+ * ```
+ */
+export declare function useFocusTrap<T extends HTMLElement = HTMLDivElement>(options?: FocusTrapOptions): React.RefObject<T | null>;