@object-ui/react 3.3.0 → 3.3.1

package/src/hooks/useOffline.ts

@@ -1,301 +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, useSyncExternalStore } from 'react';
-
-// ---------------------------------------------------------------------------
-// Types aligned with @objectstack/spec v2.0.7 OfflineConfigSchema
-// ---------------------------------------------------------------------------
-
-/** Offline strategy determines how data is fetched when connectivity is limited. */
-export type OfflineStrategy =
-  | 'cache_first'
-  | 'network_first'
-  | 'stale_while_revalidate'
-  | 'network_only'
-  | 'cache_only';
-
-/** Conflict resolution strategy for sync operations. */
-export type ConflictResolutionStrategy =
-  | 'manual'
-  | 'client_wins'
-  | 'server_wins'
-  | 'last_write_wins';
-
-/** Persist storage backend. */
-export type PersistStorageType = 'indexeddb' | 'localstorage' | 'sqlite';
-
-/** Eviction policy for cache management. */
-export type EvictionPolicyType = 'lru' | 'lfu' | 'fifo';
-
-/** Sync state of the offline system. */
-export type SyncState = 'idle' | 'syncing' | 'error' | 'offline';
-
-/** A queued mutation waiting to be synced. */
-export interface QueuedMutation {
-  id: string;
-  timestamp: number;
-  operation: 'create' | 'update' | 'delete';
-  resource: string;
-  data?: Record<string, unknown>;
-}
-
-/** Cache configuration aligned with OfflineCacheConfigSchema. */
-export interface OfflineCacheConfig {
-  maxSize?: number;
-  ttl?: number;
-  persistStorage?: PersistStorageType;
-  evictionPolicy?: EvictionPolicyType;
-}
-
-/** Sync configuration aligned with SyncConfigSchema. */
-export interface OfflineSyncConfig {
-  strategy?: OfflineStrategy;
-  conflictResolution?: ConflictResolutionStrategy;
-  retryInterval?: number;
-  maxRetries?: number;
-  batchSize?: number;
-}
-
-/** Top-level offline configuration aligned with OfflineConfigSchema. */
-export interface OfflineConfig {
-  enabled?: boolean;
-  strategy?: OfflineStrategy;
-  cache?: OfflineCacheConfig;
-  sync?: OfflineSyncConfig;
-  offlineIndicator?: boolean;
-  offlineMessage?: string;
-  queueMaxSize?: number;
-}
-
-/** Result returned by the useOffline hook. */
-export interface OfflineResult {
-  /** Whether the browser is currently online. */
-  isOnline: boolean;
-  /** Whether offline mode is enabled in config. */
-  enabled: boolean;
-  /** Current sync state. */
-  syncState: SyncState;
-  /** The active offline strategy. */
-  strategy: OfflineStrategy;
-  /** Number of pending mutations in the queue. */
-  pendingCount: number;
-  /** Queue a mutation for later sync. */
-  queueMutation: (mutation: Omit<QueuedMutation, 'id' | 'timestamp'>) => void;
-  /** Manually trigger a sync attempt. */
-  sync: () => Promise<void>;
-  /** Clear the mutation queue. */
-  clearQueue: () => void;
-  /** Whether to show the offline indicator UI. */
-  showIndicator: boolean;
-  /** The offline message to display. */
-  offlineMessage: string;
-}
-
-// ---------------------------------------------------------------------------
-// Online/offline external store (SSR-safe)
-// ---------------------------------------------------------------------------
-
-function subscribeOnline(callback: () => void) {
-  if (typeof window === 'undefined') return () => {};
-  window.addEventListener('online', callback);
-  window.addEventListener('offline', callback);
-  return () => {
-    window.removeEventListener('online', callback);
-    window.removeEventListener('offline', callback);
-  };
-}
-
-function getOnlineSnapshot(): boolean {
-  return typeof navigator !== 'undefined' ? navigator.onLine : true;
-}
-
-function getServerSnapshot(): boolean {
-  return true;
-}
-
-// ---------------------------------------------------------------------------
-// Mutation queue storage helpers
-// ---------------------------------------------------------------------------
-
-const QUEUE_STORAGE_KEY = 'objectui-offline-queue';
-
-function loadQueue(): QueuedMutation[] {
-  if (typeof localStorage === 'undefined') return [];
-  try {
-    const raw = localStorage.getItem(QUEUE_STORAGE_KEY);
-    return raw ? (JSON.parse(raw) as QueuedMutation[]) : [];
-  } catch {
-    return [];
-  }
-}
-
-function persistQueue(queue: QueuedMutation[]): void {
-  if (typeof localStorage === 'undefined') return;
-  try {
-    localStorage.setItem(QUEUE_STORAGE_KEY, JSON.stringify(queue));
-  } catch {
-    // localStorage full or unavailable — silently ignore
-  }
-}
-
-let idCounter = 0;
-function generateId(): string {
-  idCounter += 1;
-  return `mut_${Date.now()}_${idCounter}`;
-}
-
-// ---------------------------------------------------------------------------
-// useOffline hook
-// ---------------------------------------------------------------------------
-
-const DEFAULTS: Required<
-  Pick<OfflineConfig, 'enabled' | 'strategy' | 'offlineIndicator' | 'queueMaxSize'>
-> & { offlineMessage: string } = {
-  enabled: true,
-  strategy: 'network_first',
-  offlineIndicator: true,
-  offlineMessage: 'You are currently offline. Changes will be synced when reconnected.',
-  queueMaxSize: 100,
-};
-
-/**
- * Hook for offline mode detection and sync queue management.
- * Implements OfflineConfigSchema, SyncConfigSchema, and ConflictResolutionSchema
- * from @objectstack/spec v2.0.7.
- *
- * @example
- * ```tsx
- * function App() {
- *   const offline = useOffline({
- *     enabled: true,
- *     strategy: 'cache_first',
- *     sync: { conflictResolution: 'last_write_wins' },
- *   });
- *
- *   if (!offline.isOnline && offline.showIndicator) {
- *     return <Banner>{offline.offlineMessage}</Banner>;
- *   }
- *
- *   return <div>Pending mutations: {offline.pendingCount}</div>;
- * }
- * ```
- */
-export function useOffline(config: OfflineConfig = {}): OfflineResult {
-  const {
-    enabled = DEFAULTS.enabled,
-    strategy = DEFAULTS.strategy,
-    offlineIndicator = DEFAULTS.offlineIndicator,
-    offlineMessage = DEFAULTS.offlineMessage,
-    queueMaxSize = DEFAULTS.queueMaxSize,
-    sync: syncConfig,
-  } = config;
-
-  const isOnline = useSyncExternalStore(subscribeOnline, getOnlineSnapshot, getServerSnapshot);
-  const [queue, setQueue] = useState<QueuedMutation[]>(loadQueue);
-  const [syncState, setSyncState] = useState<SyncState>('idle');
-  const syncConfigRef = useRef(syncConfig);
-  syncConfigRef.current = syncConfig;
-
-  // Persist queue to localStorage whenever it changes
-  useEffect(() => {
-    persistQueue(queue);
-  }, [queue]);
-
-  // Update sync state based on online status
-  useEffect(() => {
-    if (!enabled) return;
-    if (!isOnline) {
-      setSyncState('offline');
-    } else if (syncState === 'offline') {
-      setSyncState('idle');
-    }
-  }, [isOnline, enabled, syncState]);
-
-  const queueMutation = useCallback(
-    (mutation: Omit<QueuedMutation, 'id' | 'timestamp'>) => {
-      if (!enabled) return;
-      setQueue((prev) => {
-        const newEntry: QueuedMutation = {
-          ...mutation,
-          id: generateId(),
-          timestamp: Date.now(),
-        };
-        const next = [...prev, newEntry];
-        // Enforce max queue size (FIFO eviction)
-        if (next.length > queueMaxSize) {
-          return next.slice(next.length - queueMaxSize);
-        }
-        return next;
-      });
-    },
-    [enabled, queueMaxSize],
-  );
-
-  const clearQueue = useCallback(() => {
-    setQueue([]);
-  }, []);
-
-  const sync = useCallback(async () => {
-    if (!enabled || queue.length === 0) return;
-    setSyncState('syncing');
-    try {
-      // In a real implementation, this would batch-send mutations to the server.
-      // For now, we simulate a successful sync by clearing the queue.
-      const batchSize = syncConfigRef.current?.batchSize ?? queue.length;
-      const batch = queue.slice(0, batchSize);
-
-      // Simulate network round-trip
-      await new Promise<void>((resolve) => setTimeout(resolve, 0));
-
-      // Remove synced mutations from queue
-      setQueue((prev) => prev.filter((m) => !batch.some((b) => b.id === m.id)));
-      setSyncState('idle');
-    } catch {
-      setSyncState('error');
-    }
-  }, [enabled, queue]);
-
-  // Auto-sync when coming back online (short stabilization delay)
-  useEffect(() => {
-    if (!enabled || !isOnline || queue.length === 0) return;
-    const timer = setTimeout(() => {
-      void sync();
-    }, 100);
-    return () => clearTimeout(timer);
-    // Only trigger on isOnline changes, not on every queue change
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isOnline, enabled]);
-
-  return useMemo<OfflineResult>(
-    () => ({
-      isOnline,
-      enabled,
-      syncState,
-      strategy,
-      pendingCount: queue.length,
-      queueMutation,
-      sync,
-      clearQueue,
-      showIndicator: offlineIndicator && !isOnline,
-      offlineMessage,
-    }),
-    [
-      isOnline,
-      enabled,
-      syncState,
-      strategy,
-      queue.length,
-      queueMutation,
-      sync,
-      clearQueue,
-      offlineIndicator,
-      offlineMessage,
-    ],
-  );
-}

