@meonode/ui 0.4.10 → 0.4.11

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.4.11
+
+### Fix
+- **core**: enhance MeoNodeUnmounter cleanup logic and support additional props cloning ([`02c17f7`](https://github.com/l7aromeo/meonode-ui/commit/02c17f7))
+  - Refactor MeoNodeUnmounter to use useEffectEvent for stable cleanup on unmount
+  - Cleanup removes node from BaseNode.elementCache, untracks mount via MountTrackerUtil, unregisters from BaseNode.cacheCleanupRegistry, and clears lastSignature to prevent memory leaks
+  - Support cloning and forwarding additional props to valid React children elements
+
+### Refactor
+- **node.util**: enhance documentation for utility methods and improve clarity ([`ee42c24`](https://github.com/l7aromeo/meonode-ui/commit/ee42c24))
+- **theme**: reorder ThemeResolverCache methods for clarity ([`cb842c8`](https://github.com/l7aromeo/meonode-ui/commit/cb842c8))
+  - Moved `_generateCacheKey` and `_evict` methods below the main logic in `ThemeResolverCache` for better readability and organization
+  - Removed duplicate declaration of `_instance` property
+  - Kept functionality unchanged, improving code structure and maintainability
+
+### Test
+- **perf**: add memory leak detection test for navigation cycles and improve formatMemory function ([`ba139fc`](https://github.com/l7aromeo/meonode-ui/commit/ba139fc))
+  - Added a new performance test to detect memory leaks during repeated navigation cycles between pages
+  - The test measures heap memory usage before, during, and after navigation, ensuring memory growth stays within acceptable limits
+  - Enhanced the formatMemory utility to correctly handle negative byte values and added JSDoc comments for clarity
+  - Removed an obsolete shallowly equal props performance test to streamline the test suite
+- **unmounter**: add regression test for MeoNodeUnmounter to forward implicit props in MUI RadioGroup integration ([`2ecaabd`](https://github.com/l7aromeo/meonode-ui/commit/2ecaabd))
+  - Added a test to ensure MeoNodeUnmounter correctly forwards props injected via React.cloneElement, addressing issues with libraries like MUI where RadioGroup injects 'checked' and 'onChange' into Radio components
+  - This prevents swallowing of props and verifies proper behavior of controlled radio inputs
+  - Also updated an existing cache size assertion to allow equality, reflecting improved mount tracking
+- **perf**: update react-createelement comparison tests with 5000 nested nodes and fix typings ([`b345ec0`](https://github.com/l7aromeo/meonode-ui/commit/b345ec0))
+  - Changed rerender to use React.cloneElement<any> for proper typing
+  - Updated NUM_NODES constant to 5000 for nested structure tests
+  - Removed redundant comments about node count reduction to prevent stack overflow
+
+### Chore
+- **deps**: upgrade devDependencies and update test scripts ([`2ea128e`](https://github.com/l7aromeo/meonode-ui/commit/2ea128e))
+  - add new devDependencies: @emotion/is-prop-valid@1.4.0, @emotion/styled@11.14.1, @mui/material@7.3.5, and related packages
+  - update yarn to version 4.11.0
+  - update test scripts to increase max-old-space-size to 8192 and include react-createelement-comparison.test.ts in test and perf runs
+  - update various package resolutions in yarn.lock to align with new versions and dependencies
+- **babel**: add "builtIns": false to minify plugin configuration ([`e16cdfb`](https://github.com/l7aromeo/meonode-ui/commit/e16cdfb))
+- **yarn**: update yarnPath to version 4.11.0 ([`ecb6c68`](https://github.com/l7aromeo/meonode-ui/commit/ecb6c68))
+
+### Docs
+- **CONTRIBUTING**: improve formatting and readability of contribution guidelines ([`a7462ed`](https://github.com/l7aromeo/meonode-ui/commit/a7462ed))
+
 ## 0.4.10
 
 ### Fix
@@ -887,4 +929,4 @@ All notable changes to this project will be documented in this file.
 - This changelog covers the most recent development history available
 - The project focuses on building React UIs with type-safe fluency without JSX syntax
 - Recent development has emphasized Emotion integration, type safety improvements, and enhanced flexbox support
-- For a complete history, view all commits on GitHub: [View all commits](https://github.com/l7aromeo/meonode-ui/commits)
+- For a complete history, view all commits on GitHub: [View all commits](https://github.com/l7aromeo/meonode-ui/commits)

package/dist/components/meonode-unmounter.client.d.ts

@@ -1,21 +1,23 @@
 import { type ReactNode } from 'react';
 import type { NodeInstance } from '../types/node.type.js';
 /**
- * `MeoNodeUnmounter` is a client-side React component responsible for cleaning up
- * resources associated with a rendered node when it unmounts.
+ * `MeoNodeUnmounter` is a client-side React component responsible for performing cleanup
+ * operations when a `MeoNode` instance is unmounted from the React tree.
  *
- * It uses a `useEffect` hook to register a cleanup function that runs when the component
- * unmounts or when its `stableKey` changes. The cleanup function checks if the node
- * identified by `stableKey` is currently tracked as mounted. If it is, it removes
- * the node from `BaseNode.elementCache` and untracks its mount status using `MountTrackerUtil`.
- * Additionally, it clears the `lastPropsRef` and `lastSignature` of the associated `BaseNode`
- * instance to prevent memory leaks from retained prop objects.
+ * It leverages `useEffectEvent` to create a stable cleanup function that is called
+ * when the component unmounts. This cleanup function performs the following actions:
+ * - Deletes the node from `BaseNode.elementCache` using its `stableKey`.
+ * - Untracks the node's mount status via `MountTrackerUtil.untrackMount`.
+ * - Unregisters the node from `BaseNode.cacheCleanupRegistry` to prevent redundant
+ *   finalization callbacks.
+ * - Clears the `lastSignature` of the associated `BaseNode` instance to help prevent
+ *   memory leaks from retained prop objects.
  * @param {object} props The component's props.
  * @param {NodeInstance} props.node The BaseNode instance associated with this component.
  * @param {ReactNode} [props.children] The children to be rendered by this component.
  * @returns {ReactNode} The `children` passed to the component.
  */
-export default function MeoNodeUnmounter({ node, children }: {
+export default function MeoNodeUnmounter({ node, children, ...rest }: {
     node: NodeInstance;
     children?: ReactNode;
 }): ReactNode;

package/dist/components/meonode-unmounter.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meonode-unmounter.client.d.ts","sourceRoot":"","sources":["../../src/components/meonode-unmounter.client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAA6B,MAAM,OAAO,CAAA;AAGjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAsBpH"}
+{"version":3,"file":"meonode-unmounter.client.d.ts","sourceRoot":"","sources":["../../src/components/meonode-unmounter.client.ts"],"names":[],"mappings":"AACA,OAAO,EAAgC,KAAK,SAAS,EAA6B,MAAM,OAAO,CAAA;AAG/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CA0B7H"}

package/dist/components/meonode-unmounter.client.js

@@ -1,15 +1,17 @@
-"use client";import{useEffect,useEffectEvent}from"react";import{MountTrackerUtil}from"../util/mount-tracker.util.js";import{BaseNode}from"../core.node.js";/**
- * `MeoNodeUnmounter` is a client-side React component responsible for cleaning up
- * resources associated with a rendered node when it unmounts.
+"use client";const _excluded=["node","children"];function _objectWithoutProperties(a,b){if(null==a)return{};var c,d,e=_objectWithoutPropertiesLoose(a,b);if(Object.getOwnPropertySymbols){var f=Object.getOwnPropertySymbols(a);for(d=0;d<f.length;d++)c=f[d],-1===b.indexOf(c)&&{}.propertyIsEnumerable.call(a,c)&&(e[c]=a[c])}return e}function _objectWithoutPropertiesLoose(a,b){if(null==a)return{};var c={};for(var d in a)if({}.hasOwnProperty.call(a,d)){if(-1!==b.indexOf(d))continue;c[d]=a[d]}return c}import{cloneElement,isValidElement,useEffect,useEffectEvent}from"react";import{MountTrackerUtil}from"../util/mount-tracker.util.js";import{BaseNode}from"../core.node.js";/**
+ * `MeoNodeUnmounter` is a client-side React component responsible for performing cleanup
+ * operations when a `MeoNode` instance is unmounted from the React tree.
  *
- * It uses a `useEffect` hook to register a cleanup function that runs when the component
- * unmounts or when its `stableKey` changes. The cleanup function checks if the node
- * identified by `stableKey` is currently tracked as mounted. If it is, it removes
- * the node from `BaseNode.elementCache` and untracks its mount status using `MountTrackerUtil`.
- * Additionally, it clears the `lastPropsRef` and `lastSignature` of the associated `BaseNode`
- * instance to prevent memory leaks from retained prop objects.
+ * It leverages `useEffectEvent` to create a stable cleanup function that is called
+ * when the component unmounts. This cleanup function performs the following actions:
+ * - Deletes the node from `BaseNode.elementCache` using its `stableKey`.
+ * - Untracks the node's mount status via `MountTrackerUtil.untrackMount`.
+ * - Unregisters the node from `BaseNode.cacheCleanupRegistry` to prevent redundant
+ *   finalization callbacks.
+ * - Clears the `lastSignature` of the associated `BaseNode` instance to help prevent
+ *   memory leaks from retained prop objects.
  * @param {object} props The component's props.
  * @param {NodeInstance} props.node The BaseNode instance associated with this component.
  * @param {ReactNode} [props.children] The children to be rendered by this component.
  * @returns {ReactNode} The `children` passed to the component.
- */export default function MeoNodeUnmounter({node:a,children:b}){const c=useEffectEvent(()=>{a.stableKey&&(BaseNode.elementCache.delete(a.stableKey),MountTrackerUtil.mountedNodes.has(a.stableKey)&&MountTrackerUtil.untrackMount(a.stableKey),BaseNode.cacheCleanupRegistry.unregister(a)),a.lastSignature=void 0});return useEffect(()=>()=>c(),[]),b}
+ */export default function MeoNodeUnmounter(a){let{node:b,children:c}=a,d=_objectWithoutProperties(a,_excluded);const e=useEffectEvent(()=>{b.stableKey&&(BaseNode.elementCache.delete(b.stableKey),MountTrackerUtil.mountedNodes.has(b.stableKey)&&MountTrackerUtil.untrackMount(b.stableKey),BaseNode.cacheCleanupRegistry.unregister(b)),b.lastSignature=void 0});return useEffect(()=>()=>e(),[]),isValidElement(c)?cloneElement(c,d):c}

package/dist/util/node.util.d.ts

@@ -38,19 +38,31 @@ export declare class NodeUtil {
      * This check is performed only on the client-side by checking if the property exists in `document.body.style`.
      * On the server-side, it always returns `false`.
      * @param k The string to check.
+     * @returns True if the string is a valid CSS style property, false otherwise.
      */
     static isStyleProp: (k: string) => boolean;
     /**
      * Combines FNV-1a and djb2 hash functions for a more robust signature.
-     * @method hashString
+     * This hybrid approach provides better distribution than either algorithm alone.
+     * @param str The string to hash.
+     * @returns A combined hash string in base-36 format.
      */
     static hashString(str: string): string;
+    /**
+     * Generates a fast structural hash for CSS objects without full serialization.
+     * This is an optimized hashing method that samples the first 10 keys for performance.
+     * @param css The CSS object to hash.
+     * @returns A hash string representing the CSS object structure.
+     */
     private static hashCSS;
     /**
      * Creates a unique, stable signature from the element type and props.
      * This signature includes the element's type to prevent collisions between different components
      * and handles primitive values in arrays and objects for better caching.
-     * @method createPropSignature
+     * On server environments, returns undefined as signatures are not needed for server-side rendering.
+     * @param element The element type to include in the signature.
+     * @param props The props object to include in the signature.
+     * @returns A unique signature string or undefined on the server.
      */
     static createPropSignature(element: NodeElementType, props: Record<string, unknown>): string | undefined;
     /**
@@ -59,12 +71,18 @@ export declare class NodeUtil {
      * `aria-*` attributes, `data-*` attributes, `css`, `className`, and `style`.
      * This method is used to optimize prop processing by focusing on props that are
      * most likely to influence rendering or behavior.
+     * @param props The original props object.
+     * @param keys The keys to process from the props object.
+     * @returns An object containing only the critical props with an added count property.
      */
     static extractCriticalProps(props: Record<string, unknown>, keys: string[]): Record<string, unknown>;
     /**
      * Retrieves computed CSS props from the cache with LRU tracking.
      * Access time and hit count are tracked for smarter eviction.
-     * @method getCachedCssProps
+     * Falls back to direct computation if no signature is provided or running on server.
+     * @param cacheableProps The props to compute CSS properties from.
+     * @param signature The cache signature to use for lookup.
+     * @returns An object containing the CSS props.
      */
     static getCachedCssProps(cacheableProps: Record<string, unknown>, signature?: string): {
         cssProps: Record<string, unknown>;
@@ -72,46 +90,66 @@ export declare class NodeUtil {
     /**
      * Implements an LRU eviction strategy that removes multiple entries at once.
      * It uses a scoring system where older and less frequently used entries have a higher eviction priority.
-     * @method _evictLRUEntries
+     * This batch eviction approach improves performance by avoiding frequent cache cleanup operations.
      */
     private static _evictLRUEntries;
     /**
      * Calculates an eviction score based on age and frequency of access.
      * Higher scores mean more likelihood to be evicted.
-     * @method _calculateEvictionScore
+     * The scoring system uses weighted factors: 30% recency and 70% frequency.
+     * @param value The cache entry to score.
+     * @param now The current timestamp for calculating age.
+     * @returns A numeric score representing how likely the entry should be evicted.
      */
     private static _calculateEvictionScore;
     /**
      * The main prop processing pipeline. It separates cacheable and non-cacheable props,
      * generates a signature for caching, and assembles the final props object.
-     * @method processProps
+     * This method applies optimizations like fast-path for simple props and hybrid caching strategy.
+     * @param element The element type for which props are being processed.
+     * @param rawProps The original props to process.
+     * @param stableKey The stable key used for child normalization (optional).
+     * @returns The processed props object ready for rendering.
      */
     static processProps(element: NodeElementType, rawProps?: Partial<NodeProps<NodeElementType>>, stableKey?: string): FinalNodeProps;
     /**
      * Processes and normalizes children of the node.
      * Converts raw children (React elements, primitives, or other BaseNodes) into a consistent format.
+     * Applies optimizations for single and multiple children scenarios.
      * @param children The raw children to process.
      * @param disableEmotion If true, emotion styling will be disabled for these children.
      * @param parentStableKey The stable key of the parent node, used for generating unique keys for children.
+     * @returns The processed children in normalized format.
      */
     private static _processChildren;
     /**
      * Determines if a node should update based on its dependency array.
      * Uses a shallow comparison, similar to React's `useMemo` and `useCallback`.
-     * @method shouldNodeUpdate
+     * On server environments, always returns true since SSR has no concept of re-renders.
+     * @param prevDeps Previous dependency array to compare.
+     * @param newDeps New dependency array to compare.
+     * @param parentBlocked Flag indicating if the parent is blocked from updating.
+     * @returns True if the node should update, false otherwise.
      */
     static shouldNodeUpdate(prevDeps: DependencyList | undefined, newDeps: DependencyList | undefined, parentBlocked: boolean): boolean;
     /**
      * The core normalization function for a single child. It takes any valid `NodeElement`
      * (primitive, React element, function, `BaseNode` instance) and converts it into a standardized `BaseNode`
      * instance if it isn't one already. This ensures a consistent structure for the iterative renderer.
-     * @method processRawNode
+     * Handles various node types including primitives, BaseNode instances, function-as-children, React elements,
+     * component classes, and component instances.
+     * @param node The node element to process and normalize.
+     * @param disableEmotion If true, emotion styling will be disabled for this node.
+     * @param stableKey The stable key for positional information in parent-child relationships.
+     * @returns The normalized node element in BaseNode format.
      */
     static processRawNode(node: NodeElement, disableEmotion?: boolean, stableKey?: string): NodeElement;
     /**
      * A helper to reliably identify if a given function is a "function-as-a-child" (render prop)
      * rather than a standard Function Component.
-     * @method isFunctionChild
+     * Distinguishes between render prop functions and component functions by checking for React component signatures.
+     * @param node The node to check.
+     * @returns True if the node is a function-as-a-child, false otherwise.
      */
     static isFunctionChild<E extends NodeInstance | ReactNode>(node: NodeElement): node is NodeFunction<E>;
     /**
@@ -122,11 +160,9 @@ export declare class NodeUtil {
      *
      * This allows `BaseNode` to support render props while maintaining its internal processing
      * and normalization logic for the dynamically generated content.
-     * @method functionRenderer
-     * @param {Object} props The properties passed to the renderer.
-     * @param {Function} props.render The function-as-a-child to execute.
-     * @param {boolean} [props.disableEmotion] Inherited flag to disable Emotion styling for children.
-     * @returns {ReactNode | null | undefined} The processed and rendered output of the render function.
+     * @param render The function-as-a-child to execute.
+     * @param disableEmotion Inherited flag to disable Emotion styling for children.
+     * @returns The processed and rendered output of the render function, or null if an error occurs.
      */
     static functionRenderer<E extends ReactNode | NodeInstance>({ render, disableEmotion }: FunctionRendererProps<E>): ReactNode | null | undefined;
     /**
@@ -137,7 +173,10 @@ export declare class NodeUtil {
      *
      * This method is part of the child processing pipeline, converting internal `NodeElement` representations
      * into actual React elements that can be rendered by React.
-     * @method renderProcessedNode
+     * @param processedElement The processed node element to render.
+     * @param passedKey Optional key to apply to the rendered element.
+     * @param disableEmotion Flag to disable emotion styling if needed.
+     * @returns The rendered ReactNode.
      */
     static renderProcessedNode({ processedElement, passedKey, disableEmotion }: {
         processedElement: NodeElement;
@@ -147,9 +186,16 @@ export declare class NodeUtil {
     /**
      * Ensures that the necessary DOM element and React root are available for portal rendering.
      * This is only executed on the client-side.
-     * @method ensurePortalInfrastructure
+     * Handles cleanup of stale infrastructure and creates new infrastructure as needed.
+     * @param node The node instance that requires portal infrastructure.
+     * @returns True if portal infrastructure is ready, false on server or if setup fails.
      */
     static ensurePortalInfrastructure(node: NodeInstance): boolean;
+    /**
+     * Cleans up portal infrastructure by unmounting the React root and removing the DOM element.
+     * This ensures proper memory cleanup and prevents memory leaks.
+     * @param infra The infrastructure object containing the DOM element and React root to clean up.
+     */
     static cleanupPortalInfra(infra: {
         domElement: HTMLDivElement;
         reactRoot: Root;

package/dist/util/node.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.util.d.ts","sourceRoot":"","sources":["../../src/util/node.util.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.util.d.ts","sourceRoot":"","sources":["../../src/util/node.util.ts"],"names":[],"mappings":"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"}

package/dist/util/node.util.js

@@ -6,18 +6,28 @@ const _excluded=["ref","key","children","css","props","disableEmotion"],_exclude
  */export class NodeUtil{constructor(){}// Determines if the current environment is server-side (Node.js) or client-side (browser).
 /**
    * Combines FNV-1a and djb2 hash functions for a more robust signature.
-   * @method hashString
+   * This hybrid approach provides better distribution than either algorithm alone.
+   * @param str The string to hash.
+   * @returns A combined hash string in base-36 format.
    */static hashString(a){let b=2166136261,c=5381;// FNV offset basis
 // djb2 init
 for(let d=0;d<a.length;d++){const e=a.charCodeAt(d);// FNV-1a
 // djb2
-b^=e,b=Math.imul(b,16777619),c=33*c^e}return`${(b>>>0).toString(36)}_${(c>>>0).toString(36)}`}static hashCSS(a){var b=Math.min;const c=this._cssCache.get(a);if(c)return c;// Fast structural hash without full serialization
-const d=Object.keys(a);let e=d.length;for(let c=0;c<b(d.length,10);c++){// Sample first 10
-const b=d[c],f=a[b],g=b.charCodeAt(0);e=(e<<5)-e+g,e&=e,"string"==typeof f&&(e=(e<<5)-e+f.length)}const f=e.toString(36);return this._cssCache.set(a,f),f}/**
+b^=e,b=Math.imul(b,16777619),c=33*c^e}return`${(b>>>0).toString(36)}_${(c>>>0).toString(36)}`}/**
+   * Generates a fast structural hash for CSS objects without full serialization.
+   * This is an optimized hashing method that samples the first 10 keys for performance.
+   * @param css The CSS object to hash.
+   * @returns A hash string representing the CSS object structure.
+   */static hashCSS(a){const b=this._cssCache.get(a);if(b)return b;// Fast structural hash without full serialization
+const c=Object.keys(a);let d=c.length;for(let b=0;b<Math.min(c.length,10);b++){// Sample first 10
+const e=c[b],f=a[e],g=e.charCodeAt(0);d=(d<<5)-d+g,d&=d,"string"==typeof f&&(d=(d<<5)-d+f.length)}const e=d.toString(36);return this._cssCache.set(a,e),e}/**
    * Creates a unique, stable signature from the element type and props.
    * This signature includes the element's type to prevent collisions between different components
    * and handles primitive values in arrays and objects for better caching.
-   * @method createPropSignature
+   * On server environments, returns undefined as signatures are not needed for server-side rendering.
+   * @param element The element type to include in the signature.
+   * @param props The props object to include in the signature.
+   * @returns A unique signature string or undefined on the server.
    */static createPropSignature(a,b){if(NodeUtil.isServer)return;const c=getElementTypeName(a),d=Object.keys(b);// Optimization: Only sort if there's more than one key to ensure stability
 1<d.length&&d.sort();const e=[`${c}:`];if("function"==typeof a){let b=NodeUtil._functionSignatureCache.get(a);b||(b=NodeUtil.hashString(a.toString()),NodeUtil._functionSignatureCache.set(a,b)),e.push(b)}for(const c of d){const a=b[c];let d;const f=typeof a;if("string"==f||"number"===f||"boolean"===f)d=`${c}:${a};`;else if(null===a)d=`${c}:null;`;else if(a===void 0)d=`${c}:undefined;`;else if("css"===c&&"object"==typeof a)d=`css:${this.hashCSS(a)};`;else if(Array.isArray(a)){// Hash primitive values in arrays for better cache hits
 const b=a.filter(a=>{const b=typeof a;return"string"==b||"number"===b||"boolean"===b||null===a});d=b.length===a.length?`${c}:[${b.join(",")}];`:`${c}:[${a.length}];`}else if(a&&a.isBaseNode)d=`${c}:${a.stableKey};`;else{// Include sorted keys for object structure signature
@@ -27,6 +37,9 @@ const b=Object.keys(a).sort();d=`${c}:{${b.join(",")}};`}e.push(d)}return NodeUt
    * `aria-*` attributes, `data-*` attributes, `css`, `className`, and `style`.
    * This method is used to optimize prop processing by focusing on props that are
    * most likely to influence rendering or behavior.
+   * @param props The original props object.
+   * @param keys The keys to process from the props object.
+   * @returns An object containing only the critical props with an added count property.
    */static extractCriticalProps(a,b){const c={_keyCount:b.length};let d=0;for(const e of b){if(50<=d)break;// Fast path: direct Set check first (O(1))
 if(NodeUtil.CRITICAL_PROPS.has(e)){c[e]=a[e],d++;continue}// Inline prefix checks using charCode (faster than startsWith for short prefixes)
 const f=e.charCodeAt(0);// Check 'on' prefix (111 = 'o', 110 = 'n')
@@ -36,23 +49,33 @@ if(100===f&&97===e.charCodeAt(1)&&116===e.charCodeAt(2)&&97===e.charCodeAt(3)){c
 100>=b.length&&NodeUtil.isStyleProp(e)&&(c[e]=a[e],d++)}return c}/**
    * Retrieves computed CSS props from the cache with LRU tracking.
    * Access time and hit count are tracked for smarter eviction.
-   * @method getCachedCssProps
+   * Falls back to direct computation if no signature is provided or running on server.
+   * @param cacheableProps The props to compute CSS properties from.
+   * @param signature The cache signature to use for lookup.
+   * @returns An object containing the CSS props.
    */static getCachedCssProps(a,b){if(NodeUtil.isServer||!b)return{cssProps:getCSSProps(a)};const c=BaseNode.propProcessingCache.get(b);if(c)return c.lastAccess=Date.now(),c.hitCount++,{cssProps:c.cssProps};const d=getCSSProps(a);return BaseNode.propProcessingCache.set(b,{cssProps:d,signature:b,lastAccess:Date.now(),hitCount:1}),BaseNode.propProcessingCache.size>NodeUtil.CACHE_SIZE_LIMIT&&!BaseNode.scheduledCleanup&&(BaseNode.scheduledCleanup=!0,"undefined"==typeof requestIdleCallback?setTimeout(()=>{NodeUtil._evictLRUEntries(),BaseNode.scheduledCleanup=!1},100):requestIdleCallback(()=>{NodeUtil._evictLRUEntries(),BaseNode.scheduledCleanup=!1},{timeout:2e3})),{cssProps:d}}/**
    * Implements an LRU eviction strategy that removes multiple entries at once.
    * It uses a scoring system where older and less frequently used entries have a higher eviction priority.
-   * @method _evictLRUEntries
+   * This batch eviction approach improves performance by avoiding frequent cache cleanup operations.
    */static _evictLRUEntries(){const a=Date.now(),b=new MinHeap((c,a)=>a.score-c.score);// Create max-heap (using min-heap with inverted comparison) to get highest scores first
 for(const[c,d]of BaseNode.propProcessingCache.entries()){const e=this._calculateEvictionScore(d,a);b.push({key:c,score:e})}// O(log n) eviction of top N entries
 for(let a=0;a<NodeUtil.CACHE_CLEANUP_BATCH;a++){const a=b.pop();if(a)BaseNode.propProcessingCache.delete(a.key);else// No more items to evict
 break}}/**
    * Calculates an eviction score based on age and frequency of access.
    * Higher scores mean more likelihood to be evicted.
-   * @method _calculateEvictionScore
+   * The scoring system uses weighted factors: 30% recency and 70% frequency.
+   * @param value The cache entry to score.
+   * @param now The current timestamp for calculating age.
+   * @returns A numeric score representing how likely the entry should be evicted.
    */static _calculateEvictionScore(a,b){const c=b-a.lastAccess,d=a.hitCount;// Weighted scoring: recency 30%, frequency 70% - favors frequently accessed items
 return .3*(c/1e3)+.7*(1e3/(d+1))}/**
    * The main prop processing pipeline. It separates cacheable and non-cacheable props,
    * generates a signature for caching, and assembles the final props object.
-   * @method processProps
+   * This method applies optimizations like fast-path for simple props and hybrid caching strategy.
+   * @param element The element type for which props are being processed.
+   * @param rawProps The original props to process.
+   * @param stableKey The stable key used for child normalization (optional).
+   * @returns The processed props object ready for rendering.
    */static processProps(a,b={},c){const{ref:d,key:e,children:f,css:g,props:i={},disableEmotion:h}=b,j=_objectWithoutProperties(b,_excluded);// --- Fast Path Optimization ---
 if(0===Object.keys(j).length&&!g)return omitUndefined({ref:d,key:e,disableEmotion:h,nativeProps:omitUndefined(i),children:NodeUtil._processChildren(f,h)});// --- Hybrid Caching Strategy ---
 const k={},l={},m=Object.keys(j);// 1. Categorize props into cacheable (primitives) and non-cacheable (objects/functions).
@@ -66,16 +89,22 @@ const n=NodeUtil.createPropSignature(a,k),{cssProps:o}=NodeUtil.getCachedCssProp
 return omitUndefined(_objectSpread(_objectSpread({ref:d,key:e,css:r},q),{},{disableEmotion:h,nativeProps:omitUndefined(i),children:s}))}/**
    * Processes and normalizes children of the node.
    * Converts raw children (React elements, primitives, or other BaseNodes) into a consistent format.
+   * Applies optimizations for single and multiple children scenarios.
    * @param children The raw children to process.
    * @param disableEmotion If true, emotion styling will be disabled for these children.
    * @param parentStableKey The stable key of the parent node, used for generating unique keys for children.
+   * @returns The processed children in normalized format.
    */static _processChildren(a,b,c){return a?"function"==typeof a?a:Array.isArray(a)?1===a.length?NodeUtil.processRawNode(a[0],b,`${c}_0`):a.map((a,d)=>NodeUtil.processRawNode(a,b,`${c}_${d}`)):NodeUtil.processRawNode(a,b,c):void 0;// Fast path for non-array (single child)
 // Fast path for single element array
 // General case: multiple children
 }/**
    * Determines if a node should update based on its dependency array.
    * Uses a shallow comparison, similar to React's `useMemo` and `useCallback`.
-   * @method shouldNodeUpdate
+   * On server environments, always returns true since SSR has no concept of re-renders.
+   * @param prevDeps Previous dependency array to compare.
+   * @param newDeps New dependency array to compare.
+   * @param parentBlocked Flag indicating if the parent is blocked from updating.
+   * @returns True if the node should update, false otherwise.
    */static shouldNodeUpdate(a,b,c){// SSR has no concept of re-renders, so deps system doesn't apply
 return!!NodeUtil.isServer||!c&&(!(void 0!==b)||!(void 0!==a)||b.length!==a.length||!!b.some((b,c)=>!Object.is(b,a[c])));// No deps array means always update.
 // First render for this keyed component, or no previous deps.
@@ -86,7 +115,12 @@ return!!NodeUtil.isServer||!c&&(!(void 0!==b)||!(void 0!==a)||b.length!==a.lengt
    * The core normalization function for a single child. It takes any valid `NodeElement`
    * (primitive, React element, function, `BaseNode` instance) and converts it into a standardized `BaseNode`
    * instance if it isn't one already. This ensures a consistent structure for the iterative renderer.
-   * @method processRawNode
+   * Handles various node types including primitives, BaseNode instances, function-as-children, React elements,
+   * component classes, and component instances.
+   * @param node The node element to process and normalize.
+   * @param disableEmotion If true, emotion styling will be disabled for this node.
+   * @param stableKey The stable key for positional information in parent-child relationships.
+   * @returns The normalized node element in BaseNode format.
    */static processRawNode(a,b,c){// Primitives and null/undefined are returned as-is.
 if(null===a||a===void 0||"string"==typeof a||"number"==typeof a||"boolean"==typeof a)return a;// If it's already a BaseNode, clone it with a positional key if available.
 if(NodeUtil.isNodeInstance(a)){const d=c||b&&!a.rawProps.disableEmotion;if(d){// Create a new BaseNode instance.
@@ -99,7 +133,9 @@ return isReactClassComponent(a)||isMemo(a)||isForwardRef(a)?new BaseNode(a,{disa
 }/**
    * A helper to reliably identify if a given function is a "function-as-a-child" (render prop)
    * rather than a standard Function Component.
-   * @method isFunctionChild
+   * Distinguishes between render prop functions and component functions by checking for React component signatures.
+   * @param node The node to check.
+   * @returns True if the node is a function-as-a-child, false otherwise.
    */static isFunctionChild(a){if("function"!=typeof a||isReactClassComponent(a)||isMemo(a)||isForwardRef(a))return!1;try{return!(a.prototype&&"function"==typeof a.prototype.render)}catch(a){return __DEBUG__&&console.error("MeoNode: Error checking if a node is a function child.",a),!0}}/**
    * A special internal React component used to render "function-as-a-child" (render prop) patterns.
    * When a `BaseNode` receives a function as its `children` prop, it wraps that function
@@ -108,11 +144,9 @@ return isReactClassComponent(a)||isMemo(a)||isForwardRef(a)?new BaseNode(a,{disa
    *
    * This allows `BaseNode` to support render props while maintaining its internal processing
    * and normalization logic for the dynamically generated content.
-   * @method functionRenderer
-   * @param {Object} props The properties passed to the renderer.
-   * @param {Function} props.render The function-as-a-child to execute.
-   * @param {boolean} [props.disableEmotion] Inherited flag to disable Emotion styling for children.
-   * @returns {ReactNode | null | undefined} The processed and rendered output of the render function.
+   * @param render The function-as-a-child to execute.
+   * @param disableEmotion Inherited flag to disable Emotion styling for children.
+   * @returns The processed and rendered output of the render function, or null if an error occurs.
    */static functionRenderer({render:a,disableEmotion:b}){let c;try{// Execute the render prop function to get its output.
 c=a()}catch(a){// If the render function throws, treat its output as null to prevent crashes.
 __DEBUG__&&console.error("MeoNode: Error executing function-as-a-child.",a),c=null}// Handle null or undefined results directly, as they are valid React render outputs.
@@ -138,7 +172,10 @@ return d?NodeUtil.renderProcessedNode({processedElement:d,disableEmotion:b}):c;/
    *
    * This method is part of the child processing pipeline, converting internal `NodeElement` representations
    * into actual React elements that can be rendered by React.
-   * @method renderProcessedNode
+   * @param processedElement The processed node element to render.
+   * @param passedKey Optional key to apply to the rendered element.
+   * @param disableEmotion Flag to disable emotion styling if needed.
+   * @returns The rendered ReactNode.
    */static renderProcessedNode({processedElement:a,passedKey:b,disableEmotion:c}){// Initialize an object to hold common props that might be applied to the new BaseNode.
 const d={};// If a `passedKey` is provided, add it to `commonBaseNodeProps`.
 // This key is typically used for React's reconciliation process.
@@ -158,12 +195,47 @@ return isReactClassComponent(a)?new BaseNode(a,_objectSpread(_objectSpread({},d)
 }/**
    * Ensures that the necessary DOM element and React root are available for portal rendering.
    * This is only executed on the client-side.
-   * @method ensurePortalInfrastructure
+   * Handles cleanup of stale infrastructure and creates new infrastructure as needed.
+   * @param node The node instance that requires portal infrastructure.
+   * @returns True if portal infrastructure is ready, false on server or if setup fails.
    */static ensurePortalInfrastructure(a){if(NodeUtil.isServer)return!1;let b=NodeUtil.portalInfrastructure.get(a);// Check if infrastructure exists and is still connected
 if(b?.domElement?.isConnected&&b?.reactRoot)return!0;// Clean up stale or disconnected infrastructure
 if(b&&(!b.domElement?.isConnected||!b.reactRoot)){try{b.reactRoot?.unmount?.()}catch(a){__DEBUG__&&console.error("MeoNode: Error unmounting stale portal root.",a)}NodeUtil.cleanupPortalInfra(b),NodeUtil.portalInfrastructure.delete(a),b=void 0}// Create new infrastructure
 const c=document.createElement("div");document.body.appendChild(c);const d=createRoot(c),e={render:d.render.bind(d),unmount:d.unmount.bind(d),update:()=>{}// Placeholder, will be overridden
-};return b={domElement:c,reactRoot:e},NodeUtil.portalInfrastructure.set(a,b),BaseNode.portalCleanupRegistry.register(a,{domElement:c,reactRoot:e},a),!0}static cleanupPortalInfra(a){try{a.reactRoot?.unmount&&a.reactRoot.unmount()}catch(a){__DEBUG__&&console.error("Portal cleanup error:",a)}try{a.domElement?.isConnected&&a.domElement.remove()}catch(a){__DEBUG__&&console.error("DOM removal error:",a)}}}/**
+};return b={domElement:c,reactRoot:e},NodeUtil.portalInfrastructure.set(a,b),BaseNode.portalCleanupRegistry.register(a,{domElement:c,reactRoot:e},a),!0}/**
+   * Cleans up portal infrastructure by unmounting the React root and removing the DOM element.
+   * This ensures proper memory cleanup and prevents memory leaks.
+   * @param infra The infrastructure object containing the DOM element and React root to clean up.
+   */static cleanupPortalInfra(a){try{a.reactRoot?.unmount&&a.reactRoot.unmount()}catch(a){__DEBUG__&&console.error("Portal cleanup error:",a)}try{a.domElement?.isConnected&&a.domElement.remove()}catch(a){__DEBUG__&&console.error("DOM removal error:",a)}}}/**
  * A min-heap implementation for efficient priority queue operations.
  * Used for O(log n) eviction in the LRU cache system.
- */_NodeUtil=NodeUtil,_defineProperty(NodeUtil,"isServer","undefined"==typeof window),_defineProperty(NodeUtil,"_functionSignatureCache",new WeakMap),_defineProperty(NodeUtil,"CACHE_SIZE_LIMIT",500),_defineProperty(NodeUtil,"CACHE_CLEANUP_BATCH",50),_defineProperty(NodeUtil,"_cssCache",new WeakMap),_defineProperty(NodeUtil,"CRITICAL_PROPS",new Set(["css","className","disableEmotion","props"])),_defineProperty(NodeUtil,"portalInfrastructure",new WeakMap),_defineProperty(NodeUtil,"isNodeInstance",a=>"object"==typeof a&&null!==a&&"element"in a&&"function"==typeof a.render&&"function"==typeof a.toPortal&&"isBaseNode"in a),_defineProperty(NodeUtil,"isStyleProp",_NodeUtil.isServer||"undefined"==typeof document?()=>!1:a=>a in document.body.style);class MinHeap{constructor(a){_defineProperty(this,"heap",[]),this.comparator=a}size(){return this.heap.length}isEmpty(){return 0===this.size()}push(a){this.heap.push(a),this.bubbleUp()}pop(){if(!this.isEmpty()){this.swap(0,this.size()-1);const a=this.heap.pop();return this.bubbleDown(),a}}peek(){return this.isEmpty()?void 0:this.heap[0]}bubbleUp(a=this.size()-1){for(;0<a;){const b=Math.floor((a-1)/2);if(0>=this.comparator(this.heap[b],this.heap[a]))break;this.swap(b,a),a=b}}bubbleDown(a=0){for(const b=this.size()-1;;){const c=2*a+1,d=2*a+2;let e=a;if(c<=b&&0>this.comparator(this.heap[c],this.heap[e])&&(e=c),d<=b&&0>this.comparator(this.heap[d],this.heap[e])&&(e=d),e===a)break;this.swap(a,e),a=e}}swap(a,b){[this.heap[a],this.heap[b]]=[this.heap[b],this.heap[a]]}}
+ */_NodeUtil=NodeUtil,_defineProperty(NodeUtil,"isServer","undefined"==typeof window),_defineProperty(NodeUtil,"_functionSignatureCache",new WeakMap),_defineProperty(NodeUtil,"CACHE_SIZE_LIMIT",500),_defineProperty(NodeUtil,"CACHE_CLEANUP_BATCH",50),_defineProperty(NodeUtil,"_cssCache",new WeakMap),_defineProperty(NodeUtil,"CRITICAL_PROPS",new Set(["css","className","disableEmotion","props"])),_defineProperty(NodeUtil,"portalInfrastructure",new WeakMap),_defineProperty(NodeUtil,"isNodeInstance",a=>"object"==typeof a&&null!==a&&"element"in a&&"function"==typeof a.render&&"function"==typeof a.toPortal&&"isBaseNode"in a),_defineProperty(NodeUtil,"isStyleProp",_NodeUtil.isServer||"undefined"==typeof document?()=>!1:a=>a in document.body.style);class MinHeap{/**
+   * Constructs a new MinHeap with the provided comparator function.
+   * @param comparator A function that compares two elements and returns a negative value if the first is smaller,
+   * zero if they are equal, or a positive value if the first is larger.
+   */constructor(a){_defineProperty(this,"heap",[]),this.comparator=a}/**
+   * Returns the number of elements in the heap.
+   * @returns The current size of the heap.
+   */size(){return this.heap.length}/**
+   * Checks if the heap is empty.
+   * @returns True if the heap has no elements, false otherwise.
+   */isEmpty(){return 0===this.size()}/**
+   * Adds a new value to the heap and maintains the heap property by bubbling it up to the correct position.
+   * @param value The value to add to the heap.
+   */push(a){this.heap.push(a),this.bubbleUp()}/**
+   * Removes and returns the smallest element from the heap (the root).
+   * After removal, it maintains the heap property by bubbling down the new root.
+   * @returns The smallest element in the heap, or undefined if the heap is empty.
+   */pop(){if(!this.isEmpty()){this.swap(0,this.size()-1);const a=this.heap.pop();return this.bubbleDown(),a}}/**
+   * Moves the element at the specified index up the heap until the heap property is restored.
+   * This is used after inserting a new element to maintain the heap structure.
+   * @param index The index of the element to bubble up. Defaults to the last element in the heap.
+   */bubbleUp(a=this.size()-1){for(;0<a;){const b=Math.floor((a-1)/2);if(0>=this.comparator(this.heap[b],this.heap[a]))break;this.swap(b,a),a=b}}/**
+   * Moves the element at the specified index down the heap until the heap property is restored.
+   * This is used after removing the root element to maintain the heap structure.
+   * @param index The index of the element to bubble down. Defaults to the root element (index 0).
+   */bubbleDown(a=0){for(const b=this.size()-1;;){const c=2*a+1,d=2*a+2;let e=a;if(c<=b&&0>this.comparator(this.heap[c],this.heap[e])&&(e=c),d<=b&&0>this.comparator(this.heap[d],this.heap[e])&&(e=d),e===a)break;this.swap(a,e),a=e}}/**
+   * Swaps the elements at the two specified indices in the heap array.
+   * @param i The index of the first element to swap.
+   * @param j The index of the second element to swap.
+   */swap(a,b){[this.heap[a],this.heap[b]]=[this.heap[b],this.heap[a]]}}

package/dist/util/theme.util.d.ts

@@ -1,20 +1,13 @@
 import type { CSSProperties } from '@emotion/serialize';
 import type { CssProp, Theme } from '../types/node.type.js';
-/**
- * Parsed flex shorthand components for CSS flex property
- * @interface FlexComponents
- * @property grow - The flex-grow value (how much the item should grow)
- * @property shrink - The flex-shrink value (how much the item should shrink)
- * @property basis - The flex-basis value (initial main size before free space is distributed)
- */
 interface FlexComponents {
     grow: number;
     shrink: number;
     basis: string | number;
 }
 export declare class ThemeUtil {
-    private constructor();
     private static themeCache;
+    private constructor();
     /**
      * Parses a CSS flex shorthand property into its individual components.
      *

package/dist/util/theme.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.util.d.ts","sourceRoot":"","sources":["../../src/util/theme.util.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAe,MAAM,yBAAyB,CAAA;AAiG1E;;;;;;GAMG;AACH,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CACvB;AACD,qBAAa,SAAS;IACpB,OAAO,eAAiB;IAExB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAmC;IAE5D;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAc,kBAAkB,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,cAAc,GAAG,IAAI,CA2BnF;IAED,OAAc,aAAa,uDAM1B;IAED;;;;;;;;OAQG;IACH,OAAc,mBAAmB,GAAI,CAAC;;YA0HrC;IAED,OAAc,eAAe,aAE5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,OAAc,mBAAmB,yBAmEhC;CACF"}
+{"version":3,"file":"theme.util.d.ts","sourceRoot":"","sources":["../../src/util/theme.util.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAe,MAAM,yBAAyB,CAAA;AA+F1E,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CACvB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAmC;IAE5D,OAAO,eAAiB;IAExB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAc,kBAAkB,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,cAAc,GAAG,IAAI,CA2BnF;IAED,OAAc,aAAa,uDAM1B;IAED;;;;;;;;OAQG;IACH,OAAc,mBAAmB,GAAI,CAAC;;YA0HrC;IAED,OAAc,eAAe,aAE5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,OAAc,mBAAmB,yBAmEhC;CACF"}

package/dist/util/theme.util.js

@@ -1,15 +1,9 @@
 const _excluded=["flex"];var _ThemeUtil;function _objectWithoutProperties(a,b){if(null==a)return{};var c,d,e=_objectWithoutPropertiesLoose(a,b);if(Object.getOwnPropertySymbols){var f=Object.getOwnPropertySymbols(a);for(d=0;d<f.length;d++)c=f[d],-1===b.indexOf(c)&&{}.propertyIsEnumerable.call(a,c)&&(e[c]=a[c])}return e}function _objectWithoutPropertiesLoose(a,b){if(null==a)return{};var c={};for(var d in a)if({}.hasOwnProperty.call(a,d)){if(-1!==b.indexOf(d))continue;c[d]=a[d]}return c}function ownKeys(a,b){var c=Object.keys(a);if(Object.getOwnPropertySymbols){var d=Object.getOwnPropertySymbols(a);b&&(d=d.filter(function(b){return Object.getOwnPropertyDescriptor(a,b).enumerable})),c.push.apply(c,d)}return c}function _objectSpread(a){for(var b,c=1;c<arguments.length;c++)b=null==arguments[c]?{}:arguments[c],c%2?ownKeys(Object(b),!0).forEach(function(c){_defineProperty(a,c,b[c])}):Object.getOwnPropertyDescriptors?Object.defineProperties(a,Object.getOwnPropertyDescriptors(b)):ownKeys(Object(b)).forEach(function(c){Object.defineProperty(a,c,Object.getOwnPropertyDescriptor(b,c))});return a}function _defineProperty(a,b,c){return(b=_toPropertyKey(b))in a?Object.defineProperty(a,b,{value:c,enumerable:!0,configurable:!0,writable:!0}):a[b]=c,a}function _toPropertyKey(a){var b=_toPrimitive(a,"string");return"symbol"==typeof b?b:b+""}function _toPrimitive(a,b){if("object"!=typeof a||!a)return a;var c=a[Symbol.toPrimitive];if(void 0!==c){var d=c.call(a,b||"default");if("object"!=typeof d)return d;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===b?String:Number)(a)}import{ObjHelper}from"../helper/obj.helper.js";import{getValueByPath}from"../helper/common.helper.js";/**
  * Cache manager for theme resolution operations.
- */class ThemeResolverCache{constructor(){_defineProperty(this,"CACHE_SIZE_LIMIT",500),_defineProperty(this,"CACHE_EVICTION_BATCH_SIZE",50),_defineProperty(this,"_resolutionCache",new Map),_defineProperty(this,"_pathLookupCache",new Map),_defineProperty(this,"_themeRegex",/theme\.([a-zA-Z0-9_.-]+)/g)}static getInstance(){return ThemeResolverCache._instance||(ThemeResolverCache._instance=new ThemeResolverCache),ThemeResolverCache._instance}/**
+ */class ThemeResolverCache{constructor(){_defineProperty(this,"CACHE_SIZE_LIMIT",500),_defineProperty(this,"CACHE_EVICTION_BATCH_SIZE",50),_defineProperty(this,"_resolutionCache",new Map),_defineProperty(this,"_pathLookupCache",new Map),_defineProperty(this,"_themeRegex",/theme\.([a-zA-Z0-9_.-]+)/g)}static getInstance(){return ThemeResolverCache._instance||(ThemeResolverCache._instance=new ThemeResolverCache),ThemeResolverCache._instance}getResolution(a,b){const c=this._generateCacheKey(a,b),d=this._resolutionCache.get(c);return d&&(this._resolutionCache.delete(c),this._resolutionCache.set(c,d)),d||null}setResolution(a,b,c){const d=this._generateCacheKey(a,b);this._resolutionCache.set(d,c),this._resolutionCache.size>this.CACHE_SIZE_LIMIT&&this._evict(this._resolutionCache)}getPathLookup(a,b){const c=`${ObjHelper.stringify(a)}_${b}`,d=this._pathLookupCache.get(c);return d&&(this._pathLookupCache.delete(c),this._pathLookupCache.set(c,d)),d??null}setPathLookup(a,b,c){const d=`${ObjHelper.stringify(a)}_${b}`;this._pathLookupCache.set(d,c),this._pathLookupCache.size>this.CACHE_SIZE_LIMIT&&this._evict(this._pathLookupCache)}getThemeRegex(){return this._themeRegex.lastIndex=0,this._themeRegex}shouldCache(){return"undefined"==typeof window}clear(){this._resolutionCache.clear(),this._pathLookupCache.clear()}/**
    * Generate a stable cache key from object and theme, including the theme mode.
    */_generateCacheKey(a,b){// Including theme.mode is critical for cache correctness.
-return`${ObjHelper.stringify(a)}_${b.mode}_${ObjHelper.stringify(b.system)}`}getResolution(a,b){const c=this._generateCacheKey(a,b),d=this._resolutionCache.get(c);return d&&(this._resolutionCache.delete(c),this._resolutionCache.set(c,d)),d||null}setResolution(a,b,c){const d=this._generateCacheKey(a,b);this._resolutionCache.set(d,c),this._resolutionCache.size>this.CACHE_SIZE_LIMIT&&this._evict(this._resolutionCache)}getPathLookup(a,b){const c=`${ObjHelper.stringify(a)}_${b}`,d=this._pathLookupCache.get(c);return d&&(this._pathLookupCache.delete(c),this._pathLookupCache.set(c,d)),d??null}setPathLookup(a,b,c){const d=`${ObjHelper.stringify(a)}_${b}`;this._pathLookupCache.set(d,c),this._pathLookupCache.size>this.CACHE_SIZE_LIMIT&&this._evict(this._pathLookupCache)}_evict(a){const b=a.keys();for(let c=0;c<this.CACHE_EVICTION_BATCH_SIZE;c++){const c=b.next().value;if(c)a.delete(c);else break}}getThemeRegex(){return this._themeRegex.lastIndex=0,this._themeRegex}shouldCache(){return"undefined"==typeof window}clear(){this._resolutionCache.clear(),this._pathLookupCache.clear()}}/**
- * Parsed flex shorthand components for CSS flex property
- * @interface FlexComponents
- * @property grow - The flex-grow value (how much the item should grow)
- * @property shrink - The flex-shrink value (how much the item should shrink)
- * @property basis - The flex-basis value (initial main size before free space is distributed)
- */_defineProperty(ThemeResolverCache,"_instance",null);export class ThemeUtil{constructor(){}/**
+return`${ObjHelper.stringify(a)}_${b.mode}_${ObjHelper.stringify(b.system)}`}_evict(a){const b=a.keys();for(let c=0;c<this.CACHE_EVICTION_BATCH_SIZE;c++){const c=b.next().value;if(c)a.delete(c);else break}}}_defineProperty(ThemeResolverCache,"_instance",null);export class ThemeUtil{constructor(){}/**
    * Parses a CSS flex shorthand property into its individual components.
    *
    * The CSS flex property is a shorthand for flex-grow, flex-shrink, and flex-basis.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meonode/ui",
   "description": "A structured approach to component composition, direct CSS-first prop styling, built-in theming, smart prop handling (including raw property pass-through), and dynamic children.",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "type": "module",
   "main": "./dist/main.js",
   "types": "./dist/main.d.ts",
@@ -31,9 +31,9 @@
   "scripts": {
     "watch:build": "yarn dlx nodemon --watch src --ext ts,tsx,js,json --exec \"yarn build\"",
     "lint": "eslint --fix",
-    "test": "NODE_OPTIONS='--expose-gc' node --stack-size=10000 --experimental-vm-modules node_modules/jest/bin/jest.js --ci --verbose --testPathIgnorePatterns=\"tests/performance.test.ts\"",
-    "test:perf": "NODE_OPTIONS='--expose-gc' node --stack-size=10000 --experimental-vm-modules node_modules/jest/bin/jest.js --ci --verbose tests/performance.test.ts",
-    "test:all": "NODE_OPTIONS='--expose-gc' node --stack-size=10000 --experimental-vm-modules node_modules/jest/bin/jest.js --ci --verbose",
+    "test": "NODE_OPTIONS='--expose-gc' node --stack-size=10000 --max-old-space-size=8192 --experimental-vm-modules $(yarn bin jest) --ci --verbose --testPathIgnorePatterns=\"tests/performance.test.ts\" --testPathIgnorePatterns=\"tests/react-createelement-comparison.test.ts\"",
+    "test:perf": "NODE_OPTIONS='--expose-gc' node --stack-size=10000 --max-old-space-size=8192 --experimental-vm-modules $(yarn bin jest) --ci --verbose tests/performance.test.ts tests/react-createelement-comparison.test.ts",
+    "test:all": "NODE_OPTIONS='--expose-gc' node --stack-size=10000 --max-old-space-size=8192 --experimental-vm-modules $(yarn bin jest) --ci --verbose",
     "prebuild": "yarn lint && yarn test:all",
     "build": "yarn prebuild && rm -rf ./dist && babel src --out-dir dist --extensions \".ts,.tsx,.js\" && tsgo -p tsconfig.build.json --diagnostics && tsc-alias -p tsconfig.build.json",
     "publish:pre": "./prepublish.sh && yarn build && yarn version -i prerelease && yarn npm publish --tag next",
@@ -52,7 +52,9 @@
     "@babel/preset-typescript": "^7.28.5",
     "@emotion/cache": "^11.14.0",
     "@emotion/jest": "^11.14.2",
+    "@emotion/styled": "^11.14.1",
     "@eslint/js": "^9.39.1",
+    "@mui/material": "^7.3.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
@@ -81,7 +83,7 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.47.0"
   },
-  "packageManager": "yarn@4.10.2",
+  "packageManager": "yarn@4.11.0",
   "peerDependencies": {
     "@emotion/cache": ">=11.14.0",
     "react": ">=19.2.0",