neo.mjs 10.2.1 → 10.3.0

package/buildScripts/util/templateBuildProcessor.mjs

@@ -0,0 +1,331 @@
+import { HtmlTemplate } from '../../src/functional/util/html.mjs';
+import * as parse5      from '../../dist/parse5.mjs'; // parse5 is bundled and available
+
+/**
+ * This script contains the core logic for Neo.mjs's build-time processing of HTML tagged template literals.
+ * Its primary purpose is to convert the `html`...` syntax into a standard, serializable Neo.mjs VDOM
+ * object. This transformation happens during the build process (`build-dist-esm`), meaning the code that
+ * runs in the browser receives a pre-compiled, optimized VDOM structure, eliminating the need for a
+ * client-side HTML parser and improving runtime performance.
+ *
+ * The process is carefully designed to be a "compile-time equivalent" of the client-side parser, ensuring
+ * that developers get a consistent experience between development and production modes.
+ *
+ * The core challenge is to take the raw strings and an array of code strings (representing the dynamic
+ * parts like `${this.name}`) and correctly reconstruct a VDOM tree. This involves:
+ * 1. Flattening nested templates.
+ * 2. Using `parse5` to create a standard HTML AST.
+ * 3. Walking the AST and converting each node into a VDOM object.
+ * 4. Crucially, preserving the JavaScript expressions as-is for runtime evaluation, which is achieved by
+ *    wrapping them in special placeholders (`##__NEO_EXPR__...##`) that are later converted back into
+ *    raw code in the final AST.
+ * 5. Handling mixed content (e.g., `Hello, ${this.name}!`) by converting it into a robust chain of
+ *    string concatenations rather than a fragile template literal reconstruction.
+ */
+
+// Defining regexes at the module level is a performance best practice,
+// as it prevents them from being re-created on every function call.
+const
+    /**
+     * @private
+     * @const {RegExp} regexAttribute
+     * Finds an attribute name right before an interpolated value (e.g., `... style=${...}`).
+     * This is crucial for preserving the original mixed-case spelling of attributes when they are dynamic.
+     */
+    regexAttribute            = /\s+([a-zA-Z][^=]*)\s*=\s*"?$/,
+    /**
+     * @private
+     * @const {RegExp} regexDynamicValue
+     * Finds a placeholder for a dynamic value that is the entire attribute value.
+     */
+    regexDynamicValue         = /^__DYNAMIC_VALUE_(\d+)__$/,
+    /**
+     * @private
+     * @const {RegExp} regexDynamicValueG
+     * Finds all dynamic value placeholders within a string (globally).
+     */
+    regexDynamicValueG        = /__DYNAMIC_VALUE_(\d+)__/g,
+    /**
+     * @private
+     * @const {RegExp} regexNested
+     * Finds placeholders for nested templates or dynamic component tags to re-index them during flattening.
+     */
+    regexNested               = /(__DYNAMIC_VALUE_|neotag)(\d+)/g,
+    /**
+     * @private
+     * @const {RegExp} regexOriginalTagName
+     * Extracts the original tag name from its source code string to preserve case sensitivity, as parse5 lowercases all tags.
+     */
+    regexOriginalTagName      = /<([\w\.]+)/,
+    /**
+     * @private
+     * @const {RegExp} selfClosingComponentRegex
+     * Finds self-closing custom component tags (e.g., `<MyComponent />`) and converts them to
+     * explicit start/end tags (`<MyComponent></MyComponent>`) because `parse5` in fragment mode
+     * does not correctly handle them for non-standard elements.
+     */
+    selfClosingComponentRegex = /<((?:[A-Z][\w\.]*)|(?:neotag\d+))([^>]*?)\/?>/g;
+
+/**
+ * Recursively converts a single parse5 AST node into a Neo.mjs VDOM node.
+ * This is the heart of the transformation process, translating the HTML structure into a JSON structure.
+ * @param {object} node The parse5 AST node to process.
+ * @param {string[]} values The array of placeholder strings for interpolated values (e.g., '##__NEO_EXPR__...##').
+ * @param {string} originalString The flattened, raw template string.
+ * @param {object} attributeNameMap A map of dynamic value indices to their original, case-sensitive attribute names.
+ * @param {object} options Configuration options for parsing.
+ * @param {object} parseState A state object to track parsing progress (currently unused but available).
+ * @returns {object|string|null} A VDOM node, a raw expression placeholder string, or null if the node is empty.
+ * @private
+ */
+function convertNodeToVdom(node, values, originalString, attributeNameMap, options, parseState) {
+    // 1. Handle text nodes
+    if (node.nodeName === '#text') {
+        let text = node.value;
+
+        if (options?.trimWhitespace) {
+            text = text.replace(/\s+/g, ' ').trim();
+        }
+
+        if (text === '') return null;
+
+        // CRITICAL: This handles conditional rendering (e.g., `${condition && template}`).
+        // If a text node consists of a SINGLE dynamic value, we must return the raw placeholder string.
+        // This allows the expression to be placed directly into the parent's `cn` array, where it will be
+        // evaluated at runtime. If we wrapped it in a `{vtype: 'text', ...}` object, it would always render as a string.
+        const singleDynamicMatch = text.match(/^__DYNAMIC_VALUE_(\d+)__$/);
+        if (singleDynamicMatch) {
+            const index = parseInt(singleDynamicMatch[1], 10);
+            return values[index]; // Return the raw '##__NEO_EXPR__...##' placeholder
+        }
+
+        // If the text node is a mix of strings and dynamic values (e.g., `Hello, ${name}`),
+        // we build a robust string concatenation chain (e.g., `'Hello, ' + (name)`). This is more
+        // reliable than trying to reconstruct a nested template literal, as it avoids complex escaping issues.
+        const regex = /(__DYNAMIC_VALUE_\d+__)/g;
+        const parts = text.split(regex).filter(p => p);
+
+        if (parts.length > 1) {
+            const additionChain = parts.map(part => {
+                const match = part.match(/__DYNAMIC_VALUE_(\d+)__/);
+                if (match) {
+                    const index = parseInt(match[1], 10);
+                    const value = values[index]; // This is the '##__NEO_EXPR__...' string
+                    const exprMatch = value.match(/##__NEO_EXPR__(.*)##__NEO_EXPR__##/s);
+                    if (exprMatch) {
+                        return `(${exprMatch[1]})`; // Wrap expression in parens for safety
+                    }
+                }
+                // Escape single quotes for the string literal part of the chain.
+                return `'${part.replace(/'/g, "\'" )}'`;
+            }).filter(p => p !== `''`).join(' + ');
+
+            // The entire chain becomes a single expression placeholder.
+            return { vtype: 'text', text: `##__NEO_EXPR__${additionChain}##__NEO_EXPR__##` };
+        }
+
+        // It's a simple static text node.
+        return { vtype: 'text', text };
+    }
+
+    // 2. Handle element nodes
+    if (node.nodeName && node.sourceCodeLocation?.startTag) {
+        const vdom = {};
+        const tagName = node.tagName;
+
+        // A `neotag` is a placeholder for a dynamically injected component constructor (e.g., `<${Button}>`).
+        if (tagName.startsWith('neotag')) {
+            const index = parseInt(tagName.replace('neotag', ''), 10);
+            vdom.module = values[index];
+        } else {
+            // parse5 lowercases all tag names. To support case-sensitive component tags (e.g., `<MyComponent>`),
+            // we must retrieve the original tag name from the source string.
+            const { startTag } = node.sourceCodeLocation;
+            const startTagStr = originalString.substring(startTag.startOffset, startTag.endOffset);
+            const originalTagNameMatch = startTagStr.match(regexOriginalTagName);
+            if (originalTagNameMatch) {
+                const originalTagName = originalTagNameMatch[1];
+                // By convention, a tag starting with an uppercase letter is a Neo.mjs component.
+                if (originalTagName[0] === originalTagName[0].toUpperCase()) {
+                    // At build time, we don't resolve the component. We create a placeholder that the
+                    // main build script will convert into a plain Identifier in the AST.
+                    vdom.module = { __neo_component_name__: originalTagName };
+                } else {
+                    vdom.tag = originalTagName;
+                }
+            } else {
+                vdom.tag = tagName; // Fallback
+            }
+        }
+
+        // Re-construct attributes, re-inserting dynamic values and preserving original case.
+        node.attrs?.forEach(attr => {
+            const match = attr.value.match(regexDynamicValue);
+            // If the entire attribute is a dynamic value, we can directly assign the placeholder.
+            if (match) {
+                const dynamicValueIndex = parseInt(match[1], 10);
+                const attrName = attributeNameMap[dynamicValueIndex] || attr.name;
+                vdom[attrName] = values[dynamicValueIndex];
+            } else {
+                // If the attribute is a mix of strings and dynamic values, build a concatenation chain.
+                let hasDynamicPart = false;
+                const valueParts = attr.value.split(regexDynamicValueG).map(part => {
+                    if (part.match(/^\d+$/)) {
+                        const index = parseInt(part, 10);
+                        if (values[index]) {
+                            hasDynamicPart = true;
+                            const value = values[index];
+                            const exprMatch = value.match(/##__NEO_EXPR__(.*)##__NEO_EXPR__##/s);
+                            return exprMatch ? `(${exprMatch[1]})` : JSON.stringify(value);
+                        }
+                    }
+                    return `'${part.replace(/'/g, "\'" )}'`;
+                });
+
+                if (hasDynamicPart) {
+                    const finalExpression = valueParts.filter(p => p !== `''`).join(' + ');
+                    vdom[attr.name] = `##__NEO_EXPR__${finalExpression}##__NEO_EXPR__##`;
+                } else {
+                    vdom[attr.name] = attr.value;
+                }
+            }
+        });
+
+        // Recursively process child nodes.
+        if (node.childNodes?.length > 0) {
+            const children = node.childNodes.map(child => convertNodeToVdom(child, values, originalString, attributeNameMap, options, parseState)).filter(Boolean);
+            if (children.length > 0) {
+                // Optimization: If a node has only one child, check if it's a text node (either static or dynamic)
+                // and simplify the VDOM by moving the content directly into the parent's `text` property.
+                if (children.length === 1) {
+                    const child = children[0];
+                    if (child.vtype === 'text') {
+                        vdom.text = child.text;
+                    } else if (typeof child === 'string' && child.startsWith('##__NEO_EXPR__')) {
+                        vdom.text = child; // Assign the dynamic expression placeholder directly.
+                    } else {
+                        vdom.cn = children;
+                    }
+                } else {
+                    vdom.cn = children;
+                }
+            }
+        }
+
+        return vdom;
+    }
+
+    return null;
+}
+
+/**
+ * Kicks off the AST to VDOM conversion for the entire template.
+ * @param {object} ast The root parse5 AST.
+ * @param {string[]} values The array of placeholder strings for interpolated values.
+ * @param {string} originalString The flattened, raw template string.
+ * @param {object} attributeNameMap A map of dynamic value indices to their original, case-sensitive attribute names.
+ * @param {object} options Configuration options for parsing.
+ * @param {object} parseState A state object to track parsing progress.
+ * @returns {object} The final Neo.mjs VDOM.
+ * @private
+ */
+function convertAstToVdom(ast, values, originalString, attributeNameMap, options, parseState) {
+    if (!ast.childNodes || ast.childNodes.length < 1) {
+        return {};
+    }
+
+    const children = ast.childNodes.map(child => convertNodeToVdom(child, values, originalString, attributeNameMap, options, parseState)).filter(Boolean);
+
+    // If the template has only one root node, we return it directly.
+    // Otherwise, we return a fragment-like object with children in a `cn` array.
+    if (children.length === 1) {
+        return children[0];
+    }
+
+    return { cn: children };
+}
+
+/**
+ * Flattens a potentially nested HtmlTemplate object into a single string and a corresponding array of values.
+ * This is a necessary pre-processing step before parsing with `parse5`, which only accepts a single string.
+ * It recursively walks through nested templates, merging their strings and values, and carefully re-indexes
+ * all placeholders to be unique within the final flattened structure.
+ * @param {Neo.functional.util.HtmlTemplate} template The root template object.
+ * @param {string[]} [parentValues] Used for recursion.
+ * @param {object} [parentAttributeMap] Used for recursion.
+ * @returns {{flatString: string, flatValues: Array<*>, attributeNameMap: Object}}
+ * @private
+ */
+function flattenTemplate(template, parentValues, parentAttributeMap) {
+    let flatString = '';
+    const flatValues = parentValues || [];
+    const attributeNameMap = parentAttributeMap || {};
+
+    for (let i = 0; i < template.strings.length; i++) {
+        let str = template.strings[i];
+        const attrMatch = str.match(regexAttribute);
+
+        flatString += str;
+
+        if (i < template.values.length) {
+            const value = template.values[i];
+
+            if (value instanceof HtmlTemplate) {
+                // A value can be another template. Recurse into it.
+                const nestedStartIndex = flatValues.length;
+                const nested = flattenTemplate(value, flatValues, attributeNameMap);
+                // The nested template's placeholders must be re-indexed to fit into the parent's value array.
+                const nestedString = nested.flatString.replace(regexNested, (match, p1, p2) => {
+                    return `${p1}${parseInt(p2, 10) + nestedStartIndex}`;
+                });
+                flatString += nestedString;
+                // flatValues and attributeNameMap are mutated by the recursive call, so no merge needed here.
+            } else if (value !== false && value != null) {
+                // Falsy values are ignored, enabling conditional rendering.
+                const currentIndex = flatValues.length;
+                if (attrMatch) {
+                    // If the value is for an attribute, store the original attribute name.
+                    attributeNameMap[currentIndex] = attrMatch[1];
+                }
+
+                // Replace the dynamic value with a placeholder.
+                if (template.strings[i].trim().endsWith('<') || template.strings[i].trim().endsWith('</')) {
+                    flatString += `neotag${currentIndex}`;
+                } else {
+                    flatString += `__DYNAMIC_VALUE_${currentIndex}__`;
+                }
+                flatValues.push(value);
+            }
+        }
+    }
+
+    return { flatString, flatValues, attributeNameMap };
+}
+
+/**
+ * The main entry point for the build-time template processor.
+ * It orchestrates the flattening, parsing, and VDOM conversion.
+ * @param {string[]} strings The static string parts of the template literal from the AST.
+ * @param {string[]} expressionCodeStrings The raw JavaScript code strings for the dynamic parts from the AST.
+ * @returns {object} The resulting serializable JSON VDOM object.
+ */
+export function processHtmlTemplateLiteral(strings, expressionCodeStrings) {
+    // At build time, we don't evaluate expressions. We wrap the raw code strings in placeholders.
+    // These placeholders will be converted back into real AST nodes by the main build script.
+    const values = expressionCodeStrings.map(exprCode => `##__NEO_EXPR__${exprCode}##__NEO_EXPR__##`);
+
+    // The HtmlTemplate class provides a convenient structure for handling template parts.
+    const htmlTemplateInstance = new HtmlTemplate(strings, values);
+
+    // 1. Flatten the template to handle nested templates.
+    const { flatString, flatValues, attributeNameMap } = flattenTemplate(htmlTemplateInstance);
+    // 2. Fix self-closing tags for parse5 compatibility.
+    const stringWithClosingTags = flatString.replace(selfClosingComponentRegex, '<$1$2></$1>');
+    // 3. Parse the flattened string into an AST.
+    const ast = parse5.parseFragment(stringWithClosingTags, { sourceCodeLocationInfo: true });
+    const parseState = { attrNameIndex: 0 };
+    // 4. Convert the AST into the final VDOM object.
+    const parsedVdom = convertAstToVdom(ast, flatValues, stringWithClosingTags, attributeNameMap, { trimWhitespace: true }, parseState);
+
+    return parsedVdom;
+}

package/buildScripts/util/vdomToString.mjs

@@ -0,0 +1,46 @@
+/**
+ * A regex to check if a string is a valid JavaScript identifier.
+ * @member {RegExp} validIdentifierRegex=/^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+ */
+const validIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+/**
+ * Serializes a VDOM object into a JavaScript object literal string.
+ * This is a custom implementation to ensure keys are unquoted if they are
+ * valid identifiers, and correctly quoted otherwise. It also handles
+ * special placeholders for runtime expressions.
+ * @param {Object} vdom The VDOM object to serialize.
+ * @returns {String} The string representation of the VDOM.
+ */
+export function vdomToString(vdom) {
+    if (vdom === null) {
+        return 'null';
+    }
+    if (typeof vdom !== 'object') {
+        // It's a primitive value (string, number, boolean)
+        // Check for our special expression placeholder
+        if (typeof vdom === 'string') {
+            const match = vdom.match(/##__NEO_EXPR__(.*)##__NEO_EXPR__##/);
+            if (match) {
+                return match[1]; // Return the raw expression
+            }
+        }
+        // Otherwise, stringify it normally
+        return JSON.stringify(vdom);
+    }
+
+    if (Array.isArray(vdom)) {
+        return `[${vdom.map(vdomToString).join(',')}]`;
+    }
+
+    const parts = [];
+    for (const key in vdom) {
+        if (Object.prototype.hasOwnProperty.call(vdom, key)) {
+            const value = vdom[key];
+            const keyString = validIdentifierRegex.test(key) ? key : `'${key}'`;
+            parts.push(`${keyString}:${vdomToString(value)}`);
+        }
+    }
+
+    return `{${parts.join(',')}}`;
+}

package/buildScripts/webpack/development/webpack.config.appworker.mjs

@@ -162,6 +162,17 @@ export default env => {
             chunkFilename: 'chunks/app/[id].js',
             filename     : filenameConfig.workers.app.output,
             path         : path.resolve(cwd, buildTarget.folder)
+        },
+
+        module: {
+            rules: [
+                {
+                    test: /\.mjs$/,
+                    use: [{
+                        loader: path.resolve(neoPath, 'buildScripts/webpack/loader/template-loader.mjs')
+                    }]
+                }
+            ]
         }
     }
 };

package/buildScripts/webpack/loader/template-loader.mjs

@@ -0,0 +1,21 @@
+import { processFileContent } from '../../util/astTemplateProcessor.mjs';
+
+/**
+ * This Webpack loader is responsible for applying the AST-based `html` template
+ * transformation to `.mjs` files during the Webpack build process.
+ *
+ * It acts as a pre-processor for JavaScript files before they are handled by other
+ * loaders or bundled by Webpack.
+ *
+ * @param {string} source The source code of the file being processed.
+ * @returns {string} The transformed source code.
+ */
+export default function(source) {
+    // `this.resourcePath` is a property provided by Webpack's loader context,
+    // giving us the absolute path to the file being processed. This is crucial
+    // for logging meaningful errors.
+    const result = processFileContent(source, this.resourcePath);
+
+    // Return the (potentially modified) content to the next loader in the chain.
+    return result.content;
+};

package/buildScripts/webpack/production/webpack.config.appworker.mjs

@@ -169,6 +169,17 @@ export default async function(env) {
             chunkFilename: 'chunks/app/[id].js',
             filename     : filenameConfig.workers.app.output,
             path         : path.resolve(cwd, buildTarget.folder)
+        },
+
+        module: {
+            rules: [
+                {
+                    test: /\.mjs$/,
+                    use: [{
+                        loader: path.resolve(neoPath, 'buildScripts/webpack/loader/template-loader.mjs')
+                    }]
+                }
+            ]
         }
     }
 };