package/src/hooks/usePageTransition.ts

@@ -1,187 +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 { useReducedMotion } from './useReducedMotion';
-
-// ---------------------------------------------------------------------------
-// Types aligned with @objectstack/spec v2.0.7 PageTransitionSchema
-// ---------------------------------------------------------------------------
-
-/** Page transition type. */
-export type PageTransitionType =
-  | 'none'
-  | 'fade'
-  | 'slide_up'
-  | 'slide_down'
-  | 'slide_left'
-  | 'slide_right'
-  | 'scale'
-  | 'rotate'
-  | 'flip';
-
-/** Easing function for page transitions. */
-export type PageTransitionEasing =
-  | 'linear'
-  | 'ease'
-  | 'ease_in'
-  | 'ease_out'
-  | 'ease_in_out'
-  | 'spring';
-
-/** Page transition configuration aligned with PageTransitionSchema. */
-export interface PageTransitionConfig {
-  /** Transition type. */
-  type?: PageTransitionType;
-  /** Duration in milliseconds. */
-  duration?: number;
-  /** Easing function. */
-  easing?: PageTransitionEasing;
-  /** Whether entering and exiting pages cross-fade. */
-  crossFade?: boolean;
-}
-
-/** Resolved CSS classes and styles for a page transition. */
-export interface PageTransitionResult {
-  /** Tailwind CSS classes for the enter transition. */
-  enterClassName: string;
-  /** Tailwind CSS classes for the exit transition. */
-  exitClassName: string;
-  /** Inline styles for the enter transition. */
-  enterStyle: React.CSSProperties;
-  /** Inline styles for the exit transition. */
-  exitStyle: React.CSSProperties;
-  /** Whether the transition is active (not 'none' and motion not reduced). */
-  isActive: boolean;
-  /** The resolved transition type. */
-  type: PageTransitionType;
-  /** The resolved duration in ms. */
-  duration: number;
-}
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const EASING_CSS: Record<PageTransitionEasing, string> = {
-  linear: 'linear',
-  ease: 'ease',
-  ease_in: 'ease-in',
-  ease_out: 'ease-out',
-  ease_in_out: 'ease-in-out',
-  spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
-};
-
-const ENTER_CLASSES: Record<PageTransitionType, string> = {
-  none: '',
-  fade: 'animate-in fade-in',
-  slide_up: 'animate-in slide-in-from-bottom-4',
-  slide_down: 'animate-in slide-in-from-top-4',
-  slide_left: 'animate-in slide-in-from-right-4',
-  slide_right: 'animate-in slide-in-from-left-4',
-  scale: 'animate-in zoom-in-95',
-  rotate: 'animate-in spin-in-90',
-  flip: 'animate-in fade-in zoom-in-95',
-};
-
-const EXIT_CLASSES: Record<PageTransitionType, string> = {
-  none: '',
-  fade: 'animate-out fade-out',
-  slide_up: 'animate-out slide-out-to-top-4',
-  slide_down: 'animate-out slide-out-to-bottom-4',
-  slide_left: 'animate-out slide-out-to-left-4',
-  slide_right: 'animate-out slide-out-to-right-4',
-  scale: 'animate-out zoom-out-95',
-  rotate: 'animate-out spin-out-90',
-  flip: 'animate-out fade-out zoom-out-95',
-};
-
-const DEFAULT_DURATION = 300;
-const DEFAULT_EASING: PageTransitionEasing = 'ease_in_out';
-
-// ---------------------------------------------------------------------------
-// usePageTransition hook
-// ---------------------------------------------------------------------------
-
-/**
- * Hook for page-level transition animations aligned with
- * PageTransitionSchema from @objectstack/spec v2.0.7.
- *
- * Generates Tailwind CSS animate-in / animate-out classes and inline styles
- * for enter/exit page transitions. Respects `prefers-reduced-motion`.
- *
- * @example
- * ```tsx
- * function PageWrapper({ children }: { children: React.ReactNode }) {
- *   const transition = usePageTransition({ type: 'fade', duration: 200 });
- *
- *   return (
- *     <div className={transition.enterClassName} style={transition.enterStyle}>
- *       {children}
- *     </div>
- *   );
- * }
- * ```
- */
-export function usePageTransition(config: PageTransitionConfig = {}): PageTransitionResult {
-  const {
-    type = 'none',
-    duration = DEFAULT_DURATION,
-    easing = DEFAULT_EASING,
-    crossFade = false,
-  } = config;
-
-  const reducedMotion = useReducedMotion();
-
-  return useMemo(() => {
-    const isActive = type !== 'none' && !reducedMotion;
-
-    if (!isActive) {
-      return {
-        enterClassName: '',
-        exitClassName: '',
-        enterStyle: {},
-        exitStyle: {},
-        isActive: false,
-        type,
-        duration,
-      };
-    }
-
-    const enterClassName = ENTER_CLASSES[type] || '';
-    const exitClassName = EXIT_CLASSES[type] || '';
-
-    const baseStyle: React.CSSProperties = {
-      animationDuration: `${duration}ms`,
-      animationTimingFunction: EASING_CSS[easing] || EASING_CSS.ease_in_out,
-      animationFillMode: 'both',
-    };
-
-    const enterStyle: React.CSSProperties = { ...baseStyle };
-    const exitStyle: React.CSSProperties = { ...baseStyle };
-
-    // When crossFade is enabled, both the entering and exiting pages
-    // should overlap and transition opacity simultaneously.
-    if (crossFade) {
-      enterStyle.position = 'absolute';
-      enterStyle.inset = '0';
-      exitStyle.position = 'absolute';
-      exitStyle.inset = '0';
-    }
-
-    return {
-      enterClassName,
-      exitClassName,
-      enterStyle,
-      exitStyle,
-      isActive: true,
-      type,
-      duration,
-    };
-  }, [type, duration, easing, crossFade, reducedMotion]);
-}

