@object-ui/react 0.5.0 → 3.0.0

package/src/hooks/usePerformance.ts

@@ -0,0 +1,246 @@
+/**
+ * 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/spec v2.0.7 PerformanceConfigSchema
+// ---------------------------------------------------------------------------
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+  lazyLoad: true,
+  cacheStrategy: 'stale-while-revalidate' as CacheStrategyType,
+  prefetch: false,
+  pageSize: 50,
+  debounceMs: 300,
+  virtualScroll: {
+    enabled: false,
+    itemHeight: 40,
+    overscan: 5,
+  },
+} as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+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;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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: PerformanceConfig = {}): PerformanceResult {
+  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<PerformanceMetrics>({
+    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((): (() => void) => {
+    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<Set<ReturnType<typeof setTimeout>>>(new Set());
+
+  const debounce = useCallback(
+    <T extends (...args: unknown[]) => void>(fn: T): T => {
+      let timer: ReturnType<typeof setTimeout> | null = null;
+      const debounced = (...args: unknown[]) => {
+        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 as unknown as T;
+    },
+    [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/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;
+}