@object-ui/react 0.5.0 → 3.0.0

package/dist/hooks/usePerformance.js

@@ -0,0 +1,165 @@
+/**
+ * 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 = {
+    lazyLoad: true,
+    cacheStrategy: 'stale-while-revalidate',
+    prefetch: false,
+    pageSize: 50,
+    debounceMs: 300,
+    virtualScroll: {
+        enabled: false,
+        itemHeight: 40,
+        overscan: 5,
+    },
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getFCP() {
+    if (typeof performance === 'undefined' || !performance.getEntriesByType)
+        return null;
+    try {
+        const entries = performance.getEntriesByType('paint');
+        const entry = entries.find((e) => e.name === 'first-contentful-paint');
+        return entry ? Math.round(entry.startTime) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getLCP() {
+    if (typeof performance === 'undefined' || !performance.getEntriesByType)
+        return null;
+    try {
+        const entries = performance.getEntriesByType('largest-contentful-paint');
+        const entry = entries.length > 0 ? entries[entries.length - 1] : undefined;
+        return entry ? Math.round(entry.startTime) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// usePerformance hook
+// ---------------------------------------------------------------------------
+/**
+ * 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 function usePerformance(userConfig = {}) {
+    const config = useMemo(() => ({
+        lazyLoad: userConfig.lazyLoad ?? DEFAULTS.lazyLoad,
+        cacheStrategy: userConfig.cacheStrategy ?? DEFAULTS.cacheStrategy,
+        prefetch: userConfig.prefetch ?? DEFAULTS.prefetch,
+        pageSize: userConfig.pageSize ?? DEFAULTS.pageSize,
+        debounceMs: userConfig.debounceMs ?? DEFAULTS.debounceMs,
+        virtualScroll: {
+            enabled: userConfig.virtualScroll?.enabled ?? DEFAULTS.virtualScroll.enabled,
+            itemHeight: userConfig.virtualScroll?.itemHeight ?? DEFAULTS.virtualScroll.itemHeight,
+            overscan: userConfig.virtualScroll?.overscan ?? DEFAULTS.virtualScroll.overscan,
+        },
+    }), [
+        userConfig.lazyLoad,
+        userConfig.cacheStrategy,
+        userConfig.prefetch,
+        userConfig.pageSize,
+        userConfig.debounceMs,
+        userConfig.virtualScroll?.enabled,
+        userConfig.virtualScroll?.itemHeight,
+        userConfig.virtualScroll?.overscan,
+    ]);
+    const [metrics, setMetrics] = useState({
+        lcp: null,
+        fcp: null,
+        tti: null,
+        renderCount: 0,
+        lastRenderDuration: null,
+    });
+    // Collect paint metrics on mount
+    useEffect(() => {
+        // Defer metric collection to allow paint entries to populate
+        const timer = setTimeout(() => {
+            setMetrics((prev) => ({
+                ...prev,
+                fcp: getFCP(),
+                lcp: getLCP(),
+            }));
+        }, 0);
+        return () => clearTimeout(timer);
+    }, []);
+    const markRenderStart = useCallback(() => {
+        const start = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        return () => {
+            const end = typeof performance !== 'undefined' ? performance.now() : Date.now();
+            const duration = Math.round((end - start) * 100) / 100;
+            setMetrics((prev) => ({ ...prev, lastRenderDuration: duration, renderCount: prev.renderCount + 1 }));
+        };
+    }, []);
+    const debounceMs = config.debounceMs;
+    const timersRef = useRef(new Set());
+    const debounce = useCallback((fn) => {
+        let timer = null;
+        const debounced = (...args) => {
+            if (timer) {
+                clearTimeout(timer);
+                timersRef.current.delete(timer);
+            }
+            timer = setTimeout(() => {
+                fn(...args);
+                if (timer)
+                    timersRef.current.delete(timer);
+            }, debounceMs);
+            timersRef.current.add(timer);
+        };
+        return debounced;
+    }, [debounceMs]);
+    // Cleanup all debounce timers
+    useEffect(() => {
+        const timers = timersRef.current;
+        return () => {
+            timers.forEach((t) => clearTimeout(t));
+            timers.clear();
+        };
+    }, []);
+    return useMemo(() => ({
+        config,
+        metrics,
+        markRenderStart,
+        debounce,
+    }), [config, metrics, markRenderStart, debounce]);
+}

package/dist/hooks/usePerformanceBudget.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+/** Metric names that can be tracked against a budget. */
+export type BudgetMetric = 'lcp' | 'fcp' | 'renderTime' | 'memory';
+/**
+ * Performance budget configuration.
+ * Defines thresholds for LCP, bundle size, render time, etc.
+ */
+export interface PerformanceBudget {
+    /** Max Largest Contentful Paint in ms (default: 600) */
+    maxLCP?: number;
+    /** Max First Contentful Paint in ms (default: 300) */
+    maxFCP?: number;
+    /** Max component render time in ms (default: 16) */
+    maxRenderTime?: number;
+    /** Max bundle size in KB (gzipped) - informational only */
+    maxBundleSizeKB?: number;
+    /** Max memory usage in MB */
+    maxMemoryMB?: number;
+    /** Whether to log warnings to console in dev mode (default: true) */
+    warnOnViolation?: boolean;
+    /** Callback when a budget is violated */
+    onViolation?: (violation: BudgetViolation) => void;
+}
+export interface BudgetViolation {
+    metric: BudgetMetric;
+    budget: number;
+    actual: number;
+    timestamp: number;
+}
+export interface PerformanceBudgetResult {
+    /** Current violations */
+    violations: BudgetViolation[];
+    /** Whether all budgets are within limits */
+    isWithinBudget: boolean;
+    /** Check if a specific metric is within budget */
+    checkMetric: (metric: BudgetMetric, value: number) => boolean;
+    /** Track a render and check against budget */
+    trackRender: (durationMs: number) => boolean;
+    /** Clear all recorded violations */
+    clearViolations: () => void;
+    /** Current performance snapshot */
+    snapshot: {
+        lcp: number | null;
+        fcp: number | null;
+        memoryMB: number | null;
+    };
+}
+/**
+ * Hook for performance budget enforcement aligned with ROADMAP Q3 3.3.
+ *
+ * Monitors Web Vitals (LCP, FCP), memory usage, and component render times
+ * against configurable thresholds. Violations are recorded, deduplicated,
+ * and optionally logged to the console in development mode.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const budget = usePerformanceBudget({
+ *     maxLCP: 500,
+ *     maxRenderTime: 16,
+ *     onViolation: (v) => analytics.track('perf_violation', v),
+ *   });
+ *
+ *   if (!budget.isWithinBudget) {
+ *     console.warn('Performance budget exceeded:', budget.violations);
+ *   }
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ */
+export declare function usePerformanceBudget(userBudget?: PerformanceBudget): PerformanceBudgetResult;

