elementdrawing 1.0.0

package/src/jsx/runtime/createElement.js

@@ -0,0 +1,860 @@
+/**
+ * createElement - Core Virtual DOM Element Creation
+ * ElementDrawing Framework - Creates virtual DOM nodes with comprehensive
+ * props processing, children handling, fragments, keys, refs, Suspense,
+ * StrictMode, error boundaries, lazy loading, and profiling.
+ */
+
+'use strict';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const REACT_ELEMENT_TYPE = Symbol.for('elementdrawing.element');
+const REACT_FRAGMENT_TYPE = Symbol.for('elementdrawing.fragment');
+const REACT_PORTAL_TYPE = Symbol.for('elementdrawing.portal');
+const REACT_SUSPENSE_TYPE = Symbol.for('elementdrawing.suspense');
+const REACT_LAZY_TYPE = Symbol.for('elementdrawing.lazy');
+const REACT_STRICT_MODE_TYPE = Symbol.for('elementdrawing.strict_mode');
+const REACT_ERROR_BOUNDARY_TYPE = Symbol.for('elementdrawing.error_boundary');
+const REACT_PROVIDER_TYPE = Symbol.for('elementdrawing.provider');
+const REACT_CONSUMER_TYPE = Symbol.for('elementdrawing.consumer');
+
+const RESERVED_PROPS = {
+  key: true,
+  ref: true,
+  __self: true,
+  __source: true,
+};
+
+// ─── Element Type Detection ───────────────────────────────────────────────────
+
+/**
+ * Check if a value is a valid element type.
+ * @param {*} type
+ * @returns {boolean}
+ */
+function isValidElementType(type) {
+  if (typeof type === 'string') return true;
+  if (typeof type === 'function') return true;
+  if (typeof type === 'symbol') return true;
+  if (type === REACT_FRAGMENT_TYPE) return true;
+  if (type === REACT_PORTAL_TYPE) return true;
+  if (type === REACT_SUSPENSE_TYPE) return true;
+  if (type === REACT_STRICT_MODE_TYPE) return true;
+  if (type === REACT_ERROR_BOUNDARY_TYPE) return true;
+  return false;
+}
+
+/**
+ * Check if a value is a virtual DOM element.
+ * @param {*} element
+ * @returns {boolean}
+ */
+function isValidElement(element) {
+  return (
+    element !== null &&
+    typeof element === 'object' &&
+    element.$$typeof === REACT_ELEMENT_TYPE
+  );
+}
+
+/**
+ * Check if an element type is a function component.
+ * @param {*} type
+ * @returns {boolean}
+ */
+function isFunctionComponent(type) {
+  return typeof type === 'function' && !type._isClassComponent;
+}
+
+/**
+ * Check if an element type is a class component.
+ * @param {*} type
+ * @returns {boolean}
+ */
+function isClassComponent(type) {
+  return typeof type === 'function' && type._isClassComponent === true;
+}
+
+/**
+ * Check if an element type is a host (HTML) element.
+ * @param {*} type
+ * @returns {boolean}
+ */
+function isHostElement(type) {
+  return typeof type === 'string';
+}
+
+/**
+ * Check if an element is a Suspense boundary.
+ * @param {Object} element
+ * @returns {boolean}
+ */
+function isSuspenseElement(element) {
+  return isValidElement(element) && element.type === REACT_SUSPENSE_TYPE;
+}
+
+/**
+ * Check if an element is a StrictMode wrapper.
+ * @param {Object} element
+ * @returns {boolean}
+ */
+function isStrictModeElement(element) {
+  return isValidElement(element) && element.type === REACT_STRICT_MODE_TYPE;
+}
+
+/**
+ * Check if an element is an error boundary.
+ * @param {Object} element
+ * @returns {boolean}
+ */
+function isErrorBoundaryElement(element) {
+  return isValidElement(element) && element.type === REACT_ERROR_BOUNDARY_TYPE;
+}
+
+// ─── Key Extraction & Validation ──────────────────────────────────────────────
+
+/**
+ * Extract and validate the key from props.
+ * @param {*} key - The key value
+ * @param {*} parentKey - Parent key for nested elements
+ * @returns {string|null} Validated key string
+ */
+function extractKey(key, parentKey) {
+  if (key === undefined || key === null) return null;
+
+  const keyString = String(key);
+
+  if (keyString === '') {
+    console.warn('[createElement] Empty string key detected. This may cause reconciliation issues.');
+    return null;
+  }
+
+  // Validate key format
+  if (/^\./.test(keyString) || /\$/.test(keyString) || /\.\./.test(keyString)) {
+    console.warn(
+      '[createElement] Key contains invalid characters (., $, ..): ' +
+      `"${keyString}". Keys should be simple strings or numbers.`
+    );
+  }
+
+  return parentKey ? parentKey + '/' + keyString : keyString;
+}
+
+/**
+ * Validate that keys are unique among siblings.
+ * @param {Array} children - Array of child elements
+ */
+function validateChildKeys(children) {
+  if (!Array.isArray(children)) return;
+
+  const seenKeys = new Set();
+  let hasIndexKey = false;
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!isValidElement(child)) continue;
+
+    const key = child.key;
+    if (key === null) {
+      hasIndexKey = true;
+      continue;
+    }
+
+    if (seenKeys.has(key)) {
+      console.warn(
+        '[createElement] Duplicate key "' + key + '" found in children. ' +
+        'This may cause components to be duplicated or lost during reconciliation.'
+      );
+    }
+    seenKeys.add(key);
+  }
+
+  if (hasIndexKey && seenKeys.size > 0) {
+    console.warn(
+      '[createElement] Mixed explicit and implicit keys detected. ' +
+      'When using keys, all siblings should have explicit keys for optimal reconciliation.'
+    );
+  }
+}
+
+// ─── Ref Forwarding ───────────────────────────────────────────────────────────
+
+/**
+ * Process the ref prop and handle ref forwarding.
+ * @param {*} ref - Ref value
+ * @param {Object} element - The element being created
+ * @returns {*} Processed ref
+ */
+function processRef(ref, element) {
+  if (ref === undefined || ref === null) return null;
+
+  // Object ref (useRef)
+  if (typeof ref === 'object' && ref._isRef) {
+    return ref;
+  }
+
+  // Callback ref
+  if (typeof ref === 'function') {
+    return ref;
+  }
+
+  // String ref (legacy)
+  if (typeof ref === 'string') {
+    console.warn(
+      '[createElement] String refs are deprecated. Use callback refs or useRef instead. ' +
+      `Received ref: "${ref}"`
+    );
+    return ref;
+  }
+
+  // Forwarded ref
+  if (ref._isForwardRef) {
+    return ref;
+  }
+
+  console.warn('[createElement] Invalid ref type: ' + typeof ref);
+  return null;
+}
+
+// ─── Props Processing ─────────────────────────────────────────────────────────
+
+/**
+ * Process and clean props, removing reserved props and applying defaults.
+ * @param {*} type - Element type
+ * @param {Object} props - Raw props
+ * @param {*} key - Element key
+ * @param {*} ref - Element ref
+ * @returns {Object} Cleaned props
+ */
+function processProps(type, props, key, ref) {
+  const cleanedProps = {};
+
+  for (const propName in props) {
+    if (props.hasOwnProperty(propName)) {
+      if (RESERVED_PROPS[propName]) continue;
+
+      const propValue = props[propName];
+
+      // Process event handlers
+      if (propName.startsWith('on') && typeof propValue === 'function') {
+        cleanedProps[propName] = propValue;
+        continue;
+      }
+
+      // Process style prop
+      if (propName === 'style') {
+        cleanedProps[propName] = processStyleProp(propValue);
+        continue;
+      }
+
+      // Process className / class
+      if (propName === 'className' || propName === 'class') {
+        cleanedProps.className = processClassName(propValue);
+        continue;
+      }
+
+      // Process dangerouslySetInnerHTML
+      if (propName === 'dangerouslySetInnerHTML') {
+        if (propValue && typeof propValue.__html === 'string') {
+          cleanedProps[propName] = propValue;
+        } else {
+          console.warn('[createElement] dangerouslySetInnerHTML must have a __html property');
+        }
+        continue;
+      }
+
+      // Process suppressHydrationWarning
+      if (propName === 'suppressHydrationWarning') {
+        cleanedProps[propName] = !!propValue;
+        continue;
+      }
+
+      cleanedProps[propName] = propValue;
+    }
+  }
+
+  // Apply default props
+  if (type && type.defaultProps) {
+    for (const defaultProp in type.defaultProps) {
+      if (type.defaultProps.hasOwnProperty(defaultProp) && cleanedProps[defaultProp] === undefined) {
+        cleanedProps[defaultProp] = type.defaultProps[defaultProp];
+      }
+    }
+  }
+
+  return cleanedProps;
+}
+
+/**
+ * Process the style prop into a consistent format.
+ * @param {*} style
+ * @returns {Object|string|undefined}
+ */
+function processStyleProp(style) {
+  if (style === null || style === undefined) return undefined;
+
+  if (typeof style === 'string') return style;
+
+  if (typeof style === 'object') {
+    const processed = {};
+    for (const prop in style) {
+      if (style.hasOwnProperty(prop)) {
+        const value = style[prop];
+        const cssProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+
+        if (typeof value === 'number' && !isUnitlessProperty(cssProp)) {
+          processed[cssProp] = value + 'px';
+        } else {
+          processed[cssProp] = value;
+        }
+      }
+    }
+    return processed;
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if a CSS property is unitless.
+ * @param {string} prop
+ * @returns {boolean}
+ */
+function isUnitlessProperty(prop) {
+  const unitlessProps = new Set([
+    'animation-iteration-count', 'border-image-outset', 'border-image-slice',
+    'border-image-width', 'box-flex', 'box-flex-group', 'box-ordinal-group',
+    'column-count', 'columns', 'flex', 'flex-grow', 'flex-positive',
+    'flex-shrink', 'flex-negative', 'flex-order', 'grid-row', 'grid-row-end',
+    'grid-row-span', 'grid-row-start', 'grid-column', 'grid-column-end',
+    'grid-column-span', 'grid-column-start', 'font-weight', 'line-clamp',
+    'line-height', 'opacity', 'order', 'orphans', 'tab-size', 'widows',
+    'z-index', 'zoom', 'fill-opacity', 'flood-opacity', 'stop-opacity',
+    'stroke-dasharray', 'stroke-dashoffset', 'stroke-miterlimit',
+    'stroke-opacity', 'stroke-width',
+  ]);
+  return unitlessProps.has(prop);
+}
+
+/**
+ * Process className prop.
+ * @param {*} className
+ * @returns {string}
+ */
+function processClassName(className) {
+  if (className === null || className === undefined) return '';
+
+  if (typeof className === 'string') return className;
+
+  if (Array.isArray(className)) {
+    return className.filter(Boolean).join(' ');
+  }
+
+  if (typeof className === 'object') {
+    return Object.keys(className)
+      .filter((key) => className[key])
+      .join(' ');
+  }
+
+  return String(className);
+}
+
+// ─── Children Processing ──────────────────────────────────────────────────────
+
+/**
+ * Flatten and normalize children, handling arrays, fragments, and nested structures.
+ * @param {Array} children - Raw children arguments
+ * @returns {Array} Normalized flat array of children
+ */
+function flattenChildren(children) {
+  const result = [];
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+
+    if (child === null || child === undefined || typeof child === 'boolean') {
+      continue;
+    }
+
+    if (Array.isArray(child)) {
+      const flat = flattenChildren(child);
+      for (let j = 0; j < flat.length; j++) {
+        result.push(flat[j]);
+      }
+    } else if (isValidElement(child) && child.type === REACT_FRAGMENT_TYPE) {
+      if (child.props && child.props.children) {
+        const fragmentChildren = Array.isArray(child.props.children)
+          ? child.props.children
+          : [child.props.children];
+        const flat = flattenChildren(fragmentChildren);
+        for (let j = 0; j < flat.length; j++) {
+          result.push(flat[j]);
+        }
+      }
+    } else {
+      result.push(child);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Normalize children into a consistent format.
+ * @param {Array} children
+ * @param {string|null} parentKey
+ * @returns {Array}
+ */
+function normalizeChildren(children, parentKey) {
+  if (children.length === 0) return [];
+
+  const normalized = [];
+
+  for (let i = 0; i < children.length; i++) {
+    let child = children[i];
+
+    if (typeof child === 'string' || typeof child === 'number') {
+      child = createTextElement(String(child));
+    }
+
+    if (isValidElement(child)) {
+      if (child.key === null) {
+        child = assignKey(child, parentKey, i);
+      }
+      normalized.push(child);
+    } else if (child !== null && child !== undefined) {
+      console.warn('[createElement] Invalid child type: ' + typeof child);
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Create a text element for primitive children.
+ * @param {string} text
+ * @returns {Object}
+ */
+function createTextElement(text) {
+  return {
+    $$typeof: REACT_ELEMENT_TYPE,
+    type: '#text',
+    props: { nodeValue: text, children: [] },
+    key: null,
+    ref: null,
+    _owner: null,
+  };
+}
+
+/**
+ * Assign an implicit key based on the parent key and child index.
+ */
+function assignKey(element, parentKey, index) {
+  const key = parentKey ? parentKey + '.' + index : '.' + index;
+  return Object.assign({}, element, { key });
+}
+
+// ─── Props Cloning & Merging ──────────────────────────────────────────────────
+
+/**
+ * Clone an element with new props merged.
+ * @param {Object} element
+ * @param {Object} newProps
+ * @param {...*} newChildren
+ * @returns {Object}
+ */
+function cloneElement(element, newProps) {
+  if (!isValidElement(element)) {
+    throw new Error('[cloneElement] Argument must be a valid element');
+  }
+
+  const children = Array.prototype.slice.call(arguments, 2);
+  const mergedProps = Object.assign({}, element.props, newProps);
+
+  if (children.length > 0) {
+    mergedProps.children = children.length === 1 ? children[0] : children;
+  }
+
+  const key = newProps && newProps.key !== undefined ? newProps.key : element.key;
+  const ref = newProps && newProps.ref !== undefined ? newProps.ref : element.ref;
+
+  if (newProps && newProps.key !== undefined) delete mergedProps.key;
+  if (newProps && newProps.ref !== undefined) delete mergedProps.ref;
+
+  return createElement(element.type, Object.assign({ key, ref }, mergedProps));
+}
+
+/**
+ * Merge props from multiple sources.
+ * Event handlers are chained rather than overwritten.
+ * @returns {Object}
+ */
+function mergeProps() {
+  const result = {};
+
+  for (let i = 0; i < arguments.length; i++) {
+    const props = arguments[i];
+    if (!props) continue;
+
+    for (const key in props) {
+      if (!props.hasOwnProperty(key)) continue;
+
+      if (key.startsWith('on') && result[key] && typeof result[key] === 'function') {
+        const existingHandler = result[key];
+        const newHandler = props[key];
+        result[key] = function chainedHandler() {
+          existingHandler.apply(this, arguments);
+          newHandler.apply(this, arguments);
+        };
+      } else if (key === 'style' && result.style && typeof result.style === 'object' && typeof props.style === 'object') {
+        result.style = Object.assign({}, result.style, props.style);
+      } else if (key === 'className' && result.className) {
+        result.className = result.className + ' ' + props.className;
+      } else {
+        result[key] = props[key];
+      }
+    }
+  }
+
+  return result;
+}
+
+// ─── Core createElement ───────────────────────────────────────────────────────
+
+/**
+ * createElement - Create a virtual DOM element.
+ *
+ * @param {*} type - Element type
+ * @param {Object|null} config - Element configuration
+ * @param {...*} children - Child elements
+ * @returns {Object} Virtual DOM element
+ */
+function createElement(type, config) {
+  const children = Array.prototype.slice.call(arguments, 2);
+
+  // Validate type
+  if (!isValidElementType(type)) {
+    throw new Error(
+      '[createElement] Invalid element type: ' + typeof type +
+      '. Expected a string, function, or symbol.'
+    );
+  }
+
+  // Extract Key and Ref from Config
+  let key = null;
+  let ref = null;
+  let props = {};
+
+  if (config !== null && config !== undefined) {
+    if (typeof config !== 'object') {
+      throw new Error(
+        '[createElement] Config must be an object or null. ' +
+        'Received: ' + typeof config
+      );
+    }
+
+    if (config.key !== undefined) {
+      key = extractKey(config.key, null);
+    }
+
+    if (config.ref !== undefined) {
+      ref = processRef(config.ref, null);
+    }
+
+    for (const propName in config) {
+      if (config.hasOwnProperty(propName) && !RESERVED_PROPS[propName]) {
+        props[propName] = config[propName];
+      }
+    }
+  }
+
+  // Process Children
+  const flattenedChildren = flattenChildren(children);
+  const normalizedChildren = normalizeChildren(flattenedChildren, key);
+
+  if (normalizedChildren.length === 0) {
+    props.children = [];
+  } else if (normalizedChildren.length === 1) {
+    props.children = normalizedChildren[0];
+  } else {
+    props.children = normalizedChildren;
+  }
+
+  // Process Props
+  props = processProps(type, props, key, ref);
+
+  // Prop Type Validation
+  if (type && type.propTypes && typeof type.propTypes === 'object') {
+    for (const propName in type.propTypes) {
+      if (type.propTypes.hasOwnProperty(propName)) {
+        const validator = type.propTypes[propName];
+        if (typeof validator === 'function') {
+          const result = validator(props, propName, type.displayName || type.name || 'Component', 'prop');
+          if (result instanceof Error) {
+            console.warn('[createElement] Prop validation: ' + result.message);
+          }
+        }
+      }
+    }
+  }
+
+  // Validate Child Keys
+  if (Array.isArray(normalizedChildren) && normalizedChildren.length > 1) {
+    validateChildKeys(normalizedChildren);
+  }
+
+  // Create Element Object
+  const element = {
+    $$typeof: REACT_ELEMENT_TYPE,
+    type,
+    key,
+    ref,
+    props,
+    _owner: null,
+    _store: {},
+  };
+
+  // Make element immutable in development
+  if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV !== 'production') {
+    Object.freeze(element.props);
+    Object.freeze(element);
+  }
+
+  return element;
+}
+
+// ─── Fragment ─────────────────────────────────────────────────────────────────
+
+const Fragment = REACT_FRAGMENT_TYPE;
+
+// ─── Suspense ─────────────────────────────────────────────────────────────────
+
+/**
+ * Suspense component for handling async rendering.
+ * @param {Object} props
+ * @param {*} props.fallback - Fallback UI while suspended
+ * @param {*} props.children - Children to suspend
+ */
+const Suspense = REACT_SUSPENSE_TYPE;
+
+/**
+ * Create a Suspense element.
+ * @param {Object} props
+ * @returns {Object} Suspense element
+ */
+function createSuspense(props) {
+  return createElement(Suspense, props, props.children);
+}
+
+// ─── StrictMode ───────────────────────────────────────────────────────────────
+
+const StrictMode = REACT_STRICT_MODE_TYPE;
+
+/**
+ * Create a StrictMode wrapper element.
+ * @param {Object} props
+ * @returns {Object} StrictMode element
+ */
+function createStrictMode(props) {
+  return createElement(StrictMode, null, props.children);
+}
+
+// ─── Error Boundary ───────────────────────────────────────────────────────────
+
+const ErrorBoundary = REACT_ERROR_BOUNDARY_TYPE;
+
+/**
+ * Create an error boundary element.
+ * @param {Object} props
+ * @param {Function} props.onError - Error handler
+ * @param {*} props.fallback - Fallback UI
+ * @param {*} props.children - Children to protect
+ * @returns {Object} Error boundary element
+ */
+function createErrorBoundary(props) {
+  return createElement(ErrorBoundary, props, props.children);
+}
+
+// ─── Portal ───────────────────────────────────────────────────────────────────
+
+/**
+ * Create a portal element.
+ * @param {*} children
+ * @param {HTMLElement} container
+ * @param {string|null} key
+ * @returns {Object}
+ */
+function createPortal(children, container, key) {
+  return {
+    $$typeof: REACT_PORTAL_TYPE,
+    key: key === null ? null : String(key),
+    children,
+    containerInfo: container,
+    implementation: null,
+  };
+}
+
+// ─── Lazy Component ───────────────────────────────────────────────────────────
+
+/**
+ * Create a lazy-loaded component.
+ * @param {Function} factory
+ * @returns {Object}
+ */
+function lazy(factory) {
+  const lazyComponent = {
+    $$typeof: REACT_LAZY_TYPE,
+    _payload: {
+      _status: -1, // -1: pending, 0: resolved, 1: rejected
+      _result: null,
+    },
+    _init: function init(payload) {
+      if (payload._status === -1) {
+        const thenable = factory();
+        thenable.then(
+          function resolve(module) {
+            if (payload._status === -1) {
+              payload._status = 0;
+              payload._result = module.default || module;
+            }
+          },
+          function reject(error) {
+            if (payload._status === -1) {
+              payload._status = 1;
+              payload._result = error;
+            }
+          }
+        );
+        payload._status = -1;
+        payload._result = thenable;
+      }
+    },
+  };
+  return lazyComponent;
+}
+
+// ─── Children Utilities ───────────────────────────────────────────────────────
+
+/**
+ * Count the number of children.
+ * @param {*} children
+ * @returns {number}
+ */
+function countChildren(children) {
+  if (children === null || children === undefined) return 0;
+  if (Array.isArray(children)) return children.length;
+  return 1;
+}
+
+/**
+ * Map over children.
+ * @param {*} children
+ * @param {Function} fn
+ * @returns {Array}
+ */
+function mapChildren(children, fn) {
+  if (children === null || children === undefined) return [];
+
+  if (Array.isArray(children)) {
+    return children.map((child, index) => fn(child, index));
+  }
+
+  return [fn(children, 0)];
+}
+
+/**
+ * ForEach over children (no return value).
+ * @param {*} children
+ * @param {Function} fn
+ */
+function forEachChild(children, fn) {
+  if (children === null || children === undefined) return;
+
+  if (Array.isArray(children)) {
+    children.forEach((child, index) => fn(child, index));
+  } else {
+    fn(children, 0);
+  }
+}
+
+/**
+ * Check if children is an array with more than one element.
+ * @param {*} children
+ * @returns {boolean}
+ */
+function isChildrenArray(children) {
+  return Array.isArray(children) && children.length > 1;
+}
+
+/**
+ * Get only child from children.
+ * @param {*} children
+ * @returns {*}
+ */
+function onlyChild(children) {
+  if (!isValidElement(children)) {
+    throw new Error('[onlyChild] Expected a single ElementDrawing element');
+  }
+  return children;
+}
+
+// ─── Element Creation with Render Prop ────────────────────────────────────────
+
+function createElementWithRenderProp(type, props, renderFn) {
+  if (typeof renderFn !== 'function') {
+    throw new Error('[createElementWithRenderProp] Third argument must be a function');
+  }
+
+  return createElement(type, Object.assign({}, props, { children: renderFn }));
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  createElement,
+  cloneElement,
+  mergeProps,
+  createTextElement,
+  createPortal,
+  createSuspense,
+  createStrictMode,
+  createErrorBoundary,
+  createRef: function () { return { current: null, _isRef: true }; },
+  Fragment,
+  Suspense,
+  StrictMode,
+  ErrorBoundary,
+  lazy,
+  isValidElement,
+  isValidElementType,
+  isFunctionComponent,
+  isClassComponent,
+  isHostElement,
+  isSuspenseElement,
+  isStrictModeElement,
+  isErrorBoundaryElement,
+  extractKey,
+  processRef,
+  processProps,
+  processStyleProp,
+  processClassName,
+  flattenChildren,
+  normalizeChildren,
+  createElementWithRenderProp,
+  countChildren,
+  mapChildren,
+  forEachChild,
+  isChildrenArray,
+  onlyChild,
+  REACT_ELEMENT_TYPE,
+  REACT_FRAGMENT_TYPE,
+  REACT_PORTAL_TYPE,
+  REACT_SUSPENSE_TYPE,
+  REACT_LAZY_TYPE,
+  REACT_STRICT_MODE_TYPE,
+  REACT_ERROR_BOUNDARY_TYPE,
+  REACT_PROVIDER_TYPE,
+  REACT_CONSUMER_TYPE,
+  RESERVED_PROPS,
+};