elementdrawing 1.0.0

package/src/jsx/hooks/useEffect.js

@@ -0,0 +1,704 @@
+/**
+ * useEffect Hook Implementation
+ * ElementDrawing Framework - Effect hooks with dependency tracking,
+ * cleanup, scheduling, batching, passive/layout/insertion effects,
+ * strict mode support, effect grouping, and cancellation.
+ */
+
+'use strict';
+
+// ─── Effect Types ─────────────────────────────────────────────────────────────
+
+const EFFECT_TYPES = {
+  PASSIVE: 'passive',       // useEffect - runs after paint
+  LAYOUT: 'layout',         // useLayoutEffect - runs before paint
+  INSERTION: 'insertion',   // useInsertionEffect - runs before DOM mutations
+};
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+const effectQueue = [];
+const layoutEffectQueue = [];
+const insertionEffectQueue = [];
+let isFlushingEffects = false;
+let isFlushingLayoutEffects = false;
+let isFlushingInsertionEffects = false;
+
+// ─── Strict Mode ──────────────────────────────────────────────────────────────
+
+let isStrictMode = false;
+
+/**
+ * Enable or disable strict mode. In strict mode, effects are double-invoked
+ * on mount to help find side-effect cleanup issues.
+ * @param {boolean} enabled
+ */
+function setStrictMode(enabled) {
+  isStrictMode = enabled;
+}
+
+/**
+ * Check if strict mode is enabled.
+ * @returns {boolean}
+ */
+function isInStrictMode() {
+  return isStrictMode;
+}
+
+// ─── Dependency Comparison ────────────────────────────────────────────────────
+
+/**
+ * Compare two dependency arrays for equality.
+ * @param {Array|null} prevDeps - Previous dependencies
+ * @param {Array|null} nextDeps - Next dependencies
+ * @returns {boolean} True if dependencies are the same
+ */
+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;
+}
+
+/**
+ * Deep dependency comparison for complex dependency values.
+ * @param {Array|null} prevDeps
+ * @param {Array|null} nextDeps
+ * @returns {boolean}
+ */
+function areDepsDeepEqual(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 (deepEqualValue(prevDeps[i], nextDeps[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Deep equal comparison for individual values.
+ */
+function deepEqualValue(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!deepEqualValue(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Validate that dependencies is an array or undefined.
+ * @param {*} deps - Dependencies to validate
+ */
+function validateDeps(deps) {
+  if (deps !== undefined && !Array.isArray(deps)) {
+    throw new Error(
+      '[useEffect] Dependencies must be an array or undefined. ' +
+      `Received: ${typeof deps}`
+    );
+  }
+}
+
+// ─── Effect Execution ─────────────────────────────────────────────────────────
+
+/**
+ * Execute an effect, capturing its cleanup function.
+ * @param {Object} effect - Effect object with create function
+ * @returns {Function|null} Cleanup function
+ */
+function executeEffect(effect) {
+  try {
+    const cleanup = effect.create();
+    if (cleanup !== undefined && typeof cleanup !== 'function') {
+      console.warn(
+        '[useEffect] Effect cleanup must be a function or undefined. ' +
+        `Received: ${typeof cleanup}`
+      );
+      effect.cleanup = null;
+    } else {
+      effect.cleanup = cleanup;
+    }
+  } catch (error) {
+    console.error('[useEffect] Effect execution error:', error);
+    effect.cleanup = null;
+
+    // Call error boundary if available
+    if (effect.component && effect.component._handleError) {
+      effect.component._handleError(error);
+    }
+  }
+  return effect.cleanup;
+}
+
+/**
+ * Run cleanup for an effect.
+ * @param {Object} effect - Effect object with cleanup function
+ */
+function runCleanup(effect) {
+  if (typeof effect.cleanup === 'function') {
+    try {
+      effect.cleanup();
+    } catch (error) {
+      console.error('[useEffect] Cleanup error:', error);
+      if (effect.component && effect.component._handleError) {
+        effect.component._handleError(error);
+      }
+    }
+    effect.cleanup = null;
+  }
+}
+
+/**
+ * Execute an effect in strict mode (double-invoke on mount).
+ * @param {Object} effect - Effect to execute
+ */
+function executeEffectStrictMode(effect) {
+  // First invocation
+  executeEffect(effect);
+
+  // Immediately cleanup and re-invoke in strict mode
+  runCleanup(effect);
+  executeEffect(effect);
+}
+
+// ─── Effect Scheduling ────────────────────────────────────────────────────────
+
+/**
+ * Schedule passive effects to run after the browser paint.
+ */
+function schedulePassiveEffects() {
+  if (effectQueue.length === 0) return;
+
+  // Use requestAnimationFrame then setTimeout to ensure effects run after paint
+  requestAnimationFrame(() => {
+    setTimeout(() => {
+      flushPassiveEffects();
+    }, 0);
+  });
+}
+
+/**
+ * Flush all queued passive effects.
+ */
+function flushPassiveEffects() {
+  if (isFlushingEffects) return;
+  isFlushingEffects = true;
+
+  try {
+    // Process all queued passive effects
+    while (effectQueue.length > 0) {
+      const effect = effectQueue.shift();
+
+      // Run cleanup from previous render first
+      runCleanup(effect);
+
+      // Execute the new effect
+      if (isStrictMode && !effect._hasRunBefore) {
+        executeEffectStrictMode(effect);
+        effect._hasRunBefore = true;
+      } else {
+        executeEffect(effect);
+      }
+    }
+  } finally {
+    isFlushingEffects = false;
+  }
+}
+
+/**
+ * Flush all queued layout effects (synchronous, before paint).
+ */
+function flushLayoutEffects() {
+  if (isFlushingLayoutEffects) return;
+  isFlushingLayoutEffects = true;
+
+  try {
+    while (layoutEffectQueue.length > 0) {
+      const effect = layoutEffectQueue.shift();
+      runCleanup(effect);
+
+      if (isStrictMode && !effect._hasRunBefore) {
+        executeEffectStrictMode(effect);
+        effect._hasRunBefore = true;
+      } else {
+        executeEffect(effect);
+      }
+    }
+  } finally {
+    isFlushingLayoutEffects = false;
+  }
+}
+
+/**
+ * Flush all queued insertion effects (synchronous, before DOM mutations).
+ */
+function flushInsertionEffects() {
+  if (isFlushingInsertionEffects) return;
+  isFlushingInsertionEffects = true;
+
+  try {
+    while (insertionEffectQueue.length > 0) {
+      const effect = insertionEffectQueue.shift();
+      runCleanup(effect);
+      executeEffect(effect);
+    }
+  } finally {
+    isFlushingInsertionEffects = false;
+  }
+}
+
+/**
+ * Flush effects in the correct order: insertion -> layout -> passive.
+ */
+function flushAllEffects() {
+  flushInsertionEffects();
+  flushLayoutEffects();
+  schedulePassiveEffects();
+}
+
+// ─── Effect Cancellation ──────────────────────────────────────────────────────
+
+/**
+ * Cancel a pending effect by reference.
+ * @param {Object} effect - The effect to cancel
+ * @returns {boolean} True if successfully cancelled
+ */
+function cancelEffect(effect) {
+  if (!effect) return false;
+
+  let removed = false;
+
+  // Try to remove from passive queue
+  const passiveIdx = effectQueue.indexOf(effect);
+  if (passiveIdx !== -1) {
+    effectQueue.splice(passiveIdx, 1);
+    removed = true;
+  }
+
+  // Try to remove from layout queue
+  const layoutIdx = layoutEffectQueue.indexOf(effect);
+  if (layoutIdx !== -1) {
+    layoutEffectQueue.splice(layoutIdx, 1);
+    removed = true;
+  }
+
+  // Try to remove from insertion queue
+  const insertionIdx = insertionEffectQueue.indexOf(effect);
+  if (insertionIdx !== -1) {
+    insertionEffectQueue.splice(insertionIdx, 1);
+    removed = true;
+  }
+
+  // Run cleanup if the effect had been previously executed
+  if (removed) {
+    runCleanup(effect);
+  }
+
+  return removed;
+}
+
+// ─── Effect Grouping ──────────────────────────────────────────────────────────
+
+/**
+ * Group effects together so they execute as a batch.
+ * @param {Function} callback - Function containing effectful operations
+ * @returns {Array} Array of effect objects created in the group
+ */
+const activeEffectGroup = { current: null };
+
+function beginEffectGroup() {
+  activeEffectGroup.current = [];
+}
+
+function endEffectGroup() {
+  const group = activeEffectGroup.current;
+  activeEffectGroup.current = null;
+  return group;
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+// ─── Core Effect Hook ─────────────────────────────────────────────────────────
+
+/**
+ * Internal implementation shared by all effect hooks.
+ *
+ * @param {Function} create - Effect callback (returns cleanup or undefined)
+ * @param {Array|undefined} deps - Dependency array
+ * @param {string} effectType - Type of effect (passive, layout, insertion)
+ * @returns {void}
+ */
+function useEffectImpl(create, deps, effectType) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error(
+      `[use${effectType}Effect] Must be called within a component render phase`
+    );
+  }
+
+  if (typeof create !== 'function') {
+    throw new Error(
+      `[use${effectType}Effect] 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) {
+      // Dependencies changed - queue the effect
+      hook.deps = resolvedDeps;
+      hook.create = create;
+      hook.type = effectType;
+      hook.component = component;
+      hook._shouldRun = true;
+    } else {
+      // Dependencies unchanged - skip the effect
+      hook._shouldRun = false;
+    }
+  } else {
+    // First render - always run the effect
+    hook = {
+      type: effectType,
+      create,
+      cleanup: null,
+      deps: resolvedDeps,
+      component,
+      _shouldRun: true,
+      _isMounted: false,
+      _hasRunBefore: false,
+      _createdAt: Date.now(),
+      _effectId: ++effectIdCounter,
+    };
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Queue the effect if it should run
+  if (hook._shouldRun) {
+    switch (effectType) {
+      case EFFECT_TYPES.PASSIVE:
+        effectQueue.push(hook);
+        break;
+      case EFFECT_TYPES.LAYOUT:
+        layoutEffectQueue.push(hook);
+        break;
+      case EFFECT_TYPES.INSERTION:
+        insertionEffectQueue.push(hook);
+        break;
+    }
+
+    // Track in active effect group if one exists
+    if (activeEffectGroup.current) {
+      activeEffectGroup.current.push(hook);
+    }
+  }
+
+  hookIndex++;
+}
+
+let effectIdCounter = 0;
+
+// ─── Public Hooks ─────────────────────────────────────────────────────────────
+
+/**
+ * useEffect - Schedule a passive effect that runs after the browser paint.
+ * Ideal for side effects that don't need to block visual updates.
+ *
+ * @param {Function} create - Effect callback, may return a cleanup function
+ * @param {Array} [deps] - Dependency array; effect re-runs when deps change
+ *
+ * @example
+ * useEffect(() => {
+ *   const subscription = api.subscribe(data => setData(data));
+ *   return () => subscription.unsubscribe();
+ * }, [api]);
+ */
+function useEffect(create, deps) {
+  useEffectImpl(create, deps, EFFECT_TYPES.PASSIVE);
+}
+
+/**
+ * useLayoutEffect - Schedule a layout effect that runs synchronously after
+ * all DOM mutations but before the browser paint.
+ *
+ * @param {Function} create - Effect callback, may return a cleanup function
+ * @param {Array} [deps] - Dependency array
+ *
+ * @example
+ * useLayoutEffect(() => {
+ *   const height = ref.current.clientHeight;
+ *   setTooltipPosition(calculatePosition(height));
+ * }, [ref.current]);
+ */
+function useLayoutEffect(create, deps) {
+  useEffectImpl(create, deps, EFFECT_TYPES.LAYOUT);
+}
+
+/**
+ * useInsertionEffect - Schedule an insertion effect that runs before DOM
+ * mutations. Primarily for CSS-in-JS libraries.
+ *
+ * @param {Function} create - Effect callback, may return a cleanup function
+ * @param {Array} [deps] - Dependency array
+ */
+function useInsertionEffect(create, deps) {
+  useEffectImpl(create, deps, EFFECT_TYPES.INSERTION);
+}
+
+// ─── Custom Effect Hooks ──────────────────────────────────────────────────────
+
+/**
+ * useDeepCompareEffect - Like useEffect but uses deep comparison for deps.
+ * Useful when dependencies are objects or arrays that may be recreated.
+ *
+ * @param {Function} create - Effect callback
+ * @param {Array} deps - Dependency array (compared deeply)
+ */
+function useDeepCompareEffect(create, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useDeepCompareEffect] Must be called within a component render phase');
+  }
+
+  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 = !areDepsDeepEqual(prevDeps, resolvedDeps);
+
+    if (depsChanged) {
+      hook.deps = resolvedDeps;
+      hook.create = create;
+      hook._shouldRun = true;
+    } else {
+      hook._shouldRun = false;
+    }
+  } else {
+    hook = {
+      type: EFFECT_TYPES.PASSIVE,
+      create,
+      cleanup: null,
+      deps: resolvedDeps,
+      component,
+      _shouldRun: true,
+      _isMounted: false,
+      _hasRunBefore: false,
+      _createdAt: Date.now(),
+      _effectId: ++effectIdCounter,
+    };
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  if (hook._shouldRun) {
+    effectQueue.push(hook);
+  }
+
+  hookIndex++;
+}
+
+/**
+ * useEffectOnce - Effect that only runs once on mount, like componentDidMount.
+ * @param {Function} create - Effect callback
+ */
+function useEffectOnce(create) {
+  useEffect(create, []);
+}
+
+/**
+ * useUpdateEffect - Effect that skips the first render (only runs on updates).
+ * @param {Function} create - Effect callback
+ * @param {Array} deps - Dependency array
+ */
+function useUpdateEffect(create, deps) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useUpdateEffect] Must be called within a component render phase');
+  }
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+  } else {
+    hook = {
+      _isFirstRender: true,
+    };
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  const isFirst = hook._isFirstRender;
+  hook._isFirstRender = false;
+
+  if (isFirst) {
+    // Skip the first render, but still track deps
+    const resolvedDeps = deps !== undefined ? deps : null;
+    hook.deps = resolvedDeps;
+    hookIndex++;
+    return;
+  }
+
+  useEffectImpl(create, deps, EFFECT_TYPES.PASSIVE);
+}
+
+// ─── Effect Batching ──────────────────────────────────────────────────────────
+
+/**
+ * Batch multiple effectful operations. All effects created within the
+ * callback will be collected and flushed together.
+ *
+ * @param {Function} callback - Function containing effectful operations
+ * @returns {*} Return value of the callback
+ */
+function batchEffects(callback) {
+  const prevFlushingState = isFlushingEffects;
+  isFlushingEffects = true;
+
+  try {
+    return callback();
+  } finally {
+    isFlushingEffects = prevFlushingState;
+  }
+}
+
+// ─── Effect Debug & Inspection ────────────────────────────────────────────────
+
+/**
+ * Get the count of pending effects across all queues.
+ * @returns {Object} Counts for each effect type
+ */
+function getPendingEffectCounts() {
+  return {
+    passive: effectQueue.length,
+    layout: layoutEffectQueue.length,
+    insertion: insertionEffectQueue.length,
+    total: effectQueue.length + layoutEffectQueue.length + insertionEffectQueue.length,
+  };
+}
+
+/**
+ * Get all effects for a specific component.
+ * @param {Object} component
+ * @returns {Array} Array of effect objects
+ */
+function getComponentEffects(component) {
+  if (!component._hooks) return [];
+
+  return component._hooks.filter((hook) =>
+    hook && (hook.type === EFFECT_TYPES.PASSIVE ||
+             hook.type === EFFECT_TYPES.LAYOUT ||
+             hook.type === EFFECT_TYPES.INSERTION)
+  );
+}
+
+// ─── Cleanup on Unmount ──────────────────────────────────────────────────────
+
+/**
+ * Clean up all effects for a component when it unmounts.
+ * @param {Object} component - The unmounting component
+ */
+function cleanupComponentEffects(component) {
+  if (!component._hooks) return;
+
+  component._hooks.forEach((hook) => {
+    if (hook && typeof hook.cleanup === 'function') {
+      runCleanup(hook);
+    }
+  });
+
+  // Remove effects from queues
+  for (let i = effectQueue.length - 1; i >= 0; i--) {
+    if (effectQueue[i].component === component) {
+      effectQueue.splice(i, 1);
+    }
+  }
+  for (let i = layoutEffectQueue.length - 1; i >= 0; i--) {
+    if (layoutEffectQueue[i].component === component) {
+      layoutEffectQueue.splice(i, 1);
+    }
+  }
+  for (let i = insertionEffectQueue.length - 1; i >= 0; i--) {
+    if (insertionEffectQueue[i].component === component) {
+      insertionEffectQueue.splice(i, 1);
+    }
+  }
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useEffect,
+  useLayoutEffect,
+  useInsertionEffect,
+  useDeepCompareEffect,
+  useEffectOnce,
+  useUpdateEffect,
+  setCurrentComponent,
+  resetHookIndex,
+  flushPassiveEffects,
+  flushLayoutEffects,
+  flushInsertionEffects,
+  flushAllEffects,
+  batchEffects,
+  areDepsEqual,
+  areDepsDeepEqual,
+  cancelEffect,
+  setStrictMode,
+  isInStrictMode,
+  getPendingEffectCounts,
+  getComponentEffects,
+  cleanupComponentEffects,
+  EFFECT_TYPES,
+};