package/dist/hooks/usePerformanceBudget.js

@@ -0,0 +1,209 @@
+/**
+ * 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 = {
+    maxLCP: 600,
+    maxFCP: 300,
+    maxRenderTime: 16,
+    maxMemoryMB: 128,
+    warnOnViolation: true,
+};
+// ---------------------------------------------------------------------------
+// Helpers (same getFCP/getLCP pattern as usePerformance.ts)
+// ---------------------------------------------------------------------------
+function getFCP() {
+    if (typeof performance === 'undefined' || !performance.getEntriesByType)
+        return null;
+    try {
+        const entries = performance.getEntriesByType('paint');
+        const entry = entries.find((e) => e.name === 'first-contentful-paint');
+        return entry ? Math.round(entry.startTime) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getLCP() {
+    if (typeof performance === 'undefined' || !performance.getEntriesByType)
+        return null;
+    try {
+        const entries = performance.getEntriesByType('largest-contentful-paint');
+        const entry = entries.length > 0 ? entries[entries.length - 1] : undefined;
+        return entry ? Math.round(entry.startTime) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Chrome-only memory API (guarded). */
+function getMemoryMB() {
+    try {
+        const mem = performance.memory;
+        if (mem?.usedJSHeapSize != null) {
+            return Math.round((mem.usedJSHeapSize / (1024 * 1024)) * 100) / 100;
+        }
+    }
+    catch {
+        /* not available */
+    }
+    return null;
+}
+function buildViolationKey(metric) {
+    return metric;
+}
+// ---------------------------------------------------------------------------
+// usePerformanceBudget hook
+// ---------------------------------------------------------------------------
+/**
+ * Hook for performance budget enforcement aligned with ROADMAP Q3 3.3.
+ *
+ * Monitors Web Vitals (LCP, FCP), memory usage, and component render times
+ * against configurable thresholds. Violations are recorded, deduplicated,
+ * and optionally logged to the console in development mode.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const budget = usePerformanceBudget({
+ *     maxLCP: 500,
+ *     maxRenderTime: 16,
+ *     onViolation: (v) => analytics.track('perf_violation', v),
+ *   });
+ *
+ *   if (!budget.isWithinBudget) {
+ *     console.warn('Performance budget exceeded:', budget.violations);
+ *   }
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ */
+export function usePerformanceBudget(userBudget = {}) {
+    const budget = useMemo(() => ({
+        maxLCP: userBudget.maxLCP ?? DEFAULTS.maxLCP,
+        maxFCP: userBudget.maxFCP ?? DEFAULTS.maxFCP,
+        maxRenderTime: userBudget.maxRenderTime ?? DEFAULTS.maxRenderTime,
+        maxMemoryMB: userBudget.maxMemoryMB ?? DEFAULTS.maxMemoryMB,
+        warnOnViolation: userBudget.warnOnViolation ?? DEFAULTS.warnOnViolation,
+    }), [
+        userBudget.maxLCP,
+        userBudget.maxFCP,
+        userBudget.maxRenderTime,
+        userBudget.maxMemoryMB,
+        userBudget.warnOnViolation,
+    ]);
+    const onViolationRef = useRef(userBudget.onViolation);
+    useEffect(() => {
+        onViolationRef.current = userBudget.onViolation;
+    }, [userBudget.onViolation]);
+    const [violations, setViolations] = useState([]);
+    const seenRef = useRef(new Set());
+    const [snapshot, setSnapshot] = useState({ lcp: null, fcp: null, memoryMB: null });
+    // -------------------------------------------------------------------
+    // Violation recording with deduplication
+    // -------------------------------------------------------------------
+    const recordViolation = useCallback((metric, budgetValue, actual) => {
+        const key = buildViolationKey(metric);
+        if (seenRef.current.has(key))
+            return;
+        seenRef.current.add(key);
+        const violation = {
+            metric,
+            budget: budgetValue,
+            actual: Math.round(actual * 100) / 100,
+            timestamp: Date.now(),
+        };
+        setViolations((prev) => [...prev, violation]);
+        if (budget.warnOnViolation && process.env.NODE_ENV !== 'production') {
+            console.warn(`[ObjectUI] Performance budget violated: ${metric} = ${violation.actual} (budget: ${budgetValue})`);
+        }
+        onViolationRef.current?.(violation);
+    }, [budget.warnOnViolation]);
+    // -------------------------------------------------------------------
+    // Collect Web Vitals & memory on mount
+    // -------------------------------------------------------------------
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            const fcp = getFCP();
+            const lcp = getLCP();
+            const memoryMB = getMemoryMB();
+            setSnapshot({ lcp, fcp, memoryMB });
+            if (fcp != null && fcp > budget.maxFCP) {
+                recordViolation('fcp', budget.maxFCP, fcp);
+            }
+            if (lcp != null && lcp > budget.maxLCP) {
+                recordViolation('lcp', budget.maxLCP, lcp);
+            }
+            if (memoryMB != null && memoryMB > budget.maxMemoryMB) {
+                recordViolation('memory', budget.maxMemoryMB, memoryMB);
+            }
+        }, 0);
+        return () => clearTimeout(timer);
+    }, [budget.maxFCP, budget.maxLCP, budget.maxMemoryMB, recordViolation]);
+    // -------------------------------------------------------------------
+    // Periodic memory monitoring
+    // -------------------------------------------------------------------
+    useEffect(() => {
+        // Only run when memory API is available
+        if (getMemoryMB() == null)
+            return;
+        const interval = setInterval(() => {
+            const memoryMB = getMemoryMB();
+            if (memoryMB != null) {
+                setSnapshot((prev) => ({ ...prev, memoryMB }));
+                if (memoryMB > budget.maxMemoryMB) {
+                    recordViolation('memory', budget.maxMemoryMB, memoryMB);
+                }
+            }
+        }, 10000);
+        return () => clearInterval(interval);
+    }, [budget.maxMemoryMB, recordViolation]);
+    // -------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------
+    const checkMetric = useCallback((metric, value) => {
+        let threshold;
+        switch (metric) {
+            case 'lcp':
+                threshold = budget.maxLCP;
+                break;
+            case 'fcp':
+                threshold = budget.maxFCP;
+                break;
+            case 'renderTime':
+                threshold = budget.maxRenderTime;
+                break;
+            case 'memory':
+                threshold = budget.maxMemoryMB;
+                break;
+        }
+        const withinBudget = value <= threshold;
+        if (!withinBudget) {
+            recordViolation(metric, threshold, value);
+        }
+        return withinBudget;
+    }, [budget.maxLCP, budget.maxFCP, budget.maxRenderTime, budget.maxMemoryMB, recordViolation]);
+    const trackRender = useCallback((durationMs) => {
+        return checkMetric('renderTime', durationMs);
+    }, [checkMetric]);
+    const clearViolations = useCallback(() => {
+        setViolations([]);
+        seenRef.current.clear();
+    }, []);
+    return useMemo(() => ({
+        violations,
+        isWithinBudget: violations.length === 0,
+        checkMetric,
+        trackRender,
+        clearViolations,
+        snapshot,
+    }), [violations, checkMetric, trackRender, clearViolations, snapshot]);
+}

