@meonode/ui 0.1.17 → 0.1.19

package/README.md

@@ -161,98 +161,268 @@ const Dashboard = Component(() =>
 );
 ```
 
+### Material UI Integration
+
+```shell
+yarn add @meonode/mui @mui/material
+```
+
+```ts
+import { Button, TextField } from '@meonode/mui';
+
+const MuiLoginForm = Component(() =>
+  Div({
+    maxWidth: '400px',
+    margin: '0 auto',
+    children: [
+      TextField({
+        label: 'Email',
+        fullWidth: true,
+        margin: 'normal'
+      }),
+      TextField({
+        label: 'Password',
+        type: 'password',
+        fullWidth: true,
+        margin: 'normal'
+      }),
+      Button({
+        variant: 'contained',
+        color: 'primary',
+        children: 'Sign In'
+      })
+    ]
+  })
+);
+```
+
 ### With Conditional Children That Contains Hook
 
 ```ts
 'use client'
 /**
- * This file demonstrates integration between React hooks and BaseNode components
- * using the @meonode/ui library for declarative UI construction.
- * It explores various rendering patterns, Higher-Order Component (HOC) usage,
- * and theme propagation with @meonode/ui components.
+ * This file showcases the integration of React hooks with @meonode/ui components
+ * for building declarative user interfaces. It demonstrates different rendering
+ * approaches, the use of Higher-Order Components (HOCs), and how theme context
+ * is managed and propagated within the @meonode/ui component tree.
  */
-import { Component, Column, Row, Div, P, Node } from '@meonode/ui' // Theme type is not explicitly imported or used as a prop type in this file's components.
-import { useState, useEffect } from 'react'
-import { CssBaseline, TextField } from '@meonode/mui'
+import { Component, Column, Row, P, Node, Button, Theme, Center, NodeInstance } from '@meonode/ui'
+import { useState, useEffect, ReactElement, ReactNode } from 'react'
+import { CssBaseline, FormControlLabel, TextField } from '@meonode/mui'
+import { Switch as MUISwitch } from '@mui/material'
+import { styled } from '@mui/material'
+
+const MaterialUISwitch = styled(MUISwitch)(({ theme }) => ({
+  width: 62,
+  height: 34,
+  padding: 7,
+  '& .MuiSwitch-switchBase': {
+    margin: 1,
+    padding: 0,
+    transform: 'translateX(6px)',
+    '&.Mui-checked': {
+      color: '#fff',
+      transform: 'translateX(22px)',
+      '& .MuiSwitch-thumb:before': {
+        backgroundImage: `url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" height="20" width="20" viewBox="0 0 20 20"><path fill="${encodeURIComponent(
+          '#fff',
+        )}" d="M4.2 2.5l-.7 1.8-1.8.7 1.8.7.7 1.8.6-1.8L6.7 5l-1.9-.7-.6-1.8zm15 8.3a6.7 6.7 0 11-6.6-6.6 5.8 5.8 0 006.6 6.6z"/></svg>')`,
+      },
+      '& + .MuiSwitch-track': {
+        opacity: 1,
+        backgroundColor: '#aab4be',
+        ...theme.applyStyles('dark', {
+          backgroundColor: '#8796A5',
+        }),
+      },
+    },
+  },
+  '& .MuiSwitch-thumb': {
+    backgroundColor: '#001e3c',
+    width: 32,
+    height: 32,
+    '&::before': {
+      content: "''",
+      position: 'absolute',
+      width: '100%',
+      height: '100%',
+      left: 0,
+      top: 0,
+      backgroundRepeat: 'no-repeat',
+      backgroundPosition: 'center',
+      backgroundImage: `url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" height="20" width="20" viewBox="0 0 20 20"><path fill="${encodeURIComponent(
+        '#fff',
+      )}" d="M9.305 1.667V3.75h1.389V1.667h-1.39zm-4.707 1.95l-.982.982L5.09 6.072l.982-.982-1.473-1.473zm10.802 0L13.927 5.09l.982.982 1.473-1.473-.982-.982zM10 5.139a4.872 4.872 0 00-4.862 4.86A4.872 4.872 0 0010 14.862 4.872 4.872 0 0014.86 10 4.872 4.872 0 0010 5.139zm0 1.389A3.462 3.462 0 0113.471 10a3.462 3.462 0 01-3.473 3.472A3.462 3.462 0 016.527 10 3.462 3.462 0 0110 6.528zM1.665 9.305v1.39h2.083v-1.39H1.666zm14.583 0v1.39h2.084v-1.39h-2.084zM5.09 13.928L3.616 15.4l.982.982 1.473-1.473-.982-.982zm9.82 0l-.982.982 1.473 1.473.982-.982-1.473-1.473zM9.305 16.25v2.083h1.389V16.25h-1.39z"/></svg>')`,
+    },
+    ...theme.applyStyles('dark', {
+      backgroundColor: '#003892',
+    }),
+  },
+  '& .MuiSwitch-track': {
+    opacity: 1,
+    backgroundColor: '#aab4be',
+    borderRadius: 20 / 2,
+    ...theme.applyStyles('dark', {
+      backgroundColor: '#8796A5',
+    }),
+  },
+}))
 
 /**
- * Global theme configuration.
- * Contains color palette definitions used by @meonode/ui components
- * when they resolve theme strings from context.
- * This can be extracted to a separate theme file for larger applications.
+ * Defines the color palette for the light theme.
+ * These color values are used by @meonode/ui components when they encounter
+ * theme string references (e.g., 'theme.primary') and the current theme mode is 'light'.
+ * In a larger application, this theme object would typically reside in a dedicated theme file.
  */
