@object-ui/react 2.0.0 → 3.0.0

package/src/hooks/usePerformanceBudget.ts

@@ -0,0 +1,313 @@
+/**
+ * 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 for performance budget enforcement
+// ---------------------------------------------------------------------------
+
+/** 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;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+  maxLCP: 600,
+  maxFCP: 300,
+  maxRenderTime: 16,
+  maxMemoryMB: 128,
+  warnOnViolation: true,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Helpers (same getFCP/getLCP pattern as usePerformance.ts)
+// ---------------------------------------------------------------------------
+
+function getFCP(): number | null {
+  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(): number | null {
+  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(): number | null {
+  try {
+    const mem = (performance as unknown as { memory?: { usedJSHeapSize?: number } }).memory;
+    if (mem?.usedJSHeapSize != null) {
+      return Math.round((mem.usedJSHeapSize / (1024 * 1024)) * 100) / 100;
+    }
+  } catch {
+    /* not available */
+  }
+  return null;
+}
+
+function buildViolationKey(metric: BudgetMetric): string {
+  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: PerformanceBudget = {},
+): PerformanceBudgetResult {
+  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<BudgetViolation[]>([]);
+  const seenRef = useRef<Set<string>>(new Set());
+
+  const [snapshot, setSnapshot] = useState<{
+    lcp: number | null;
+    fcp: number | null;
+    memoryMB: number | null;
+  }>({ lcp: null, fcp: null, memoryMB: null });
+
+  // -------------------------------------------------------------------
+  // Violation recording with deduplication
+  // -------------------------------------------------------------------
+
+  const recordViolation = useCallback(
+    (metric: BudgetMetric, budgetValue: number, actual: number) => {
+      const key = buildViolationKey(metric);
+      if (seenRef.current.has(key)) return;
+      seenRef.current.add(key);
+
+      const violation: BudgetViolation = {
+        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);
+        }
+      }
+    }, 10_000);
+
+    return () => clearInterval(interval);
+  }, [budget.maxMemoryMB, recordViolation]);
+
+  // -------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------
+
+  const checkMetric = useCallback(
+    (metric: BudgetMetric, value: number): boolean => {
+      let threshold: number;
+      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: number): boolean => {
+      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/src/hooks/useReducedMotion.ts

@@ -0,0 +1,53 @@
+/**
+ * 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(): boolean {
+  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: MediaQueryListEvent) => {
+      setPrefersReducedMotion(event.matches);
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+    return () => {
+      mediaQuery.removeEventListener('change', handleChange);
+    };
+  }, []);
+
+  return prefersReducedMotion;
+}

package/src/hooks/useSchemaPersistence.ts

@@ -0,0 +1,222 @@
+/**
+ * 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, useCallback, useRef, useMemo } from 'react';
+
+/**
+ * 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 function createLocalStorageAdapter(prefix = 'objectui-schema'): SchemaPersistenceAdapter {
+  return {
+    async save(id: string, schema: Record<string, unknown>): Promise<string> {
+      const key = `${prefix}:${id}`;
+      const entry = { schema, updatedAt: new Date().toISOString() };
+      localStorage.setItem(key, JSON.stringify(entry));
+      // Update the index
+      const indexKey = `${prefix}:__index__`;
+      const index: string[] = JSON.parse(localStorage.getItem(indexKey) || '[]');
+      if (!index.includes(id)) {
+        index.push(id);
+        localStorage.setItem(indexKey, JSON.stringify(index));
+      }
+      return id;
+    },
+    async load(id: string): Promise<Record<string, unknown> | null> {
+      const key = `${prefix}:${id}`;
+      const raw = localStorage.getItem(key);
+      if (!raw) return null;
+      const entry = JSON.parse(raw);
+      return entry.schema ?? null;
+    },
+    async list(): Promise<Array<{ id: string; name?: string; updatedAt?: string }>> {
+      const indexKey = `${prefix}:__index__`;
+      const index: string[] = JSON.parse(localStorage.getItem(indexKey) || '[]');
+      return index.map((id) => {
+        const raw = localStorage.getItem(`${prefix}:${id}`);
+        const entry = raw ? JSON.parse(raw) : {};
+        return { id, name: id, updatedAt: entry.updatedAt };
+      });
+    },
+    async delete(id: string): Promise<void> {
+      const key = `${prefix}:${id}`;
+      localStorage.removeItem(key);
+      const indexKey = `${prefix}:__index__`;
+      const index: string[] = JSON.parse(localStorage.getItem(indexKey) || '[]');
+      localStorage.setItem(indexKey, JSON.stringify(index.filter((i) => i !== id)));
+    },
+  };
+}
+
+/**
+ * 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 function useSchemaPersistence(
+  adapter?: SchemaPersistenceAdapter,
+): SchemaPersistenceResult {
+  const defaultAdapter = useRef(createLocalStorageAdapter());
+  const adapterRef = useRef(adapter ?? defaultAdapter.current);
+  // Keep the ref up to date if the adapter prop changes
+  adapterRef.current = adapter ?? defaultAdapter.current;
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [isDirty, setIsDirty] = useState(false);
+  const [lastSavedAt, setLastSavedAt] = useState<Date | null>(null);
+
+  const save = useCallback(
+    async (id: string, schema: Record<string, unknown>): Promise<string | null> => {
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await adapterRef.current.save(id, schema);
+        setIsDirty(false);
+        setLastSavedAt(new Date());
+        return result;
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [],
+  );
+
+  const load = useCallback(async (id: string): Promise<Record<string, unknown> | null> => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await adapterRef.current.load(id);
+      setIsDirty(false);
+      return result;
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      return null;
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const list = useCallback(async (): Promise<Array<{ id: string; name?: string; updatedAt?: string }>> => {
+    setLoading(true);
+    setError(null);
+    try {
+      if (adapterRef.current.list) {
+        return await adapterRef.current.list();
+      }
+      return [];
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      return [];
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const remove = useCallback(async (id: string): Promise<boolean> => {
+    setLoading(true);
+    setError(null);
+    try {
+      if (adapterRef.current.delete) {
+        await adapterRef.current.delete(id);
+        return true;
+      }
+      return false;
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      return false;
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const markDirty = useCallback(() => setIsDirty(true), []);
+  const clearError = useCallback(() => setError(null), []);
+
+  return useMemo(
+    () => ({
+      loading,
+      error,
+      isDirty,
+      lastSavedAt,
+      save,
+      load,
+      list,
+      remove,
+      markDirty,
+      clearError,
+    }),
+    [loading, error, isDirty, lastSavedAt, save, load, list, remove, markDirty, clearError],
+  );
+}