npm - neo.mjs - Versions diffs - 10.2.1 → 10.3.0 - Mend

neo.mjs 10.2.1 → 10.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/.github/CONCEPT.md +2 -4
package/.github/GETTING_STARTED.md +72 -51
package/.github/RELEASE_NOTES/v10.3.0.md +54 -0
package/.github/epic-string-based-templates.md +690 -0
package/ServiceWorker.mjs +2 -2
package/apps/covid/view/MainContainer.mjs +1 -1
package/apps/covid/view/country/Table.mjs +1 -1
package/apps/portal/index.html +1 -1
package/apps/portal/view/home/FooterContainer.mjs +1 -1
package/apps/portal/view/learn/ContentComponent.mjs +1 -1
package/apps/realworld/api/Base.mjs +2 -2
package/apps/sharedcovid/view/MainContainer.mjs +1 -1
package/apps/sharedcovid/view/MainContainerController.mjs +1 -1
package/buildScripts/buildESModules.mjs +23 -75
package/buildScripts/bundleParse5.mjs +27 -0
package/buildScripts/util/astTemplateProcessor.mjs +210 -0
package/buildScripts/util/templateBuildProcessor.mjs +331 -0
package/buildScripts/util/vdomToString.mjs +46 -0
package/buildScripts/webpack/development/webpack.config.appworker.mjs +11 -0
package/buildScripts/webpack/loader/template-loader.mjs +21 -0
package/buildScripts/webpack/production/webpack.config.appworker.mjs +11 -0
package/examples/README.md +1 -1
package/examples/component/wrapper/googleMaps/MarkerDialog.mjs +2 -2
package/examples/form/field/email/MainContainer.mjs +0 -1
package/examples/form/field/number/MainContainer.mjs +0 -1
package/examples/form/field/picker/MainContainer.mjs +0 -1
package/examples/form/field/time/MainContainer.mjs +0 -1
package/examples/form/field/trigger/copyToClipboard/MainContainer.mjs +0 -1
package/examples/form/field/url/MainContainer.mjs +0 -1
package/examples/functional/nestedTemplateComponent/Component.mjs +100 -0
package/examples/functional/nestedTemplateComponent/MainContainer.mjs +48 -0
package/examples/functional/nestedTemplateComponent/app.mjs +6 -0
package/examples/functional/nestedTemplateComponent/index.html +11 -0
package/examples/functional/nestedTemplateComponent/neo-config.json +6 -0
package/examples/functional/templateComponent/Component.mjs +61 -0
package/examples/functional/templateComponent/MainContainer.mjs +48 -0
package/examples/functional/templateComponent/app.mjs +6 -0
package/examples/functional/templateComponent/index.html +11 -0
package/examples/functional/templateComponent/neo-config.json +6 -0
package/learn/gettingstarted/Setup.md +29 -12
package/learn/guides/fundamentals/ApplicationBootstrap.md +2 -2
package/learn/guides/fundamentals/InstanceLifecycle.md +5 -5
package/learn/guides/uibuildingblocks/HtmlTemplates.md +191 -0
package/learn/guides/uibuildingblocks/HtmlTemplatesUnderTheHood.md +156 -0
package/learn/guides/uibuildingblocks/WorkingWithVDom.md +1 -1
package/learn/tree.json +2 -0
package/package.json +62 -56
package/src/DefaultConfig.mjs +3 -3
package/src/calendar/view/calendars/List.mjs +1 -1
package/src/calendar/view/month/Component.mjs +1 -1
package/src/calendar/view/week/Component.mjs +1 -1
package/src/component/Abstract.mjs +1 -1
package/src/component/Base.mjs +33 -27
package/src/container/Base.mjs +5 -5
package/src/controller/Application.mjs +5 -5
package/src/dialog/Base.mjs +6 -6
package/src/draggable/DragProxyComponent.mjs +4 -4
package/src/form/field/ComboBox.mjs +1 -1
package/src/functional/_export.mjs +2 -1
package/src/functional/component/Base.mjs +142 -93
package/src/functional/util/HtmlTemplateProcessor.mjs +243 -0
package/src/functional/util/html.mjs +24 -67
package/src/list/Base.mjs +2 -2
package/src/manager/Toast.mjs +1 -1
package/src/menu/List.mjs +1 -1
package/src/mixin/VdomLifecycle.mjs +87 -90
package/src/tab/Container.mjs +2 -2
package/src/tooltip/Base.mjs +1 -1
package/src/tree/Accordion.mjs +2 -2
package/src/worker/App.mjs +7 -7
package/test/components/files/component/Base.mjs +1 -1
package/test/siesta/siesta.js +2 -0
package/test/siesta/tests/classic/Button.mjs +5 -5
package/test/siesta/tests/functional/Button.mjs +6 -6
package/test/siesta/tests/functional/HtmlTemplateComponent.mjs +193 -33
package/test/siesta/tests/functional/Parse5Processor.mjs +82 -0
package/test/siesta/tests/vdom/VdomRealWorldUpdates.mjs +5 -5
package/.github/epic-functional-components.md +0 -498
package/.github/ticket-asymmetric-vdom-updates.md +0 -122

