@meonode/ui 0.1.13 → 0.1.14

package/README.md

@@ -164,129 +164,166 @@ const Dashboard = Component(() =>
 ### With Conditional Children That Contains Hook
 
 ```ts
-// Wraps a hook-capable component into a BaseNode-compatible Client Component
 'use client'
 /**
  * This file demonstrates integration between React hooks and BaseNode components
- * using the @meonode/ui library for declarative UI construction
+ * 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.
  */
-import { Component, Column, Row, Div, P, Node } from '@meonode/ui'
+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'
 
 /**
- * Global theme configuration
- * Contains color palette definitions used throughout components
- * Can be extracted to separate theme file if needed
+ * 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.
  */
 const theme = {
   background: { primary: 'lightgreen', secondary: 'lightyellow' },
 }
 
 /**
- * Main page component wrapped in Component HOC to enable client-side features
- * Demonstrates conditional rendering and component composition patterns
+ * 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.
  */
 export default Component(() => {
-  // Controls visibility of detail sections
-  const [showDetails, setShowDetails] = useState(false)
+  // State hook to control the visibility of additional content sections.
+  const [showMore, setShowDetails] = useState(false) // 'showMore' controls visibility, 'setShowDetails' is the updater.
 
   /**
-   * Main layout structured as a Column with:
-   * - Header row containing toggle button
-   * - Conditional detail sections using different rendering approaches
+   * 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,
+   *   both unconditionally and conditionally, highlighting theme propagation.
    */
   return Column({
-    theme,
+    theme, // Provide the global theme to the Column and its descendants via React context.
     padding: 20,
     gap: 15,
     children: [
-      // Interactive header section
+      CssBaseline, // Applies baseline MUI styles.
+      // Interactive header section for toggling more content.
       Row({
         gap: 10,
         children: [
           Div({
-            onClick: () => setShowDetails(prev => !prev), // Toggle detail visibility
-            cursor: 'pointer',
-            userSelect: 'none', // Prevent text selection
+            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', // Themed background
+            backgroundColor: 'theme.background.primary', // Background color sourced from the theme context.
             borderRadius: 5,
             fontWeight: 'bold',
-            children: showDetails ? 'Hide Details' : 'Show Details',
+            children: showMore ? 'Hide' : 'Show More', // Dynamically sets button text based on 'showMore' state.
           }),
         ],
       }),
 
       /**
-       * Multiple approaches to conditional detail rendering:
-       * 1. Direct function wrapping
-       * 2. Component HOC wrapping
-       * 3. Node with ReturnRenderedDetailComponent
-       * 4. Non-working example with raw Node usage
+       * 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.
        */
-      showDetails && (() => DetailComponent({ info: 'Here are some details 1!' })), // Method 1
-      showDetails && Component(() => DetailComponent({ info: 'Here are some details 2!' })), // Method 2
-      showDetails && Node(ReturnRenderedDetailComponent, { info: 'Here are some details 2!' }).render(), // Method 3
+      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.
+
+      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.
 
-      // Fails because DetailComponent returns Node instance instead of ReactNode
-      showDetails && Node(DetailComponent, { info: 'Here are some details 2!' }).render(), // ❌ Invalid
+      /**
+       * 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.
+
+      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.
+      // 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.
     ],
   })
 })
 
 /**
- * Displays a styled detail section with lifecycle logging
- * @param {Object} props - Component properties
- * @param {string} props.info - Text content to display
- * @returns {Node} Rendered Div Node instance
+ * 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.
+ *
+ * @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.
  */
 const DetailComponent = ({ info }: { info: string }) => {
-  // Log component lifecycle for debugging
+  // useEffect hook for logging component mount and unmount phases (for debugging).
   useEffect(() => {
-    console.log('DetailComponent mounted')
+    console.log('DetailComponent mounted:', info) // Example mount log
     return () => {
-      console.log('DetailComponent unmounted')
+      console.log('DetailComponent unmounted:', info) // Example unmount log
     }
-  }, [])
+  }, [info]) // Effect depends on 'info' prop.
 
-  // Themed container with text content
-  return Div({
-    padding: 15,
+  // Returns a @meonode/ui Row component configured with props and children.
+  // Its styling (e.g., backgroundColor) will resolve theme strings from React context.
+  return Row({
+    gap: 10,
+    padding: 4,
     border: '1px solid green',
     borderRadius: 6,
     color: 'red',
-    backgroundColor: 'theme.background.secondary', // Theme-aware background
-    children: P(info),
+    backgroundColor: 'theme.background.secondary', // Background color sourced from theme in React context.
+    children: [P(info), TextField({ background: 'theme.background.primary' })],
   })
 }
 
 /**
- * Alternative implementation that explicitly returns rendered content
- * Functionally identical to DetailComponent but compatible with Node wrapper
- * @param {Object} props - Component properties
- * @param {string} props.info - Text content to display
- * @returns {ReactNode} Rendered React element
+ * 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`.
+ * It uses `useEffect` for lifecycle logging. The internal `Row` sources its
+ * theme from React context.
+ *
+ * @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 }) => {
-  // Log component lifecycle for debugging
+  // useEffect hook for logging component mount and unmount phases (for debugging).
   useEffect(() => {
-    console.log('DetailComponent mounted')
+    console.log('ReturnRenderedDetailComponent mounted:', info) // Example mount log
     return () => {
-      console.log('DetailComponent unmounted')
+      console.log('ReturnRenderedDetailComponent unmounted:', info) // Example unmount log
     }
-  }, [])
-
-  // Themed container with text content
-  return Div({
-    padding: 15,
+  }, [info]) // Effect depends on 'info' prop.
+
+  // Constructs a @meonode/ui Row and immediately calls .render() on it.
+  // 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({
+    gap: 10,
+    padding: 4,
     border: '1px solid green',
     borderRadius: 6,
     color: 'red',
-    backgroundColor: 'theme.background.secondary', // Theme-aware background
-    children: P(info),
-  }).render()
+    backgroundColor: 'theme.background.secondary', // Theme-aware background; relies on theme from React context.
+    children: [P(info), TextField({ background: 'theme.background.primary' })],
+  }).render() // Explicitly renders to ReactNode.
 }
