elementdrawing 1.0.0

package/src/jsx/hooks/useState.js

@@ -0,0 +1,854 @@
+/**
+ * useState Hook Implementation
+ * ElementDrawing Framework - State management hook with batched updates,
+ * functional updates, lazy initialization, state comparison, subscriptions,
+ * priority-based updates, transition support, and debug tracing.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+let isBatchingUpdates = false;
+const pendingStateUpdates = new Map();
+const stateSubscribers = new Map();
+const statePersistenceKeys = new WeakMap();
+let scheduleUpdateCallback = null;
+
+// ─── Update Priority Levels ──────────────────────────────────────────────────
+
+const PRIORITY = {
+  IMMEDIATE: 0,    // Synchronous, user-initiated (click, keypress)
+  NORMAL: 1,       // Standard state update
+  TRANSITION: 2,   // Non-urgent, can be interrupted (useTransition)
+  IDLE: 3,         // Lowest priority, runs when idle
+};
+
+let currentUpdatePriority = PRIORITY.NORMAL;
+
+/**
+ * Get the current update priority level.
+ * @returns {number}
+ */
+function getCurrentPriority() {
+  return currentUpdatePriority;
+}
+
+/**
+ * Set the current update priority level.
+ * @param {number} priority
+ */
+function setCurrentPriority(priority) {
+  if (!Object.values(PRIORITY).includes(priority)) {
+    console.warn('[useState] Invalid priority level:', priority);
+    return;
+  }
+  currentUpdatePriority = priority;
+}
+
+// ─── Update Queue ─────────────────────────────────────────────────────────────
+
+/**
+ * Represents a pending state update in the queue.
+ * @param {*} updateFnOrValue - New value or updater function
+ * @param {number} priority - Update priority
+ * @param {number} lane - Lane for concurrent rendering
+ */
+function createStateUpdate(updateFnOrValue, priority, lane) {
+  return {
+    updateFnOrValue,
+    priority: priority !== undefined ? priority : currentUpdatePriority,
+    lane: lane || 0,
+    timestamp: Date.now(),
+    id: ++updateIdCounter,
+  };
+}
+
+let updateIdCounter = 0;
+
+// ─── Batching System ─────────────────────────────────────────────────────────
+
+/**
+ * Start batching state updates. All setState calls within the batch
+ * will be deferred until endBatchUpdates is called.
+ */
+function startBatchUpdates() {
+  isBatchingUpdates = true;
+}
+
+/**
+ * Flush all pending batched updates and re-render affected components.
+ */
+function endBatchUpdates() {
+  isBatchingUpdates = false;
+  flushPendingUpdates();
+}
+
+/**
+ * Flush all pending state updates, merging multiple updates for the same hook.
+ * Processes updates by priority order (IMMEDIATE first).
+ */
+function flushPendingUpdates() {
+  if (pendingStateUpdates.size === 0) return;
+
+  const updates = new Map(pendingStateUpdates);
+  pendingStateUpdates.clear();
+
+  updates.forEach((stateQueue, component) => {
+    if (stateQueue.length === 0) return;
+
+    // Sort updates by priority (lower number = higher priority)
+    stateQueue.sort((a, b) => a.priority - b.priority);
+
+    const hooks = component._hooks;
+    stateQueue.forEach(({ hookIdx, update }) => {
+      const hook = hooks[hookIdx];
+      if (!hook) return;
+
+      let newValue;
+      if (typeof update.updateFnOrValue === 'function') {
+        newValue = update.updateFnOrValue(hook.state);
+      } else {
+        newValue = update.updateFnOrValue;
+      }
+
+      // State comparison - skip update if value is the same
+      const areEqual = hook._areEqual || Object.is;
+      if (areEqual(hook.state, newValue)) return;
+
+      const prevState = hook.state;
+      hook.state = newValue;
+
+      // Track update in debug history
+      if (hook._debug) {
+        hook._updateHistory.push({
+          prev: prevState,
+          next: newValue,
+          timestamp: Date.now(),
+          priority: update.priority,
+        });
+        // Keep only last 50 entries
+        if (hook._updateHistory.length > 50) {
+          hook._updateHistory.shift();
+        }
+      }
+
+      // Notify subscribers of state change
+      notifySubscribers(component, hookIdx, newValue, prevState);
+
+      // Persist state if persistence is configured
+      persistState(component, hookIdx, newValue);
+    });
+
+    // Schedule re-render for the component
+    if (scheduleUpdateCallback) {
+      scheduleUpdateCallback(component);
+    } else if (component._scheduleReRender) {
+      component._scheduleReRender();
+    }
+  });
+}
+
+/**
+ * Execute a function with batched updates enabled.
+ * @param {Function} fn - Function to execute within the batch
+ * @returns {*} Return value of the executed function
+ */
+function batchedUpdates(fn) {
+  startBatchUpdates();
+  try {
+    return fn();
+  } finally {
+    endBatchUpdates();
+  }
+}
+
+/**
+ * Execute a function at a specific priority level.
+ * @param {number} priority - PRIORITY.IMMEDIATE | NORMAL | TRANSITION | IDLE
+ * @param {Function} fn - Function to execute
+ * @returns {*} Return value of the executed function
+ */
+function runWithPriority(priority, fn) {
+  const prevPriority = currentUpdatePriority;
+  setCurrentPriority(priority);
+  try {
+    return fn();
+  } finally {
+    setCurrentPriority(prevPriority);
+  }
+}
+
+// ─── Transition Support ───────────────────────────────────────────────────────
+
+let isTransitionActive = false;
+const pendingTransitions = [];
+
+/**
+ * Start a transition - marks updates as non-urgent.
+ * @param {Function} fn - Function containing transition updates
+ */
+function startTransition(fn) {
+  isTransitionActive = true;
+  const prevPriority = currentUpdatePriority;
+  currentUpdatePriority = PRIORITY.TRANSITION;
+
+  try {
+    fn();
+  } finally {
+    isTransitionActive = false;
+    currentUpdatePriority = prevPriority;
+  }
+}
+
+/**
+ * Check if a transition is currently active.
+ * @returns {boolean}
+ */
+function isTransitionInProgress() {
+  return isTransitionActive;
+}
+
+// ─── Subscription System ──────────────────────────────────────────────────────
+
+/**
+ * Subscribe to state changes for a specific component's hook.
+ * @param {Object} component - The component instance
+ * @param {number} hookIdx - The hook index
+ * @param {Function} callback - Called with (newValue, oldValue)
+ * @returns {Function} Unsubscribe function
+ */
+function subscribeToState(component, hookIdx, callback) {
+  if (!stateSubscribers.has(component)) {
+    stateSubscribers.set(component, new Map());
+  }
+  const componentSubs = stateSubscribers.get(component);
+
+  if (!componentSubs.has(hookIdx)) {
+    componentSubs.set(hookIdx, new Set());
+  }
+  const subs = componentSubs.get(hookIdx);
+  subs.add(callback);
+
+  return function unsubscribe() {
+    subs.delete(callback);
+    if (subs.size === 0) {
+      componentSubs.delete(hookIdx);
+    }
+    if (componentSubs.size === 0) {
+      stateSubscribers.delete(component);
+    }
+  };
+}
+
+/**
+ * Notify all subscribers of a state change.
+ */
+function notifySubscribers(component, hookIdx, newValue, oldValue) {
+  const componentSubs = stateSubscribers.get(component);
+  if (!componentSubs) return;
+
+  const subs = componentSubs.get(hookIdx);
+  if (!subs) return;
+
+  subs.forEach((callback) => {
+    try {
+      callback(newValue, oldValue);
+    } catch (error) {
+      console.error('[useState] Subscriber error:', error);
+    }
+  });
+}
+
+// ─── State Persistence ────────────────────────────────────────────────────────
+
+/**
+ * Configure state persistence for a hook.
+ * @param {string} key - The localStorage/sessionStorage key
+ * @param {Object} options - Persistence options
+ * @param {string} options.storage - 'localStorage' | 'sessionStorage'
+ * @param {Function} [options.serialize] - Custom serialize function
+ * @param {Function} [options.deserialize] - Custom deserialize function
+ * @param {number} [options.debounceMs] - Debounce persistence writes
+ */
+function configurePersistence(key, options = {}) {
+  const config = {
+    key,
+    storage: options.storage || 'localStorage',
+    serialize: options.serialize || JSON.stringify,
+    deserialize: options.deserialize || JSON.parse,
+    debounceMs: options.debounceMs || 0,
+  };
+  return config;
+}
+
+/**
+ * Persist state to storage.
+ */
+let persistenceTimers = new Map();
+
+function persistState(component, hookIdx, value) {
+  const persistenceConfig = component._hooks[hookIdx]?._persistence;
+  if (!persistenceConfig) return;
+
+  const writeFn = () => {
+    try {
+      const storage = window[persistenceConfig.storage];
+      const serialized = persistenceConfig.serialize(value);
+      storage.setItem(persistenceConfig.key, serialized);
+    } catch (error) {
+      console.error('[useState] Persistence error:', error);
+    }
+  };
+
+  // Debounced persistence
+  if (persistenceConfig.debounceMs > 0) {
+    const timerKey = component._hooks[hookIdx]._persistenceTimer;
+    if (timerKey) clearTimeout(timerKey);
+    component._hooks[hookIdx]._persistenceTimer = setTimeout(writeFn, persistenceConfig.debounceMs);
+  } else {
+    writeFn();
+  }
+}
+
+/**
+ * Load persisted state from storage.
+ */
+function loadPersistedState(persistenceConfig) {
+  if (!persistenceConfig) return undefined;
+
+  try {
+    const storage = window[persistenceConfig.storage];
+    const serialized = storage.getItem(persistenceConfig.key);
+    if (serialized === null) return undefined;
+    return persistenceConfig.deserialize(serialized);
+  } catch (error) {
+    console.error('[useState] Load persistence error:', error);
+    return undefined;
+  }
+}
+
+// ─── State Comparison Utilities ───────────────────────────────────────────────
+
+/**
+ * Deep comparison function for state values.
+ * @param {*} a - First value
+ * @param {*} b - Second value
+ * @returns {boolean} True if deeply equal
+ */
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+    return false;
+  }
+
+  if (Array.isArray(a) !== Array.isArray(b)) 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 (!keysB.includes(key)) return false;
+    if (!deepEqual(a[key], b[key])) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Shallow comparison function for state values.
+ * @param {*} a - First value
+ * @param {*} b - Second value
+ * @returns {boolean}
+ */
+function shallowEqual(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 (!Object.is(a[key], b[key])) return false;
+  }
+
+  return true;
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+/**
+ * Set the currently rendering component (called by the framework before render).
+ * @param {Object} component - The component being rendered
+ */
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+/**
+ * Get the currently rendering component.
+ * @returns {Object|null}
+ */
+function getCurrentComponent() {
+  return currentlyRenderingComponent;
+}
+
+/**
+ * Reset the hook index after rendering is complete.
+ */
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+/**
+ * Set the framework's update scheduling callback.
+ * @param {Function} callback - Called with (component) to schedule re-render
+ */
+function setScheduleUpdateCallback(callback) {
+  scheduleUpdateCallback = callback;
+}
+
+// ─── useState Hook ────────────────────────────────────────────────────────────
+
+/**
+ * useState - State hook with initial value, lazy initializer, batched updates,
+ * functional updates, state comparison, subscriptions, persistence, and
+ * priority-based updates.
+ *
+ * @param {*} initialState - Initial state value or lazy initializer function
+ * @param {Object} [options] - Additional options
+ * @param {Object} [options.persistence] - Persistence configuration
+ * @param {Function} [options.areEqual] - Custom equality comparison function
+ * @param {boolean} [options.debug] - Enable debug tracing for this state
+ * @returns {[*, Function]} Tuple of [currentState, setState]
+ *
+ * @example
+ * // Simple state
+ * const [count, setCount] = useState(0);
+ *
+ * @example
+ * // Lazy initializer (expensive computation runs once)
+ * const [data, setData] = useState(() => computeExpensiveValue());
+ *
+ * @example
+ * // Functional update
+ * setCount(prev => prev + 1);
+ *
+ * @example
+ * // With persistence
+ * const [theme, setTheme] = useState('light', {
+ *   persistence: configurePersistence('app-theme', { storage: 'localStorage' })
+ * });
+ *
+ * @example
+ * // With deep comparison
+ * const [form, setForm] = useState({}, { areEqual: deepEqual });
+ */
+function useState(initialState, options = {}) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useState] Must be called within a component render phase');
+  }
+
+  // Initialize hooks array on first render
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  // Get or create the hook state
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    // Re-render: use existing hook state
+    hook = component._hooks[currentHookIndex];
+  } else {
+    // First render: initialize hook state
+    let resolvedInitialState;
+
+    // Check for persisted state first
+    if (options.persistence) {
+      const persistedValue = loadPersistedState(options.persistence);
+      if (persistedValue !== undefined) {
+        resolvedInitialState = persistedValue;
+      }
+    }
+
+    // If no persisted value, resolve initial state
+    if (resolvedInitialState === undefined) {
+      if (typeof initialState === 'function') {
+        // Lazy initializer - only called once on mount
+        try {
+          resolvedInitialState = initialState();
+        } catch (error) {
+          console.error('[useState] Lazy initializer error:', error);
+          resolvedInitialState = undefined;
+        }
+      } else {
+        resolvedInitialState = initialState;
+      }
+    }
+
+    hook = {
+      state: resolvedInitialState,
+      _persistence: options.persistence || null,
+      _areEqual: options.areEqual || Object.is,
+      _isMounted: false,
+      _pendingUpdates: [],
+      _queue: [],
+      _debug: options.debug || false,
+      _updateHistory: options.debug ? [] : null,
+      _persistenceTimer: null,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Process any pending functional updates that were queued
+  if (hook._pendingUpdates.length > 0) {
+    const updates = hook._pendingUpdates.splice(0);
+    updates.forEach((update) => {
+      if (typeof update === 'function') {
+        hook.state = update(hook.state);
+      } else {
+        hook.state = update;
+      }
+    });
+  }
+
+  // Increment hook index for the next hook call
+  hookIndex++;
+
+  // ─── setState Implementation ────────────────────────────────────────────
+
+  /**
+   * Update state with a new value or updater function.
+   * Supports batching, functional updates, priority, and state comparison.
+   *
+   * @param {*} updateFnOrValue - New state value or updater function
+   */
+  const setState = function setState(updateFnOrValue) {
+    if (!component._hooks) {
+      console.warn('[useState] setState called on unmounted component');
+      return;
+    }
+
+    const targetHook = component._hooks[currentHookIndex];
+    if (!targetHook) {
+      console.warn('[useState] Hook index out of bounds');
+      return;
+    }
+
+    const update = createStateUpdate(updateFnOrValue, currentUpdatePriority);
+
+    if (isBatchingUpdates) {
+      // Queue the update for batch processing
+      if (!pendingStateUpdates.has(component)) {
+        pendingStateUpdates.set(component, []);
+      }
+      pendingStateUpdates.get(component).push({
+        hookIdx: currentHookIndex,
+        update,
+      });
+    } else {
+      // Immediate update
+      let newValue;
+      if (typeof updateFnOrValue === 'function') {
+        newValue = updateFnOrValue(targetHook.state);
+      } else {
+        newValue = updateFnOrValue;
+      }
+
+      // Use custom equality check or Object.is
+      const areEqual = targetHook._areEqual;
+      if (areEqual(targetHook.state, newValue)) {
+        return; // Skip update - state is the same
+      }
+
+      const prevState = targetHook.state;
+      targetHook.state = newValue;
+
+      // Track update in debug history
+      if (targetHook._debug && targetHook._updateHistory) {
+        targetHook._updateHistory.push({
+          prev: prevState,
+          next: newValue,
+          timestamp: Date.now(),
+          priority: update.priority,
+        });
+        if (targetHook._updateHistory.length > 50) {
+          targetHook._updateHistory.shift();
+        }
+      }
+
+      // Notify subscribers
+      notifySubscribers(component, currentHookIndex, newValue, prevState);
+
+      // Persist state if configured
+      persistState(component, currentHookIndex, newValue);
+
+      // Schedule re-render
+      if (scheduleUpdateCallback) {
+        scheduleUpdateCallback(component);
+      } else if (component._scheduleReRender) {
+        component._scheduleReRender();
+      }
+    }
+  };
+
+  // ─── Extended setState Methods ──────────────────────────────────────────
+
+  /**
+   * Reset state to initial value.
+   */
+  setState.reset = function reset() {
+    let resetValue;
+    if (typeof initialState === 'function') {
+      resetValue = initialState();
+    } else {
+      resetValue = initialState;
+    }
+    setState(resetValue);
+  };
+
+  /**
+   * Subscribe to state changes.
+   * @param {Function} callback - Called with (newValue, oldValue)
+   * @returns {Function} Unsubscribe function
+   */
+  setState.subscribe = function subscribe(callback) {
+    return subscribeToState(component, currentHookIndex, callback);
+  };
+
+  /**
+   * Get current state without triggering a re-render.
+   * @returns {*} Current state value
+   */
+  setState.getCurrent = function getCurrent() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook ? targetHook.state : undefined;
+  };
+
+  /**
+   * Check if the component is mounted.
+   * @returns {boolean}
+   */
+  setState.isMounted = function isMounted() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook ? targetHook._isMounted : false;
+  };
+
+  /**
+   * Set state with a specific priority level.
+   * @param {*} updateFnOrValue - New state value or updater function
+   * @param {number} priority - PRIORITY level
+   */
+  setState.withPriority = function withPriority(updateFnOrValue, priority) {
+    const prevPriority = currentUpdatePriority;
+    setCurrentPriority(priority);
+    try {
+      setState(updateFnOrValue);
+    } finally {
+      setCurrentPriority(prevPriority);
+    }
+  };
+
+  /**
+   * Set state as a transition (non-urgent update).
+   * @param {*} updateFnOrValue - New state value or updater function
+   */
+  setState.asTransition = function asTransition(updateFnOrValue) {
+    startTransition(() => {
+      setState(updateFnOrValue);
+    });
+  };
+
+  /**
+   * Get the update history for debugging (only if debug mode is enabled).
+   * @returns {Array|null} Update history array or null
+   */
+  setState.getHistory = function getHistory() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook?._updateHistory || null;
+  };
+
+  return [hook.state, setState];
+}
+
+// ─── useTransition Hook ───────────────────────────────────────────────────────
+
+/**
+ * useTransition - Hook for marking updates as transitions (non-urgent).
+ * Returns a pending flag and a startTransition function.
+ *
+ * @returns {[boolean, Function]} Tuple of [isPending, startTransition]
+ *
+ * @example
+ * const [isPending, startTransition] = useTransition();
+ * startTransition(() => {
+ *   setSearchResults(filteredData);
+ * });
+ */
+function useTransition() {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useTransition] 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 = {
+      type: 'transition',
+      isPending: false,
+      _pendingCount: 0,
+    };
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  hookIndex++;
+
+  const startTransitionFn = function startTransitionFn(callback) {
+    hook._pendingCount++;
+    hook.isPending = true;
+
+    startTransition(() => {
+      try {
+        callback();
+      } finally {
+        hook._pendingCount--;
+        if (hook._pendingCount <= 0) {
+          hook.isPending = false;
+          hook._pendingCount = 0;
+        }
+      }
+    });
+  };
+
+  return [hook.isPending, startTransitionFn];
+}
+
+// ─── useDeferredValue Hook ────────────────────────────────────────────────────
+
+/**
+ * useDeferredValue - Returns a deferred version of the value that may lag
+ * behind the current value. Useful for optimizing renders of expensive lists.
+ *
+ * @param {*} value - The value to defer
+ * @param {number} [timeoutMs] - Maximum time to defer (optional)
+ * @returns {*} Deferred value
+ *
+ * @example
+ * const deferredQuery = useDeferredValue(query);
+ * const filteredItems = useMemo(() => items.filter(i => i.name.includes(deferredQuery)), [deferredQuery, items]);
+ */
+function useDeferredValue(value, timeoutMs) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useDeferredValue] 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];
+
+    // Update the current value immediately
+    hook.currentValue = value;
+
+    // If no timeout or no deferred update pending, use current value
+    if (!hook._deferredUpdatePending) {
+      hook.deferredValue = value;
+    }
+  } else {
+    hook = {
+      type: 'deferred-value',
+      currentValue: value,
+      deferredValue: value,
+      _deferredUpdatePending: false,
+      _timeoutId: null,
+    };
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  hookIndex++;
+  return hook.deferredValue;
+}
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Clean up hook state when a component unmounts.
+ * @param {Object} component - The unmounting component
+ */
+function cleanupComponentState(component) {
+  // Remove all subscribers for this component
+  stateSubscribers.delete(component);
+
+  // Remove any pending updates
+  pendingStateUpdates.delete(component);
+
+  // Clean up persistence timers and references
+  if (component._hooks) {
+    component._hooks.forEach((hook) => {
+      hook._pendingUpdates = [];
+      hook._queue = [];
+      if (hook._persistenceTimer) {
+        clearTimeout(hook._persistenceTimer);
+      }
+      if (hook._updateHistory) {
+        hook._updateHistory = null;
+      }
+    });
+  }
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useState,
+  useTransition,
+  useDeferredValue,
+  setCurrentComponent,
+  getCurrentComponent,
+  resetHookIndex,
+  setScheduleUpdateCallback,
+  startBatchUpdates,
+  endBatchUpdates,
+  batchedUpdates,
+  configurePersistence,
+  subscribeToState,
+  cleanupComponentState,
+  deepEqual,
+  shallowEqual,
+  runWithPriority,
+  startTransition,
+  isTransitionInProgress,
+  getCurrentPriority,
+  setCurrentPriority,
+  PRIORITY,
+};