@object-ui/react 3.3.0 → 3.3.2

package/src/hooks/useETagCache.ts

@@ -1,404 +0,0 @@
-/**
- * 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/useExpression.ts

@@ -1,56 +0,0 @@
-/**
- * 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 { useMemo } from 'react';
-import { ExpressionEvaluator } from '@object-ui/core';
-
-/**
- * Hook for evaluating expressions with dynamic context
- * 
- * @example
- * ```tsx
- * const isVisible = useExpression('${data.age >= 18}', { data });
- * const label = useExpression('Hello ${user.name}!', { user });
- * ```
- */
-export function useExpression(
-  expression: string | boolean | number | null | undefined,
-  context: Record<string, any> = {}
-): any {
-  // We evaluate directly without caching the evaluator to avoid issues with context changes
-  return useMemo(
-    () => {
-      const evaluator = new ExpressionEvaluator(context);
-      return evaluator.evaluate(expression);
-    },
-    [expression, context]
-  );
-}
-
-/**
- * Hook for evaluating conditional expressions
- * Returns a boolean value
- * 
- * @example
- * ```tsx
- * const isVisible = useCondition('${data.status === "active"}', { data });
- * ```
- */
-export function useCondition(
-  condition: string | boolean | undefined,
-  context: Record<string, any> = {}
-): boolean {
-  // We evaluate directly without caching the evaluator to avoid issues with context changes
-  return useMemo(
-    () => {
-      const evaluator = new ExpressionEvaluator(context);
-      return evaluator.evaluateCondition(condition);
-    },
-    [condition, context]
-  );
-}

package/src/hooks/useFocusManagement.ts

@@ -1,248 +0,0 @@
-/**
- * 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 };
-}