-const theme = {
-  background: { primary: 'lightgreen', secondary: 'lightyellow' },
+const lightTheme: Theme = {
+  mode: 'light',
+  colors: {
+    primary: '#2563eb',
+    secondary: '#64748b',
+    accent: '#10b981',
+    background: '#ffffff',
+    foreground: '#0f172a',
+    border: '#e2e8f0',
+    muted: '#f8fafc',
+    success: '#16a34a',
+    warning: '#eab308',
+    danger: '#dc2626',
+  },
 }
 
 /**
- * The page's main logic is defined as a function (which may use React hooks).
- * This function is wrapped in the `Component` HOC from @meonode/ui.
- * The HOC standardizes it as a React component, ensuring it returns a ReactNode.
- * This makes the component compatible with React's rendering process,
- * supporting both client-side and server-side rendering.
+ * Defines the color palette for the dark theme.
+ * Similar to the light theme, these colors are used by @meonode/ui components
+ * when resolving theme string references, but specifically when the current theme
+ * mode is 'dark'.
+ */
+const darkTheme: Theme = {
+  mode: 'dark',
+  colors: {
+    primary: '#3b82f6',
+    secondary: '#94a3b8',
+    accent: '#34d399',
+    background: '#0f172a',
+    foreground: '#f8fafc',
+    border: '#334155',
+    muted: '#1e293b',
+    success: '#22c55e',
+    warning: '#facc15',
+    danger: '#ef4444',
+  },
+}
+
+/**
+ * The main page component, implemented as a functional component using React hooks.
+ * It manages the theme mode state and the visibility of additional content.
+ *
+ * This function is wrapped by the `Component` HOC from `@meonode/ui`. The `Component`
+ * HOC transforms the function into a standard React component that returns a `ReactNode`,
+ * making it compatible with React's rendering lifecycle and enabling SSR/CSR.
  */
 export default Component(() => {
   // State hook to control the visibility of additional content sections.
   const [showMore, setShowDetails] = useState(false) // 'showMore' controls visibility, 'setShowDetails' is the updater.
+  const [mode, setMode] = useState<'dark' | 'light'>('light')
+  const theme = mode === 'dark' ? darkTheme : lightTheme
 
   /**
-   * The main layout is structured as a Column.
-   * It includes:
-   * - A header row with a button to toggle the visibility of additional content.
-   * - A series of examples demonstrating different ways to render detail components,
+   * The root of the UI tree is a `Column` component from `@meonode/ui`.
+   * This `Column` sets the theme context for its children.
+   * Its children include:
+   * - A theme toggle switch using MUI components wrapped in `@meonode/ui`'s `Node`.
+   * - A button to toggle the visibility of the detail sections.
+   * - Various examples demonstrating how to render components that return either
+   *   `@meonode/ui` `Node` instances or `ReactNode`s, illustrating theme propagation
    *   both unconditionally and conditionally, highlighting theme propagation.
    */
   return Column({
-    theme, // Provide the global theme to the Column and its descendants via React context.
+    theme: theme.colors,
     padding: 20,
     gap: 15,
+    minHeight: '100vh',
+    backgroundColor: 'theme.background',
+    color: 'theme.foreground',
     children: [
-      CssBaseline, // Applies baseline MUI styles.
-      // Interactive header section for toggling more content.
-      Row({
-        gap: 10,
-        children: [
-          Div({
-            onClick: () => setShowDetails(prev => !prev), // Click handler to toggle the 'showMore' state.
-            cursor: 'pointer', // Visual cue for clickability.
-            userSelect: 'none', // Prevents text selection on the button.
-            padding: '10px 20px',
-            backgroundColor: 'theme.background.primary', // Background color sourced from the theme context.
-            borderRadius: 5,
-            fontWeight: 'bold',
-            children: showMore ? 'Hide' : 'Show More', // Dynamically sets button text based on 'showMore' state.
-          }),
-        ],
+      // Theme toggle switch using MUI components wrapped with @meonode/ui's Node HOC.
+      Center({
+        children: FormControlLabel({
+          control: Node(MaterialUISwitch).render() as ReactElement,
+          alignItems: 'center',
+          label: mode === 'dark' ? 'Dark Mode' : 'Light Mode',
+          labelPlacement: 'start',
+          checked: mode === 'dark',
+          onChange: () => setMode(prev => (prev === 'dark' ? 'light' : 'dark')),
+        }),
+      }),
+      // Button to toggle the visibility of the detail sections.
+      Button(showMore ? 'Hide' : 'Show More', {
+        onClick: () => setShowDetails(prev => !prev), // Click handler to toggle the 'showMore' state.
+        cursor: 'pointer', // Visual cue for clickability.
+        userSelect: 'none', // Prevents text selection on the button.
+        padding: '10px 20px',
+        backgroundColor: 'theme.accent', // Background color sourced from the theme context.
+        borderRadius: 5,
+        fontWeight: 'bold',
+        color: 'white',
       }),
+      CssBaseline, // Applies baseline Material UI styles for consistent rendering.
 
       /**
-       * Unconditional rendering examples:
-       * Demonstrates rendering DetailComponent (returns a @meonode/ui Node instance) and
-       * ReturnRenderedDetailComponent (returns a ReactNode), and usage of the Node HOC.
-       * Pay attention to how theme is (or isn't) propagated to these components.
+       * --- Unconditional Rendering Examples ---
+       * These examples demonstrate rendering components that return either a
+       * `@meonode/ui` `Node` instance (`DetailComponent`) or a `ReactNode`
+       * (`ReturnRenderedDetailComponent`), and how the `Node` HOC affects this.
+       * Observe how theme context is propagated (or not) in each case.
        */
-      DetailComponent({ info: 'Here are some details 1!' }), // Renders DetailComponent; its internal Row sources theme from parent Column's context.
-      DetailComponent({ info: 'Here are some details 2!' }).render(), // Renders DetailComponent (invoking .render()); its internal Row sources theme from parent Column's context.
-      // Node(DetailComponent, { info: 'Here are some details 3!' }), // ❌ Fails: Node HOC expects its first argument (a component function) to return ReactNode. DetailComponent returns a @meonode/ui Node instance.
+      // 1. Rendering a component that returns a @meonode/ui Node instance directly.
+      //    The internal Row component correctly receives theme context from the parent Column.
+      DetailComponent({ info: 'Detail 1 (Node instance)' }),
+
+      // 2. Rendering a component that returns a @meonode/ui Node instance, then calling .render().
+      //    The internal Row component also correctly receives theme context.
+      DetailComponent({ info: 'Detail 2 (Node instance + .render())' }).render(),
+
+      // 3. Attempting to wrap a component returning a Node instance with Node HOC.
+      //    ❌ Fails: The Node HOC expects the wrapped function to return a ReactNode, not a @meonode/ui Node instance.
+      // Node(DetailComponent, { info: 'Detail 3 (Node HOC on Node instance)' }),
+
+      // 4. Rendering a component that explicitly returns a ReactNode (.render() is called internally).
+      //    The internal Row component correctly receives theme context from the parent Column.
+      ReturnRenderedDetailComponent({ info: 'Detail 4 (ReactNode)' }),
+
+      // 5. Wrapping a component returning ReactNode with Node HOC.
+      //    Renders successfully. However, the Node HOC does NOT propagate theme context to the wrapped component's children.
+      Node(ReturnRenderedDetailComponent, { info: 'Detail 5 (Node HOC on ReactNode)' }),
 
-      ReturnRenderedDetailComponent({ info: 'Here are some details 4!' }), // Renders ReturnRenderedDetailComponent; its internal Row inherits theme from parent Column's context.
-      Node(ReturnRenderedDetailComponent, { info: 'Here are some details 5!' }), // Node HOC with a function returning ReactNode: Renders. Theme from Column is NOT propagated by Node HOC to the internal Row.
-      Node(ReturnRenderedDetailComponent, { info: 'Here are some details 6!' }).render(), // Node HOC (then .render()): Renders. Theme from Column is NOT propagated by Node HOC to the internal Row.
-      // Node(DetailComponent, { info: 'Here are some details 7!' }).render(), // ❌ Fails: Same reason as above; Node HOC expects a function returning ReactNode.
+      // 6. Wrapping a component returning ReactNode with Node HOC, then calling .render().
+      //    Renders successfully. Theme context is NOT propagated by the Node HOC.
+      Node(ReturnRenderedDetailComponent, { info: 'Detail 6 (Node HOC on ReactNode + .render())' }).render(),
 
       /**
        * Conditional rendering examples (shown when 'showMore' is true):
        * These demonstrate various wrapping techniques (inline functions, Component HOC)
        * and their effect on rendering and theme propagation for both types of detail components.
        */
-      showMore && (() => DetailComponent({ info: 'Here are some details 8!' })), // Method 1 (inline function wrapper): Renders DetailComponent; its internal Row sources theme from context.
-      showMore && (() => DetailComponent({ info: 'Here are some details 9!' }).render()), // Method 2 (inline function wrapper + .render()): Renders DetailComponent; its internal Row sources theme from context.
-      showMore && Component(() => DetailComponent({ info: 'Here are some details 10!' })), // Method 3 (Component HOC wrapper): Renders DetailComponent; its internal Row sources theme from context.
+      // 7. Conditional rendering of a component returning a Node instance using an inline function wrapper.
+      //    Renders successfully when `showMore` is true. The internal Row receives theme context.
+      showMore && (() => DetailComponent({ info: 'Detail 7 (Conditional inline function + Node instance)' })),
 
-      showMore && (() => ReturnRenderedDetailComponent({ info: 'Here are some details 12!' })), // Method 4 (inline function wrapper): Renders ReturnRenderedDetailComponent; internal Row inherits theme from Column's context.
-      showMore && Component(() => ReturnRenderedDetailComponent({ info: 'Here are some details 13!' })), // Method 5 (Component HOC wrapper): Renders ReturnRenderedDetailComponent; internal Row inherits theme from Column's context.
-      showMore && Node(ReturnRenderedDetailComponent, { info: 'Here are some details 14!' }).render(), // Method 6 (Node HOC + .render()): Renders. Theme from Column is NOT propagated by Node HOC to internal Row.
+      // 8. Conditional rendering of a component returning a Node instance using an inline function wrapper, then calling .render().
+      //    Renders successfully when `showMore` is true. The internal Row receives theme context.
+      showMore && (() => DetailComponent({ info: 'Detail 8 (Conditional inline function + Node instance + .render())' }).render()),
+
+      // 9. Conditional rendering of a component returning a Node instance using the Component HOC wrapper.
+      //    Renders successfully when `showMore` is true. The internal Row receives theme context.
+      showMore && Component(() => DetailComponent({ info: 'Detail 9 (Conditional Component HOC + Node instance)' })),
+
+      // 10. Conditional rendering of a component returning ReactNode using an inline function wrapper.
+      //     Renders successfully when `showMore` is true. The internal Row receives theme context.
+      showMore && (() => ReturnRenderedDetailComponent({ info: 'Detail 10 (Conditional inline function + ReactNode)' })),
+
+      // 11. Conditional rendering of a component returning ReactNode using the Component HOC wrapper.
+      //     Renders successfully when `showMore` is true. The internal Row receives theme context.
+      showMore && Component(() => ReturnRenderedDetailComponent({ info: 'Detail 11 (Conditional Component HOC + ReactNode)' })),
       // showMore && ReturnRenderedDetailComponent({ info: 'Here are some details 15!' }), // ❌ Fails: Direct call to a component function using hooks (ReturnRenderedDetailComponent) inside render logic without a React-aware wrapper. This can violate Rules of Hooks.
     ],
   })
@@ -261,15 +431,17 @@ export default Component(() => {
 /**
  * A component that displays a styled detail section.
  * It uses `useEffect` for lifecycle logging. The internal `Row` component
- * sources its theme from the React context established by an ancestor
- * @meonode/ui component (e.g., the main Column in this page).
- * This component returns a @meonode/ui `Row` Node instance.
+ * sources its theme from the React context provided by an ancestor `@meonode/ui`
+ * component (like the main `Column` in this page).
  *
+ * This component returns a @meonode/ui `Row` Node instance.
+ * This type of component is suitable for direct inclusion as a child within other
+ * `@meonode/ui` components that expect `Node` instances or arrays of `Node` instances.
  * @param {object} props - Component properties.
  * @param {string} props.info - Text content to display in the detail section.
- * @returns {import('@meonode/ui').Node} A @meonode/ui Row Node instance.
+ * @returns {NodeInstance} A @meonode/ui Row Node instance.
  */
-const DetailComponent = ({ info }: { info: string }) => {
+const DetailComponent = ({ info }: { info: string }): NodeInstance => {
   // useEffect hook for logging component mount and unmount phases (for debugging).
   useEffect(() => {
     console.log('DetailComponent mounted:', info) // Example mount log
@@ -278,31 +450,34 @@ const DetailComponent = ({ info }: { info: string }) => {
     }
   }, [info]) // Effect depends on 'info' prop.
 
-  // Returns a @meonode/ui Row component configured with props and children.
+  // Returns a @meonode/ui Row Node instance configured with props and children.
   // Its styling (e.g., backgroundColor) will resolve theme strings from React context.
   return Row({
+    alignItems: 'center',
     gap: 10,
     padding: 4,
-    border: '1px solid green',
+    border: '2px solid theme.accent',
     borderRadius: 6,
-    color: 'red',
-    backgroundColor: 'theme.background.secondary', // Background color sourced from theme in React context.
-    children: [P(info), TextField({ background: 'theme.background.primary' })],
+    backgroundColor: 'theme.warning', // Background color sourced from theme in React context.
+    color: 'theme.danger',
+    children: [P(info, { flex: 1, padding: '0 20px' }), TextField({ flex: 1, sx: { background: 'theme.primary' } })],
   })
 }
 
 /**
  * An alternative detail component implementation that explicitly calls `.render()`
  * to return a `ReactNode` (a rendered React element) directly.
- * This makes it compatible with wrappers like the `Node` HOC that expect a function returning `ReactNode`.
+ * This makes it compatible with standard React rendering patterns and wrappers
+ * like the `Node` HOC that specifically expect a function returning `ReactNode`.
  * It uses `useEffect` for lifecycle logging. The internal `Row` sources its
  * theme from React context.
  *
+ * This component returns a `ReactNode`.
  * @param {object} props - Component properties.
  * @param {string} props.info - Text content to display.
  * @returns {React.ReactNode} A rendered React element (the result of `Row(...).render()`).
  */
-const ReturnRenderedDetailComponent = ({ info }: { info: string }) => {
+const ReturnRenderedDetailComponent = ({ info }: { info: string }): ReactNode => {
   // useEffect hook for logging component mount and unmount phases (for debugging).
   useEffect(() => {
     console.log('ReturnRenderedDetailComponent mounted:', info) // Example mount log
@@ -315,52 +490,18 @@ const ReturnRenderedDetailComponent = ({ info }: { info: string }) => {
   // The Row itself will attempt to resolve theme strings (e.g., 'theme.background.secondary')
   // from the React context provided by an ancestor @meonode/ui component (like the main Column).
   return Row({
+    alignItems: 'center',
     gap: 10,
     padding: 4,
-    border: '1px solid green',
+    border: '2px solid theme.accent',
     borderRadius: 6,
-    color: 'red',
-    backgroundColor: 'theme.background.secondary', // Theme-aware background; relies on theme from React context.
-    children: [P(info), TextField({ background: 'theme.background.primary' })],
+    backgroundColor: 'theme.warning', // Theme-aware background; relies on theme from React context.
+    color: 'theme.danger',
+    children: [P(info, { flex: 1, padding: '0 20px' }), TextField({ flex: 1, sx: { background: 'theme.primary' } })],
   }).render() // Explicitly renders to ReactNode.
 }
 ```
 
-### Material UI Integration
-
-```shell
-yarn add @meonode/mui @mui/material
-```
-
-```ts
-import { Button, TextField } from '@meonode/mui';
-
-const MuiLoginForm = Component(() =>
-  Div({
-    maxWidth: '400px',
-    margin: '0 auto',
-    children: [
-      TextField({
-        label: 'Email',
-        fullWidth: true,
-        margin: 'normal'
-      }),
-      TextField({
-        label: 'Password',
-        type: 'password',
-        fullWidth: true,
-        margin: 'normal'
-      }),
-      Button({
-        variant: 'contained',
-        color: 'primary',
-        children: 'Sign In'
-      })
-    ]
-  })
-);
-```
-
 ## API Reference
 
 ### Core Functions

package/dist/core.node.d.ts

@@ -1,12 +1,12 @@
 import React, { type ReactNode } from 'react';
-import type { BaseNodeInstance, ComponentNode, NodeElement, NodeProps, Theme } from './node.type.js';
+import type { ComponentNode, NodeElement, NodeInstance, NodeProps, Theme } from './node.type.js';
 /**
  * Factory function to create a BaseNode instance.
  * @param element The React element type.
  * @param props The props for the node.
- * @returns BaseNodeInstance<E> - A new BaseNode instance.
+ * @returns NodeInstance<E> - A new BaseNode instance.
  */
-export declare function Node<E extends NodeElement>(element: E, props?: Partial<NodeProps<E>>): BaseNodeInstance<E>;
+export declare function Node<E extends NodeElement>(element: E, props?: Partial<NodeProps<E>>): NodeInstance<E>;
 /**
  * Higher-order component wrapper that converts BaseNode components into React components.
  * This wrapper ensures proper theme propagation and component rendering in the React ecosystem.
@@ -31,5 +31,5 @@ export declare function Node<E extends NodeElement>(element: E, props?: Partial<
  */
 export declare function Component<T extends Record<string, any> & {
     theme?: Theme;
-}>(component: (props: T) => ComponentNode): (props?: T) => string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | BaseNodeInstance<any> | (() => BaseNodeInstance<any> | ReactNode) | null | undefined;
+}>(component: (props: T) => ComponentNode): (props?: any) => string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | NodeInstance<any> | (() => NodeInstance<any> | ReactNode) | null | undefined;
 //# sourceMappingURL=core.node.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"core.node.d.ts","sourceRoot":"","sources":["../src/core.node.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAsG,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACjJ,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAyC,WAAW,EAAE,SAAS,EAAgB,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAyX5J;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,GAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAU9G;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,aAAa,IAEzG,QAAO,CAAW,8ZAmB3B"}
+{"version":3,"file":"core.node.d.ts","sourceRoot":"","sources":["../src/core.node.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAkF,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC7H,OAAO,KAAK,EAAE,aAAa,EAAyC,WAAW,EAAE,YAAY,EAAE,SAAS,EAAgB,KAAK,EAAE,MAAM,mBAAmB,CAAA;AA0bxJ;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,GAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAU1G;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,aAAa,IAEzG,QAAO,GAAQ,sZAmBxB"}

package/dist/core.node.js

@@ -1,4 +1,4 @@
-"use strict";var _excluded=["children","nodeTheme"],_excluded2=["children","key"];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 _classCallCheck(b,a){if(!(b instanceof a))throw new TypeError("Cannot call a class as a function")}function _defineProperties(a,b){for(var c,d=0;d<b.length;d++)c=b[d],c.enumerable=c.enumerable||!1,c.configurable=!0,"value"in c&&(c.writable=!0),Object.defineProperty(a,_toPropertyKey(c.key),c)}function _createClass(a,b,c){return b&&_defineProperties(a.prototype,b),c&&_defineProperties(a,c),Object.defineProperty(a,"prototype",{writable:!1}),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,{createElement,isValidElement}from"react";import{getComponentType,getCSSProps,getDOMProps,getElementTypeName,getValueByPath}from"./node.helper.js";import{isForwardRef,isMemo,isReactClassComponent,isValidElementType}from"./react-is.helper.js";/**
+"use strict";var _excluded=["children","nodeTheme","theme"],_excluded2=["children","key"];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 _classCallCheck(b,a){if(!(b instanceof a))throw new TypeError("Cannot call a class as a function")}function _defineProperties(a,b){for(var c,d=0;d<b.length;d++)c=b[d],c.enumerable=c.enumerable||!1,c.configurable=!0,"value"in c&&(c.writable=!0),Object.defineProperty(a,_toPropertyKey(c.key),c)}function _createClass(a,b,c){return b&&_defineProperties(a.prototype,b),c&&_defineProperties(a,c),Object.defineProperty(a,"prototype",{writable:!1}),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,{createElement,isValidElement}from"react";import{getComponentType,getCSSProps,getDOMProps,getElementTypeName,getValueByPath}from"./node.helper.js";import{isForwardRef,isMemo,isReactClassComponent,isValidElementType}from"./react-is.helper.js";import{createRoot}from"react-dom/client";/**
  * 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,7 +6,7 @@
  * - Child node processing and management
  * - Style processing with theme variables
  * @template E The type of React element or component this node represents
- */var BaseNode=/*#__PURE__*/function(){/** The underlying React element or component type that this node represents *//** Original props passed during construction, preserved for cloning/recreation *//** Processed props after theme resolution, style processing, and child normalization *//**
+ */var BaseNode=/*#__PURE__*/function(){/**
    * Creates a new BaseNode instance that wraps a React element.
    * Processes raw props by:
    * - Extracting and resolving theme-aware styles
@@ -14,28 +14,34 @@
    * - Normalizing children with theme inheritance
    * @param element The React element/component to wrap
    * @param rawProps Initial props including theme, styles, and children
-   */function BaseNode(a,b){var c=this;_classCallCheck(this,BaseNode),_defineProperty(this,"_normalizeChild",function(a){var b,d;if(!a)return a;var e=(null===(b=c.rawProps)||void 0===b?void 0:b.nodeTheme)||(null===(d=c.rawProps)||void 0===d?void 0:d.theme)||c.props.nodeTheme||c.props.theme;// For BaseNode instances, apply current theme if child has no theme
+   */function BaseNode(a){var b=this,c=1<arguments.length&&arguments[1]!==void 0?arguments[1]:{};_classCallCheck(this,BaseNode),_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
 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()}// For React.Component instances, wrap in BaseNode with theme if needed
 if(a instanceof React.Component)return a.props.nodeTheme||void 0===e?a.render():new BaseNode(a.render(),_objectSpread(_objectSpread({},a.props),{},{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=b;var d=b||{},e=d.children,f=d.nodeTheme,g=_objectWithoutProperties(d,_excluded),h=getCSSProps(g),i=this._resolveStyleWithTheme(h,f);// Process styles with theme variables
-i=0<Object.keys(i).length?i:{};// Extract non-style DOM props
-var j=getDOMProps(g),k=void 0;// Process children with theme inheritance
-if(e!==void 0&&null!==e)if(Array.isArray(e)){k=e.map(function(a,b){return c._processRawNode(a,f,b)})}else k=this._processRawNode(e,f);// Build final normalized props
-this.props=_objectSpread(_objectSpread({},j),{},{style:i,nodeTheme:f,children:k})}/**
-   * Resolves style properties by replacing theme path placeholders with actual theme values.
-   * Handles complex strings like '1px solid theme.background.primary' and iterative resolution.
-   * @param initialCssProps The initial CSS properties object.
+return a}),this.element=a,this.rawProps=c;// Destructure raw props into relevant parts
+var d=c.children,e=c.nodeTheme,f=c.theme,g=_objectWithoutProperties(c,_excluded),h=this._resolveObjWithTheme(g,e),i=getCSSProps(h),j=getDOMProps(h),k=void 0;// Resolve any theme variables in the remaining props
+// Extract style-related props that match valid CSS properties
+// Extract remaining props that are valid DOM attributes
+// Process children while maintaining theme inheritance
+// Combine processed props into final normalized form
+d&&(Array.isArray(d)?k=d.map(function(a,c){return b._processRawNode(a,e,c)}):k=this._processRawNode(d,e)),this.props=_objectSpread(_objectSpread({},j),{},{style:i,nodeTheme:e,children:k})}/**
+   * Resolves obj properties by replacing theme path placeholders with actual theme values.
+   * Handles complex strings like '1px solid theme.background.primary' and nested objects.
+   * @param obj The initial obj properties object.
    * @param theme The theme object to use for resolving paths.
    * @returns A new CSSProperties object with theme values resolved.
-   */return _createClass(BaseNode,[{key:"_resolveStyleWithTheme",value:function _resolveStyleWithTheme(a,b){var c;// If no theme is provided or there are no initial CSS props to process, return the initial props.
-if(!b||0===Object.keys(a).length)return a;var d=_objectSpread(_objectSpread({},null===(c=this.rawProps)||void 0===c?void 0:c.nodeTheme),b),e=_objectSpread({},a);// Merge nodeTheme from rawProps with theme
-for(var f in e)if(Object.prototype.hasOwnProperty.call(e,f)){var g=e[f];if("string"==typeof g&&g.includes("theme.")){var h=g;// Iteratively resolve theme references within the string
-h=h.replace(/theme\.([a-zA-Z0-9_.-]+)/g,function(a,b){var c=getValueByPath(d,b);// Use 'theme' passed to the function
-// Replace it if themeValue is found and is a string or number.
-// null is explicitly excluded to avoid 'null' string in output unless intended.
-return void 0!==c&&null!==c&&("string"==typeof c||"number"==typeof c)?c+"":a;// If themeValue is not a string or number or is undefined/null, keep the original placeholder
-}),e[f]=h}}return e}/**
+   */return _createClass(BaseNode,[{key:"_resolveObjWithTheme",value:function _resolveObjWithTheme(a,b){var c;// Return early if no theme or empty object
+if(!b||0===Object.keys(a).length)return a;// Merge raw nodeTheme with passed theme for resolution
+var d=_objectSpread(_objectSpread({},null===(c=this.rawProps)||void 0===c?void 0:c.nodeTheme),b),e=function resolveRecursively(a){var b={};// Process each property in the current object
+for(var c in a){var f=a[c];if(c.startsWith("_"))return a;// Handle string values containing theme references
+if("string"==typeof f&&f.includes("theme.")){var g=f;// Replace theme path placeholders with actual theme values
+g=g.replace(/theme\.([a-zA-Z0-9_.-]+)/g,function(a,b){var c=getValueByPath(d,b);// Convert the theme value to string if it exists and is a valid type
+return null!=c&&["string","number"].includes(_typeof(c))?c+"":a}),b[c]=g}// Recursively process nested objects (excluding arrays)
+else b[c]=f&&"object"===_typeof(f)?e(f):f}return b};/**
+     * Recursively resolves theme values in an object
+     * @param currentObj The current object level being processed
+     * @returns New object with resolved theme values
+     */return e(a)}/**
    * React component that renders the result of a function child, supporting theme propagation.
    *
    * This component is used to render children that are functions (i.e., `() => Children`).
@@ -48,11 +54,9 @@ return void 0!==c&&null!==c&&("string"==typeof c||"number"==typeof c)?c+"":a;//
    */},{key:"_functionRenderer",value:function _functionRenderer(a){var b=a.render,c=a.passedTheme,d=a.passedKey,e=a.processRawNode,f=b();// Call the user-provided render function to get the child.
 if(f instanceof React.Component){var g=f.render(),h=e(g,c);return h instanceof BaseNode?h.render():h}if(f instanceof BaseNode){var i,j=f;// If the returned BaseNode does not have its own theme, but a theme is provided,
 // re-create the node with the provided theme to ensure correct theme propagation.
-return void 0===(null===(i=j.rawProps)||void 0===i?void 0:i.nodeTheme)&&void 0!==c?new BaseNode(j.element,_objectSpread(_objectSpread({},j.rawProps||{}),{},{nodeTheme:c,theme:c,// Pass theme for consistency if used in rawProps
-key:d})).render():j.render();// If the node already has a theme or no theme is provided, render as-is.
+return void 0===(null===(i=j.rawProps)||void 0===i?void 0:i.nodeTheme)&&void 0!==c?new BaseNode(j.element,_objectSpread(_objectSpread({},j.rawProps||{}),{},{nodeTheme:c,theme:c,key:d})).render():j.render();// If the node already has a theme or no theme is provided, render as-is.
 }// Process the result if it's not a React.Component or BaseNode
-var k=e(f,c);if(k instanceof BaseNode){var l,m;if(((null===(l=k.rawProps)||void 0===l?void 0:l.theme)||(null===(m=k.rawProps)||void 0===m?void 0:m.nodeTheme))===void 0&&c!==void 0){var n,o,p;return new BaseNode(k.element,_objectSpread(_objectSpread({},k.rawProps),{},{nodeTheme:(null===(n=k.rawProps)||void 0===n?void 0:n.theme)||(null===(o=k.rawProps)||void 0===o?void 0:o.nodeTheme)||c,key:(null===(p=k.rawProps)||void 0===p?void 0:p.key)||d// Use an existing key or passed key
-})).render()}return k.render()}// If the result is not a BaseNode (e.g., JSX, string, etc.), return it directly.
+var k=e(f,c);if(k instanceof BaseNode){var l,m;if(((null===(l=k.rawProps)||void 0===l?void 0:l.theme)||(null===(m=k.rawProps)||void 0===m?void 0:m.nodeTheme))===void 0&&c!==void 0){var n,o,p;return new BaseNode(k.element,_objectSpread(_objectSpread({},k.rawProps),{},{nodeTheme:(null===(n=k.rawProps)||void 0===n?void 0:n.theme)||(null===(o=k.rawProps)||void 0===o?void 0:o.nodeTheme)||c,key:(null===(p=k.rawProps)||void 0===p?void 0:p.key)||d})).render()}return k.render()}// If the result is not a BaseNode (e.g., JSX, string, etc.), return it directly.
 // Note: Non-BaseNode results will not automatically receive the theme.
 return f}/**
    * Processes a single raw child element, converting it into a ProcessedChild.
@@ -119,11 +123,11 @@ var h=_objectSpread(_objectSpread({},e),{},{// Cast otherProps
 key:d// This is the key of the current BaseNode itself
 });// Prepare props for React.createElement
 // Delete the key `nodeTheme` as it's not a valid DOM/React prop for the element
-return delete h.nodeTheme,createElement(this.element,h,f)}}])}();/**
+return delete h.nodeTheme,createElement(this.element,h,f)}},{key:"_ensurePortalInfrastructure",value:function _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}},{key:"toPortal",value:function 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.
  * @param element The React element type.
  * @param props The props for the node.
- * @returns BaseNodeInstance<E> - A new BaseNode instance.
+ * @returns NodeInstance<E> - A new BaseNode instance.
  */export function Node(a){var b=1<arguments.length&&void 0!==arguments[1]?arguments[1]:{},c=_objectSpread({},b);// Ensure we are working with a mutable copy
 // 'theme' prop itself is not directly used by BaseNode after this, nodeTheme is used.
 // We can keep `theme` in rawProps if needed for cloning or inspection.
@@ -149,7 +153,7 @@ return c.theme&&void 0===c.nodeTheme&&(c.nodeTheme=c.theme),new BaseNode(a,c)}/*
  * })
  * ```
  */export function Component(a){// Create a wrapper component that handles theme and rendering
-return function(){var b=0<arguments.length&&arguments[0]!==void 0?arguments[0]:{},c=a(_objectSpread({},b));// Execute wrapped component
+return function(){var b=0<arguments.length&&arguments[0]!==void 0?arguments[0]:{},c=a(b);// Execute wrapped component
 // Handle BaseNode results - requires special processing
 if(c instanceof BaseNode){var d,e;// Theme merging: Check if we need to handle theme inheritance
 if(!!(null!==b&&void 0!==b&&b.theme||null!==b&&void 0!==b&&b.nodeTheme)||!!(null!==(d=c.rawProps)&&void 0!==d&&d.theme||null!==(e=c.rawProps)&&void 0!==e&&e.nodeTheme)){var f,g;return new BaseNode(c.element,_objectSpread(_objectSpread({},c.rawProps),{},{// Theme priority: props.theme > rawProps.theme > rawProps.nodeTheme