elementdrawing 1.0.0

package/src/jsx/hooks/useReducer.js

@@ -0,0 +1,729 @@
+/**
+ * useReducer Hook Implementation
+ * ElementDrawing Framework - Reducer-based state management with lazy
+ * initialization, dispatch, action batching, middleware support,
+ * action creators, undo/redo, optimistic updates, and action history.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+let isBatchingDispatches = false;
+const pendingDispatches = new Map();
+let scheduleUpdateCallback = null;
+
+// ─── Batching System ─────────────────────────────────────────────────────────
+
+/**
+ * Start batching dispatches. All dispatched actions within the batch
+ * will be deferred until endBatchDispatches is called.
+ */
+function startBatchDispatches() {
+  isBatchingDispatches = true;
+}
+
+/**
+ * Flush all pending batched dispatches.
+ */
+function endBatchDispatches() {
+  isBatchingDispatches = false;
+  flushPendingDispatches();
+}
+
+/**
+ * Flush all pending dispatch actions, processing them in order.
+ */
+function flushPendingDispatches() {
+  if (pendingDispatches.size === 0) return;
+
+  const dispatches = new Map(pendingDispatches);
+  pendingDispatches.clear();
+
+  dispatches.forEach((actions, component) => {
+    if (actions.length === 0) return;
+
+    // Process all queued actions through the reducer
+    actions.forEach(({ hookIdx, action, reducer }) => {
+      const hook = component._hooks[hookIdx];
+      if (!hook) return;
+
+      // Apply middleware chain before reducing
+      let processedAction = action;
+      if (hook._middleware && hook._middleware.length > 0) {
+        processedAction = applyMiddlewareChain(hook._middleware, action, hook.state);
+        if (processedAction === null) return; // Action cancelled
+      }
+
+      // Run the reducer
+      const newState = reducer(hook.state, processedAction);
+
+      // State comparison - skip update if unchanged
+      if (Object.is(hook.state, newState)) return;
+
+      const prevState = hook.state;
+      hook.state = newState;
+
+      // Track in action history
+      if (hook._actionHistory) {
+        hook._actionHistory.push({
+          action: processedAction,
+          prevState,
+          nextState: newState,
+          timestamp: Date.now(),
+        });
+        if (hook._actionHistory.length > (hook._maxHistorySize || 100)) {
+          hook._actionHistory.shift();
+        }
+      }
+
+      // Notify state change subscribers
+      if (hook._subscribers) {
+        hook._subscribers.forEach((callback) => {
+          try {
+            callback(newState, prevState, processedAction);
+          } catch (error) {
+            console.error('[useReducer] Subscriber error:', error);
+          }
+        });
+      }
+
+      // Persist state if configured
+      if (hook._persistence) {
+        try {
+          const storage = window[hook._persistence.storage];
+          storage.setItem(hook._persistence.key, hook._persistence.serialize(newState));
+        } catch (error) {
+          console.error('[useReducer] Persistence error:', error);
+        }
+      }
+    });
+
+    // Schedule re-render
+    if (scheduleUpdateCallback) {
+      scheduleUpdateCallback(component);
+    } else if (component._scheduleReRender) {
+      component._scheduleReRender();
+    }
+  });
+}
+
+/**
+ * Execute a function with batched dispatches enabled.
+ * @param {Function} fn
+ * @returns {*}
+ */
+function batchDispatches(fn) {
+  startBatchDispatches();
+  try {
+    return fn();
+  } finally {
+    endBatchDispatches();
+  }
+}
+
+// ─── Middleware System ─────────────────────────────────────────────────────────
+
+/**
+ * Apply a chain of middleware to an action before it reaches the reducer.
+ * Middleware signature: (action, state) => action (or throw to cancel)
+ *
+ * @param {Function[]} middleware - Array of middleware functions
+ * @param {*} action - The dispatched action
+ * @param {*} state - Current state
+ * @returns {*} Processed action
+ */
+function applyMiddlewareChain(middleware, action, state) {
+  let processedAction = action;
+
+  for (let i = 0; i < middleware.length; i++) {
+    try {
+      const result = middleware[i](processedAction, state);
+      if (result === null) return null; // Middleware cancelled the action
+      processedAction = result;
+    } catch (error) {
+      console.error('[useReducer] Middleware error:', error);
+      return action; // Fall back to original action
+    }
+  }
+
+  return processedAction;
+}
+
+/**
+ * Create a logging middleware that logs all dispatched actions.
+ * @param {string} [prefix] - Log prefix
+ * @returns {Function} Middleware function
+ */
+function createLoggerMiddleware(prefix = 'Reducer') {
+  return function loggerMiddleware(action, state) {
+    console.log(`[${prefix}] Action:`, action, '| State:', state);
+    return action;
+  };
+}
+
+/**
+ * Create a middleware that validates actions against a schema.
+ * @param {Object} schema - Action type to validator mapping
+ * @returns {Function} Middleware function
+ */
+function createValidationMiddleware(schema) {
+  return function validationMiddleware(action) {
+    if (action && action.type && schema[action.type]) {
+      const validator = schema[action.type];
+      if (typeof validator === 'function') {
+        const isValid = validator(action);
+        if (!isValid) {
+          console.warn('[useReducer] Action validation failed:', action);
+          return null; // Cancel invalid action
+        }
+      }
+    }
+    return action;
+  };
+}
+
+/**
+ * Create a middleware that transforms actions.
+ * @param {Function} transformer - (action, state) => newAction
+ * @returns {Function} Middleware function
+ */
+function createTransformMiddleware(transformer) {
+  return function transformMiddleware(action, state) {
+    return transformer(action, state);
+  };
+}
+
+/**
+ * Create a middleware that throttles actions of a given type.
+ * @param {string} actionType - Action type to throttle
+ * @param {number} intervalMs - Throttle interval
+ * @returns {Function} Middleware function
+ */
+function createThrottleMiddleware(actionType, intervalMs) {
+  let lastDispatch = 0;
+  return function throttleMiddleware(action) {
+    if (action && action.type === actionType) {
+      const now = Date.now();
+      if (now - lastDispatch < intervalMs) {
+        return null; // Cancel throttled action
+      }
+      lastDispatch = now;
+    }
+    return action;
+  };
+}
+
+// ─── Action Creator Factory ───────────────────────────────────────────────────
+
+/**
+ * Create action creator functions from an action definition map.
+ *
+ * @param {Object} actionMap - Map of action type to payload creator function
+ * @returns {Object} Object of action creator functions
+ *
+ * @example
+ * const actions = createActionCreators({
+ *   increment: () => ({ type: 'INCREMENT' }),
+ *   add: (amount) => ({ type: 'ADD', payload: amount }),
+ *   reset: () => ({ type: 'RESET' }),
+ * });
+ *
+ * dispatch(actions.increment());
+ * dispatch(actions.add(5));
+ */
+function createActionCreators(actionMap) {
+  const creators = {};
+  for (const type in actionMap) {
+    if (!actionMap.hasOwnProperty(type)) continue;
+    const payloadCreator = actionMap[type];
+    creators[type] = function actionCreator() {
+      return payloadCreator.apply(null, arguments);
+    };
+  }
+  return creators;
+}
+
+/**
+ * Create a simple action creator for a type.
+ * @param {string} type - Action type
+ * @returns {Function} Action creator
+ */
+function createAction(type) {
+  return function actionCreator(payload) {
+    return { type, payload };
+  };
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+function setScheduleUpdateCallback(callback) {
+  scheduleUpdateCallback = callback;
+}
+
+// ─── useReducer Hook ──────────────────────────────────────────────────────────
+
+/**
+ * useReducer - Reducer-based state management hook.
+ *
+ * @param {Function} reducer - Pure function: (state, action) => newState
+ * @param {*} initialArg - Initial state value or argument for lazy initializer
+ * @param {Function} [init] - Lazy initializer: (initialArg) => initialState
+ * @param {Object} [options] - Additional options
+ * @param {Function[]} [options.middleware] - Middleware chain for actions
+ * @param {Object} [options.persistence] - State persistence configuration
+ * @param {boolean} [options.trackHistory] - Track action history for debugging
+ * @param {number} [options.maxHistorySize] - Maximum history entries
+ * @returns {[*, Function]} Tuple of [state, dispatch]
+ *
+ * @example
+ * function counterReducer(state, action) {
+ *   switch (action.type) {
+ *     case 'increment': return { count: state.count + 1 };
+ *     case 'decrement': return { count: state.count - 1 };
+ *     case 'reset':     return { count: action.payload };
+ *     default:          return state;
+ *   }
+ * }
+ *
+ * const [state, dispatch] = useReducer(counterReducer, { count: 0 });
+ *
+ * @example
+ * // Lazy initialization
+ * const [state, dispatch] = useReducer(reducer, initialCount, (count) => {
+ *   return { count: count * 2 };
+ * });
+ *
+ * @example
+ * // With middleware and history
+ * const [state, dispatch] = useReducer(reducer, initialState, undefined, {
+ *   middleware: [createLoggerMiddleware('Counter')],
+ *   trackHistory: true,
+ * });
+ */
+function useReducer(reducer, initialArg, init, options = {}) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useReducer] Must be called within a component render phase');
+  }
+
+  if (typeof reducer !== 'function') {
+    throw new Error(
+      '[useReducer] First argument must be a reducer function. ' +
+      `Received: ${typeof reducer}`
+    );
+  }
+
+  // Initialize hooks array
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    // Re-render: use existing hook state
+    hook = component._hooks[currentHookIndex];
+  } else {
+    // First render: compute initial state
+    let initialState;
+
+    // Check for persisted state first
+    if (options.persistence) {
+      try {
+        const storage = window[options.persistence.storage || 'localStorage'];
+        const persisted = storage.getItem(options.persistence.key);
+        if (persisted !== null) {
+          initialState = (options.persistence.deserialize || JSON.parse)(persisted);
+        }
+      } catch (error) {
+        console.error('[useReducer] Load persistence error:', error);
+      }
+    }
+
+    // If no persisted state, compute initial state
+    if (initialState === undefined) {
+      if (typeof init === 'function') {
+        // Lazy initialization
+        try {
+          initialState = init(initialArg);
+        } catch (error) {
+          console.error('[useReducer] Lazy initializer error:', error);
+          initialState = initialArg;
+        }
+      } else {
+        initialState = initialArg;
+      }
+    }
+
+    hook = {
+      type: 'reducer',
+      state: initialState,
+      reducer,
+      _middleware: options.middleware || [],
+      _persistence: options.persistence || null,
+      _subscribers: new Set(),
+      _isDispatching: false,
+      _actionHistory: options.trackHistory ? [] : null,
+      _maxHistorySize: options.maxHistorySize || 100,
+      _undoStack: [],
+      _redoStack: [],
+      _optimisticState: null,
+      _isOptimistic: false,
+    };
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Update reducer reference in case it changes
+  hook.reducer = reducer;
+
+  hookIndex++;
+
+  // ─── Dispatch Implementation ────────────────────────────────────────────
+
+  /**
+   * Dispatch an action to the reducer.
+   *
+   * @param {*} action - The action to dispatch (typically { type, payload })
+   */
+  const dispatch = function dispatch(action) {
+    if (!component._hooks) {
+      console.warn('[useReducer] Dispatch called on unmounted component');
+      return;
+    }
+
+    const targetHook = component._hooks[currentHookIndex];
+    if (!targetHook) {
+      console.warn('[useReducer] Hook index out of bounds');
+      return;
+    }
+
+    // Prevent dispatching during reducer execution
+    if (targetHook._isDispatching) {
+      throw new Error(
+        '[useReducer] Cannot dispatch an action while the reducer is executing. ' +
+        'This is not allowed to prevent infinite loops.'
+      );
+    }
+
+    if (isBatchingDispatches) {
+      // Queue the dispatch for batch processing
+      if (!pendingDispatches.has(component)) {
+        pendingDispatches.set(component, []);
+      }
+      pendingDispatches.get(component).push({
+        hookIdx: currentHookIndex,
+        action,
+        reducer: targetHook.reducer,
+      });
+      return;
+    }
+
+    // Immediate dispatch
+    let processedAction = action;
+
+    // Apply middleware chain
+    if (targetHook._middleware && targetHook._middleware.length > 0) {
+      processedAction = applyMiddlewareChain(targetHook._middleware, action, targetHook.state);
+      if (processedAction === null) return; // Action was cancelled by middleware
+    }
+
+    // Run the reducer
+    targetHook._isDispatching = true;
+    let newState;
+    try {
+      newState = targetHook.reducer(targetHook.state, processedAction);
+    } catch (error) {
+      targetHook._isDispatching = false;
+      console.error('[useReducer] Reducer error:', error);
+      if (component._handleError) {
+        component._handleError(error);
+      }
+      return;
+    }
+    targetHook._isDispatching = false;
+
+    // State comparison
+    if (Object.is(targetHook.state, newState)) return;
+
+    const prevState = targetHook.state;
+    targetHook.state = newState;
+
+    // Track in action history
+    if (targetHook._actionHistory) {
+      targetHook._actionHistory.push({
+        action: processedAction,
+        prevState,
+        nextState: newState,
+        timestamp: Date.now(),
+      });
+      if (targetHook._actionHistory.length > targetHook._maxHistorySize) {
+        targetHook._actionHistory.shift();
+      }
+    }
+
+    // Notify subscribers
+    targetHook._subscribers.forEach((callback) => {
+      try {
+        callback(newState, prevState, processedAction);
+      } catch (error) {
+        console.error('[useReducer] Subscriber error:', error);
+      }
+    });
+
+    // Persist state
+    if (targetHook._persistence) {
+      try {
+        const storage = window[targetHook._persistence.storage || 'localStorage'];
+        const serialized = (targetHook._persistence.serialize || JSON.stringify)(newState);
+        storage.setItem(targetHook._persistence.key, serialized);
+      } catch (error) {
+        console.error('[useReducer] Persistence error:', error);
+      }
+    }
+
+    // Schedule re-render
+    if (scheduleUpdateCallback) {
+      scheduleUpdateCallback(component);
+    } else if (component._scheduleReRender) {
+      component._scheduleReRender();
+    }
+  };
+
+  // ─── Extended Dispatch Methods ──────────────────────────────────────────
+
+  /**
+   * Get the current state without triggering a re-render.
+   * @returns {*} Current state
+   */
+  dispatch.getState = function getState() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook ? targetHook.state : undefined;
+  };
+
+  /**
+   * Subscribe to state changes from this reducer.
+   * @param {Function} callback - Called with (newState, prevState, action)
+   * @returns {Function} Unsubscribe function
+   */
+  dispatch.subscribe = function subscribe(callback) {
+    const targetHook = component._hooks?.[currentHookIndex];
+    if (!targetHook) return function noop() {};
+
+    targetHook._subscribers.add(callback);
+    return function unsubscribe() {
+      targetHook._subscribers.delete(callback);
+    };
+  };
+
+  /**
+   * Add middleware to this reducer's middleware chain.
+   * @param {Function} middleware - Middleware function
+   * @returns {Function} Removal function
+   */
+  dispatch.addMiddleware = function addMiddleware(middleware) {
+    const targetHook = component._hooks?.[currentHookIndex];
+    if (!targetHook) return function noop() {};
+
+    targetHook._middleware.push(middleware);
+    return function removeMiddleware() {
+      const idx = targetHook._middleware.indexOf(middleware);
+      if (idx !== -1) targetHook._middleware.splice(idx, 1);
+    };
+  };
+
+  /**
+   * Dispatch multiple actions at once (batched).
+   * @param {Array} actions - Array of actions
+   */
+  dispatch.batch = function batch(actions) {
+    if (!Array.isArray(actions)) {
+      console.warn('[useReducer] dispatch.batch expects an array of actions');
+      return;
+    }
+    startBatchDispatches();
+    try {
+      actions.forEach((action) => dispatch(action));
+    } finally {
+      endBatchDispatches();
+    }
+  };
+
+  /**
+   * Reset state to the initial value.
+   */
+  dispatch.reset = function reset() {
+    let resetState;
+    if (typeof init === 'function') {
+      resetState = init(initialArg);
+    } else {
+      resetState = initialArg;
+    }
+    dispatch({ type: '__RESET__', payload: resetState });
+  };
+
+  /**
+   * Get the action history (if tracking is enabled).
+   * @returns {Array|null}
+   */
+  dispatch.getHistory = function getHistory() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook?._actionHistory || null;
+  };
+
+  // ─── Undo/Redo Support ──────────────────────────────────────────────────
+
+  /**
+   * Undo the last action. Pushes the current state to the redo stack.
+   * @returns {boolean} True if undo was successful
+   */
+  dispatch.undo = function undo() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    if (!targetHook || targetHook._undoStack.length === 0) return false;
+
+    const prev = targetHook._undoStack.pop();
+    targetHook._redoStack.push(targetHook.state);
+    targetHook.state = prev;
+
+    if (component._scheduleReRender) component._scheduleReRender();
+    return true;
+  };
+
+  /**
+   * Redo the last undone action.
+   * @returns {boolean} True if redo was successful
+   */
+  dispatch.redo = function redo() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    if (!targetHook || targetHook._redoStack.length === 0) return false;
+
+    const next = targetHook._redoStack.pop();
+    targetHook._undoStack.push(targetHook.state);
+    targetHook.state = next;
+
+    if (component._scheduleReRender) component._scheduleReRender();
+    return true;
+  };
+
+  /**
+   * Check if undo is available.
+   * @returns {boolean}
+   */
+  dispatch.canUndo = function canUndo() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook ? targetHook._undoStack.length > 0 : false;
+  };
+
+  /**
+   * Check if redo is available.
+   * @returns {boolean}
+   */
+  dispatch.canRedo = function canRedo() {
+    const targetHook = component._hooks?.[currentHookIndex];
+    return targetHook ? targetHook._redoStack.length > 0 : false;
+  };
+
+  // ─── Optimistic Updates ─────────────────────────────────────────────────
+
+  /**
+   * Dispatch an optimistic update. The state is immediately updated
+   * with the optimistic value, then rolled back if the async action fails.
+   *
+   * @param {*} optimisticState - The optimistic state to apply immediately
+   * @param {Promise} asyncAction - Promise that resolves to an action
+   */
+  dispatch.optimistic = function optimistic(optimisticState, asyncAction) {
+    const targetHook = component._hooks?.[currentHookIndex];
+    if (!targetHook) return;
+
+    // Save current state for rollback
+    const realState = targetHook.state;
+    targetHook._undoStack.push(realState);
+    targetHook._optimisticState = realState;
+    targetHook._isOptimistic = true;
+
+    // Apply optimistic state immediately
+    targetHook.state = optimisticState;
+    if (component._scheduleReRender) component._scheduleReRender();
+
+    // Handle async resolution
+    if (asyncAction && typeof asyncAction.then === 'function') {
+      asyncAction.then(
+        function resolve(action) {
+          targetHook._isOptimistic = false;
+          targetHook._optimisticState = null;
+          dispatch(action);
+        },
+        function reject(error) {
+          // Roll back to the real state
+          targetHook._isOptimistic = false;
+          targetHook.state = targetHook._optimisticState || realState;
+          targetHook._optimisticState = null;
+          if (component._scheduleReRender) component._scheduleReRender();
+          console.error('[useReducer] Optimistic update failed:', error);
+        }
+      );
+    }
+  };
+
+  return [hook.state, dispatch];
+}
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Clean up reducer state when a component unmounts.
+ * @param {Object} component - The unmounting component
+ */
+function cleanupReducerState(component) {
+  if (!component._hooks) return;
+
+  component._hooks.forEach((hook) => {
+    if (hook && hook.type === 'reducer') {
+      hook._subscribers.clear();
+      hook._middleware = [];
+      hook._isDispatching = false;
+      if (hook._actionHistory) {
+        hook._actionHistory = null;
+      }
+      hook._undoStack = [];
+      hook._redoStack = [];
+    }
+  });
+
+  pendingDispatches.delete(component);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  useReducer,
+  setCurrentComponent,
+  resetHookIndex,
+  setScheduleUpdateCallback,
+  startBatchDispatches,
+  endBatchDispatches,
+  batchDispatches,
+  createLoggerMiddleware,
+  createValidationMiddleware,
+  createTransformMiddleware,
+  createThrottleMiddleware,
+  createActionCreators,
+  createAction,
+  applyMiddlewareChain,
+  cleanupReducerState,
+};