-
 ```
 
 ### Material UI Integration

package/dist/core.node.d.ts

@@ -20,6 +20,7 @@ export declare function Node<E extends NodeElement>(element: E, props?: Partial<
  * @param component Component function that returns a BaseNode or ReactNode
  * @returns A React function component that handles BaseNode conversion and theme propagation
  * @example
+ * ```ts
  * // Basic usage
  * const Button = Component((props) => {
  *   return Node('button', {
@@ -27,6 +28,7 @@ export declare function Node<E extends NodeElement>(element: E, props?: Partial<
  *     theme: { color: 'blue' }
  *   })
  * })
+ * ```
  */
 export declare function Component<T extends Record<string, any> & {
     theme?: Theme;

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,EAAwC,WAAW,EAAE,SAAS,EAAqB,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAoXjJ;;;;;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;;;;;;;;;;;;;;;;;;;;GAoBG;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,gBAAgB,CAAC,GAAG,CAAC,GAAG,SAAS,IAE7H,QAAO,CAAW,kXAmB3B"}
+{"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,EAAwC,WAAW,EAAE,SAAS,EAAqB,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAoXjJ;;;;;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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,gBAAgB,CAAC,GAAG,CAAC,GAAG,SAAS,IAE7H,QAAO,CAAW,kXAmB3B"}

package/dist/core.node.js

@@ -14,7 +14,7 @@ if(!isValidElementType(a)){var g=getComponentType(a);throw new Error("Invalid el
 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);// Extract children and theme
 // 1. Resolve styles and DOM props for this node
 i=0<Object.keys(i).length?i:{};var j=getDOMProps(g),k=void 0;// Extract DOM-related props
-// 2. Process rawNoderen into BaseNode instances or primitives, passing down currentTheme
+// 2. Process rawNoderen into BaseNode instances or primitives, passing down the currentTheme
 if(e!==void 0&&null!==e)if(Array.isArray(e)){k=e.map(function(a,b){return c._processRawNode(a,f,b)}// Process each child, passing index
 )}else// For a single child, no index is passed; existing key logic in _processRawNode will apply
 k=this._processRawNode(e,f);// 3. Construct final this.props
@@ -29,9 +29,9 @@ this.props=_objectSpread(_objectSpread({},j),{},{style:i,nodeTheme:f,children:k/
 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 if themeValue is found and is a string or number.
+// 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/number, or is undefined/null, keep the original placeholder
+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}/**
    * React component that renders the result of a function child, supporting theme propagation.
    *
@@ -48,7 +48,7 @@ if(f instanceof React.Component){var g=f.render(),h=e(g,c);return h instanceof B
 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.
 }// 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 existing key or passed key
+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.
 // Note: Non-BaseNode results will not automatically receive the theme.
 return f}/**
@@ -78,16 +78,16 @@ var j=e(this._functionRenderer,void 0);// Generate key for function renderer
 return new BaseNode(this._functionRenderer,{processRawNode:this._processRawNode.bind(this),render:a,passedTheme:b,key:j// Assign the generated key
 })}// Case 4: Child is a React Element (JSX element like <div> or <MyComponent>)
 if(isValidElement(a)){var k,l=_objectSpread({},a.props);// Extract and merge props from the JSX element, flattening style props
-l=_objectSpread(_objectSpread({},l.style),l),delete l.style;// Remove original style object after merging
-// Handle theme: prefer nodeTheme from child's props, fallback to parent theme
-var m=(null===(k=l)||void 0===k?void 0:k.nodeTheme)||b,n=e(a.type,a.key);// For array children without keys, generate stable key from element type and index
-// Create new BaseNode instance with processed props and theme
+l=_objectSpread(_objectSpread({},l.style),l),delete l.style;// Remove the original style object after merging
+// Handle theme: prefer nodeTheme from child's props, fallback to the parent theme
+var m=(null===(k=l)||void 0===k?void 0:k.nodeTheme)||b,n=e(a.type,a.key);// For array children without keys, generate a stable key from element type and index
+// Create a new BaseNode instance with processed props and theme
 return new BaseNode(a.type,_objectSpread(_objectSpread({},l),{},{nodeTheme:m,key:n// Assign the generated key
 }))}// Case 5: Child is an ElementType (string tag, class component, Memo/ForwardRef)
 if(isReactClassComponent(a)||"object"===d&&(isMemo(a)||isForwardRef(a))){// ElementTypes don't have an intrinsic key from the rawNode itself.
 var o=e(a,void 0);return new BaseNode(a,{nodeTheme:b,// Apply parent theme
 key:o})}// Case 6: Handle instances of React.Component
-if(a instanceof React.Component){var p=a.render();// Recursively process the rendered element with parent theme and index if available
+if(a instanceof React.Component){var p=a.render();// Recursively process the rendered element with a parent theme and index if available
 return this._processRawNode(p,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.
@@ -111,12 +111,12 @@ return a}/**
    */function render(){if(!isValidElementType(this.element)){var a=getComponentType(this.element);throw new Error("Invalid element type: ".concat(a," provided!"))}var b=this.props,c=b.children,d=b.key,e=_objectWithoutProperties(b,_excluded2),f=void 0;// Extract children and key
 // More accurate type
 if(void 0!==c&&null!==c)if(!Array.isArray(c))f=this._normalizeChild(c);else if(0<c.length){var g=c.map(this._normalizeChild);// Normalize each child in the array
-// Check if all children are null/undefined (e.g. conditional rendering resulted in nothing)
+// Check if all children are null/undefined (e.g., conditional rendering resulted in nothing)
 f=g.every(function(a){return null===a||void 0===a})?void 0:g}else f=void 0;// Prepare props for React.createElement
 var h=_objectSpread(_objectSpread({},e),{},{// Cast otherProps
 key:d// This is the key of the current BaseNode itself
 });// Prepare props for React.createElement
-// Delete key `nodeTheme` as it's not a valid DOM/React prop for the element
+// 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)}}])}();/**
  * Factory function to create a BaseNode instance.
  * @param element The React element type.
@@ -138,6 +138,7 @@ return c.theme&&void 0===c.nodeTheme&&(c.nodeTheme=c.theme),new BaseNode(a,c)}/*
  * @param component Component function that returns a BaseNode or ReactNode
  * @returns A React function component that handles BaseNode conversion and theme propagation
  * @example
+ * ```ts
  * // Basic usage
  * const Button = Component((props) => {
  *   return Node('button', {
@@ -145,7 +146,8 @@ return c.theme&&void 0===c.nodeTheme&&(c.nodeTheme=c.theme),new BaseNode(a,c)}/*
  *     theme: { color: 'blue' }
  *   })
  * })
- */export function Component(a){// Create wrapper component that handles theme and rendering
+ * ```
+ */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
 // Handle BaseNode results - requires special processing
 if(c instanceof BaseNode){var d,e;// Theme merging: Check if we need to handle theme inheritance

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meonode/ui",
   "description": "A structured approach to component composition with built-in theming, prop separation, and dynamic children handling.",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "main": "./dist/main.js",
   "types": "./dist/main.d.ts",