@object-ui/react 2.0.0 → 3.0.0

package/src/hooks/usePageTransition.ts

@@ -0,0 +1,187 @@
+/**
+ * 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/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],
+  );
+}