@object-ui/react 0.5.0 → 3.0.0

package/dist/hooks/useOffline.js

@@ -0,0 +1,185 @@
+/**
+ * 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';
+// ---------------------------------------------------------------------------
+// Online/offline external store (SSR-safe)
+// ---------------------------------------------------------------------------
+function subscribeOnline(callback) {
+    if (typeof window === 'undefined')
+        return () => { };
+    window.addEventListener('online', callback);
+    window.addEventListener('offline', callback);
+    return () => {
+        window.removeEventListener('online', callback);
+        window.removeEventListener('offline', callback);
+    };
+}
+function getOnlineSnapshot() {
+    return typeof navigator !== 'undefined' ? navigator.onLine : true;
+}
+function getServerSnapshot() {
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Mutation queue storage helpers
+// ---------------------------------------------------------------------------
+const QUEUE_STORAGE_KEY = 'objectui-offline-queue';
+function loadQueue() {
+    if (typeof localStorage === 'undefined')
+        return [];
+    try {
+        const raw = localStorage.getItem(QUEUE_STORAGE_KEY);
+        return raw ? JSON.parse(raw) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function persistQueue(queue) {
+    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() {
+    idCounter += 1;
+    return `mut_${Date.now()}_${idCounter}`;
+}
+// ---------------------------------------------------------------------------
+// useOffline hook
+// ---------------------------------------------------------------------------
+const DEFAULTS = {
+    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 = {}) {
+    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(loadQueue);
+    const [syncState, setSyncState] = useState('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) => {
+        if (!enabled)
+            return;
+        setQueue((prev) => {
+            const newEntry = {
+                ...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((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(() => ({
+        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/dist/hooks/usePageTransition.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/** 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;
+}
+/**
+ * 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 declare function usePageTransition(config?: PageTransitionConfig): PageTransitionResult;

package/dist/hooks/usePageTransition.js

@@ -0,0 +1,111 @@
+/**
+ * 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';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const EASING_CSS = {
+    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 = {
+    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 = {
+    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 = '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 = {}) {
+    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 = {
+            animationDuration: `${duration}ms`,
+            animationTimingFunction: EASING_CSS[easing] || EASING_CSS.ease_in_out,
+            animationFillMode: 'both',
+        };
+        const enterStyle = { ...baseStyle };
+        const exitStyle = { ...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/dist/hooks/usePageVariables.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 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;
+}
+/**
+ * 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 declare const PageVariablesProvider: React.FC<PageVariablesProviderProps>;
+/**
+ * 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 declare function usePageVariables(): PageVariablesContextValue;
+/**
+ * Hook to check if a PageVariablesProvider is available.
+ */
+export declare function useHasPageVariables(): boolean;

package/dist/hooks/usePageVariables.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { createContext, useContext, useState, useCallback, useMemo } from 'react';
+const PageVariablesContext = createContext(null);
+/**
+ * Initialize page variables from their definitions.
+ * Sets each variable to its defaultValue or type-appropriate default.
+ */
+function initializeVariables(definitions) {
+    if (!definitions || definitions.length === 0)
+        return {};
+    const initial = {};
+    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;
+}
+/**
+ * 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 = ({ definitions, children, }) => {
+    const [variables, setVariablesState] = useState(() => initializeVariables(definitions));
+    const setVariable = useCallback((name, value) => {
+        setVariablesState((prev) => ({ ...prev, [name]: value }));
+    }, []);
+    const setVariables = useCallback((updates) => {
+        setVariablesState((prev) => ({ ...prev, ...updates }));
+    }, []);
+    const resetVariables = useCallback(() => {
+        setVariablesState(initializeVariables(definitions));
+    }, [definitions]);
+    const value = useMemo(() => ({ variables, setVariable, setVariables, resetVariables }), [variables, setVariable, setVariables, resetVariables]);
+    return (_jsx(PageVariablesContext.Provider, { value: value, children: children }));
+};
+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() {
+    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() {
+    return useContext(PageVariablesContext) !== null;
+}

package/dist/hooks/usePerformance.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+/** Cache strategy for data fetching. */
+export type CacheStrategyType = 'none' | 'cache-first' | 'network-first' | 'stale-while-revalidate';
+/** Virtual scroll configuration. */
+export interface VirtualScrollConfig {
+    enabled?: boolean;
+    itemHeight?: number;
+    overscan?: number;
+}
+/** Performance configuration aligned with PerformanceConfigSchema. */
+export interface PerformanceConfig {
+    /** Whether to lazy-load components/data. */
+    lazyLoad?: boolean;
+    /** Virtual scroll settings for large lists. */
+    virtualScroll?: VirtualScrollConfig;
+    /** Cache strategy for data fetching. */
+    cacheStrategy?: CacheStrategyType;
+    /** Whether to prefetch linked resources. */
+    prefetch?: boolean;
+    /** Default page size for paginated views. */
+    pageSize?: number;
+    /** Debounce interval in milliseconds for user input. */
+    debounceMs?: number;
+}
+/** Web Vitals metrics snapshot. */
+export interface PerformanceMetrics {
+    /** Largest Contentful Paint (ms). */
+    lcp: number | null;
+    /** First Contentful Paint (ms). */
+    fcp: number | null;
+    /** Time to Interactive (ms). */
+    tti: number | null;
+    /** Total render count since mount. */
+    renderCount: number;
+    /** Last render duration (ms). */
+    lastRenderDuration: number | null;
+}
+/** Result returned by the usePerformance hook. */
+export interface PerformanceResult {
+    /** The resolved performance configuration (with defaults). */
+    config: Required<Omit<PerformanceConfig, 'virtualScroll'>> & {
+        virtualScroll: Required<VirtualScrollConfig>;
+    };
+    /** Current performance metrics. */
+    metrics: PerformanceMetrics;
+    /** Mark a rendering start (returns stop function). */
+    markRenderStart: () => () => void;
+    /** Create a debounced version of a callback. */
+    debounce: <T extends (...args: unknown[]) => void>(fn: T) => T;
+}
+/**
+ * Hook for performance monitoring and configuration aligned with
+ * PerformanceConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * Provides resolved config values, Web Vitals metrics, and utility functions
+ * (debounce, render marking) for performance-aware components.
+ *
+ * @example
+ * ```tsx
+ * function DataGrid({ data }: { data: unknown[] }) {
+ *   const perf = usePerformance({
+ *     lazyLoad: true,
+ *     virtualScroll: { enabled: true, itemHeight: 40 },
+ *     debounceMs: 200,
+ *   });
+ *
+ *   const handleSearch = perf.debounce((query: string) => {
+ *     // debounced search
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {perf.config.virtualScroll.enabled
+ *         ? <VirtualList itemHeight={perf.config.virtualScroll.itemHeight} />
+ *         : <NormalList />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePerformance(userConfig?: PerformanceConfig): PerformanceResult;