@meonode/ui 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.12] - 2025-09-11
+
+### Fixed
+- **core.node**: Removed the child processing cache to fix a critical bug that caused infinite page loads in server-side rendering environments.
+- **helper**: Corrected the element type retrieval logic within the hashing function used for child node processing.
+
+## [0.2.11] - 2025-09-11
+
+### Enhanced
+- **core.node**: Significantly improved JSDoc documentation for the `BaseNode` class, providing better clarity on prop processing, child handling, and rendering logic.
+- **core.node**: Overhauled the child processing and caching mechanism to improve server-side performance and resolve a memory leak. This includes a move from object stringification to a more performant hashing strategy for cache keys and the introduction of a cache management policy.
+
+### Fixed
+- **helper**: Corrected an issue in flexbox style processing where an unnecessary string check was performed.
+- **core.node**: Updated a function placeholder to adhere to the unused parameter naming convention.
+
 ## [0.2.10] - 2025-09-10
 
 ### Added
@@ -58,7 +74,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
       Div<{ field: string }>({ field: 'Hello' })
   
       // Override existing React props
-      Input<{ onChange: (e: { target: { value: string } }) => void }>({
+      Input<{ onChange: (e: { target: { value: string } }) => void }>({ 
         onChange: ({ target }) => console.log(target.value),
       })
       ```

package/dist/core.node.d.ts

@@ -15,87 +15,186 @@ export declare class BaseNode<E extends NodeElement> implements NodeInstance<E>
     element: E;
     /** Original props passed during construction, preserved for cloning/recreation */
     rawProps: RawNodeProps<E>;
-    /** Processed props after theme resolution, style processing, and child normalization */
-    props: FinalNodeProps;
     /** Flag to identify BaseNode instances */
     readonly isBaseNode: boolean;
+    /** Processed props after theme resolution, style processing, and child normalization */
+    private _props?;
     /** DOM element used for portal rendering */
     private _portalDOMElement;
     /** React root instance for portal rendering */
     private _portalReactRoot;
+    /** Hash of the current children and theme to detect changes */
+    private _childrenHash?;
+    /** Cache for normalized children */
+    private _normalizedChildren?;
     /**
-     * Creates a new BaseNode instance that wraps a React element.
-     * Processes raw props by:
-     * - Extracting and resolving theme-aware styles
-     * - Processing DOM-related props
-     * - Normalizing children with theme inheritance
-     * @param element The React element/component to wrap
-     * @param rawProps Initial props including theme, styles, and children
+     * Constructs a new BaseNode instance.
+     *
+     * This constructor initializes a node with a given React element or component type
+     * and the raw props passed to it. The props are not processed until they are
+     * accessed via the `props` getter, allowing for lazy evaluation.
+     * @param element The React element or component type this node will represent.
+     * @param rawProps The initial, unprocessed props for the element.
      */
     constructor(element: E, rawProps?: RawNodeProps<E>);
+    /**
+     * Lazily processes and retrieves the final, normalized props for the node.
+     *
+     * The first time this getter is accessed, it triggers `_processProps` to resolve
+     * themes, styles, and children. Subsequent accesses return the cached result
+     * until the node is cloned or recreated.
+     * @returns The fully processed and normalized `FinalNodeProps`.
+     */
+    get props(): FinalNodeProps;
+    /**
+     * Performs the core logic of processing raw props into their final, normalized form.
+     *
+     * This method is called by the `props` getter on its first access. It handles:
+     * 1.  **Theme Resolution**: Selects the active theme from `theme` or `nodetheme` props.
+     * 2.  **Prop Resolution**: Resolves theme-aware values (functions) in `rawProps` and `nativeProps.style`.
+     * 3.  **Style Extraction**: Separates style-related props (`css`, `style`) from other DOM/component props.
+     * 4.  **Default Style Merging**: Combines default styles with resolved style props.
+     * 5.  **Child Processing**: Normalizes the `children` prop, propagating the theme.
+     * @returns The processed `FinalNodeProps` object.
+     * @private
+     */
+    private _processProps;
+    /**
+     * Processes raw children, wrapping them in `BaseNode` instances where necessary
+     * and propagating the theme.
+     *
+     * This method recursively processes each child to ensure consistent theme handling
+     * and to convert valid elements into `BaseNode` instances. It uses caching to
+     * optimize performance, with different strategies for server-side (string-based key)
+     * and client-side (WeakMap-based key) environments.
+     * @param children The raw child or array of children to process.
+     * @param theme The theme to propagate to the children.
+     * @returns The processed children, ready to be normalized for rendering.
+     * @private
+     */
     private _processChildren;
     /**
-     * Renders a processed NodeElement into a ReactNode, applying theme and key if needed.
+     * Renders a processed `NodeElement` into a `ReactNode`, applying a theme and key if necessary.
      *
-     * Handles the following cases:
-     * 1. If the element is a BaseNode instance, it re-wraps it to apply the key and theme if needed.
-     * 2. If the element is a React class component type, it wraps it in a BaseNode.
-     * 3. If the element is a NodeInstance object, it calls its render method.
-     * 4. If the element is a React.Component instance, it calls its render method.
-     * 5. If the element is a functional component, it creates a React element with the provided key.
-     * 6. For all other valid ReactNode types, it returns the element as-is.
-     * @param processedElement The processed node element to render.
-     * @param passedTheme The theme to apply, if any.
-     * @param passedKey The key to assign, if any.
-     * @returns The rendered ReactNode.
+     * This static method centralizes the logic for converting various types of processed elements
+     * into renderable React nodes. It handles:
+     * - `BaseNode` instances: Re-wraps them to apply a new key or theme.
+     * - React class components: Wraps them in a new `BaseNode`.
+     * - `NodeInstance` objects: Invokes their `render()` method.
+     * - React component instances: Invokes their `render()` method.
+     * - Functional components: Creates a React element from them.
+     * - Other valid `ReactNode` types (strings, numbers, etc.): Returns them as-is.
+     * @param processedElement The node element to render.
+     * @param passedTheme The theme to propagate.
+     * @param passedKey The React key to assign.
+     * @returns A renderable `ReactNode`.
+     * @private
+     * @static
      */
     static _renderProcessedNode(processedElement: NodeElement, passedTheme: Theme | undefined, passedKey: string | undefined): ReactNode;
     /**
-     * Renders the result of a function child, supporting theme propagation.
+     * Renders the output of a function-as-a-child, ensuring theme propagation.
      *
-     * Used for children that are functions (`() => Children`). If the returned value is a `BaseNode`
-     * without an explicit theme, the parent theme is injected. Otherwise, the result is rendered as-is.
-     * @template E - The type of ReactNode or NodeInstance.
-     * @param props Renderer props.
-     * @param props.render Function to invoke for rendering the child.
-     * @param props.passedTheme Theme to provide to the child, if applicable.
-     * @param props.passedKey Key to assign to the rendered node.
-     * @param props.processRawNode Function to process raw nodes.
-     * @returns The rendered ReactNode, with theme applied if necessary.
+     * This method is designed to handle "render prop" style children (`() => ReactNode`).
+     * It invokes the function, processes its result, and ensures the parent's theme is
+     * correctly passed down to any `BaseNode` instances returned by the function.
+     * @param props The properties for the function renderer.
+     * @param props.render The function to execute to get the child content.
+     * @param props.passedTheme The theme to propagate to the rendered child.
+     * @param props.passedKey The React key to assign to the rendered node.
+     * @param props.processRawNode A reference to the `_processRawNode` method for recursive processing.
+     * @returns The rendered `ReactNode`.
+     * @private
      */
     private _functionRenderer;
     /**
-     * Processes a single raw child element, converting it into a ProcessedChild.
-     * If the child is part of an array and lacks an explicit key, a stable indexed key
-     * (`elementName_child_index`) is generated for new BaseNode instances.
-     * @param rawNode The raw child element to process.
-     * @param parentTheme The theme inherited from the parent node.
-     * @param nodeIndex Optional index of the child if it's part of an array.
-     * @returns The processed child.
+     * Generates a stable key for a node, especially for elements within an array.
+     *
+     * If an `existingKey` is provided, it is returned. Otherwise, a key is generated
+     * based on the element's type name and its index within a list of siblings.
+     * This helps prevent re-rendering issues in React when dealing with dynamic lists.
+     * @param options The options for key generation.
+     * @param options.nodeIndex The index of the node in an array of children.
+     * @param options.element The element for which to generate a key.
+     * @param options.existingKey An existing key, if one was already provided.
+     * @param options.children The children of the node, used to add complexity to the key.
+     * @returns A React key, or `undefined` if no key could be generated.
+     * @private
+     */
+    private _generateKey;
+    /**
+     * Processes a single raw node, recursively converting it into a `BaseNode` or other renderable type.
+     *
+     * This is a central method for normalizing children. It handles various types of input:
+     * - **`BaseNode` instances**: Re-creates them to ensure the correct theme and key are applied.
+     * - **Primitives**: Returns strings, numbers, booleans, null, and undefined as-is.
+     * - **Functions (Render Props)**: Wraps them in a `BaseNode` that uses `_functionRenderer` to delay execution.
+     * - **Valid React Elements**: Converts them into `BaseNode` instances, extracting props and propagating the theme.
+     * - **React Component Types**: Wraps them in a `BaseNode` with the parent theme.
+     * - **React Component Instances**: Renders them and processes the output recursively.
+     *
+     * It also generates a stable key for elements within an array if one is not provided.
+     * @param rawNode The raw child node to process.
+     * @param parentTheme The theme inherited from the parent.
+     * @param nodeIndex The index of the child if it is in an array, used for key generation.
+     * @returns A processed `NodeElement` (typically a `BaseNode` instance or a primitive).
+     * @private
      */
-    _processRawNode(rawNode: NodeElement, parentTheme?: Theme, nodeIndex?: number): NodeElement;
+    private _processRawNode;
     /**
-     * Normalizes a child node into a renderable ReactNode.
-     * Processes different types of child nodes to ensure they can be properly rendered
-     * while maintaining theme inheritance.
+     * Normalizes a processed child node into a final, renderable `ReactNode`.
      *
-     * Handles:
-     * - BaseNode instances (applies theme if needed)
-     * - React.Component instances (applies theme if needed)
-     * - Other valid React element types (returned as-is)
-     * - null/undefined values (returned as-is)
-     * @param child The child node to normalize into a renderable form
-     * @returns The normalized ReactNode that can be rendered by React
-     * @throws Error if child is an invalid element type
+     * This method is called during the `render` phase. It takes a child that has already
+     * been processed by `_processChildren` and prepares it for `React.createElement`.
+     *
+     * - For `BaseNode` instances, it calls their `render()` method, ensuring the theme is consistent.
+     * - It validates that other children are valid React element types.
+     * - Primitives and other valid nodes are returned as-is.
+     * @param child The processed child node to normalize.
+     * @returns A renderable `ReactNode`.
+     * @throws {Error} If the child is not a valid React element type.
+     * @private
      */
     private _normalizeChild;
     /**
-     * Converts this BaseNode instance into a renderable React node.
-     * Recursively processes child nodes and uses `React.createElement` to construct the final React element.
-     * @returns A ReactNode representing the rendered element.
+     * Renders the `BaseNode` into a `ReactElement`.
+     *
+     * This method is the final step in the rendering pipeline. It constructs a React element
+     * by:
+     * 1.  Validating that the node's `element` type is renderable.
+     * 2.  Normalizing processed children into `ReactNode`s using `_normalizeChild`.
+     * 3.  Caching normalized children to avoid re-processing on subsequent renders.
+     * 4.  Assembling the final props, including `key`, `style`, and other attributes.
+     * 5.  If the element has a `css` prop, it may be wrapped in a `StyledRenderer` to handle
+     * CSS-in-JS styling.
+     * 6.  Finally, calling `React.createElement` with the element, props, and children.
+     * @returns The rendered `ReactElement`.
+     * @throws {Error} If the node's `element` is not a valid React element type.
      */
     render(): ReactElement;
+    /**
+     * Ensures the necessary DOM elements for portal rendering are created and attached.
+     *
+     * On the client-side, this method checks for or creates a `div` element appended
+     * to the `document.body` and initializes a React root on it. This setup is
+     * required for the `toPortal` method to function. It is idempotent and safe
+     * to call multiple times.
+     * @returns `true` if the portal infrastructure is ready, `false` if on the server.
+     * @private
+     */
     private _ensurePortalInfrastructure;
+    /**
+     * Renders the node into a React Portal.
+     *
+     * This method mounts the node's rendered content into a separate DOM tree
+     * attached to the `document.body`. It's useful for rendering components like
+     * modals, tooltips, or notifications that need to appear above other UI elements.
+     *
+     * The returned object includes an `unmount` function to clean up the portal.
+     * @returns A `ReactDOMRoot` instance for managing the portal, or `null` if
+     * called in a server-side environment. The returned instance is enhanced
+     * with a custom `unmount` method that also cleans up the associated DOM element.
+     */
     toPortal(): ReactDOMRoot | null;
 }
 /**

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

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

package/dist/core.node.js

@@ -1,4 +1,4 @@
-"use strict";var _excluded=["ref","key","children","nodetheme","theme","props"],_excluded2=["style"],_excluded3=["style","css"],_excluded4=["style"],_excluded5=["children","key","nativeProps"];function _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(a){return typeof a}:function(a){return a&&"function"==typeof Symbol&&a.constructor===Symbol&&a!==Symbol.prototype?"symbol":typeof a},_typeof(a)}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 React,{Fragment,createElement,isValidElement}from"react";import{isNodeInstance,resolveDefaultStyle,resolveObjWithTheme}from"./helper/node.helper.js";import{isForwardRef,isFragment,isMemo,isReactClassComponent,isValidElementType}from"./helper/react-is.helper.js";import{createRoot}from"react-dom/client";import{getComponentType,getCSSProps,getDOMProps,getElementTypeName,hasNoStyleTag}from"./helper/common.helper.js";import StyledRenderer from"./components/styled-renderer.client.js";/**
+"use strict";var _excluded=["ref","key","children","nodetheme","theme","props"],_excluded2=["style"],_excluded3=["style","css"],_excluded4=["style"],_excluded5=["children","key","nativeProps"];function _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(a){return typeof a}:function(a){return a&&"function"==typeof Symbol&&a.constructor===Symbol&&a!==Symbol.prototype?"symbol":typeof a},_typeof(a)}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 React,{Fragment,createElement,isValidElement}from"react";import{createStableHash,isNodeInstance,resolveDefaultStyle}from"./helper/node.helper.js";import{isForwardRef,isFragment,isMemo,isReactClassComponent,isValidElementType}from"./helper/react-is.helper.js";import{createRoot}from"react-dom/client";import{getComponentType,getCSSProps,getDOMProps,getElementTypeName,hasNoStyleTag,shallowEqual}from"./helper/common.helper.js";import StyledRenderer from"./components/styled-renderer.client.js";import{resolveObjWithTheme}from"./helper/theme.helper.js";/**
  * Represents a node in a React component tree with theme and styling capabilities.
  * This class wraps React elements and handles:
  * - Props processing and normalization
@@ -6,114 +6,199 @@
  * - Child node processing and management
  * - Style processing with theme variables
  * @template E The type of React element or component this node represents
- */export class BaseNode{/**
-   * Creates a new BaseNode instance that wraps a React element.
-   * Processes raw props by:
-   * - Extracting and resolving theme-aware styles
-   * - Processing DOM-related props
-   * - Normalizing children with theme inheritance
-   * @param element The React element/component to wrap
-   * @param rawProps Initial props including theme, styles, and children
-   */constructor(a){var b=this,c=1<arguments.length&&arguments[1]!==void 0?arguments[1]:{};_defineProperty(this,"rawProps",{}),_defineProperty(this,"isBaseNode",!0),_defineProperty(this,"_portalDOMElement",null),_defineProperty(this,"_portalReactRoot",null),_defineProperty(this,"_normalizeChild",function(a){var c,d;if(!a)return a;var e=(null===(c=b.rawProps)||void 0===c?void 0:c.nodetheme)||(null===(d=b.rawProps)||void 0===d?void 0:d.theme)||b.props.nodetheme||b.props.theme;// For BaseNode instances, apply current theme if child has no theme
+ */export class BaseNode{/** Hash of the current children and theme to detect changes *//** Cache for normalized children *//**
+   * Constructs a new BaseNode instance.
+   *
+   * This constructor initializes a node with a given React element or component type
+   * and the raw props passed to it. The props are not processed until they are
+   * accessed via the `props` getter, allowing for lazy evaluation.
+   * @param element The React element or component type this node will represent.
+   * @param rawProps The initial, unprocessed props for the element.
+   */constructor(a){var b=this,c=1<arguments.length&&arguments[1]!==void 0?arguments[1]:{};/** The underlying React element or component type that this node represents *//** Original props passed during construction, preserved for cloning/recreation *//** Flag to identify BaseNode instances *//** DOM element used for portal rendering *//** React root instance for portal rendering *//**
+   * Generates a stable key for a node, especially for elements within an array.
+   *
+   * If an `existingKey` is provided, it is returned. Otherwise, a key is generated
+   * based on the element's type name and its index within a list of siblings.
+   * This helps prevent re-rendering issues in React when dealing with dynamic lists.
+   * @param options The options for key generation.
+   * @param options.nodeIndex The index of the node in an array of children.
+   * @param options.element The element for which to generate a key.
+   * @param options.existingKey An existing key, if one was already provided.
+   * @param options.children The children of the node, used to add complexity to the key.
+   * @returns A React key, or `undefined` if no key could be generated.
+   * @private
+   *//**
+   * Normalizes a processed child node into a final, renderable `ReactNode`.
+   *
+   * This method is called during the `render` phase. It takes a child that has already
+   * been processed by `_processChildren` and prepares it for `React.createElement`.
+   *
+   * - For `BaseNode` instances, it calls their `render()` method, ensuring the theme is consistent.
+   * - It validates that other children are valid React element types.
+   * - Primitives and other valid nodes are returned as-is.
+   * @param child The processed child node to normalize.
+   * @returns A renderable `ReactNode`.
+   * @throws {Error} If the child is not a valid React element type.
+   * @private
+   */_defineProperty(this,"rawProps",{}),_defineProperty(this,"isBaseNode",!0),_defineProperty(this,"_portalDOMElement",null),_defineProperty(this,"_portalReactRoot",null),_defineProperty(this,"_generateKey",function(a){var b=a.nodeIndex,c=a.element,d=a.existingKey,e=a.children;if(d)return d;var f,g=getElementTypeName(c);return f=Array.isArray(e)&&0<e.length?void 0===b?"".concat(g,"-").concat(e.length):"".concat(g,"-").concat(b,"-").concat(e.length):void 0===b?g:"".concat(g,"-").concat(b),f}),_defineProperty(this,"_normalizeChild",function(a){var c,d;if(!a)return a;var e=(null===(c=b.rawProps)||void 0===c?void 0:c.nodetheme)||(null===(d=b.rawProps)||void 0===d?void 0:d.theme)||b.props.nodetheme||b.props.theme;// For BaseNode instances, apply current theme if child has no theme
 if(a instanceof BaseNode){var f;return null!==(f=a.rawProps)&&void 0!==f&&f.nodetheme||void 0===e?a.render():new BaseNode(a.element,_objectSpread(_objectSpread({},a.rawProps),{},{nodetheme:e})).render()}// Validate element type before returning
 if(!isValidElementType(a)){var g=getComponentType(a);throw new Error("Invalid element type: ".concat(g," provided!"))}// Return valid React elements as-is
-return a}),this.element=a,this.rawProps=c;// Destructure raw props into relevant parts
-var d=c.ref,e=c.key,f=c.children,g=c.nodetheme,h=c.theme,i=c.props,j=void 0===i?{}:i,k=_objectWithoutProperties(c,_excluded),l=h||g,m=j,n=m.style,o=_objectWithoutProperties(m,_excluded2),p=resolveObjWithTheme(k,l),q=resolveObjWithTheme(n,l),r=p.style,s=p.css,t=_objectWithoutProperties(p,_excluded3),u=getCSSProps(t),v=getDOMProps(t),w=resolveDefaultStyle(_objectSpread(_objectSpread({},u),r)),x=this._processChildren(f,l);// Process children while maintaining theme inheritance
+return a}),this.element=a,this.rawProps=c}/**
+   * Lazily processes and retrieves the final, normalized props for the node.
+   *
+   * The first time this getter is accessed, it triggers `_processProps` to resolve
+   * themes, styles, and children. Subsequent accesses return the cached result
+   * until the node is cloned or recreated.
+   * @returns The fully processed and normalized `FinalNodeProps`.
+   */get props(){return this._props||(this._props=this._processProps()),this._props}/**
+   * Performs the core logic of processing raw props into their final, normalized form.
+   *
+   * This method is called by the `props` getter on its first access. It handles:
+   * 1.  **Theme Resolution**: Selects the active theme from `theme` or `nodetheme` props.
+   * 2.  **Prop Resolution**: Resolves theme-aware values (functions) in `rawProps` and `nativeProps.style`.
+   * 3.  **Style Extraction**: Separates style-related props (`css`, `style`) from other DOM/component props.
+   * 4.  **Default Style Merging**: Combines default styles with resolved style props.
+   * 5.  **Child Processing**: Normalizes the `children` prop, propagating the theme.
+   * @returns The processed `FinalNodeProps` object.
+   * @private
+   */_processProps(){// Destructure raw props into relevant parts
+var a=this.rawProps,b=a.ref,c=a.key,d=a.children,e=a.nodetheme,f=a.theme,g=a.props,h=void 0===g?{}:g,i=_objectWithoutProperties(a,_excluded),j=f||e,k=h,l=k.style,m=_objectWithoutProperties(k,_excluded2),n=resolveObjWithTheme(i,j),o=resolveObjWithTheme(l,j),p=n.style,q=n.css,r=_objectWithoutProperties(n,_excluded3),s=getCSSProps(r),t=getDOMProps(r),u=resolveDefaultStyle(_objectSpread(_objectSpread({},s),p)),v=this._processChildren(d,j);// Process children while maintaining theme inheritance
 // Combine processed props into final normalized form
-this.props=_objectSpread(_objectSpread({ref:d,key:e,nodetheme:l,theme:h,css:_objectSpread(_objectSpread({},w),s),style:q},v),{},{nativeProps:o,children:x})}_processChildren(a,b){var c=this;return a?Array.isArray(a)?a.map(function(a,d){return c._processRawNode(a,b,d)}):this._processRawNode(a,b):void 0}/**
-   * Renders a processed NodeElement into a ReactNode, applying theme and key if needed.
+return _objectSpread(_objectSpread({ref:b,key:c,nodetheme:j,theme:f,css:_objectSpread(_objectSpread({},u),q),style:o},t),{},{nativeProps:m,children:v})}/**
+   * Processes raw children, wrapping them in `BaseNode` instances where necessary
+   * and propagating the theme.
    *
-   * Handles the following cases:
-   * 1. If the element is a BaseNode instance, it re-wraps it to apply the key and theme if needed.
-   * 2. If the element is a React class component type, it wraps it in a BaseNode.
-   * 3. If the element is a NodeInstance object, it calls its render method.
-   * 4. If the element is a React.Component instance, it calls its render method.
-   * 5. If the element is a functional component, it creates a React element with the provided key.
-   * 6. For all other valid ReactNode types, it returns the element as-is.
-   * @param processedElement The processed node element to render.
-   * @param passedTheme The theme to apply, if any.
-   * @param passedKey The key to assign, if any.
-   * @returns The rendered ReactNode.
+   * This method recursively processes each child to ensure consistent theme handling
+   * and to convert valid elements into `BaseNode` instances. It uses caching to
+   * optimize performance, with different strategies for server-side (string-based key)
+   * and client-side (WeakMap-based key) environments.
+   * @param children The raw child or array of children to process.
+   * @param theme The theme to propagate to the children.
+   * @returns The processed children, ready to be normalized for rendering.
+   * @private
+   */_processChildren(a,b){var c=this;return a?Array.isArray(a)?a.map(function(a,d){return c._processRawNode(a,b,d)}):this._processRawNode(a,b):void 0;// No caching on the client, as it was ineffective and complex.
+}/**
+   * Renders a processed `NodeElement` into a `ReactNode`, applying a theme and key if necessary.
+   *
+   * This static method centralizes the logic for converting various types of processed elements
+   * into renderable React nodes. It handles:
+   * - `BaseNode` instances: Re-wraps them to apply a new key or theme.
+   * - React class components: Wraps them in a new `BaseNode`.
+   * - `NodeInstance` objects: Invokes their `render()` method.
+   * - React component instances: Invokes their `render()` method.
+   * - Functional components: Creates a React element from them.
+   * - Other valid `ReactNode` types (strings, numbers, etc.): Returns them as-is.
+   * @param processedElement The node element to render.
+   * @param passedTheme The theme to propagate.
+   * @param passedKey The React key to assign.
+   * @returns A renderable `ReactNode`.
+   * @private
+   * @static
    */static _renderProcessedNode(a,b,c){var d={};// 1. BaseNode instance: re-wrap to apply key/theme if needed
-if(void 0!==c&&(d.key=c),a instanceof BaseNode){var e,f,g=(null===(e=a.rawProps)||void 0===e?void 0:e.theme)||(null===(f=a.rawProps)||void 0===f?void 0:f.nodetheme)||b;return new BaseNode(a.element,_objectSpread(_objectSpread(_objectSpread({},a.rawProps),d),{},{nodetheme:g})).render()}// 2. React class component type: wrap in BaseNode
+if(void 0!==c&&(d.key=c),a instanceof BaseNode){var e,f,g,h,i,j=(null===(e=a.rawProps)||void 0===e?void 0:e.theme)||(null===(f=a.rawProps)||void 0===f?void 0:f.nodetheme)||b;// Avoid creating new BaseNode if props are identical
+return shallowEqual(d,{key:null===(g=a.rawProps)||void 0===g?void 0:g.key})&&j===((null===(h=a.rawProps)||void 0===h?void 0:h.nodetheme)||(null===(i=a.rawProps)||void 0===i?void 0:i.theme))?a.render():new BaseNode(a.element,_objectSpread(_objectSpread(_objectSpread({},a.rawProps),d),{},{nodetheme:j})).render()}// 2. React class component type: wrap in BaseNode
 return isReactClassComponent(a)?new BaseNode(a,d).render():isNodeInstance(a)?a.render():a instanceof React.Component?a.render():"function"==typeof a?createElement(a,{key:c}):a;// 3. NodeInstance object: call its render
 // 4. React.Component instance: call its render
 // 5. Functional component: create element with key
 // 6. Other valid ReactNode types
 }/**
-   * Renders the result of a function child, supporting theme propagation.
+   * Renders the output of a function-as-a-child, ensuring theme propagation.
    *
-   * Used for children that are functions (`() => Children`). If the returned value is a `BaseNode`
-   * without an explicit theme, the parent theme is injected. Otherwise, the result is rendered as-is.
-   * @template E - The type of ReactNode or NodeInstance.
-   * @param props Renderer props.
-   * @param props.render Function to invoke for rendering the child.
-   * @param props.passedTheme Theme to provide to the child, if applicable.
-   * @param props.passedKey Key to assign to the rendered node.
-   * @param props.processRawNode Function to process raw nodes.
-   * @returns The rendered ReactNode, with theme applied if necessary.
+   * This method is designed to handle "render prop" style children (`() => ReactNode`).
+   * It invokes the function, processes its result, and ensures the parent's theme is
+   * correctly passed down to any `BaseNode` instances returned by the function.
+   * @param props The properties for the function renderer.
+   * @param props.render The function to execute to get the child content.
+   * @param props.passedTheme The theme to propagate to the rendered child.
+   * @param props.passedKey The React key to assign to the rendered node.
+   * @param props.processRawNode A reference to the `_processRawNode` method for recursive processing.
+   * @returns The rendered `ReactNode`.
+   * @private
    */_functionRenderer(a){var b=a.render,c=a.passedTheme,d=a.passedKey,e=a.processRawNode,f=b();// Invoke the render function to get the child node.
 // Handle React.Component instance
 if(f instanceof React.Component){var g=f.render(),h=e(g,c);return BaseNode._renderProcessedNode(h,c,d)}// Handle BaseNode instance
 if(f instanceof BaseNode||isNodeInstance(f)){var i,j=f;return void 0===(null===(i=j.rawProps)||void 0===i?void 0:i.nodetheme)&&void 0!==c?new BaseNode(j.element,_objectSpread(_objectSpread({key:d},j.rawProps),{},{nodetheme:c})).render():j.render()}// Process other result types
 var k=e(f,c);return k?BaseNode._renderProcessedNode(k,c,d):f}/**
-   * Processes a single raw child element, converting it into a ProcessedChild.
-   * If the child is part of an array and lacks an explicit key, a stable indexed key
-   * (`elementName_child_index`) is generated for new BaseNode instances.
-   * @param rawNode The raw child element to process.
-   * @param parentTheme The theme inherited from the parent node.
-   * @param nodeIndex Optional index of the child if it's part of an array.
-   * @returns The processed child.
+   * Processes a single raw node, recursively converting it into a `BaseNode` or other renderable type.
+   *
+   * This is a central method for normalizing children. It handles various types of input:
+   * - **`BaseNode` instances**: Re-creates them to ensure the correct theme and key are applied.
+   * - **Primitives**: Returns strings, numbers, booleans, null, and undefined as-is.
+   * - **Functions (Render Props)**: Wraps them in a `BaseNode` that uses `_functionRenderer` to delay execution.
+   * - **Valid React Elements**: Converts them into `BaseNode` instances, extracting props and propagating the theme.
+   * - **React Component Types**: Wraps them in a `BaseNode` with the parent theme.
+   * - **React Component Instances**: Renders them and processes the output recursively.
+   *
+   * It also generates a stable key for elements within an array if one is not provided.
+   * @param rawNode The raw child node to process.
+   * @param parentTheme The theme inherited from the parent.
+   * @param nodeIndex The index of the child if it is in an array, used for key generation.
+   * @returns A processed `NodeElement` (typically a `BaseNode` instance or a primitive).
+   * @private
    */_processRawNode(a,b,c// Index for generating stable keys for array children
-){var d=getComponentType(a),e=function generateKey(a){var b=a.element,d=a.existingKey,e=a.children;if(d)return d;var f=getElementTypeName(b);return Array.isArray(e)&&0<e.length?void 0===c?"".concat(f,"-").concat(e.length):"".concat(f,"-").concat(c,"-").concat(e.length):void 0===c?f:"".concat(f,"-").concat(c)};// Determine the type of the raw node
-// Helper to generate an indexed key if no explicit key is present and an index is available.
+){var d=getComponentType(a);// Determine the type of the raw node
 // Case 1: Child is already a BaseNode instance
-if(a instanceof BaseNode){var f=a,g=f.rawProps||{},h=g.theme||g.nodetheme||b,i=e({element:f.element,existingKey:g.key,children:g.children});// Get initial raw props of the child
+if(a instanceof BaseNode){var e=a,f=e.rawProps||{},g=f.theme||f.nodetheme||b;// Get initial raw props of the child
 // Prefer child's own theme
-// Generate key if needed
-return new BaseNode(f.element,_objectSpread(_objectSpread({},g),{},{nodetheme:h,// Use the determined theme for the new node
-key:i}));// Create a new BaseNode with merged props and theme
+// Check if we can reuse the existing node
+if(f.nodetheme===g&&f.key!==void 0)return e;var h=this._generateKey({nodeIndex:c,element:e.element,existingKey:f.key,children:f.children});// Generate key if needed
+return new BaseNode(e.element,_objectSpread(_objectSpread({},f),{},{nodetheme:g,// Use the determined theme for the new node
+key:h}));// Create a new BaseNode with merged props and theme
 }// Case 2: Child is a primitive (string, number, boolean, null, undefined)
 if("string"===d||"number"===d||"boolean"===d||null===a||void 0===a)return a;// Case 3: Child is a function that needs to be called during render (FunctionRenderer).
 if("function"===d&&!isReactClassComponent(a)&&!isMemo(a)&&!isForwardRef(a)){// The key is for the BaseNode that wraps the _functionRenderer component.
 // Functions themselves don't have a .key prop that we can access here.
-var j=e({element:this._functionRenderer});// Generate key for function renderer
-return new BaseNode(this._functionRenderer,{processRawNode:this._processRawNode.bind(this),render:a,passedTheme:b,key:j})}// Case 4: Child is a React Element (JSX element like <div> or <MyComponent>)
-if(isValidElement(a)){var k=a.props,l=k.style,m=_objectWithoutProperties(k,_excluded4),n=_objectSpread(_objectSpread({},m),l||{}),o=n.theme||n.nodetheme||b,p=e({element:a.type,existingKey:a.key,children:n.children});// Combine top-level props from the element with its flattened style object properties
-return new BaseNode(a.type,_objectSpread(_objectSpread({},n),{},{// Pass the combined props
-nodetheme:o,key:p}))}// Case 5: Child is an ElementType (string tag, class component, Memo/ForwardRef)
-if(isReactClassComponent(a)||"object"===d&&(isMemo(a)||isForwardRef(a))){var q,r=e({element:a,children:"object"===_typeof(a)&&"props"in a?null===(q=a.props)||void 0===q?void 0:q.children:void 0});// ElementTypes don't have an intrinsic key from the rawNode itself.
+var i=this._generateKey({nodeIndex:c,element:this._functionRenderer});// Generate key for function renderer
+return new BaseNode(this._functionRenderer,{processRawNode:this._processRawNode.bind(this),render:a,passedTheme:b,key:i})}// Case 4: Child is a React Element (JSX element like <div> or <MyComponent>)
+if(isValidElement(a)){var j=a.props,k=j.style,l=_objectWithoutProperties(j,_excluded4),m=_objectSpread(_objectSpread({},l),k||{}),n=m.theme||m.nodetheme||b,o=this._generateKey({nodeIndex:c,element:a.type,existingKey:a.key,children:m.children});// Combine top-level props from the element with its flattened style object properties
+return new BaseNode(a.type,_objectSpread(_objectSpread({},m),{},{// Pass the combined props
+nodetheme:n,key:o}))}// Case 5: Child is an ElementType (string tag, class component, Memo/ForwardRef)
+if(isReactClassComponent(a)||"object"===d&&(isMemo(a)||isForwardRef(a))){var p,q=this._generateKey({nodeIndex:c,element:a,children:"object"===_typeof(a)&&"props"in a?null===(p=a.props)||void 0===p?void 0:p.children:void 0});// ElementTypes don't have an intrinsic key from the rawNode itself.
 return new BaseNode(a,{nodetheme:b,// Apply parent theme
-key:r})}// Case 6: Handle instances of React.Component
-if(a instanceof React.Component){var s=a.render();// Recursively process the rendered element with a parent theme and index if available
-return this._processRawNode(s,b,c)}// Case 7: Fallback for other ReactNode types (e.g., Fragments, Portals if not caught by isValidElement)
+key:q})}// Case 6: Handle instances of React.Component
+if(a instanceof React.Component){var r=a.render();// Recursively process the rendered element with a parent theme and index if available
+return this._processRawNode(r,b,c)}// Case 7: Fallback for other ReactNode types (e.g., Fragments, Portals if not caught by isValidElement)
 // These are returned as-is. If they are elements within an array, React expects them to have keys.
 // This logic primarily adds keys to BaseNode instances we create, other ReactNodes are returned as-is.
 return a}/**
-   * Normalizes a child node into a renderable ReactNode.
-   * Processes different types of child nodes to ensure they can be properly rendered
-   * while maintaining theme inheritance.
+   * Renders the `BaseNode` into a `ReactElement`.
    *
-   * Handles:
-   * - BaseNode instances (applies theme if needed)
-   * - React.Component instances (applies theme if needed)
-   * - Other valid React element types (returned as-is)
-   * - null/undefined values (returned as-is)
-   * @param child The child node to normalize into a renderable form
-   * @returns The normalized ReactNode that can be rendered by React
-   * @throws Error if child is an invalid element type
-   *//**
-   * Converts this BaseNode instance into a renderable React node.
-   * Recursively processes child nodes and uses `React.createElement` to construct the final React element.
-   * @returns A ReactNode representing the rendered element.
+   * This method is the final step in the rendering pipeline. It constructs a React element
+   * by:
+   * 1.  Validating that the node's `element` type is renderable.
+   * 2.  Normalizing processed children into `ReactNode`s using `_normalizeChild`.
+   * 3.  Caching normalized children to avoid re-processing on subsequent renders.
+   * 4.  Assembling the final props, including `key`, `style`, and other attributes.
+   * 5.  If the element has a `css` prop, it may be wrapped in a `StyledRenderer` to handle
+   * CSS-in-JS styling.
+   * 6.  Finally, calling `React.createElement` with the element, props, and children.
+   * @returns The rendered `ReactElement`.
+   * @throws {Error} If the node's `element` is not a valid React element type.
    */render(){var a=this;if(!isValidElementType(this.element)){var b=getComponentType(this.element);throw new Error("Invalid element type: ".concat(b," provided!"))}// Extract children and key
-var c=this.props,d=c.children,e=c.key,f=c.nativeProps,g=_objectWithoutProperties(c,_excluded5),h=void 0;if(void 0!==d&&null!==d)if(!Array.isArray(d))h=this._normalizeChild(d);else if(0<d.length){// Normalize each child in the array
-var i=d.map(function(b){return a._normalizeChild(b)});// Check if all children are null/undefined (e.g., conditional rendering resulted in nothing)
-h=i.every(function(a){return null===a||void 0===a})?void 0:i}else// Empty array of children
-h=void 0;// Prepare props for React.createElement
+var c=this.props,d=c.children,e=c.key,f=c.nativeProps,g=_objectWithoutProperties(c,_excluded5),h=void 0;if(void 0!==d&&null!==d){if(!this._normalizedChildren||this._childrenHash!==createStableHash(d,this.props.nodetheme||this.props.theme))if(!Array.isArray(d))this._normalizedChildren=this._normalizeChild(d);else if(0<d.length){var i=d.map(function(b){return a._normalizeChild(b)});this._normalizedChildren=i.every(function(a){return null===a||void 0===a})?void 0:i}else this._normalizedChildren=void 0;h=this._normalizedChildren}// Prepare props for React.createElement
 var j;// If the element has a `css` prop and has style tag, render using the `StyledRenderer` component
 // This enables emotion-based style handling for the element
-return j=this.element===Fragment||isFragment(this.element)?{key:e}:_objectSpread(_objectSpread(_objectSpread({},g),{},{key:e},f),{},{suppressHydrationWarning:!0}),this.element&&!hasNoStyleTag(this.element)&&j.css?createElement(StyledRenderer,_objectSpread({element:this.element},j),h):createElement(this.element,j,h)}_ensurePortalInfrastructure(){if("undefined"==typeof window)return!1;if(this._portalDOMElement&&this._portalReactRoot)return!0;if(this._portalDOMElement&&!this._portalDOMElement.isConnected&&(this._portalDOMElement=null,this._portalDOMElement=null),this._portalDOMElement||(this._portalDOMElement=document.createElement("div"),document.body.appendChild(this._portalDOMElement)),!this._portalReactRoot){if(!this._portalDOMElement)return!1;this._portalReactRoot=createRoot(this._portalDOMElement)}return!0}toPortal(){var a=this;if(!this._ensurePortalInfrastructure()||!this._portalReactRoot)return null;var b=this.render();return this._portalReactRoot.render(b),_objectSpread(_objectSpread({},this._portalReactRoot),{},{unmount:function unmount(){a._portalReactRoot&&(a._portalReactRoot.unmount(),a._portalReactRoot=null),a._portalDOMElement&&(a._portalDOMElement.parentNode&&a._portalDOMElement.parentNode.removeChild(a._portalDOMElement),a._portalDOMElement=null)}})}}/**
+return j=this.element===Fragment||isFragment(this.element)?{key:e}:_objectSpread(_objectSpread(_objectSpread({},g),{},{key:e},f),{},{suppressHydrationWarning:!0}),this.element&&!hasNoStyleTag(this.element)&&j.css?createElement(StyledRenderer,_objectSpread({element:this.element},j),h):createElement(this.element,j,h)}/**
+   * Ensures the necessary DOM elements for portal rendering are created and attached.
+   *
+   * On the client-side, this method checks for or creates a `div` element appended
+   * to the `document.body` and initializes a React root on it. This setup is
+   * required for the `toPortal` method to function. It is idempotent and safe
+   * to call multiple times.
+   * @returns `true` if the portal infrastructure is ready, `false` if on the server.
+   * @private
+   */_ensurePortalInfrastructure(){if("undefined"==typeof window)return!1;if(this._portalDOMElement&&this._portalReactRoot)return!0;if(this._portalDOMElement&&!this._portalDOMElement.isConnected&&(this._portalDOMElement=null,this._portalDOMElement=null),this._portalDOMElement||(this._portalDOMElement=document.createElement("div"),document.body.appendChild(this._portalDOMElement)),!this._portalReactRoot){if(!this._portalDOMElement)return!1;this._portalReactRoot=createRoot(this._portalDOMElement)}return!0}/**
+   * Renders the node into a React Portal.
+   *
+   * This method mounts the node's rendered content into a separate DOM tree
+   * attached to the `document.body`. It's useful for rendering components like
+   * modals, tooltips, or notifications that need to appear above other UI elements.
+   *
+   * The returned object includes an `unmount` function to clean up the portal.
+   * @returns A `ReactDOMRoot` instance for managing the portal, or `null` if
+   * called in a server-side environment. The returned instance is enhanced
+   * with a custom `unmount` method that also cleans up the associated DOM element.
+   */toPortal(){var a=this;if(!this._ensurePortalInfrastructure()||!this._portalReactRoot)return null;var b=this.render();return this._portalReactRoot.render(b),_objectSpread(_objectSpread({},this._portalReactRoot),{},{unmount:function unmount(){a._portalReactRoot&&(a._portalReactRoot.unmount(),a._portalReactRoot=null),a._portalDOMElement&&(a._portalDOMElement.parentNode&&a._portalDOMElement.parentNode.removeChild(a._portalDOMElement),a._portalDOMElement=null)}})}}/**
  * Factory function to create a `BaseNode` instance.
  * @template AdditionalProps Additional props to merge with node props.
  * @template E The React element or component type.

package/dist/helper/common.helper.d.ts

@@ -77,4 +77,6 @@ export declare function getDOMProps<E extends ElementType, T extends ComponentPr
  * @returns `true` if the tag is in the no-style set, otherwise `false`.
  */
 export declare function hasNoStyleTag(tag?: NodeElement): boolean;
+// Shallow comparison utility
+export declare function shallowEqual(obj1: any, obj2: any): boolean;
 //# sourceMappingURL=common.helper.d.ts.map

package/dist/helper/common.helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.helper.d.ts","sourceRoot":"","sources":["../../src/helper/common.helper.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,iCAE1B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,qCAmC5B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAsFxD;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAA0B,CAAA;AAEjE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAU3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAUjH;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAGxD"}
+{"version":3,"file":"common.helper.d.ts","sourceRoot":"","sources":["../../src/helper/common.helper.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,iCAE1B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,qCAmC5B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAsFxD;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAA0B,CAAA;AAEjE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAU3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAUjH;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAGxD;AAED,6BAA6B;AAC7B,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAgB1D"}

package/dist/helper/common.helper.js

@@ -61,4 +61,5 @@ function _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof
  * Checks if a given tag is in the set of tags that should not receive style props.
  * @param tag The tag name to check (e.g., 'script', 'style').
  * @returns `true` if the tag is in the no-style set, otherwise `false`.
- */export function hasNoStyleTag(a){return!!(a&&"string"==typeof a)&&noStyleTagsSet.has(a.toLowerCase())}
+ */export function hasNoStyleTag(a){return!!(a&&"string"==typeof a)&&noStyleTagsSet.has(a.toLowerCase())}// Shallow comparison utility
+export function shallowEqual(a,b){if(a===b)return!0;if(!a||!b)return!1;if("object"!==_typeof(a)||"object"!==_typeof(b))return a===b;var c=Object.keys(a),d=Object.keys(b);if(c.length!==d.length)return!1;for(var e,f=0,g=c;f<g.length;f++)if(e=g[f],!(e in b)||a[e]!==b[e])return!1;return!0}

package/dist/helper/node.helper.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from 'react';
-import type { NodeInstance } from '../node.type.js';
+import type { NodeElement, NodeInstance, Theme } from '../node.type.js';
 /**
  * Type guard to check if an object is a NodeInstance.
  *
@@ -12,21 +12,6 @@ import type { NodeInstance } from '../node.type.js';
  * @returns True if the object is a NodeInstance, false otherwise.
  */
 export declare const isNodeInstance: (obj: unknown) => obj is NodeInstance<any>;
-/**
- * Resolves theme variable references in an object's values recursively.
- * This function performs a "smart merge" to maintain object reference identity
- * for parts of the object that do not contain resolved theme variables or
- * other modifications. Only creates new objects or properties when a change occurs.
- * Handles nested objects and arrays, and prevents circular references.
- * Theme variables are referenced using the format "theme.path.to.value".
- * @param obj The object (or array) whose values should be resolved against the theme. Defaults to an empty object.
- * @param theme The theme object containing variable definitions. Optional.
- * @returns A new object (or array) with all theme variables resolved to their corresponding values,
- * or the original object (or array) if no changes were necessary.
- */
-export declare const resolveObjWithTheme: (obj?: Record<string, any>, theme?: Partial<{
-    [key: string]: any;
-}> | undefined) => any;
 /**
  * Resolves default CSS styles to fix common flexbox layout issues.
  *
@@ -908,4 +893,25 @@ export declare const resolveDefaultStyle: (style: CSSProperties) => {
     minHeight: import("csstype").Property.MinHeight<string | number>;
     minWidth: import("csstype").Property.MinWidth<string | number>;
 };
+/**
+ * Creates a stable hash string based on the provided children and optional theme.
+ *
+ * This function generates a hash that represents the structure and types of the given
+ * children nodes, along with an optional theme. The hash is designed to be stable across
+ * renders, meaning that the same input will always produce the same hash output.
+ *
+ * The hashing strategy includes:
+ * - For arrays of children, it includes the length and samples the types of the first few children.
+ * - For single child nodes, it includes the type of the node.
+ * - For primitive values (strings, numbers, etc.), it includes their type.
+ * - If a theme is provided, it includes a stringified version of the theme.
+ *
+ * This approach avoids deep traversal of potentially large or complex node trees,
+ * focusing instead on key characteristics that are likely to change when the structure
+ * or content changes.
+ * @param children The child nodes to hash, which can be a single node or an array of nodes.
+ * @param theme An optional theme object or string to include in the hash.
+ * @returns A stable hash string representing the structure and types of the children and theme.
+ */
+export declare function createStableHash(children: NodeElement | NodeElement[], theme?: Theme): string;
 //# sourceMappingURL=node.helper.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"node.helper.d.ts","sourceRoot":"","sources":["../../src/helper/node.helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAS,MAAM,mBAAmB,CAAA;AAG5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,4CAS1B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB;;sBA+G/B,CAAA;AA+DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE/B,CAAA"}
+{"version":3,"file":"node.helper.d.ts","sourceRoot":"","sources":["../../src/helper/node.helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAIzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,4CAS1B,CAAA;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE/B,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CA0B7F"}

package/dist/helper/node.helper.js

@@ -1,4 +1,4 @@
-"use strict";var _excluded=["flex"];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)}function _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(a){return typeof a}:function(a){return a&&"function"==typeof Symbol&&a.constructor===Symbol&&a!==Symbol.prototype?"symbol":typeof a},_typeof(a)}import{getValueByPath}from"./common.helper.js";/**
+"use strict";var _excluded=["flex"];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)}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 _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(a){return typeof a}:function(a){return a&&"function"==typeof Symbol&&a.constructor===Symbol&&a!==Symbol.prototype?"symbol":typeof a},_typeof(a)}import{getElementTypeName}from"./common.helper.js";import{ObjHelper}from"./obj.helper.js";/**
  * Type guard to check if an object is a NodeInstance.
  *
  * A NodeInstance is expected to be a non-null object with:
@@ -9,32 +9,6 @@
  * @param obj The object to check.
  * @returns True if the object is a NodeInstance, false otherwise.
  */export var isNodeInstance=function isNodeInstance(a){return"object"===_typeof(a)&&null!==a&&"element"in a&&"function"==typeof a.render&&"function"==typeof a.toPortal&&"isBaseNode"in a};/**
- * Resolves theme variable references in an object's values recursively.
- * This function performs a "smart merge" to maintain object reference identity
- * for parts of the object that do not contain resolved theme variables or
- * other modifications. Only creates new objects or properties when a change occurs.
- * Handles nested objects and arrays, and prevents circular references.
- * Theme variables are referenced using the format "theme.path.to.value".
- * @param obj The object (or array) whose values should be resolved against the theme. Defaults to an empty object.
- * @param theme The theme object containing variable definitions. Optional.
- * @returns A new object (or array) with all theme variables resolved to their corresponding values,
- * or the original object (or array) if no changes were necessary.
- */export var resolveObjWithTheme=function resolveObjWithTheme(){var a=0<arguments.length&&arguments[0]!==void 0?arguments[0]:{},b=1<arguments.length?arguments[1]:void 0;if(!b||!!b&&"object"===_typeof(b)&&0===Object.keys(b).length||0===Object.keys(a).length)return a;/**
-   * Recursively resolves theme variables within an object or array.
-   * It tracks visited objects to prevent infinite recursion caused by circular references.
-   * This function implements a "smart merge" to preserve object/array identity for unchanged parts.
-   * @param currentObj The current object or array being processed in the recursion.
-   * @param visited A Set to keep track of objects that have already been visited to detect circular references.
-   * @returns The processed object/array with theme variables resolved, or the original `currentObj`
-   * if no changes were made to it or its direct children (excluding deeper nested changes).
-   */var c=function resolveRecursively(a,d){// Base cases for non-objects/null, or already visited objects (circular reference)
-if(null===a||"object"!==_typeof(a))return a;if(d.has(a))return a;// Handle Arrays
-if(d.add(a),Array.isArray(a)){for(var e=a,f=!1,g=0;g<a.length;g++){var h=a[g],j=c(h,d);j===h?f&&(e[g]=h):(!f&&(e=[...a],f=!0),e[g]=j)}return e}// Handle Plain Objects (only process objects created with {})
-var k=a,l=!1,m=function _loop(){// Ensure it's an own property
-var e=a[n],f=e;if("function"==typeof e||"object"===_typeof(e)&&null!==e&&!Array.isArray(e)&&Object.getPrototypeOf(e)!==Object.prototype||// Exclude plain objects and arrays
-"object"!==_typeof(e)&&"string"!=typeof e)f=e;else if("string"==typeof e&&e.includes("theme.")){var g=e,h=!1;g=g.replace(/theme\.([a-zA-Z0-9_.-]+)/g,function(a,c){var d=getValueByPath(b,c);return void 0!==d&&null!==d?(h=!0,"object"===_typeof(d)&&!Array.isArray(d)&&"default"in d?d["default"]:d):a}),f=h&&g!==e?g:e}else"object"===_typeof(e)&&null!==e&&(// Recursively process nested objects or arrays
-f=c(e,d));f===e?l&&(k[n]=e):(!l&&(k=_objectSpread({},a),l=!0),k[n]=f)};for(var n in a)m();return k};// Initial call, ensure `obj` could be an array as well
-return c(a,new Set)};/**
  * Parsed flex shorthand components for CSS flex property
  * @interface FlexComponents
  * @property grow - The flex-grow value (how much the item should grow)
@@ -59,8 +33,7 @@ return c(a,new Set)};/**
  * parseFlexShorthand('1 0 auto') // → {grow: 1, shrink: 0, basis: 'auto'}
  */function parseFlexShorthand(a){// Early returns for invalid inputs
 if(null===a||a===void 0)return null;// Handle numeric flex values (e.g., flex: 1)
-if("number"==typeof a)return{grow:a,shrink:1,basis:"0%"};// Only process string values
-if("string"!=typeof a)return null;var b=a.trim().toLowerCase();if(!b)return null;// Handle CSS keyword values
+if("number"==typeof a)return{grow:a,shrink:1,basis:"0%"};var b=a.trim().toLowerCase();if(!b)return null;// Handle CSS keyword values
 return"none"===b?{grow:0,shrink:0,basis:"auto"}:"auto"===b?{grow:1,shrink:1,basis:"auto"}:"initial"===b?{grow:0,shrink:1,basis:"auto"}:null}/**
  * Resolves default CSS styles to fix common flexbox layout issues.
  *
@@ -136,4 +109,23 @@ if(!f){var k="column"===d.flexDirection||"column-reverse"===d.flexDirection,l="r
 return _objectSpread({flex:c,// Preserve original flex shorthand
 flexShrink:j,// Apply computed or explicit flexShrink
 minHeight:0,// Fix flex item scrolling issues
-minWidth:0},d)};
+minWidth:0},d)};/**
+ * Creates a stable hash string based on the provided children and optional theme.
+ *
+ * This function generates a hash that represents the structure and types of the given
+ * children nodes, along with an optional theme. The hash is designed to be stable across
+ * renders, meaning that the same input will always produce the same hash output.
+ *
+ * The hashing strategy includes:
+ * - For arrays of children, it includes the length and samples the types of the first few children.
+ * - For single child nodes, it includes the type of the node.
+ * - For primitive values (strings, numbers, etc.), it includes their type.
+ * - If a theme is provided, it includes a stringified version of the theme.
+ *
+ * This approach avoids deep traversal of potentially large or complex node trees,
+ * focusing instead on key characteristics that are likely to change when the structure
+ * or content changes.
+ * @param children The child nodes to hash, which can be a single node or an array of nodes.
+ * @param theme An optional theme object or string to include in the hash.
+ * @returns A stable hash string representing the structure and types of the children and theme.
+ */export function createStableHash(a,b){var c=Math.min,d="";if(b&&(d+="t:".concat("object"===_typeof(b)?ObjHelper.stringify(b):b+"",";")),Array.isArray(a)){d+="a:".concat(a.length,";");for(var e,f=c(3,a.length),g=0;g<f;g++)e=a[g],d+=e&&"object"===_typeof(e)&&"type"in e?"c".concat(g,":").concat(getElementTypeName(e),";"):"c".concat(g,":").concat(_typeof(e),";")}else d+=a&&"object"===_typeof(a)&&"type"in a?"s:".concat(getElementTypeName(a),";"):"s:".concat(_typeof(a),";");return d}

package/dist/helper/obj.helper.d.ts

@@ -0,0 +1,6 @@
+export declare class ObjHelper {
+    private constructor();
+    static stringify(obj: any, space?: number): string;
+    static parse(str: string): any;
+}
+//# sourceMappingURL=obj.helper.d.ts.map

package/dist/helper/obj.helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obj.helper.d.ts","sourceRoot":"","sources":["../../src/helper/obj.helper.ts"],"names":[],"mappings":"AAWA,qBAAa,SAAS;IACpB,OAAO,eAAiB;IAExB,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,SAAI,GAAG,MAAM,CAiD5C;IAED,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CA+C7B;CACF"}

package/dist/helper/obj.helper.js

@@ -0,0 +1 @@
+function _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(a){return typeof a}:function(a){return a&&"function"==typeof Symbol&&a.constructor===Symbol&&a!==Symbol.prototype?"symbol":typeof a},_typeof(a)}export class ObjHelper{constructor(){}static stringify(a){var b=1<arguments.length&&arguments[1]!==void 0?arguments[1]:2,c=new Map,d=new Map,e=0,f=0,g=function replacer(a,b){if("function"==typeof b)return d.has(b)||d.set(b,f++),{$type:"Function",name:b.name||"",id:d.get(b)};if("symbol"===_typeof(b)){var g;return{$type:"Symbol",key:null!==(g=b.description)&&void 0!==g?g:""}}if("bigint"==typeof b)return{$type:"BigInt",value:b.toString()};if(b instanceof Date)return{$type:"Date",value:b.toISOString()};if(b instanceof RegExp)return{$type:"RegExp",source:b.source,flags:b.flags};if(b instanceof Map)return{$type:"Map",entries:Array.from(b.entries())};if(b instanceof Set)return{$type:"Set",values:Array.from(b.values())};if("object"===_typeof(b)&&null!==b){if(c.has(b))return{$type:"Circular",ref:c.get(b)};c.set(b,e++)}return b};return JSON.stringify(a,g,b)}static parse(a){var b=[],c=function reviver(a,b){if(b&&"object"===_typeof(b)&&"$type"in b)switch(b.$type){case"Function":return function FunctionPlaceholder(){throw new Error("Function placeholder called: ".concat(b.name||"anonymous","#").concat(b.id))};case"Symbol":return Symbol(b.key);case"BigInt":return BigInt(b.value);case"Date":return new Date(b.value);case"RegExp":return new RegExp(b.source,b.flags);case"Map":return new Map(b.entries);case"Set":return new Set(b.values);case"Circular":return{$circularRef:b.ref}}return b},d=JSON.parse(a,c),e=function fixCirculars(a){if(a&&"object"===_typeof(a)){if(a.$circularRef!==void 0)return b[a.$circularRef];if(!b.includes(a)){b.push(a);for(var c,d=0,f=Object.keys(a);d<f.length;d++)c=f[d],a[c]=e(a[c])}}return a};return e(d)}}

package/dist/helper/theme.helper.d.ts

@@ -0,0 +1,79 @@
+import type { Theme } from '../node.type.js';
+/**
+ * Cache manager for theme resolution operations.
+ * Provides singleton-based caching with different strategies for server vs client environments.
+ */
+declare class ThemeResolverCache {
+    private static _instance;
+    private readonly _resolutionCache;
+    private readonly _pathLookupCache;
+    private readonly _themeRegex;
+    // Track cache statistics for performance monitoring
+    private _stats;
+    private constructor();
+    /**
+     * Get the singleton instance of the cache manager
+     */
+    static getInstance(): ThemeResolverCache;
+    /**
+     * Generate a stable cache key from object and theme
+     */
+    private _generateCacheKey;
+    /**
+     * Check if resolution result exists in cache
+     */
+    getResolution(obj: Record<string, any>, theme: Theme): any | null;
+    /**
+     * Store resolution result in cache
+     */
+    setResolution(obj: Record<string, any>, theme: Theme, result: any): void;
+    /**
+     * Get cached theme path lookup
+     */
+    getPathLookup(theme: Theme, path: string): any | null;
+    /**
+     * Cache theme path lookup result
+     */
+    setPathLookup(theme: Theme, path: string, value: any): void;
+    /**
+     * Get the shared regex instance (reused for performance)
+     */
+    getThemeRegex(): RegExp;
+    /**
+     * Clear all caches (useful for testing or memory management)
+     */
+    clearCaches(): void;
+    /**
+     * Get cache statistics for performance monitoring
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        pathHits: number;
+        pathMisses: number;
+    };
+    /**
+     * Check if we should use caching (server-side only for RSC optimization)
+     */
+    shouldCache(): boolean;
+}
+// Module-level cache instance
+declare const themeCache: ThemeResolverCache;
+/**
+ * Resolves theme variable references in an object's values recursively.
+ * This function performs a "smart merge" to maintain object reference identity
+ * for parts of the object that do not contain resolved theme variables or
+ * other modifications. Only creates new objects or properties when a change occurs.
+ * Handles nested objects and arrays, and prevents circular references.
+ * Theme variables are referenced using the format "theme.path.to.value".
+ * @param obj The object (or array) whose values should be resolved against the theme. Defaults to an empty object.
+ * @param theme The theme object containing variable definitions. Optional.
+ * @returns A new object (or array) with all theme variables resolved to their corresponding values,
+ * or the original object (or array) if no changes were necessary.
+ */
+export declare const resolveObjWithTheme: (obj?: Record<string, any>, theme?: Partial<{
+    [key: string]: any;
+}> | undefined) => any;
+// Export cache instance for testing and monitoring
+export { themeCache as ThemeResolverCache };
+//# sourceMappingURL=theme.helper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"theme.helper.d.ts","sourceRoot":"","sources":["../../src/helper/theme.helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAG9C;;;GAGG;AACH,cAAM,kBAAkB;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAkC;IAE1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAE1D,oDAAoD;IACpD,OAAO,CAAC,MAAM,CAKb;IAED,OAAO,eAEN;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,kBAAkB,CAKvC;IAED;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,GAAG,GAAG,IAAI,CAUhE;IAED;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,CAGvE;IAED;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAUpD;IAED;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAG1D;IAED;;OAEG;IACH,aAAa,IAAI,MAAM,CAItB;IAED;;OAEG;IACH,WAAW,IAAI,IAAI,CAIlB;IAED;;OAEG;IACH,QAAQ;;;;;MAEP;IAED;;OAEG;IACH,WAAW,IAAI,OAAO,CAErB;CACF;AAED,8BAA8B;AAC9B,QAAA,MAAM,UAAU,oBAAmC,CAAA;AAEnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB;;sBAwI/B,CAAA;AAED,mDAAmD;AACnD,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,CAAA"}

package/dist/helper/theme.helper.js

@@ -0,0 +1,59 @@
+function _typeof(a){"@babel/helpers - typeof";return _typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(a){return typeof a}:function(a){return a&&"function"==typeof Symbol&&a.constructor===Symbol&&a!==Symbol.prototype?"symbol":typeof a},_typeof(a)}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{getValueByPath}from"./common.helper.js";import{ObjHelper}from"./obj.helper.js";/**
+ * Cache manager for theme resolution operations.
+ * Provides singleton-based caching with different strategies for server vs client environments.
+ */class ThemeResolverCache{constructor(){// Track cache statistics for performance monitoring
+_defineProperty(this,"_resolutionCache",new Map),_defineProperty(this,"_pathLookupCache",new Map),_defineProperty(this,"_themeRegex",/theme\.([a-zA-Z0-9_.-]+)/g),_defineProperty(this,"_stats",{hits:0,misses:0,pathHits:0,pathMisses:0})}// Private constructor for singleton pattern
+/**
+   * Get the singleton instance of the cache manager
+   */static getInstance(){return ThemeResolverCache._instance||(ThemeResolverCache._instance=new ThemeResolverCache),ThemeResolverCache._instance}/**
+   * Generate a stable cache key from object and theme
+   */_generateCacheKey(a,b){// Use a more efficient key generation for better performance
+return"".concat(ObjHelper.stringify(a),"_").concat(ObjHelper.stringify(b))}/**
+   * Check if resolution result exists in cache
+   */getResolution(a,b){var c=this._generateCacheKey(a,b);return this._resolutionCache.has(c)?(this._stats.hits++,this._resolutionCache.get(c)):(this._stats.misses++,null)}/**
+   * Store resolution result in cache
+   */setResolution(a,b,c){var d=this._generateCacheKey(a,b);this._resolutionCache.set(d,c)}/**
+   * Get cached theme path lookup
+   */getPathLookup(a,b){var c="".concat(ObjHelper.stringify(a),"_").concat(b);return this._pathLookupCache.has(c)?(this._stats.pathHits++,this._pathLookupCache.get(c)):(this._stats.pathMisses++,null)}/**
+   * Cache theme path lookup result
+   */setPathLookup(a,b,c){var d="".concat(ObjHelper.stringify(a),"_").concat(b);this._pathLookupCache.set(d,c)}/**
+   * Get the shared regex instance (reused for performance)
+   */getThemeRegex(){return this._themeRegex.lastIndex=0,this._themeRegex}/**
+   * Clear all caches (useful for testing or memory management)
+   */clearCaches(){this._resolutionCache.clear(),this._pathLookupCache.clear(),this._stats={hits:0,misses:0,pathHits:0,pathMisses:0}}/**
+   * Get cache statistics for performance monitoring
+   */getStats(){return _objectSpread({},this._stats)}/**
+   * Check if we should use caching (server-side only for RSC optimization)
+   */shouldCache(){return"undefined"==typeof window}}// Module-level cache instance
+_defineProperty(ThemeResolverCache,"_instance",null);var themeCache=ThemeResolverCache.getInstance();/**
+ * Resolves theme variable references in an object's values recursively.
+ * This function performs a "smart merge" to maintain object reference identity
+ * for parts of the object that do not contain resolved theme variables or
+ * other modifications. Only creates new objects or properties when a change occurs.
+ * Handles nested objects and arrays, and prevents circular references.
+ * Theme variables are referenced using the format "theme.path.to.value".
+ * @param obj The object (or array) whose values should be resolved against the theme. Defaults to an empty object.
+ * @param theme The theme object containing variable definitions. Optional.
+ * @returns A new object (or array) with all theme variables resolved to their corresponding values,
+ * or the original object (or array) if no changes were necessary.
+ */export var resolveObjWithTheme=function resolveObjWithTheme(){var a=0<arguments.length&&void 0!==arguments[0]?arguments[0]:{},b=1<arguments.length?arguments[1]:void 0;if(!b||!!b&&"object"===_typeof(b)&&0===Object.keys(b).length||0===Object.keys(a).length)return a;// Check cache first (only on server-side for RSC optimization)
+if(themeCache.shouldCache()){var c=themeCache.getResolution(a,b);if(null!==c)return c}/**
+   * Recursively resolves theme variables within an object or array.
+   * It tracks visited objects to prevent infinite recursion caused by circular references.
+   * This function implements a "smart merge" to preserve object/array identity for unchanged parts.
+   * @param currentObj The current object or array being processed in the recursion.
+   * @param visited A Set to keep track of objects that have already been visited to detect circular references.
+   * @returns The processed object/array with theme variables resolved, or the original `currentObj`
+   * if no changes were made to it or its direct children (excluding deeper nested changes).
+   */var d=function resolveRecursively(a,c){// Base cases for non-objects/null, or already visited objects (circular reference)
+if(null===a||"object"!==_typeof(a))return a;if(c.has(a))return a;// Handle Arrays
+if(c.add(a),Array.isArray(a)){for(var e=a,f=!1,g=0;g<a.length;g++){var h=a[g],j=d(h,c);j===h?f&&(e[g]=h):(!f&&(e=[...a],f=!0),e[g]=j)}return e}// Handle Plain Objects (only process objects created with {})
+var k=a,l=!1,m=function _loop(){// Ensure it's an own property
+var e=a[n],f=e;if("function"==typeof e||"object"===_typeof(e)&&null!==e&&!Array.isArray(e)&&Object.getPrototypeOf(e)!==Object.prototype||// Exclude plain objects and arrays
+"object"!==_typeof(e)&&"string"!=typeof e)f=e;else if("string"==typeof e&&e.includes("theme.")){var g=e,h=!1,i=themeCache.getThemeRegex();// Use cached regex instance
+g=g.replace(i,function(a,c){// Check path lookup cache first
+var d=themeCache.getPathLookup(b,c);return null===d&&(d=getValueByPath(b,c),themeCache.setPathLookup(b,c,d)),void 0!==d&&null!==d?(h=!0,"object"===_typeof(d)&&!Array.isArray(d)&&"default"in d?d["default"]:d):a}),f=h&&g!==e?g:e}else"object"===_typeof(e)&&null!==e&&(// Recursively process nested objects or arrays
+f=d(e,c));f===e?l&&(k[n]=e):(!l&&(k=_objectSpread({},a),l=!0),k[n]=f)};for(var n in a)m();return k},e=d(a,new Set);// Perform the resolution
+// Cache the result (only on server-side)
+return themeCache.shouldCache()&&themeCache.setResolution(a,b,e),e};// Export cache instance for testing and monitoring
+export{themeCache as ThemeResolverCache};

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.2.10",
+  "version": "0.2.12",
   "type": "module",
   "main": "./dist/main.js",
   "types": "./dist/main.d.ts",
@@ -53,10 +53,10 @@
     "babel-plugin-module-resolver": "^5.0.2",
     "babel-preset-minify": "^0.5.2",
     "eslint": "^9.35.0",
-    "eslint-plugin-jsdoc": "^54.7.0",
+    "eslint-plugin-jsdoc": "^55.4.0",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-unused-imports": "^4.2.0",
-    "next": "^15.5.2",
+    "next": "^15.5.3",
     "prettier": "^3.6.2",
     "react-dom": "^19.1.1",
     "tsc-alias": "^1.8.16",