elementdrawing 1.0.0

package/src/jsx/hooks/useContext.js

@@ -0,0 +1,586 @@
+/**
+ * useContext Hook Implementation
+ * ElementDrawing Framework - Context API with creation, provider/consumer,
+ * default values, subscription, nested contexts, selectors, observers,
+ * context versioning, and change notification optimization.
+ */
+
+'use strict';
+
+// ─── Internal State ───────────────────────────────────────────────────────────
+
+let currentlyRenderingComponent = null;
+let hookIndex = 0;
+let contextIdCounter = 0;
+
+// ─── Context Versioning ───────────────────────────────────────────────────────
+
+/**
+ * Track context value versions to optimize change notifications.
+ * When a provider value is the same version, consumers can skip re-renders.
+ */
+const contextVersions = new WeakMap();
+
+function getContextVersion(context) {
+  return contextVersions.get(context) || 0;
+}
+
+function incrementContextVersion(context) {
+  const current = contextVersions.get(context) || 0;
+  contextVersions.set(context, current + 1);
+  return current + 1;
+}
+
+// ─── Context Creation ─────────────────────────────────────────────────────────
+
+/**
+ * Create a new context with a default value.
+ *
+ * @param {*} defaultValue - The default value used when no Provider is found
+ * @returns {Object} Context object with Provider and Consumer
+ *
+ * @example
+ * const ThemeContext = createContext('light');
+ * const LocaleContext = createContext({ language: 'en', region: 'US' });
+ */
+function createContext(defaultValue) {
+  const contextId = '__ED_CTX_' + (++contextIdCounter) + '__';
+
+  // Unique symbol for storing context value on providers
+  const valueKey = Symbol.for(contextId + '_value');
+  const subscribersKey = Symbol.for(contextId + '_subscribers');
+  const versionKey = Symbol.for(contextId + '_version');
+
+  // ─── Context Object ────────────────────────────────────────────────────
+
+  const context = {
+    _id: contextId,
+    _valueKey: valueKey,
+    _subscribersKey: subscribersKey,
+    _versionKey: versionKey,
+    _defaultValue: defaultValue,
+    _isContext: true,
+    _displayName: null,
+
+    /**
+     * Provider component that supplies context value to descendant consumers.
+     *
+     * @param {Object} props
+     * @param {*} props.value - The context value to provide
+     * @param {*} props.children - Child components
+     * @returns {Object} Virtual DOM node
+     */
+    Provider: null, // Assigned below
+
+    /**
+     * Consumer component that reads context value.
+     *
+     * @param {Object} props
+     * @param {Function} props.children - Render prop receiving context value
+     * @returns {*} Rendered result
+     */
+    Consumer: null, // Assigned below
+
+    /**
+     * Get the current context value by traversing the component tree upward.
+     * @param {Object} component - Starting component
+     * @returns {*} Context value or default value
+     */
+    _getValue(component) {
+      let current = component;
+      while (current) {
+        // Check if this component is a Provider for this context
+        if (current._contextProvider === contextId && current[valueKey] !== undefined) {
+          return current[valueKey];
+        }
+        current = current._parentComponent;
+      }
+      return defaultValue;
+    },
+
+    /**
+     * Get the version of the current context value.
+     * @param {Object} component - Starting component
+     * @returns {number} Version number
+     */
+    _getVersion(component) {
+      let current = component;
+      while (current) {
+        if (current._contextProvider === contextId) {
+          return current[versionKey] || 0;
+        }
+        current = current._parentComponent;
+      }
+      return 0;
+    },
+
+    /**
+     * Subscribe to context value changes.
+     * @param {Object} component - The subscribing component
+     * @param {Function} callback - Called with (newValue, oldValue)
+     * @returns {Function} Unsubscribe function
+     */
+    _subscribe(component, callback) {
+      let current = component;
+      while (current) {
+        if (current._contextProvider === contextId) {
+          if (!current[subscribersKey]) {
+            current[subscribersKey] = new Set();
+          }
+          const sub = { component, callback };
+          current[subscribersKey].add(sub);
+
+          return function unsubscribe() {
+            if (current[subscribersKey]) {
+              current[subscribersKey].delete(sub);
+            }
+          };
+        }
+        current = current._parentComponent;
+      }
+      return function noop() {};
+    },
+
+    /**
+     * Subscribe with a selector for optimized re-renders.
+     * @param {Object} component - The subscribing component
+     * @param {Function} selector - Selector function
+     * @param {Function} callback - Called when selected value changes
+     * @returns {Function} Unsubscribe function
+     */
+    _subscribeWithSelector(component, selector, callback) {
+      let lastSelectedValue = selector(context._getValue(component));
+
+      return context._subscribe(component, (newValue, oldValue) => {
+        const newSelectedValue = selector(newValue);
+        if (!Object.is(lastSelectedValue, newSelectedValue)) {
+          const prevSelected = lastSelectedValue;
+          lastSelectedValue = newSelectedValue;
+          callback(newSelectedValue, prevSelected);
+        }
+      });
+    },
+
+    /**
+     * Notify all subscribers when the Provider value changes.
+     * @param {Object} providerComponent - The Provider component
+     * @param {*} newValue - New context value
+     * @param {*} oldValue - Previous context value
+     */
+    _notifySubscribers(providerComponent, newValue, oldValue) {
+      const subs = providerComponent[subscribersKey];
+      if (!subs) return;
+
+      subs.forEach(({ component, callback }) => {
+        try {
+          callback(newValue, oldValue);
+        } catch (error) {
+          console.error('[useContext] Subscriber notification error:', error);
+          if (component._handleError) {
+            component._handleError(error);
+          }
+        }
+      });
+    },
+  };
+
+  // ─── Provider Implementation ────────────────────────────────────────────
+
+  /**
+   * Provider component wraps children and supplies a context value.
+   * When the value prop changes, all subscribed consumers re-render.
+   */
+  context.Provider = function Provider(props) {
+    const component = currentlyRenderingComponent;
+
+    // Mark this component as a provider for this context
+    if (component) {
+      component._contextProvider = contextId;
+
+      // Check if value changed
+      const prevValue = component[valueKey];
+      const newValue = props.value;
+
+      if (!Object.is(prevValue, newValue)) {
+        component[valueKey] = newValue;
+
+        // Increment version
+        const newVersion = (component[versionKey] || 0) + 1;
+        component[versionKey] = newVersion;
+        incrementContextVersion(context);
+
+        // Notify subscribers of value change
+        context._notifySubscribers(component, newValue, prevValue);
+      }
+
+      // Initialize subscribers set
+      if (!component[subscribersKey]) {
+        component[subscribersKey] = new Set();
+      }
+    }
+
+    return props.children;
+  };
+
+  context.Provider._context = context;
+  context.Provider.displayName = 'Context.Provider';
+
+  // ─── Consumer Implementation ────────────────────────────────────────────
+
+  /**
+   * Consumer component uses the render prop pattern to access context value.
+   */
+  context.Consumer = function Consumer(props) {
+    const component = currentlyRenderingComponent;
+    let value = defaultValue;
+
+    if (component) {
+      value = context._getValue(component);
+    }
+
+    if (typeof props.children === 'function') {
+      return props.children(value);
+    }
+
+    console.warn(
+      '[useContext] Consumer children should be a function. ' +
+      'Received: ' + typeof props.children
+    );
+    return props.children;
+  };
+
+  context.Consumer._context = context;
+  context.Consumer.displayName = 'Context.Consumer';
+
+  return context;
+}
+
+// ─── useContext Hook ───────────────────────────────────────────────────────────
+
+/**
+ * useContext - Read context value and subscribe to changes.
+ *
+ * @param {Object} context - Context object created by createContext
+ * @returns {*} Current context value
+ *
+ * @example
+ * const theme = useContext(ThemeContext);
+ * const { language } = useContext(LocaleContext);
+ */
+function useContext(context) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useContext] Must be called within a component render phase');
+  }
+
+  if (!context || !context._isContext) {
+    throw new Error(
+      '[useContext] Argument must be a context object created by createContext()'
+    );
+  }
+
+  // Initialize hooks array
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    // Re-render: reuse existing hook
+    hook = component._hooks[currentHookIndex];
+  } else {
+    // First render: create hook and subscribe to context
+    hook = {
+      type: 'context',
+      context,
+      _unsubscribe: null,
+      _lastValue: null,
+      _version: 0,
+    };
+
+    // Subscribe to context changes to trigger re-render
+    const unsubscribe = context._subscribe(component, (newValue, oldValue) => {
+      // Schedule re-render when context value changes
+      if (component._scheduleReRender) {
+        component._scheduleReRender();
+      }
+    });
+    hook._unsubscribe = unsubscribe;
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Get the current context value
+  const value = context._getValue(component);
+  hook._lastValue = value;
+  hook._version = context._getVersion(component);
+
+  hookIndex++;
+  return value;
+}
+
+// ─── Context Selector Hook ────────────────────────────────────────────────────
+
+/**
+ * useContextSelector - Read a specific slice of context using a selector.
+ * Only re-renders when the selected value changes, not on every context change.
+ *
+ * @param {Object} context - Context object created by createContext
+ * @param {Function} selector - Function that extracts a value from context
+ * @returns {*} Selected value from context
+ *
+ * @example
+ * const theme = useContextSelector(ThemeContext, ctx => ctx.mode);
+ * const language = useContextSelector(LocaleContext, ctx => ctx.language);
+ */
+function useContextSelector(context, selector) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useContextSelector] Must be called within a component render phase');
+  }
+
+  if (!context || !context._isContext) {
+    throw new Error('[useContextSelector] First argument must be a context object');
+  }
+
+  if (typeof selector !== 'function') {
+    throw new Error('[useContextSelector] Second argument must be a selector function');
+  }
+
+  // Initialize hooks array
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+    hook.selector = selector;
+  } else {
+    hook = {
+      type: 'context-selector',
+      context,
+      selector,
+      _unsubscribe: null,
+      _lastSelectedValue: undefined,
+    };
+
+    // Subscribe with selector for optimized updates
+    const unsubscribe = context._subscribeWithSelector(
+      component,
+      selector,
+      (newSelected, oldSelected) => {
+        if (component._scheduleReRender) {
+          component._scheduleReRender();
+        }
+      }
+    );
+    hook._unsubscribe = unsubscribe;
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  // Compute selected value
+  const fullValue = context._getValue(component);
+  const selectedValue = selector(fullValue);
+  hook._lastSelectedValue = selectedValue;
+
+  hookIndex++;
+  return selectedValue;
+}
+
+// ─── Context Observer Hook ────────────────────────────────────────────────────
+
+/**
+ * useContextObserver - Observe context changes with a callback instead of
+ * triggering a re-render. Useful for logging, analytics, or side effects.
+ *
+ * @param {Object} context - Context object
+ * @param {Function} observer - Called with (newValue, oldValue) on changes
+ * @returns {*} Current context value
+ *
+ * @example
+ * const theme = useContextObserver(ThemeContext, (newTheme) => {
+ *   analytics.track('theme_changed', { theme: newTheme });
+ * });
+ */
+function useContextObserver(context, observer) {
+  const component = currentlyRenderingComponent;
+  if (!component) {
+    throw new Error('[useContextObserver] Must be called within a component render phase');
+  }
+
+  if (!context || !context._isContext) {
+    throw new Error('[useContextObserver] First argument must be a context object');
+  }
+
+  if (typeof observer !== 'function') {
+    throw new Error('[useContextObserver] Second argument must be an observer function');
+  }
+
+  if (!component._hooks) {
+    component._hooks = [];
+  }
+
+  const currentHookIndex = hookIndex;
+  let hook;
+
+  if (component._hooks[currentHookIndex]) {
+    hook = component._hooks[currentHookIndex];
+    hook.observer = observer;
+  } else {
+    hook = {
+      type: 'context-observer',
+      context,
+      observer,
+      _unsubscribe: null,
+    };
+
+    // Subscribe to context changes (observer doesn't trigger re-render)
+    const unsubscribe = context._subscribe(component, (newValue, oldValue) => {
+      try {
+        observer(newValue, oldValue);
+      } catch (error) {
+        console.error('[useContextObserver] Observer error:', error);
+      }
+    });
+    hook._unsubscribe = unsubscribe;
+
+    component._hooks[currentHookIndex] = hook;
+  }
+
+  const value = context._getValue(component);
+  hookIndex++;
+  return value;
+}
+
+// ─── Nested Context Support ───────────────────────────────────────────────────
+
+/**
+ * Merge multiple contexts into a single object for convenience.
+ *
+ * @param {Object[]} contexts - Array of context objects
+ * @returns {Object} Object with current values from all contexts
+ *
+ * @example
+ * const { theme, locale } = useMergedContext([ThemeContext, LocaleContext]);
+ */
+function useMergedContext(contexts) {
+  if (!Array.isArray(contexts)) {
+    throw new Error('[useMergedContext] Expected an array of context objects');
+  }
+
+  const values = {};
+  contexts.forEach((ctx) => {
+    const name = ctx._id.replace('__ED_CTX_', '').replace('__', '');
+    values[name] = useContext(ctx);
+  });
+  return values;
+}
+
+/**
+ * Create a composed context that derives its value from multiple parent contexts.
+ *
+ * @param {Object[]} contexts - Array of parent context objects
+ * @param {Function} compute - Function that receives parent values and returns composed value
+ * @returns {Object} New context object
+ *
+ * @example
+ * const ComposedCtx = composeContexts(
+ *   [ThemeContext, LocaleContext],
+ *   (theme, locale) => ({ theme, locale, isDark: theme === 'dark' })
+ * );
+ */
+function composeContexts(contexts, compute) {
+  const defaultValues = contexts.map((ctx) => ctx._defaultValue);
+  const composedDefault = compute(...defaultValues);
+  return createContext(composedDefault);
+}
+
+// ─── Context Tree Utilities ───────────────────────────────────────────────────
+
+/**
+ * Find the nearest Provider for a given context in the component tree.
+ * @param {Object} component - Starting component
+ * @param {Object} context - Context to search for
+ * @returns {Object|null} Provider component or null
+ */
+function findNearestProvider(component, context) {
+  let current = component;
+  while (current) {
+    if (current._contextProvider === context._id) {
+      return current;
+    }
+    current = current._parentComponent;
+  }
+  return null;
+}
+
+/**
+ * Get all context values from the component tree.
+ * @param {Object} component - Starting component
+ * @returns {Object} Map of context IDs to values
+ */
+function getAllContextValues(component) {
+  const values = {};
+  let current = component;
+  while (current) {
+    if (current._contextProvider && current[Symbol.for('__ED_CTX_' + current._contextProvider + '__value')]) {
+      values[current._contextProvider] = current[Symbol.for('__ED_CTX_' + current._contextProvider + '__value')];
+    }
+    current = current._parentComponent;
+  }
+  return values;
+}
+
+// ─── Hook Context Management ──────────────────────────────────────────────────
+
+function setCurrentComponent(component) {
+  currentlyRenderingComponent = component;
+  hookIndex = 0;
+}
+
+function resetHookIndex() {
+  hookIndex = 0;
+  currentlyRenderingComponent = null;
+}
+
+// ─── Cleanup ──────────────────────────────────────────────────────────────────
+
+/**
+ * Clean up context subscriptions when a component unmounts.
+ * @param {Object} component - The unmounting component
+ */
+function cleanupContextSubscriptions(component) {
+  if (!component._hooks) return;
+
+  component._hooks.forEach((hook) => {
+    if (hook && (hook.type === 'context' || hook.type === 'context-selector' || hook.type === 'context-observer')) {
+      if (typeof hook._unsubscribe === 'function') {
+        hook._unsubscribe();
+        hook._unsubscribe = null;
+      }
+    }
+  });
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  createContext,
+  useContext,
+  useContextSelector,
+  useContextObserver,
+  useMergedContext,
+  composeContexts,
+  setCurrentComponent,
+  resetHookIndex,
+  findNearestProvider,
+  getAllContextValues,
+  cleanupContextSubscriptions,
+  getContextVersion,
+};