package/examples/functional/nestedTemplateComponent/index.html ADDED Viewed

@@ -0,0 +1,11 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta charset="UTF-8">
+    <title>Neo Functional Nested Templates</title>
+</head>
+<body>
+    <script src="../../../src/MicroLoader.mjs" type="module"></script>
+</body>
+</html>

package/examples/functional/nestedTemplateComponent/neo-config.json ADDED Viewed

@@ -0,0 +1,6 @@
+{
+    "appPath"    : "examples/functional/nestedTemplateComponent/app.mjs",
+    "basePath"   : "../../../",
+    "environment": "development",
+    "mainPath"   : "./Main.mjs"
+}

package/examples/functional/templateComponent/Component.mjs ADDED Viewed

@@ -0,0 +1,61 @@
+import {defineComponent, html, useConfig, useEvent} from '../../../src/functional/_export.mjs';
+export default defineComponent({
+    config: {
+        /**
+         * @member {String} className='Neo.examples.functional.templateComponent.Component'
+         */
+        className: 'Neo.examples.functional.templateComponent.Component',
+        /**
+         * 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);
+        useEvent('click', () => setIsActive(prev => !prev));
+        const cardStyle = {
+            border    : '1px solid #eee',
+            borderRadius: '8px',
+            padding   : '16px',
+            textAlign : 'center',
+            cursor    : 'pointer',
+            boxShadow : '0 2px 4px rgba(0,0,0,0.1)'
+        };
+        const statusStyle = {
+            display      : 'inline-block',
+            padding      : '4px 8px',
+            borderRadius : '12px',
+            color        : 'white',
+            backgroundColor: isActive ? '#28a745' : '#dc3545',
+            fontSize     : '12px',
+            marginTop    : '10px'
+        };
+        return html`
+            <div style="${cardStyle}">
+                <h2>${config.greeting}, Neo!</h2>
+                <p>${config.jobTitle}</p>
+                <div style="${statusStyle}">
+                    ${isActive ? 'Active' : 'Inactive'}
+                </div>
+            </div>
+        `
+    }
+});

package/examples/functional/templateComponent/MainContainer.mjs ADDED Viewed

@@ -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.templateComponent.MainContainer
+ * @extends Neo.examples.ConfigurationViewport
+ */
+class MainContainer extends ConfigurationViewport {
+    static config = {
+        className           : 'Neo.examples.functional.templateComponent.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/templateComponent/app.mjs ADDED Viewed

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

package/examples/functional/templateComponent/index.html ADDED Viewed

@@ -0,0 +1,11 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta charset="UTF-8">
+    <title>Neo Functional Template Component</title>
+</head>
+<body>
+    <script src="../../../src/MicroLoader.mjs" type="module"></script>
+</body>
+</html>

package/examples/functional/templateComponent/neo-config.json ADDED Viewed

@@ -0,0 +1,6 @@
+{
+    "appPath"    : "examples/functional/templateComponent/app.mjs",
+    "basePath"   : "../../../",
+    "environment": "development",
+    "mainPath"   : "./Main.mjs"
+}

package/learn/gettingstarted/Setup.md CHANGED Viewed

@@ -1,24 +1,41 @@
 # Setup
-Setting up Neo.mjs is pretty easy &mdash; all you have to do is confirm that you have some required
-software then follow a single npx script.
+Setting up a Neo.mjs project is straightforward. The recommended method is to use `npx neo-app`, a command-line tool that generates a ready-to-use workspace for you.
 ## Prerequisites
-Before you get started, Neo.mjs requires that you have a few of things installed:
+Before you begin, ensure you have the following software installed:
-- npm & nodejs (see <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">https://docs.npmjs.com/downloading-and-installing-node-js-and-npm</a>)
-- npx (see <a href="https://www.npmjs.com/package/npx" target="_blank">https://www.npmjs.com/package/npx</a>)
+-   **Node.js and npm**: Required for running JavaScript projects and managing packages.
+    (see <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">https://docs.npmjs.com/downloading-and-installing-node-js-and-npm</a>)
+-   **npx**: Comes bundled with npm and is used to execute npm packages.
+    (see <a href="https://www.npmjs.com/package/npx" target="_blank">https://www.npmjs.com/package/npx</a>)
-## Installation
+## Creating a Workspace
-Your neo.mjs work is done in a _workspace_, which is an npm project that includes the Neo.mjs package,
-and an `app` directory that holds your applications. To generate a Neo.mjs workspace follow these
-steps.
+Your Neo.mjs work is done in a **workspace**, which is an npm project that includes the Neo.mjs framework as a dependency and an `apps` directory to hold your applications.
-Open a terminal window and navigate to an empty director on your computer.
-Then run the following command, choosing the defaults for each prompt.
+To generate a new workspace, open a terminal window, navigate to an empty directory, and run the following command:
 `npx neo-app@latest`
-When you're finished you should have a Neo.mjs workspace, as described in the _Workspaces and Applications_ topic, which follows.
+This script automates the entire setup process:
+1.  It scaffolds the workspace directory structure.
+2.  It creates a `package.json` file for your project.
+3.  It installs all necessary dependencies (`npm install`).
+4.  It runs the initial framework builds (`npm run build-all`).
+5.  It starts the development server for you (`npm run server-start`).
+When you're finished, you will have a complete Neo.mjs workspace, as described in the _Workspaces and Applications_ topic, which follows.
+## Understanding the Four Environments
+A unique advantage of Neo.mjs is its support for four distinct environments, allowing you to switch between a rapid, zero-builds development workflow and highly optimized deployment builds. Understanding these environments is key to leveraging the full power of the framework.
+-   **Development Mode**: No builds needed. Edit your code and see changes instantly in the browser. This is your primary environment for building and debugging.
+-   **dist/esm**: A modern deployment target that ships your application as native ES modules, preserving the file structure for easier debugging in production.
+-   **dist/production**: Creates highly optimized, minified bundles for each framework thread, ensuring the smallest possible footprint for deployment.
+-   **dist/development**: A bundled, non-minified version with source maps, useful for debugging issues that might only appear in a bundled environment.
+For a detailed explanation of each environment and how they work together, please read our comprehensive guide:
+**[Learn more: The 4 Environments](../benefits/FourEnvironments.md)**

package/learn/guides/fundamentals/ApplicationBootstrap.md CHANGED Viewed

@@ -1,7 +1,7 @@
 # Neo.mjs Application Bootstrap Process
 This guide explains how Neo.mjs applications start, initialize, and come to life - from the initial HTML file to your
-first rendered component.
+first mounted component.
 ## Overview
@@ -322,7 +322,7 @@ The component instantiation process:
 3. Event listeners are attached via the framework's event system
 4. Data bindings are established for reactive updates
-### 9. VDom Generation and Initial Render
+### 9. VDom Generation and Initial VNode Initialization
 Once the component tree is built:

package/learn/guides/fundamentals/InstanceLifecycle.md CHANGED Viewed

@@ -8,7 +8,7 @@ This guide will walk you through the entire lifecycle, which can be broken down
 1.  **Synchronous Creation**: The initial, synchronous setup of the instance and its configuration.
 2.  **Asynchronous Initialization**: An optional phase for asynchronous tasks like data fetching.
-3.  **Mounting & Unmounting**: The dynamic phase where a component is rendered into the DOM, and potentially unmounted
+3.  **Mounting & Unmounting**: The dynamic phase where a component is initialized and mounted into the DOM, and potentially unmounted
     and re-mounted.
 4.  **Destruction**: The final cleanup phase.
@@ -29,7 +29,7 @@ instance. Always let the framework handle instantiation.
 When the framework creates a new instance, it executes a sequence of synchronous methods. This initial phase is
 responsible for setting up the instance's basic configuration and state. **At this stage, the component has not been
-rendered to the DOM.**
+mounted to the DOM.**
 The synchronous lifecycle methods are called in the following order:
@@ -43,7 +43,7 @@ The synchronous lifecycle methods are called in the following order:
 3.  **`onConstructed()`**: This hook is called immediately after `construct()` has finished. It's the ideal place to
     perform any setup that depends on the initial configuration. **Crucially, do not attempt to access the DOM here**,
-    as the component is not yet rendered.
+    as the component is not yet mounted.
 4.  **`onAfterConstructed()`**: This hook is called after `onConstructed()`. It provides another opportunity for setup logic.
@@ -158,10 +158,10 @@ multiple times, even into different browser windows, all while preserving its in
 ### `mounted`: The DOM-Ready Signal
 The `mounted_` config is the key to this phase. It is a boolean flag that indicates whether the component is currently
-rendered in the DOM.
+painted in the DOM.
 *   **`afterSetMounted(isMounted, wasMounted)`**: This is the most important hook for DOM interaction. It is called with
-* `true` when the component's VDOM is successfully rendered into the DOM, and with `false` when it is removed.
+* `true` when the component's VDOM is successfully initialized and mounted into the DOM, and with `false` when it is removed.
 **This is the only safe and reliable place to perform DOM measurements or manipulations.**

package/learn/guides/uibuildingblocks/HtmlTemplates.md ADDED Viewed

@@ -0,0 +1,191 @@
+# Using HTML Templates for VDOM
+This guide covers the purpose, syntax, and trade-offs of using tagged template literals (HTML-like syntax) to define VDOM structures in neo.mjs. This feature provides an intuitive and familiar alternative to the traditional JSON-based VDOM approach, especially for developers coming from other traditional, single-threaded frameworks.
+## The "Why": An Alternative, Not a Replacement
+The core of neo.mjs is built on a highly efficient, JSON-based VDOM structure. This approach is powerful and performant, as it requires zero parsing or transformation at runtime.
+However, we recognize that many developers are accustomed to writing UI with an HTML-like syntax. HTML templates are offered as a **beginner-friendly and transitional option** to lower the barrier to entry. They allow you to get started quickly, leveraging familiar patterns, while you learn the more advanced capabilities of the framework.
+## The Trade-Off: Performance in Development
+Using this feature comes with a clear trade-off. To enable live parsing of HTML templates in your browser during development, the framework must load the `parse5` library. This adds **~176KB (minified)** to your application's initial download size in development mode.
+For production builds, this penalty is removed, as the templates are pre-compiled into the standard JSON VDOM format.
+## Best Practices
+-   **Use for simpler components:** Templates are excellent for components with relatively static structures, such as informational dialogs, buttons, or basic forms.
+-   **Prefer JSON VDOM for complex views:** For highly dynamic, data-driven, or programmatically generated views (like complex grids or dashboards), the native JSON VDOM approach is often clearer and more performant.
+-   **Embrace JavaScript for Logic:** Do not look for template-specific directives like `n-if` or `n-for`. All conditional logic and looping should be handled with standard JavaScript inside your `createVdom` method, before the `html` tag is even used.
+## For Developers Coming from JSX (e.g., React)
+You may be accustomed to writing component tags directly, like `<Button>`. In neo.mjs, the equivalent is `<${Button}>`. This small difference is intentional and unlocks significant architectural benefits.
+-   **JSX Requires a Compiler:** JSX is not standard JavaScript. It must be compiled into `React.createElement(Button, ...)` calls. The simplicity of `<Button>` is an abstraction provided by a mandatory build step.
+-   **neo.mjs Templates are Native JavaScript:** The `html`...`` syntax is a standard JavaScript feature called a "tagged template literal." It runs directly in the browser without a build step in development. The `<${Button}>` syntax is the native JavaScript way to pass the actual `Button` component constructor (the variable) into the template function.
+This approach means you are not learning a special template language; you are using the full power of JavaScript itself for all your view logic, including conditionals and loops, which is a core design principle of the framework.
+## Basic Usage
+To use this feature, import the `html` tag from `neo.mjs/src/functional/util/html.mjs` and use it to wrap your template string.
+```javascript
+import { html } from '../../../src/functional/util/html.mjs';
+const vdom = html`
+    <div class="container">
+        <h1>Hello, World!</h1>
+    </div>
+`;
+```
+## Component vs. HTML Tags
+The template processor distinguishes between standard HTML elements and neo.mjs components based on the tag itself.
+### 1. HTML Tags
+Standard HTML tags are written as lowercase literal strings, as you would in normal HTML.
+```javascript
+const vdom = html`
+    <section>
+        <p>This is a standard HTML paragraph.</p>
+    </section>
+`;
+```
+### 2. Component Tags
+There are two ways to render a neo.mjs component, with the first being the strongly recommended approach.
+#### Recommended: Interpolation (Lexical Scope)
+Import the component you need and pass the constructor directly into the template as the tag name using `${...}` syntax. This is the most explicit and robust method, as it uses the file's lexical scope.
+**Note:** Components can and should be self-closing if they do not have children.
+```javascript
+import { html } from '../../../src/functional/util/html.mjs';
+import Button   from '../../../src/button/Base.mjs';
+const vdom = html`<${Button} text="Click Me" />`;
+```
+#### Fallback: Global Namespace
+If a tag name is written as a literal string in `PascalCase` or with dots (e.g., `Neo.button.Base` or `MyApp.view.MyButton`), the processor will attempt to resolve it from the global namespace using the `Neo.ns()` utility. This should be used sparingly, as the interpolation method is more explicit and less prone to issues with name collisions or refactoring.
+```javascript
+const vdom = html`<Neo.button.Base text="Global Button" />`;
+```
+## Attributes and Configs
+Attributes are used to pass configuration values to both HTML tags and components.
+### Primitives (String, Number, Boolean)
+Static strings can be passed directly. For dynamic values (including numbers, booleans, or variables), use interpolation.
+```javascript
+const myId    = 'main-container';
+const disabled = true;
+const vdom = html`
+    <div id="${myId}" class="static-class"></div>
+    <${Button} text="Submit" disabled="${disabled}" />
+`;
+```
+### Objects, Arrays, and Functions
+To pass non-string data like objects (for styles), arrays (for child items), or functions (for renderers or handlers), you **must** use interpolation.
+```javascript
+import { html } from '../../../src/functional/util/html.mjs';
+import Grid from '../../../src/grid/Container.mjs';
+const myStyle = { color: 'blue', fontSize: '16px' };
+// A renderer function for a grid column
+const statusRenderer = ({ value }) => {
+    const color = value === 'Active' ? 'green' : 'red';
+    // A renderer can return a VDOM object for rich cell content
+    return { tag: 'span', style: { color }, cn: [value] };
+};
+// The array of column configuration objects
+const gridColumns = [
+    { dataField: 'name', text: 'Name' },
+    { dataField: 'status', text: 'Status', renderer: statusRenderer } // The function is passed here
+];
+const vdom = html`
+    <div style="${myStyle}">Styled Text</div>
+    <${Grid} columns="${gridColumns}" />
+`;
+```
+## Dynamic and Conditional Rendering
+Unlike other frameworks, neo.mjs templates do not have special directives for logic. Instead, you use the full power of JavaScript to build your dynamic UI *before* it goes into the template.
+### Conditional Rendering
+Use standard JavaScript constructs like `if/else` statements, ternary operators, or `&&` for conditional rendering.
+```javascript
+// Using a ternary operator
+const content = isVisible
+    ? html`<p>Now you see me.</p>`
+    : html`<small>Now you don't.</small>`;
+const vdom = html`
+    <div>
+        <h1>Conditional Content</h1>
+        ${content}
+    </div>
+`;
+// Using short-circuiting (&&)
+const vdom2 = html`
+    <div>
+        <h2>Admin Section</h2>
+        ${isAdmin && html`<p>Welcome, Admin!</p>`}
+    </div>
+`;
+```
+### Rendering Lists
+Use the standard `Array.prototype.map()` method to transform an array of data into an array of VDOM nodes.
+```javascript
+const items = [
+    { id: 1, name: 'First Item' },
+    { id: 2, name: 'Second Item' }
+];
+const listItems = items.map(item => html`
+    <li id="${item.id}">${item.name}</li>
+`);
+const vdom = html`
+    <ul>
+        ${listItems}
+    </ul>
+`;
+```
+**IMPORTANT:** When rendering lists, always provide a unique `id` attribute to each element in the list. This is crucial for the VDOM diffing algorithm to efficiently update, reorder, or remove items.
+## DOM Events (Out of Scope)
+This template system **does not** support inline DOM event handlers (e.g., `onClick="..."`).
+To handle DOM events, you must continue to use the framework's standard, efficient, and secure delegated event system via the `domListeners` config on class-based components or the `useEvent()` hook in functional components. This maintains architectural consistency and performance.

package/learn/guides/uibuildingblocks/HtmlTemplatesUnderTheHood.md ADDED Viewed

@@ -0,0 +1,156 @@
+# Under the Hood: The Philosophy and Mechanics of HTML Templates
+This guide explores the "why" and "how" behind the HTML template feature in Neo.mjs. It's a deep dive into an architecture
+designed to deliver on a core framework promise: a zero-builds, instant-feedback development mode that doesn't sacrifice
+production performance.
+This serves as a companion to the [Using HTML Templates](./HtmlTemplates.md) guide, which focuses on syntax
+and best practices.
+## The Core Philosophy: Why Not JSX?
+One of the most critical design goals for Neo.mjs is to provide a **zero-builds development environment**. We believe
+that developers should be able to write code and see their changes instantly in the browser, without a mandatory
+compilation step. This philosophy directly informed our approach to UI templating.
+Frameworks like React and Angular rely on non-standard syntax (JSX, Angular templates) that **must** be compiled into
+valid JavaScript. This requirement for a build step, even in development, introduces complexity and slows down
+the feedback loop.
+Neo.mjs chose a different path: **Tagged Template Literals**. This is a standard, native JavaScript feature. By using
+`html`... ``, we are not inventing a new language; we are leveraging the power of JavaScript itself. This allows for:
+1.  **True Zero-Builds Development:** Your template code runs directly in the browser. What you write is what you get,
+    with no hidden magic or required transformations.
+2.  **No Special Directives:** Logic isn't handled by template-specific directives like `n-if` or `n-for`. You use
+    standard JavaScript (`if/else`, `map()`) for all conditionals and loops, which is more powerful and familiar.
+3.  **Architectural Purity:** The template is just a function call that returns a data structure (a VDOM object).
+    This maintains a clean separation between your view definition and the framework's rendering engine.
+## Mechanism 1: The Zero-Builds Development Experience
+In development mode, templates must be parsed at runtime. This is where the trade-off for instant feedback becomes
+apparent.
+### Conditional Loading: A Smart Optimization
+To parse HTML strings, we need an HTML parser. Neo.mjs uses `parse5`, a robust and spec-compliant library. However, at
+~176KB, we don't want to load it unless absolutely necessary.
+This is why the parser is **only loaded if a component on the page actually uses an HTML template**. This check happens
+inside the `initAsync` method of `Neo.functional.component.Base`.
+```javascript
+// src/functional/component/Base.mjs
+async initAsync() {
+    await super.initAsync();
+    if (this.enableHtmlTemplates && Neo.config.environment === 'development') {
+        if (!Neo.ns('Neo.functional.util.HtmlTemplateProcessor')) {
+            const module = await import('../util/HtmlTemplateProcessor.mjs');
+            this.htmlTemplateProcessor = module.default
+        }
+    }
+}
+```
+If `enableHtmlTemplates` is true, the component dynamically imports the `HtmlTemplateProcessor`, which in turn pulls in
+`parse5`. This ensures that applications not using this feature pay no performance penalty.
+### The Runtime Parsing Process
+When a component's `createVdom()` method returns an `HtmlTemplate` object, it's handed off to the `HtmlTemplateProcessor`.
+You can inspect its source code here:
+[src/functional/util/HtmlTemplateProcessor.mjs](../../../../src/functional/util/HtmlTemplateProcessor.mjs).
+The processor executes a series of steps to convert the template literal into a VDOM object, which are detailed in the
+expandable section below.
+<details>
+<summary>Detailed Runtime Parsing Steps</summary>
+1.  **Flattening:** It recursively flattens any nested templates into a single string and a corresponding array of
+    dynamic values.
+2.  **Placeholder Injection:** It replaces dynamic values (e.g., event handlers, component configs, other components)
+    with special placeholders in the string (e.g., `__DYNAMIC_VALUE_0__`, `neotag1`).
+3.  **Self-Closing Tag Conversion:** Since `parse5` does not handle self-closing custom element tags, a regular
+    expression adds explicit closing tags (e.g., `<MyComponent />` becomes `<MyComponent></MyComponent>`).
+4.  **Parsing:** The sanitized HTML string is parsed into a standard AST using `parse5.parseFragment()`.
+5.  **VDOM Conversion:** The processor traverses the `parse5` AST and converts it back into a Neo.mjs VDOM object.
+    During this process, it re-inserts the original dynamic values from the `values` array, preserving their rich data
+    types (functions, objects, etc.). It also carefully reconstructs the original case-sensitive tag names for custom
+    components.
+</details>
+Once the VDOM is constructed, it's passed back to the component's `continueUpdateWithVdom()` method, and the standard
+rendering lifecycle proceeds.
+## Mechanism 2: Maximum Performance for Production
+For production, the goal is to achieve the exact same VDOM output as the development mode, but with **zero runtime
+parsing overhead**. This is accomplished with a powerful build-time AST (Abstract Syntax Tree) transformation.
+This work is handled by two main scripts:
+-   [buildScripts/util/templateBuildProcessor.mjs](../../../../buildScripts/util/templateBuildProcessor.mjs):
+    Contains the core logic for parsing the template string and converting it to a serializable VDOM object.
+-   [buildScripts/util/astTemplateProcessor.mjs](../../../../buildScripts/util/astTemplateProcessor.mjs):
+    Orchestrates the overall process of reading a JS file, finding `html` templates, and replacing them with the final
+    VDOM object via AST manipulation.
+### The AST Transformation Process
+The `astTemplateProcessor.mjs` script is a marvel of build-time engineering. Instead of just doing a simple text
+replacement, it performs a full AST transformation to ensure 100% accuracy.
+1.  **Parse Code:** It uses `acorn` to parse the JavaScript file content into an AST.
+2.  **Find Templates:** It traverses the AST to find all `html` tagged template expressions.
+3.  **Process Template:** Each template is processed by `templateBuildProcessor.mjs`, which converts the HTML-like syntax
+    into a serializable VDOM object.
+4.  **Convert to AST:** The resulting VDOM object is converted back into a valid AST `ObjectExpression` node.
+5.  **Replace Node:** The original `TaggedTemplateExpression` is replaced in the main AST with the new `ObjectExpression`.
+6.  **Generate Code:** The modified AST is converted back into a string of JavaScript code using `astring`.
+As a developer convenience, if a template is the return value of a method named `render`, the build script automatically
+renames the method to `createVdom`.
+### Integration with Build Environments
+This logic is seamlessly integrated into all three of Neo.mjs's production build environments:
+-   **`dist/esm`:** The [buildScripts/buildESModules.mjs](../../../../buildScripts/buildESModules.mjs) script directly
+    invokes the `processFileContent` function from the `astTemplateProcessor` for each JavaScript file before minification.
+-   **`dist/dev` & `dist/prod`:** These environments use Webpack. The transformation is handled by a custom loader:
+    [buildScripts/webpack/loader/template-loader.mjs](../../../../buildScripts/webpack/loader/template-loader.mjs).
+    This loader is strategically applied **only to the App worker's build configuration**, an optimization that saves
+    build time by not processing code for other workers.
+### Key Differences from Runtime Parsing
+The build-time process is fundamentally different from the runtime parsing:
+-   **No Lexical Scope:** The build script cannot access runtime variables like `this`. It captures the raw code (e.g.,
+    `this.name`) as a string.
+-   **Placeholder Wrapping:** These code strings are wrapped in special placeholders (e.g.,
+    `##__NEO_EXPR__this.name##__NEO_EXPR__##`).
+-   **Custom Resolution:** During the VDOM-to-AST conversion, the `jsonToAst` function uses `acorn.parseExpressionAt`
+    to parse these placeholders back into proper AST nodes, perfectly preserving the original expressions for runtime
+    evaluation.
+-   **Component Tag Handling:** A tag like `<MyComponent>` is converted into a placeholder object
+    (`{ __neo_component_name__: 'MyComponent' }`) which the `astTemplateProcessor` turns into a plain `Identifier` in
+    the final AST.
+## Conclusion: The Neo.mjs Advantage
+The dual-mode approach to HTML templates is a perfect example of the Neo.mjs philosophy in action. It provides:
+-   **An Unmatched Developer Experience:** The zero-builds development mode offers an instant feedback loop that is
+    impossible in frameworks requiring mandatory compilation. You write standard JavaScript and it simply works.
+-   **Maximum Production Performance:** The build-time AST transformation ensures that your production code is as fast
+    as possible, with no client-side parsing overhead. The `parse5` library is completely eliminated from your final bundle.
+-   **Architectural Consistency:** The system is designed to produce the exact same VDOM structure in both modes.
+    This eliminates a whole class of bugs where development and production environments behave differently.
+This architecture isn't just a feature; it's a statement. It demonstrates a commitment to web standards, developer
+productivity, and end-user performance that sets Neo.mjs apart from the crowd.

package/learn/guides/uibuildingblocks/WorkingWithVDom.md CHANGED Viewed

@@ -355,7 +355,7 @@ class DataList extends Component {
         this.update();   // Trigger VDom reconciliation
     }
-    // Automatically re-render list when 'data' config changes
+    // Automatically update list VDom when 'data' config changes
     afterSetData(value, oldValue) {
         if (value) { // Only create items if data is set
             this.createListItems();

package/learn/tree.json CHANGED Viewed

@@ -43,6 +43,8 @@
             {"name": "Layouts",                                        "parentId": "guides/uibuildingblocks",                             "id": "guides/uibuildingblocks/Layouts"},
             {"name": "Custom Components",                              "parentId": "guides/uibuildingblocks",                             "id": "guides/uibuildingblocks/CustomComponents"},
             {"name": "Working with VDom",                              "parentId": "guides/uibuildingblocks",                             "id": "guides/uibuildingblocks/WorkingWithVDom"},
+            {"name": "HTML Templates",                                 "parentId": "guides/uibuildingblocks",                             "id": "guides/uibuildingblocks/HtmlTemplates"},
+            {"name": "Under the Hood: HTML Templates",                 "parentId": "guides/uibuildingblocks",                             "id": "guides/uibuildingblocks/HtmlTemplatesUnderTheHood"},
         {"name": "Data Handling",                                      "parentId": "guides",                             "isLeaf": false, "id": "guides/datahandling", "collapsed": true},
             {"name": "Collections",                                    "parentId": "guides/datahandling",                                 "id": "guides/datahandling/Collections"},
             {"name": "Records",                                        "parentId": "guides/datahandling",                                 "id": "guides/datahandling/Records"},