@object-ui/react 2.0.0 → 3.0.0

package/src/hooks/useETagCache.ts

@@ -0,0 +1,404 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Types aligned with @objectstack/client ETag caching
+// ---------------------------------------------------------------------------
+
+/** Configuration for ETag-based HTTP caching. */
+export interface ETagCacheConfig {
+  /** Enable ETag caching (default: true) */
+  enabled?: boolean;
+  /** Storage backend for ETags ('memory' | 'localStorage') */
+  storage?: 'memory' | 'localStorage';
+  /** Storage key prefix (default: 'oui-etag') */
+  storagePrefix?: string;
+  /** Max cache entries (default: 1000) */
+  maxEntries?: number;
+  /** Cache TTL in ms (default: 3600000 = 1 hour) */
+  ttl?: number;
+  /** Whether to register a Service Worker for caching (default: false) */
+  useServiceWorker?: boolean;
+  /** Service Worker script URL */
+  serviceWorkerUrl?: string;
+}
+
+/** A single cache entry with its associated ETag and metadata. */
+export interface CacheEntry<T = unknown> {
+  data: T;
+  etag: string;
+  url: string;
+  timestamp: number;
+  lastModified?: string;
+}
+
+/** Result returned by the useETagCache hook. */
+export interface ETagCacheResult {
+  /** Fetch data with ETag support — sends If-None-Match header, returns cached data on 304. */
+  fetchWithETag: <T>(
+    url: string,
+    options?: RequestInit,
+  ) => Promise<{ data: T; fromCache: boolean; etag?: string }>;
+  /** Invalidate cache for a specific URL. */
+  invalidate: (url: string) => void;
+  /** Invalidate all cache entries matching a pattern. */
+  invalidatePattern: (pattern: string | RegExp) => void;
+  /** Clear entire cache. */
+  clearCache: () => void;
+  /** Number of cached entries. */
+  cacheSize: number;
+  /** Whether Service Worker is registered and active. */
+  serviceWorkerActive: boolean;
+  /** Register/update the Service Worker. */
+  registerServiceWorker: () => Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+  enabled: true,
+  storage: 'memory' as const,
+  storagePrefix: 'oui-etag',
+  maxEntries: 1000,
+  ttl: 3_600_000, // 1 hour
+  useServiceWorker: false,
+  serviceWorkerUrl: '/service-worker.js',
+} as const;
+
+// ---------------------------------------------------------------------------
+// LRU cache implementation (module-scoped, shared across instances)
+// ---------------------------------------------------------------------------
+
+const memoryCache = new Map<string, CacheEntry>();
+
+/** Access order tracking for LRU eviction — most recently used at the end. */
+const accessOrder: string[] = [];
+
+function touchAccessOrder(url: string): void {
+  const idx = accessOrder.indexOf(url);
+  if (idx !== -1) accessOrder.splice(idx, 1);
+  accessOrder.push(url);
+}
+
+function evictLRU(maxEntries: number): void {
+  while (memoryCache.size > maxEntries && accessOrder.length > 0) {
+    const oldest = accessOrder.shift();
+    if (oldest) memoryCache.delete(oldest);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// localStorage helpers (SSR-safe)
+// ---------------------------------------------------------------------------
+
+function loadFromLocalStorage(prefix: string): Map<string, CacheEntry> {
+  if (typeof localStorage === 'undefined') return new Map();
+  const entries = new Map<string, CacheEntry>();
+  try {
+    const raw = localStorage.getItem(`${prefix}:index`);
+    if (!raw) return entries;
+    const keys = JSON.parse(raw) as string[];
+    for (const key of keys) {
+      const item = localStorage.getItem(`${prefix}:${key}`);
+      if (item) {
+        entries.set(key, JSON.parse(item) as CacheEntry);
+      }
+    }
+  } catch {
+    // corrupted storage — ignore
+  }
+  return entries;
+}
+
+function persistToLocalStorage(prefix: string, cache: Map<string, CacheEntry>): void {
+  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: string): void {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    const raw = localStorage.getItem(`${prefix}:index`);
+    if (raw) {
+      const keys = JSON.parse(raw) as string[];
+      for (const key of keys) {
+        localStorage.removeItem(`${prefix}:${key}`);
+      }
+    }
+    localStorage.removeItem(`${prefix}:index`);
+  } catch {
+    // ignore
+  }
+}
+
+function removeFromLocalStorage(prefix: string, url: string): void {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    localStorage.removeItem(`${prefix}:${url}`);
+    const raw = localStorage.getItem(`${prefix}:index`);
+    if (raw) {
+      const keys = (JSON.parse(raw) as string[]).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: ETagCacheConfig = {}): ETagCacheResult {
+  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: CacheEntry): boolean => {
+    return Date.now() - entry.timestamp > configRef.current.ttl;
+  }, []);
+
+  const setEntry = useCallback(
+    (url: string, entry: CacheEntry): void => {
+      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: string): void => {
+      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 <T>(
+      url: string,
+      options?: RequestInit,
+    ): Promise<{ data: T; fromCache: boolean; etag?: string }> => {
+      // 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()) as T;
+        return { data, fromCache: false, etag: res.headers.get('etag') ?? undefined };
+      }
+
+      const cached = memoryCache.get(url) as CacheEntry<T> | undefined;
+      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()) as T;
+      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: string): void => {
+      removeEntry(url);
+    },
+    [removeEntry],
+  );
+
+  const invalidatePattern = useCallback(
+    (pattern: string | RegExp): void => {
+      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((): void => {
+    memoryCache.clear();
+    accessOrder.length = 0;
+
+    if (configRef.current.storage === 'localStorage') {
+      clearLocalStorage(configRef.current.storagePrefix);
+    }
+    setCacheSize(0);
+  }, []);
+
+  const registerSW = useCallback(async (): Promise<boolean> => {
+    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<ETagCacheResult>(
+    () => ({
+      fetchWithETag,
+      invalidate,
+      invalidatePattern,
+      clearCache,
+      cacheSize,
+      serviceWorkerActive,
+      registerServiceWorker: registerSW,
+    }),
+    [fetchWithETag, invalidate, invalidatePattern, clearCache, cacheSize, serviceWorkerActive, registerSW],
+  );
+}

package/src/hooks/useFocusManagement.ts

@@ -0,0 +1,248 @@
+/**
+ * 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';
+
+// ─── useFocusReturn ────────────────────────────────────────────────────────────
+
+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 function useFocusReturn(options: FocusReturnOptions = {}): {
+  /** Manually restore focus to the previously focused element. */
+  returnFocus: () => void;
+} {
+  const { enabled = true, restoreOnUnmount = true } = options;
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+
+  // Capture focused element on mount
+  useEffect(() => {
+    if (!enabled) return;
+    previousFocusRef.current = document.activeElement as HTMLElement | null;
+  }, [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 };
+}
+
+// ─── useRovingFocus ────────────────────────────────────────────────────────────
+
+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 function useRovingFocus<T extends HTMLElement = HTMLDivElement>(
+  options: RovingFocusOptions = {}
+): RovingFocusReturn<T> {
+  const {
+    enabled = true,
+    orientation = 'vertical',
+    loop = true,
+    onFocusChange,
+  } = options;
+
+  const containerRef = useRef<T | null>(null);
+  const [focusedIndex, setFocusedIndexState] = useState(-1);
+  const onFocusChangeRef = useRef(onFocusChange);
+  useEffect(() => {
+    onFocusChangeRef.current = onFocusChange;
+  }, [onFocusChange]);
+
+  const getItems = useCallback((): HTMLElement[] => {
+    if (!containerRef.current) return [];
+    return Array.from(
+      containerRef.current.querySelectorAll<HTMLElement>('[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: number) => {
+      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: KeyboardEvent) => {
+      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: number | null = 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: FocusEvent) => {
+      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 };
+}