package/src/hooks/usePageVariables.tsx

@@ -1,157 +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 React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
-import type { PageVariable } from '@object-ui/types';
-
-/**
- * Page variables context value.
- * Provides access to page-level state variables.
- */
-export interface PageVariablesContextValue {
-  /** Current variable values */
-  variables: Record<string, any>;
-  /** Set a single variable value */
-  setVariable: (name: string, value: any) => void;
-  /** Set multiple variable values at once */
-  setVariables: (updates: Record<string, any>) => void;
-  /** Reset all variables to their default values */
-  resetVariables: () => void;
-}
-
-const PageVariablesContext = createContext<PageVariablesContextValue | null>(null);
-
-/**
- * Initialize page variables from their definitions.
- * Sets each variable to its defaultValue or type-appropriate default.
- */
-function initializeVariables(definitions?: PageVariable[]): Record<string, any> {
-  if (!definitions || definitions.length === 0) return {};
-
-  const initial: Record<string, any> = {};
-  for (const def of definitions) {
-    if (def.defaultValue !== undefined) {
-      initial[def.name] = def.defaultValue;
-    } else {
-      // Type-appropriate defaults
-      switch (def.type) {
-        case 'number':
-          initial[def.name] = 0;
-          break;
-        case 'boolean':
-          initial[def.name] = false;
-          break;
-        case 'object':
-          initial[def.name] = {};
-          break;
-        case 'array':
-          initial[def.name] = [];
-          break;
-        case 'string':
-        default:
-          initial[def.name] = '';
-          break;
-      }
-    }
-  }
-  return initial;
-}
-
-/**
- * Props for PageVariablesProvider
- */
-export interface PageVariablesProviderProps {
-  /** Variable definitions from PageSchema.variables */
-  definitions?: PageVariable[];
-  /** Child components */
-  children: React.ReactNode;
-}
-
-/**
- * PageVariablesProvider — Provides page-level state variables to the component tree.
- *
- * Initializes variables from their definitions and provides read/write access
- * to all child components via the usePageVariables hook.
- *
- * @example
- * ```tsx
- * <PageVariablesProvider definitions={[
- *   { name: 'selectedId', type: 'string', defaultValue: '' },
- *   { name: 'count', type: 'number', defaultValue: 0 },
- * ]}>
- *   <MyComponents />
- * </PageVariablesProvider>
- * ```
- */
-export const PageVariablesProvider: React.FC<PageVariablesProviderProps> = ({
-  definitions,
-  children,
-}) => {
-  const [variables, setVariablesState] = useState<Record<string, any>>(() =>
-    initializeVariables(definitions)
-  );
-
-  const setVariable = useCallback((name: string, value: any) => {
-    setVariablesState((prev) => ({ ...prev, [name]: value }));
-  }, []);
-
-  const setVariables = useCallback((updates: Record<string, any>) => {
-    setVariablesState((prev) => ({ ...prev, ...updates }));
-  }, []);
-
-  const resetVariables = useCallback(() => {
-    setVariablesState(initializeVariables(definitions));
-  }, [definitions]);
-
-  const value = useMemo<PageVariablesContextValue>(
-    () => ({ variables, setVariable, setVariables, resetVariables }),
-    [variables, setVariable, setVariables, resetVariables]
-  );
-
-  return (
-    <PageVariablesContext.Provider value={value}>
-      {children}
-    </PageVariablesContext.Provider>
-  );
-};
-
-PageVariablesProvider.displayName = 'PageVariablesProvider';
-
-/**
- * Hook to access page-level variables.
- *
- * Returns the current variable values and setter functions.
- * Returns a no-op fallback if used outside a PageVariablesProvider.
- *
- * @example
- * ```tsx
- * const { variables, setVariable } = usePageVariables();
- * const userId = variables.selectedId;
- * setVariable('selectedId', '123');
- * ```
- */
-export function usePageVariables(): PageVariablesContextValue {
-  const ctx = useContext(PageVariablesContext);
-  if (!ctx) {
-    // Graceful fallback — allows components to work outside a Page
-    return {
-      variables: {},
-      setVariable: () => {},
-      setVariables: () => {},
-      resetVariables: () => {},
-    };
-  }
-  return ctx;
-}
-
-/**
- * Hook to check if a PageVariablesProvider is available.
- */
-export function useHasPageVariables(): boolean {
-  return useContext(PageVariablesContext) !== null;
-}