package/dist/hooks/useReducedMotion.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/**
+ * Hook that detects the user's motion preference.
+ * Implements MotionConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * Respects the `prefers-reduced-motion` media query to provide
+ * accessible animation experiences.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedCard() {
+ *   const prefersReducedMotion = useReducedMotion();
+ *
+ *   return (
+ *     <div className={prefersReducedMotion ? '' : 'animate-fade-in'}>
+ *       Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useReducedMotion(): boolean;

package/dist/hooks/useReducedMotion.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { useState, useEffect } from 'react';
+/**
+ * Hook that detects the user's motion preference.
+ * Implements MotionConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * Respects the `prefers-reduced-motion` media query to provide
+ * accessible animation experiences.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedCard() {
+ *   const prefersReducedMotion = useReducedMotion();
+ *
+ *   return (
+ *     <div className={prefersReducedMotion ? '' : 'animate-fade-in'}>
+ *       Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useReducedMotion() {
+    const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
+        if (typeof window === 'undefined')
+            return false;
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    });
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+        const handleChange = (event) => {
+            setPrefersReducedMotion(event.matches);
+        };
+        mediaQuery.addEventListener('change', handleChange);
+        return () => {
+            mediaQuery.removeEventListener('change', handleChange);
+        };
+    }, []);
+    return prefersReducedMotion;
+}

package/dist/hooks/useSchemaPersistence.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.
+ */
+/**
+ * Persistence adapter interface for schema save/load operations.
+ * Implement this to connect to any backend (REST API, GraphQL, localStorage, etc.).
+ */
+export interface SchemaPersistenceAdapter {
+    /** Save a schema to the backend. Returns the saved schema ID. */
+    save: (id: string, schema: Record<string, unknown>) => Promise<string>;
+    /** Load a schema from the backend by ID. */
+    load: (id: string) => Promise<Record<string, unknown> | null>;
+    /** List all available schemas. */
+    list?: () => Promise<Array<{
+        id: string;
+        name?: string;
+        updatedAt?: string;
+    }>>;
+    /** Delete a schema from the backend. */
+    delete?: (id: string) => Promise<void>;
+}
+export interface SchemaPersistenceState {
+    /** Whether a save/load operation is in progress */
+    loading: boolean;
+    /** The last error from a save/load operation */
+    error: Error | null;
+    /** Whether the current schema has unsaved changes */
+    isDirty: boolean;
+    /** The last saved timestamp */
+    lastSavedAt: Date | null;
+}
+export interface SchemaPersistenceResult extends SchemaPersistenceState {
+    /** Save the current schema */
+    save: (id: string, schema: Record<string, unknown>) => Promise<string | null>;
+    /** Load a schema by ID */
+    load: (id: string) => Promise<Record<string, unknown> | null>;
+    /** List available schemas */
+    list: () => Promise<Array<{
+        id: string;
+        name?: string;
+        updatedAt?: string;
+    }>>;
+    /** Delete a schema */
+    remove: (id: string) => Promise<boolean>;
+    /** Mark the current schema as dirty (has unsaved changes) */
+    markDirty: () => void;
+    /** Clear the error state */
+    clearError: () => void;
+}
+/**
+ * Default localStorage adapter for schema persistence.
+ * Useful for development and demos.
+ */
+export declare function createLocalStorageAdapter(prefix?: string): SchemaPersistenceAdapter;
+/**
+ * Hook for persisting designer schemas (save/load/list/delete).
+ * Implements schema persistence for @object-ui/plugin-designer.
+ *
+ * Accepts a pluggable adapter for connecting to any backend.
+ * Falls back to a localStorage adapter for development use.
+ *
+ * @example
+ * ```tsx
+ * // With default localStorage adapter
+ * const persistence = useSchemaPersistence();
+ *
+ * // Save current design
+ * await persistence.save('my-page', pageSchema);
+ *
+ * // Load a design
+ * const schema = await persistence.load('my-page');
+ *
+ * // With custom API adapter
+ * const apiAdapter: SchemaPersistenceAdapter = {
+ *   save: (id, schema) => fetch(`/api/schemas/${id}`, { method: 'PUT', body: JSON.stringify(schema) }).then(r => r.json()),
+ *   load: (id) => fetch(`/api/schemas/${id}`).then(r => r.json()),
+ *   list: () => fetch('/api/schemas').then(r => r.json()),
+ *   delete: (id) => fetch(`/api/schemas/${id}`, { method: 'DELETE' }).then(() => {}),
+ * };
+ * const persistence = useSchemaPersistence(apiAdapter);
+ * ```
+ */
+export declare function useSchemaPersistence(adapter?: SchemaPersistenceAdapter): SchemaPersistenceResult;