package/examples/README.md

@@ -1,7 +1,7 @@
 # Client Requirements
 
 Running the examples locally works fine in all environments inside all major browsers at this point:
-Chromium, Safari & Firefox
+Chrome, Edge, Firefox & Safari
 
 
 # Local Web-Server Requirements

package/examples/component/wrapper/googleMaps/MarkerDialog.mjs

@@ -71,8 +71,8 @@ class MarkerDialog extends DialogBase {
         return `${day}. ${month} <b>${year}</b> ${hour}:${minute}`
     }
 
-    async onRender(data, automount) {
-        super.onRender(data, automount)
+    async onInitVnode(data, automount) {
+        super.onInitVnode(data, automount)
 
         let me = this;
 

package/examples/form/field/email/MainContainer.mjs

@@ -118,7 +118,6 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create(EmailField, {
-            autoRender: false,
             clearable : true,
             labelText : 'Label',
             labelWidth: 70,

package/examples/form/field/number/MainContainer.mjs

@@ -114,7 +114,6 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create(NumberField, {
-            autoRender          : false,
             clearToOriginalValue: true,
             labelText           : 'Label',
             labelWidth          : 70,

package/examples/form/field/picker/MainContainer.mjs

@@ -110,7 +110,6 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create(PickerField, {
-            autoRender          : false,
             clearToOriginalValue: true,
             labelText           : 'Label',
             labelWidth          : 70,

package/examples/form/field/time/MainContainer.mjs

@@ -136,7 +136,6 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create(TimeField, {
-            autoRender   : false,
             clearable    : true,
             labelPosition: 'inline',
             labelText    : 'Pick a time',

package/examples/form/field/trigger/copyToClipboard/MainContainer.mjs

@@ -106,7 +106,6 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create(TextField, {
-            autoRender : false,
             clearable  : true,
             showOnHover: true,
             labelText  : 'Label',

package/examples/form/field/url/MainContainer.mjs

@@ -118,7 +118,6 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create(UrlField, {
-            autoRender      : false,
             clearable       : true,
             labelText       : 'Label',
             labelWidth      : 70,

package/examples/functional/nestedTemplateComponent/Component.mjs

@@ -0,0 +1,100 @@
+import Button from '../../../src/button/Base.mjs';
+import {defineComponent, html, useConfig, useEvent} from '../../../src/functional/_export.mjs';
+
+export default defineComponent({
+    config: {
+        /**
+         * @member {String} className='Neo.examples.functional.nestedTemplateComponent.Component'
+         */
+        className: 'Neo.examples.functional.nestedTemplateComponent.Component',
+        /**
+         * @member {String} detailsText_='Here are some more details!'
+         * @reactive
+         */
+        detailsText_: 'Here are some more details!',
+        /**
+         * This is the key to unlock the `Template literals` based syntax for VDOM.
+         * @member {Boolean} enableHtmlTemplates=true
+         * @reactive
+         */
+        enableHtmlTemplates: true,
+        /**
+         * @member {String} greeting_='Hello'
+         * @reactive
+         */
+        greeting_: 'Hello',
+        /**
+         * @member {String} jobTitle_='Neo.mjs Developer'
+         * @reactive
+         */
+        jobTitle_: 'Neo.mjs Developer'
+    },
+
+    render(config) {
+        const [isActive, setIsActive] = useConfig(true);
+        const [showDetails, setShowDetails] = useConfig(false);
+
+        // This event listener is for the main container to toggle the active state
+        useEvent('click', (event) => {
+            // Stop the event from bubbling up to avoid toggling the active state
+            // when the button is clicked. The button has its own handler.
+            if (event.target.id === 'details-button') {
+                event.stopPropagation();
+            } else {
+                setIsActive(prev => !prev);
+            }
+        });
+
+        // The idiomatic way to handle a button click is with the handler config.
+        const onButtonClick = () => {
+            setShowDetails(prev => !prev);
+        };
+
+        const cardStyle = {
+            border      : '1px solid #eee',
+            borderRadius: '8px',
+            boxShadow   : '0 2px 4px rgba(0,0,0,0.1)',
+            cursor      : 'pointer',
+            padding     : '16px',
+            textAlign   : 'center'
+        };
+
+        const statusStyle = {
+            backgroundColor: isActive ? '#28a745' : '#dc3545',
+            borderRadius   : '12px',
+            color          : 'white',
+            display        : 'inline-block',
+            fontSize       : '12px',
+            marginTop      : '10px',
+            padding        : '4px 8px'
+        };
+
+        // 1. Nested Template: A separate template for the details section
+        const detailsTemplate = html`
+            <div style="margin-top: 15px; padding: 10px; border-top: 1px solid #eee;">
+                <p>${config.detailsText}</p>
+            </div>
+        `;
+
+        return html`
+            <div style=${cardStyle}>
+                <h2>${config.greeting}, Neo!</h2>
+                <p>${config.jobTitle}</p>
+
+                <!-- 3. Component via Tag Name, using the idiomatic handler config -->
+                <${Button}
+                    handler=${onButtonClick}
+                    id="details-button"
+                    text="${showDetails ? 'Hide' : 'Show'} Details"
+                />
+
+                <!-- 2. Conditional Rendering: Using a boolean to show the nested template -->
+                ${showDetails && detailsTemplate}
+
+                <div style="${statusStyle}">
+                    ${isActive ? 'Active' : 'Inactive'}
+                </div>
+            </div>
+        `
+    }
+});

package/examples/functional/nestedTemplateComponent/MainContainer.mjs

@@ -0,0 +1,48 @@
+import ConfigurationViewport from '../../ConfigurationViewport.mjs';
+import MyFunctionalComponent from './Component.mjs';
+import TextField             from '../../../src/form/field/Text.mjs';
+
+/**
+ * @class Neo.examples.functional.nestedTemplateComponent.MainContainer
+ * @extends Neo.examples.ConfigurationViewport
+ */
+class MainContainer extends ConfigurationViewport {
+    static config = {
+        className           : 'Neo.examples.functional.nestedTemplateComponent.MainContainer',
+        configItemLabelWidth: 160,
+        configItemWidth     : 280,
+        layout              : {ntype: 'hbox', align: 'stretch'}
+    }
+
+    createConfigurationComponents() {
+        let me = this;
+
+        return [{
+            module    : TextField,
+            clearable : true,
+            labelText : 'greeting',
+            listeners : {change: me.onConfigChange.bind(me, 'greeting')},
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.greeting
+        }, {
+            module    : TextField,
+            clearable : true,
+            labelText : 'jobTitle',
+            listeners : {change: me.onConfigChange.bind(me, 'jobTitle')},
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.jobTitle
+        }]
+    }
+
+    /**
+     * @returns {Neo.functional.Component}
+     */
+    createExampleComponent() {
+        return {
+            module  : MyFunctionalComponent,
+            greeting: 'Hi'
+        }
+    }
+}
+
+export default Neo.setupClass(MainContainer);

package/examples/functional/nestedTemplateComponent/app.mjs

@@ -0,0 +1,6 @@
+import MainContainer from './MainContainer.mjs';
+
+export const onStart = () => Neo.app({
+    mainView: MainContainer,
+    name    : 'Neo.examples.functional.nestedTemplateComponent'
+});