elementdrawing 1.0.0

package/src/jsx/hooks/useRef.js

@@ -0,0 +1,542 @@
+/**
+ * useRef Hook Implementation
+ * ElementDrawing Framework - Mutable ref objects, DOM refs, callback refs,
+ * ref forwarding, ref merging, previous value tracking, ref lifecycle,
+ * and DOM measurement helpers.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+const refRegistry = new WeakMap();
+
+// ─── Ref Lifecycle Tracking ───────────────────────────────────────────────────
+
+const refLifecycle = new WeakMap();
+
+/**
+ * Get the lifecycle state of a ref (mounted/unmounted).
+ * @param {Object} ref - Ref object
+ * @returns {string} 'mounted' | 'unmounted' | 'unknown'
+ */
+function getRefLifecycle(ref) {
+  if (!ref || !ref._isRef) return 'unknown';
+  return refLifecycle.get(ref) || 'unknown';
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+// ─── Ref Object Creation ──────────────────────────────────────────────────────
+
+/**
+ * Create a mutable ref object with a current property.
+ *
+ * @param {*} initialValue - Initial value for current
+ * @returns {Object} Ref object with { current } property
+ *
+ * @example
+ * const countRef = useRef(0);
+ * countRef.current++; // Mutable without re-renders
+ */
+function createRef(initialValue) {
+  const ref = {
+    current: initialValue,
+  };
+
+  Object.defineProperty(ref, '_isRef', {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: true,
+  });
+
+  Object.defineProperty(ref, '_createdAt', {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: Date.now(),
+  });
+
+  return ref;
+}
+
+// ─── useRef Hook ───────────────────────────────────────────────────────────────
+
+/**
+ * useRef - Create a mutable ref object that persists across renders.
+ * Mutating .current does NOT trigger a re-render.
+ *
+ * @param {*} initialValue - Initial value for the ref's current property
+ * @returns {Object} Ref object { current: initialValue }
+ *
+ * @example
+ * // DOM ref
+ * const inputRef = useRef(null);
+ * <input ref={inputRef} />
+ * inputRef.current.focus();
+ *
+ * @example
+ * // Instance variable
+ * const timerRef = useRef(null);
+ * timerRef.current = setInterval(() => {}, 1000);
+ *
+ * @example
+ * // Previous value tracking
+ * const prevCountRef = useRef(count);
+ * useEffect(() => { prevCountRef.current = count; }, [count]);
+ */
+function useRef(initialValue) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useRef] Must be called within a component render phase');
+  }
+
+  // Initialize hooks array
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    // Re-render: return existing ref (never changes identity)
+    hook = component._hooks[currentHookIndex];
+  } else {
+    // First render: create the ref object
+    const ref = createRef(initialValue);
+
+    hook = {
+      type: 'ref',
+      ref,
+      _isDOMRef: false,
+      _cleanup: null,
+      _prevValues: [],
+    };
+
+    component._hooks[currentHookIndex] = hook;
+
+    // Register in the global ref registry
+    if (!refRegistry.has(component)) {
+      refRegistry.set(component, new Set());
+    }
+    refRegistry.get(component).add(currentHookIndex);
+  }
+
+  hookIndex++;
+  return hook.ref;
+}
+
+// ─── Previous Value Tracking ──────────────────────────────────────────────────
+
+/**
+ * usePrevious - Track the previous value of a variable across renders.
+ *
+ * @param {*} value - Current value
+ * @returns {*} Previous value (undefined on first render)
+ *
+ * @example
+ * const [count, setCount] = useState(0);
+ * const prevCount = usePrevious(count);
+ * console.log(`Current: ${count}, Previous: ${prevCount}`);
+ */
+function usePrevious(value) {
+  const ref = useRef(undefined);
+
+  // Store the previous value
+  const previousValue = ref.current;
+
+  // Schedule the update for next render (not immediate)
+  if (currentlyRenderingComponent) {
+    const component = currentlyRenderingComponent;
+    // Queue the update to happen after render
+    if (!component._pendingPrevUpdates) {
+      component._pendingPrevUpdates = [];
+    }
+    component._pendingPrevUpdates.push(() => {
+      ref.current = value;
+    });
+  }
+
+  return previousValue;
+}
+
+/**
+ * usePreviousWithInit - Like usePrevious but with an explicit initial previous value.
+ *
+ * @param {*} value - Current value
+ * @param {*} initPrev - Initial "previous" value for first render
+ * @returns {*} Previous value
+ */
+function usePreviousWithInit(value, initPrev) {
+  const ref = useRef(initPrev);
+  const previousValue = ref.current;
+
+  if (currentlyRenderingComponent) {
+    const component = currentlyRenderingComponent;
+    if (!component._pendingPrevUpdates) {
+      component._pendingPrevUpdates = [];
+    }
+    component._pendingPrevUpdates.push(() => {
+      ref.current = value;
+    });
+  }
+
+  return previousValue;
+}
+
+// ─── Callback Refs ────────────────────────────────────────────────────────────
+
+/**
+ * Create a callback ref that invokes a function when the DOM node changes.
+ *
+ * @param {Function} callback - Called with (node) when the ref value changes
+ * @returns {Function} Callback ref function
+ *
+ * @example
+ * const measureRef = useCallbackRef((node) => {
+ *   if (node) {
+ *     const { width, height } = node.getBoundingClientRect();
+ *     setSize({ width, height });
+ *   }
+ * });
+ */
+function useCallbackRef(callback) {
+  if (typeof callback !== 'function') {
+    throw new Error('[useCallbackRef] Argument must be a function');
+  }
+
+  let lastNode = null;
+
+  const callbackRef = function refFunction(node) {
+    // Clean up previous node
+    if (lastNode && typeof callbackRef._cleanup === 'function') {
+      try {
+        callbackRef._cleanup(lastNode);
+      } catch (error) {
+        console.error('[useCallbackRef] Cleanup error:', error);
+      }
+    }
+
+    // Invoke callback with new node
+    if (node !== null) {
+      try {
+        const result = callback(node);
+        if (typeof result === 'function') {
+          callbackRef._cleanup = result;
+        }
+      } catch (error) {
+        console.error('[useCallbackRef] Callback error:', error);
+      }
+    } else {
+      callbackRef._cleanup = null;
+    }
+
+    lastNode = node;
+
+    // Track lifecycle
+    refLifecycle.set(callbackRef, node ? 'mounted' : 'unmounted');
+  };
+
+  callbackRef._isCallbackRef = true;
+  callbackRef._cleanup = null;
+
+  return callbackRef;
+}
+
+// ─── Ref Forwarding ───────────────────────────────────────────────────────────
+
+/**
+ * Create a forwarded ref component that passes refs through to child components.
+ *
+ * @param {Function} render - Function (props, ref) => VNode
+ * @returns {Function} Forwarded ref component
+ *
+ * @example
+ * const FancyInput = forwardRef((props, ref) => (
+ *   <input ref={ref} className="fancy-input" {...props} />
+ * ));
+ *
+ * <FancyInput ref={inputRef} />
+ */
+function forwardRef(render) {
+  if (typeof render !== 'function') {
+    throw new Error(
+      '[forwardRef] Argument must be a render function. ' +
+      `Received: ${typeof render}`
+    );
+  }
+
+  const ForwardedComponent = function ForwardRefComponent(props) {
+    const ref = props.ref;
+    const restProps = Object.assign({}, props);
+    delete restProps.ref;
+
+    return render(restProps, ref);
+  };
+
+  ForwardedComponent._isForwardRef = true;
+  ForwardedComponent.displayName = render.displayName || render.name || 'ForwardRef';
+  ForwardedComponent.render = render;
+
+  return ForwardedComponent;
+}
+
+/**
+ * Check if a component was created with forwardRef.
+ * @param {Function} component
+ * @returns {boolean}
+ */
+function isForwardRef(component) {
+  return component && component._isForwardRef === true;
+}
+
+// ─── Ref Merging ──────────────────────────────────────────────────────────────
+
+/**
+ * Merge multiple refs into a single callback ref.
+ * Supports object refs, callback refs, and forwarded refs.
+ *
+ * @param {...(Object|Function|null)} refs - Refs to merge
+ * @returns {Function} Callback ref that sets all provided refs
+ *
+ * @example
+ * const mergedRef = useMergedRefs(externalRef, localRef);
+ * <div ref={mergedRef} />
+ */
+function useMergedRefs() {
+  const refs = Array.prototype.slice.call(arguments);
+
+  const mergedRef = function mergedRefCallback(node) {
+    refs.forEach((ref) => {
+      if (!ref) return;
+
+      if (typeof ref === 'function') {
+        // Callback ref
+        ref(node);
+      } else if (typeof ref === 'object' && ref._isRef) {
+        // Object ref
+        ref.current = node;
+      } else if (typeof ref === 'object' && ref !== null) {
+        // Plain object ref
+        ref.current = node;
+      }
+    });
+  };
+
+  mergedRef._isMergedRef = true;
+  return mergedRef;
+}
+
+// ─── DOM Ref Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Create a ref that measures the DOM node dimensions.
+ *
+ * @returns {Array} [ref, dimensions] where dimensions is { width, height, x, y }
+ *
+ * @example
+ * const [measureRef, dimensions] = useMeasureRef();
+ * <div ref={measureRef} />
+ * console.log(dimensions.width, dimensions.height);
+ */
+function useMeasureRef() {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useMeasureRef] Must be called within a component render phase');
+  }
+
+  const dimensionsRef = useRef({ width: 0, height: 0, x: 0, y: 0 });
+  const observerRef = useRef(null);
+
+  const callbackRef = useCallbackRef((node) => {
+    if (observerRef.current) {
+      observerRef.current.disconnect();
+    }
+
+    if (node) {
+      // Measure initial dimensions
+      const rect = node.getBoundingClientRect();
+      dimensionsRef.current = {
+        width: rect.width,
+        height: rect.height,
+        x: rect.x,
+        y: rect.y,
+      };
+
+      // Observe size changes
+      if (typeof ResizeObserver !== 'undefined') {
+        observerRef.current = new ResizeObserver((entries) => {
+          const entry = entries[0];
+          if (entry) {
+            const { width, height } = entry.contentRect;
+            const { x, y } = entry.target.getBoundingClientRect();
+            dimensionsRef.current = { width, height, x, y };
+          }
+        });
+        observerRef.current.observe(node);
+      }
+    }
+  });
+
+  return [callbackRef, dimensionsRef.current];
+}
+
+/**
+ * Create a ref that tracks whether the element is in the viewport.
+ *
+ * @param {Object} [options] - IntersectionObserver options
+ * @returns {Array} [ref, isIntersecting]
+ */
+function useInViewRef(options) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useInViewRef] Must be called within a component render phase');
+  }
+
+  const inViewRef = useRef(false);
+  const observerRef = useRef(null);
+
+  const callbackRef = useCallbackRef((node) => {
+    if (observerRef.current) {
+      observerRef.current.disconnect();
+    }
+
+    if (node && typeof IntersectionObserver !== 'undefined') {
+      observerRef.current = new IntersectionObserver((entries) => {
+        const entry = entries[0];
+        if (entry) {
+          inViewRef.current = entry.isIntersecting;
+        }
+      }, options);
+      observerRef.current.observe(node);
+    }
+  });
+
+  return [callbackRef, inViewRef.current];
+}
+
+/**
+ * Create a ref that tracks focus state.
+ *
+ * @returns {Array} [ref, isFocused]
+ */
+function useFocusRef() {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useFocusRef] Must be called within a component render phase');
+  }
+
+  const focusRef = useRef(false);
+
+  const callbackRef = useCallbackRef((node) => {
+    if (node) {
+      node.addEventListener('focus', () => { focusRef.current = true; });
+      node.addEventListener('blur', () => { focusRef.current = false; });
+      focusRef.current = document.activeElement === node;
+    }
+  });
+
+  return [callbackRef, focusRef.current];
+}
+
+/**
+ * Create a ref that auto-scrolls to the element when dependencies change.
+ *
+ * @param {Array} deps - Dependencies that trigger scroll
+ * @returns {Function} Ref callback
+ */
+function useScrollRef(deps) {
+  const scrolledRef = useRef(false);
+
+  const callbackRef = useCallbackRef((node) => {
+    if (node) {
+      node.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+      scrolledRef.current = true;
+    }
+  });
+
+  return callbackRef;
+}
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Process pending previous value updates after render.
+ * @param {Object} component
+ */
+function processPendingPrevUpdates(component) {
+  if (component._pendingPrevUpdates && component._pendingPrevUpdates.length > 0) {
+    component._pendingPrevUpdates.forEach((fn) => fn());
+    component._pendingPrevUpdates = [];
+  }
+}
+
+/**
+ * Clean up refs when a component unmounts.
+ * @param {Object} component
+ */
+function cleanupRefs(component) {
+  if (!component._hooks) return;
+
+  component._hooks.forEach((hook) => {
+    if (hook && hook.type === 'ref') {
+      // Run cleanup for callback refs
+      if (typeof hook._cleanup === 'function') {
+        try {
+          hook._cleanup(null);
+        } catch (error) {
+          console.error('[useRef] Cleanup error:', error);
+        }
+      }
+
+      // Clear DOM refs
+      if (hook._isDOMRef && hook.ref) {
+        hook.ref.current = null;
+        refLifecycle.set(hook.ref, 'unmounted');
+      }
+    }
+  });
+
+  refRegistry.delete(component);
+
+  // Process any remaining pending updates
+  if (component._pendingPrevUpdates) {
+    component._pendingPrevUpdates = [];
+  }
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useRef,
+  usePrevious,
+  usePreviousWithInit,
+  createRef,
+  useCallbackRef,
+  forwardRef,
+  isForwardRef,
+  useMergedRefs,
+  useMeasureRef,
+  useInViewRef,
+  useFocusRef,
+  useScrollRef,
+  setCurrentComponent,
+  resetHookIndex,
+  cleanupRefs,
+  processPendingPrevUpdates,
+  getRefLifecycle,
+};