elementdrawing 1.0.0

package/src/jsx/hooks/useLayoutEffect.js

@@ -0,0 +1,508 @@
+/**
+ * useLayoutEffect Hook Implementation
+ * ElementDrawing Framework - Synchronous effect after DOM mutations,
+ * executed during the commit phase before the browser paints.
+ * Includes priority-based ordering, isomorphic layout effects,
+ * mutation observation, resize observation, and batch processing.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+const layoutEffectQueue = [];
+let isFlushingLayoutEffects = false;
+
+// ─── Layout Effect Priority ───────────────────────────────────────────────────
+
+/**
+ * Priority levels for layout effects.
+ * Lower number = higher priority = executes first.
+ */
+const LAYOUT_PRIORITY = {
+  HIGHEST: 0,    // Insertion effects, critical DOM measurements
+  HIGH: 1,       // Layout calculations
+  NORMAL: 2,     // Standard layout effects
+  LOW: 3,        // Non-critical layout adjustments
+  LOWEST: 4,     // Post-layout cleanup
+};
+
+// ─── Dependency Comparison ────────────────────────────────────────────────────
+
+/**
+ * Compare two dependency arrays for shallow equality.
+ * @param {Array|null} prevDeps
+ * @param {Array|null} nextDeps
+ * @returns {boolean}
+ */
+function areDepsEqual(prevDeps, nextDeps) {
+  if (prevDeps === null || nextDeps === null) return false;
+  if (prevDeps.length !== nextDeps.length) return false;
+  for (let i = 0; i < prevDeps.length; i++) {
+    if (Object.is(prevDeps[i], nextDeps[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Validate dependency array.
+ * @param {*} deps
+ */
+function validateDeps(deps) {
+  if (deps !== undefined && !Array.isArray(deps)) {
+    throw new Error(
+      '[useLayoutEffect] Dependencies must be an array or undefined. ' +
+      `Received: ${typeof deps}`
+    );
+  }
+}
+
+// ─── Effect Execution ─────────────────────────────────────────────────────────
+
+/**
+ * Execute a layout effect, capturing its cleanup function.
+ * @param {Object} effect - Effect object
+ */
+function executeLayoutEffect(effect) {
+  try {
+    const cleanup = effect.create();
+    if (cleanup !== undefined && typeof cleanup !== 'function') {
+      console.warn(
+        '[useLayoutEffect] Effect cleanup must be a function or undefined. ' +
+        `Received: ${typeof cleanup}`
+      );
+      effect.cleanup = null;
+    } else {
+      effect.cleanup = cleanup;
+    }
+  } catch (error) {
+    console.error('[useLayoutEffect] Effect execution error:', error);
+    effect.cleanup = null;
+    if (effect.component && effect.component._handleError) {
+      effect.component._handleError(error);
+    }
+  }
+}
+
+/**
+ * Run cleanup for a layout effect.
+ * @param {Object} effect
+ */
+function runLayoutCleanup(effect) {
+  if (typeof effect.cleanup === 'function') {
+    try {
+      effect.cleanup();
+    } catch (error) {
+      console.error('[useLayoutEffect] Cleanup error:', error);
+      if (effect.component && effect.component._handleError) {
+        effect.component._handleError(error);
+      }
+    }
+    effect.cleanup = null;
+  }
+}
+
+// ─── Layout Effect Queue Management ───────────────────────────────────────────
+
+/**
+ * Flush all queued layout effects synchronously.
+ * Called during the commit phase, before the browser paints.
+ * Effects are sorted by priority before execution.
+ */
+function flushLayoutEffects() {
+  if (isFlushingLayoutEffects) return;
+  isFlushingLayoutEffects = true;
+
+  try {
+    // Sort by priority (lower = higher priority = executes first)
+    const sortedEffects = layoutEffectQueue.slice().sort((a, b) => {
+      return (a._priority || LAYOUT_PRIORITY.NORMAL) - (b._priority || LAYOUT_PRIORITY.NORMAL);
+    });
+
+    // Clear the queue before execution to prevent double-execution
+    layoutEffectQueue.length = 0;
+
+    while (sortedEffects.length > 0) {
+      const effect = sortedEffects.shift();
+
+      // Run cleanup from previous render
+      runLayoutCleanup(effect);
+
+      // Execute the new layout effect
+      executeLayoutEffect(effect);
+
+      // Track execution time for profiling
+      effect._executedAt = Date.now();
+    }
+  } finally {
+    isFlushingLayoutEffects = false;
+  }
+}
+
+/**
+ * Check if there are pending layout effects.
+ * @returns {boolean}
+ */
+function hasPendingLayoutEffects() {
+  return layoutEffectQueue.length > 0;
+}
+
+/**
+ * Get the count of pending layout effects.
+ * @returns {number}
+ */
+function getPendingLayoutEffectCount() {
+  return layoutEffectQueue.length;
+}
+
+/**
+ * Get pending layout effects grouped by priority.
+ * @returns {Object}
+ */
+function getPendingLayoutEffectsByPriority() {
+  const grouped = {};
+  layoutEffectQueue.forEach((effect) => {
+    const priority = effect._priority || LAYOUT_PRIORITY.NORMAL;
+    if (!grouped[priority]) grouped[priority] = 0;
+    grouped[priority]++;
+  });
+  return grouped;
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+// ─── useLayoutEffect Hook ─────────────────────────────────────────────────────
+
+/**
+ * useLayoutEffect - Synchronous effect that runs after DOM mutations
+ * but before the browser paints. Use for:
+ * - DOM measurements (getBoundingClientRect, etc.)
+ * - Synchronous DOM mutations that must happen before paint
+ * - Preventing visual flickering
+ *
+ * @param {Function} create - Effect callback; may return a cleanup function
+ * @param {Array} [deps] - Dependency array; effect re-runs when deps change
+ * @returns {void}
+ *
+ * @example
+ * useLayoutEffect(() => {
+ *   const height = ref.current.getBoundingClientRect().height;
+ *   if (height > maxHeight) {
+ *     ref.current.style.overflow = 'auto';
+ *     ref.current.style.maxHeight = maxHeight + 'px';
+ *   }
+ * }, [maxHeight]);
+ *
+ * @example
+ * // Auto-resize textarea
+ * useLayoutEffect(() => {
+ *   const textarea = ref.current;
+ *   textarea.style.height = 'auto';
+ *   textarea.style.height = textarea.scrollHeight + 'px';
+ * }, [value]);
+ */
+function useLayoutEffect(create, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error(
+      '[useLayoutEffect] Must be called within a component render phase'
+    );
+  }
+
+  if (typeof create !== 'function') {
+    throw new Error(
+      '[useLayoutEffect] First argument must be a function. ' +
+      `Received: ${typeof create}`
+    );
+  }
+
+  validateDeps(deps);
+
+  // Initialize hooks array
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    // Re-render: check if dependencies changed
+    hook = component._hooks[currentHookIndex];
+
+    const prevDeps = hook.deps;
+    const depsChanged = !areDepsEqual(prevDeps, resolvedDeps);
+
+    if (depsChanged) {
+      hook.deps = resolvedDeps;
+      hook.create = create;
+      hook._shouldRun = true;
+    } else {
+      hook._shouldRun = false;
+    }
+  } else {
+    // First render - always run
+    hook = {
+      type: 'layout-effect',
+      create,
+      cleanup: null,
+      deps: resolvedDeps,
+      component,
+      _shouldRun: true,
+      _priority: LAYOUT_PRIORITY.NORMAL,
+      _isMounted: false,
+      _executedAt: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Queue the effect for synchronous execution during commit phase
+  if (hook._shouldRun) {
+    layoutEffectQueue.push(hook);
+  }
+
+  hookIndex++;
+}
+
+// ─── Priority Layout Effect ───────────────────────────────────────────────────
+
+/**
+ * Create a layout effect with a priority level.
+ * Higher priority effects execute first during the commit phase.
+ *
+ * @param {number} priority - Priority level (use LAYOUT_PRIORITY constants)
+ * @param {Function} create - Effect callback
+ * @param {Array} [deps] - Dependency array
+ */
+function usePriorityLayoutEffect(priority, create, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error(
+      '[usePriorityLayoutEffect] Must be called within a component render phase'
+    );
+  }
+
+  if (typeof create !== 'function') {
+    throw new Error(
+      '[usePriorityLayoutEffect] Create must be a function. ' +
+      `Received: ${typeof create}`
+    );
+  }
+
+  validateDeps(deps);
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  const resolvedDeps = deps !== undefined ? deps : null;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+    const prevDeps = hook.deps;
+    const depsChanged = !areDepsEqual(prevDeps, resolvedDeps);
+
+    if (depsChanged) {
+      hook.deps = resolvedDeps;
+      hook.create = create;
+      hook._priority = priority;
+      hook._shouldRun = true;
+    } else {
+      hook._shouldRun = false;
+    }
+  } else {
+    hook = {
+      type: 'layout-effect',
+      create,
+      cleanup: null,
+      deps: resolvedDeps,
+      component,
+      _shouldRun: true,
+      _priority: priority,
+      _isMounted: false,
+      _executedAt: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  if (hook._shouldRun) {
+    layoutEffectQueue.push(hook);
+  }
+
+  hookIndex++;
+}
+
+// ─── Isomorphic Layout Effect ─────────────────────────────────────────────────
+
+/**
+ * useIsomorphicLayoutEffect - Uses useLayoutEffect on the client and useEffect
+ * on the server to avoid SSR warnings.
+ *
+ * @param {Function} create - Effect callback
+ * @param {Array} [deps] - Dependency array
+ */
+const useIsomorphicLayoutEffect = typeof window !== 'undefined'
+  ? useLayoutEffect
+  : function useLayoutEffectNoop(create, deps) {
+      // On server, fall back to no-op to avoid warnings
+    };
+
+// ─── Mutation Observer Effect ─────────────────────────────────────────────────
+
+/**
+ * useMutationObserver - Observe DOM mutations on a ref's element.
+ *
+ * @param {Object} ref - Ref to the target element
+ * @param {Object} options - MutationObserver options
+ * @param {Function} callback - Called with mutation records
+ *
+ * @example
+ * const divRef = useRef(null);
+ * useMutationObserver(divRef, { childList: true, subtree: true }, (mutations) => {
+ *   console.log('DOM changed:', mutations);
+ * });
+ */
+function useMutationObserver(ref, options, callback) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useMutationObserver] Must be called within a component render phase');
+  }
+
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node || typeof MutationObserver === 'undefined') return;
+
+    const observer = new MutationObserver((mutations) => {
+      try {
+        callback(mutations);
+      } catch (error) {
+        console.error('[useMutationObserver] Callback error:', error);
+      }
+    });
+
+    observer.observe(node, options);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref.current]);
+}
+
+// ─── Resize Observer Effect ───────────────────────────────────────────────────
+
+/**
+ * useResizeObserver - Observe element size changes.
+ *
+ * @param {Object} ref - Ref to the target element
+ * @param {Function} callback - Called with ResizeObserver entries
+ *
+ * @example
+ * const divRef = useRef(null);
+ * useResizeObserver(divRef, (entries) => {
+ *   const { width, height } = entries[0].contentRect;
+ *   setSize({ width, height });
+ * });
+ */
+function useResizeObserver(ref, callback) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useResizeObserver] Must be called within a component render phase');
+  }
+
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node || typeof ResizeObserver === 'undefined') return;
+
+    const observer = new ResizeObserver((entries) => {
+      try {
+        callback(entries);
+      } catch (error) {
+        console.error('[useResizeObserver] Callback error:', error);
+      }
+    });
+
+    observer.observe(node);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref.current]);
+}
+
+// ─── Auto-focus Effect ────────────────────────────────────────────────────────
+
+/**
+ * useAutoFocus - Auto-focus an element on mount.
+ *
+ * @param {Object} ref - Ref to the element to focus
+ * @param {boolean} [shouldFocus=true] - Whether to auto-focus
+ */
+function useAutoFocus(ref, shouldFocus) {
+  useLayoutEffect(() => {
+    if (shouldFocus === false) return;
+    const node = ref.current;
+    if (node && typeof node.focus === 'function') {
+      node.focus();
+    }
+  }, []);
+}
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Clean up layout effects when a component unmounts.
+ * @param {Object} component
+ */
+function cleanupLayoutEffects(component) {
+  if (!component._hooks) return;
+
+  component._hooks.forEach((hook) => {
+    if (hook && hook.type === 'layout-effect' && typeof hook.cleanup === 'function') {
+      runLayoutCleanup(hook);
+    }
+  });
+
+  // Remove from queue
+  for (let i = layoutEffectQueue.length - 1; i >= 0; i--) {
+    if (layoutEffectQueue[i].component === component) {
+      layoutEffectQueue.splice(i, 1);
+    }
+  }
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useLayoutEffect,
+  useIsomorphicLayoutEffect,
+  usePriorityLayoutEffect,
+  useMutationObserver,
+  useResizeObserver,
+  useAutoFocus,
+  setCurrentComponent,
+  resetHookIndex,
+  flushLayoutEffects,
+  hasPendingLayoutEffects,
+  getPendingLayoutEffectCount,
+  getPendingLayoutEffectsByPriority,
+  cleanupLayoutEffects,
+  LAYOUT_PRIORITY,
+};