neo.mjs 10.3.0 → 10.3.2

package/.github/RELEASE_NOTES/v10.3.0.md

@@ -33,7 +33,9 @@ This new feature is built on a core Neo.mjs principle: **a commitment to a zero-
 To achieve both developer convenience and production performance, the framework uses a sophisticated dual-mode approach:
 
 1.  **Development Mode:** Templates are parsed live in the browser using `parse5`. This parser is **only loaded if templates are actually used**, ensuring zero overhead for applications that stick to the JSON VDOM.
-2.  **Production Mode:** For `dist/esm`, `dist/dev`, and `dist/prod` builds, a powerful **build-time AST transformation** converts templates directly into optimized VDOM objects. This eliminates the `parse5` dependency from production builds entirely, resulting in **zero runtime parsing overhead** and maximum performance.
+2.  **Production Mode:** For `dist/esm`, `dist/dev`, and `dist/prod` builds, a powerful **build-time AST transformation** converts templates directly into optimized VDOM objects. This eliminates the `parse5` dependency from production builds entirely, resulting in **zero runtime parsing overhead** and maximum performance. The `enableHtmlTemplates` flag is also automatically set to `false` in production environments, ensuring that the runtime parser is never accidentally used.
+
+As a developer convenience, if you name your template-generating method `render()`, the build process will automatically rename it to `createVdom()` for you, aligning with the framework's lifecycle methods while providing a familiar entry point.
 
 ## Foundational Enhancements
 
@@ -48,7 +50,22 @@ The introduction of HTML templates was made possible by a series of significant
 
 To support this major new feature, we have added two comprehensive guides:
 
--   [Using HTML Templates](../learn/guides/uibuildingblocks/HtmlTemplates.md): A guide focused on the syntax, features, and best practices for using the new template system.
--   [Under the Hood: HTML Templates](../learn/guides/uibuildingblocks/HtmlTemplatesUnderTheHood.md): A deep dive into the philosophy and the dual-mode architecture, explaining how templates work in both development and production environments.
+-   [Using HTML Templates](https://github.com/neomjs/neo/blob/dev/learn/guides/uibuildingblocks/HtmlTemplates.md): A guide focused on the syntax, features, and best practices for using the new template system.
+-   [Under the Hood: HTML Templates](https://github.com/neomjs/neo/blob/dev/learn/guides/uibuildingblocks/HtmlTemplatesUnderTheHood.md): A deep dive into the philosophy and the dual-mode architecture, explaining how templates work in both development and production environments.
+
+All changes combined into 1 commit: https://github.com/neomjs/neo/commit/0841e7e1a715c7afe67d07eebb8229e54828eedd
 
 We are incredibly excited about this release and believe it makes Neo.mjs more powerful and accessible than ever. Please explore the new feature, read the documentation, and share your feedback!
+
+Try it out by yourself:</br>
+https://neomjs.com/examples/functional/nestedTemplateComponent/
+
+<img width="1603" height="1292" alt="Screenshot 2025-08-02 at 17 01 25" src="https://github.com/user-attachments/assets/79cb4aad-b791-4b03-bf25-7147bbeeed39" />
+
+https://neomjs.com/dist/esm/examples/functional/nestedTemplateComponent/
+
+<img width="1606" height="1062" alt="Screenshot 2025-08-02 at 17 00 12" src="https://github.com/user-attachments/assets/7a21638f-cb68-4f28-ba04-6ebaccb3b3f3" />
+
+https://neomjs.com/dist/development/examples/functional/nestedTemplateComponent/
+
+<img width="1602" height="1179" alt="Screenshot 2025-08-02 at 17 06 24" src="https://github.com/user-attachments/assets/2c1d3ef7-2008-41a1-9025-2859d907ce2d" />

package/.github/RELEASE_NOTES/v10.3.1.md

@@ -0,0 +1,14 @@
+# Neo.mjs v10.3.1: Build Process Reliability
+
+This is a patch release focused on improving the stability and reliability of the core build process.
+
+## Key Fix: Build Process Dependency Order
+
+### The Problem
+The main `buildAll.mjs` script could fail on a clean repository checkout. The build steps that process HTML templates (e.g., `buildESModules`) have a dependency on the `dist/parse5.mjs` bundle. However, the script did not guarantee that this bundle was created before it was needed, leading to a potential crash.
+
+### The Solution
+We have updated `buildAll.mjs` to explicitly run the `bundleParse5.mjs` script as one of its first actions, immediately after the optional `npm install`.
+
+### The Impact
+This change ensures the `parse5` dependency is always available for subsequent build tasks. It makes the build process more robust and predictable, particularly for developers setting up the project for the first time.

package/.github/RELEASE_NOTES/v10.3.2.md

@@ -0,0 +1,10 @@
+# v10.3.2 Hotfix Release
+
+This hotfix addresses an issue where changing the `tabBarPosition` config for `tab.Container` did not correctly update the UI. Additionally, a broader refactoring was applied to improve component lifecycle management.
+
+## Fixes
+
+- **tab.Container:** Resolved an issue where switching `tabBarPosition` did not correctly update the UI. The `tabBar` component's `dock` config now properly reflects the new position, ensuring correct rendering. This fix involved adding `tabBarPosition` to the `config` object, and implementing `afterSetTabBarPosition` and `beforeSetTabBarPosition` methods to manage UI updates and component creation.
+- **Component Lifecycle:** Replaced `this.rendered` with `this.vnodeInitialized` across various components (`Circle`, `Gallery`, `Helix`, `Dialog`, `Text` field, `GridBody`, `Flexbox`, `List`, `TableBody`). This change refines the component lifecycle management, ensuring that UI updates and other operations are performed when the virtual DOM node is properly initialized.
+- **Font Awesome v7** Adjusted 3 spots inside our theming, where v6 was still in use.
+- **Earthquakes Tutorial** Fixed a malformed code closing tag, added a warning that the labs are currently not working.

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='10.3.0'
+         * @member {String} version='10.3.2'
          */
-        version: '10.3.0'
+        version: '10.3.2'
     }
 
     /**

package/apps/portal/index.html

@@ -16,7 +16,7 @@
         "@type": "Organization",
         "name": "Neo.mjs"
       },
-      "datePublished": "2025-08-02",
+      "datePublished": "2025-08-03",
       "publisher": {
         "@type": "Organization",
         "name": "Neo.mjs"

package/apps/portal/view/home/FooterContainer.mjs

@@ -108,7 +108,7 @@ class FooterContainer extends Container {
             }, {
                 module: Component,
                 cls   : ['neo-version'],
-                text  : 'v10.3.0'
+                text  : 'v10.3.2'
             }]
         }],
         /**

package/buildScripts/buildAll.mjs

@@ -129,6 +129,10 @@ if (programOpts.info) {
             childProcess.status && process.exit(childProcess.status);
         }
 
+        console.log(chalk.blue('Bundling parse5...'));
+        childProcess = spawnSync('node', [`${neoPath}/buildScripts/bundleParse5.mjs`], cpOpts);
+        childProcess.status && process.exit(childProcess.status);
+
         if (themes === 'yes') {
             childProcess = spawnSync('node', [`${neoPath}/buildScripts/buildThemes.mjs`].concat(cpArgs), cpOpts);
             childProcess.status && process.exit(childProcess.status);

package/examples/functional/nestedTemplateComponent/Component.mjs

@@ -31,7 +31,7 @@ export default defineComponent({
     },
 
     render(config) {
-        const [isActive, setIsActive] = useConfig(true);
+        const [isActive, setIsActive]       = useConfig(true);
         const [showDetails, setShowDetails] = useConfig(false);
 
         // This event listener is for the main container to toggle the active state
@@ -39,15 +39,15 @@ export default defineComponent({
             // 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();
+                event.stopPropagation()
             } else {
-                setIsActive(prev => !prev);
+                setIsActive(prev => !prev)
             }
         });
 
         // The idiomatic way to handle a button click is with the handler config.
         const onButtonClick = () => {
-            setShowDetails(prev => !prev);
+            setShowDetails(prev => !prev)
         };
 
         const cardStyle = {

package/learn/guides/uibuildingblocks/HtmlTemplatesUnderTheHood.md

@@ -40,7 +40,7 @@ To parse HTML strings, we need an HTML parser. Neo.mjs uses `parse5`, a robust a
 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
+```javascript readonly
 // src/functional/component/Base.mjs
 async initAsync() {
     await super.initAsync();
@@ -61,7 +61,7 @@ If `enableHtmlTemplates` is true, the component dynamically imports the `HtmlTem
 
 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).
+[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.
@@ -93,9 +93,9 @@ parsing overhead**. This is accomplished with a powerful build-time AST (Abstrac
 
 This work is handled by two main scripts:
 
--   [buildScripts/util/templateBuildProcessor.mjs](../../../../buildScripts/util/templateBuildProcessor.mjs):
+-   [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):
+-   [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.
 
@@ -119,10 +119,10 @@ renames the method to `createVdom`.
 
 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
+-   **`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).
+    [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.
 

package/learn/tutorials/Earthquakes.md

@@ -5,6 +5,11 @@ and show the information in two views: a table, and a map.
 
 You'll do this in a series of labs. 
 
+<span style='color: red;'>
+    Important: The labs inside this Tutorial cannot run currently, since the Google Maps API changed
+    and our addon needs adjustments. The chapters still contain valuable input.
+</span>
+
 ## Goals 
 
 What are the goals of this lengthy topic?
@@ -167,7 +172,8 @@ If you look in `neo-config.json` you should see this content. Note the `mainThre
     "mainPath"        : "../node_modules/neo.mjs/src/Main.mjs",
     "mainThreadAddons": ["DragDrop", "Navigator", "Stylesheet"],
     "workerBasePath"  : "../../node_modules/neo.mjs/src/worker/"
-}```
+}
+```
 
 You're free to edit `neo-config.json` if you were to change your mind later about the theme or need for other add-ons.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neo.mjs",
-    "version": "10.3.0",
+    "version": "10.3.2",
     "description": "Neo.mjs: The multi-threaded UI framework for building ultra-fast, desktop-like web applications with uncompromised responsiveness, inherent security, and a transpilation-free dev mode.",
     "type": "module",
     "repository": {
@@ -29,7 +29,6 @@
         "inject-package-version": "node ./buildScripts/injectPackageVersion.mjs",
         "server-start": "webpack serve -c ./buildScripts/webpack/webpack.server.config.mjs --open",
         "test": "echo \"Error: no test specified\" && exit 1",
-        "build-single-file": "node ./buildScripts/buildSingleFile.mjs",
         "watch-themes": "node ./buildScripts/watchThemes.mjs"
     },
     "keywords": [

package/resources/scss/src/apps/portal/about/MemberContainer.scss

@@ -24,7 +24,7 @@
 
         .portal-profile-location {
             color       : #777;
-            font-family : "Font Awesome 6 Free";
+            font-family : "Font Awesome 7 Free";
             font-style  : normal;
             font-weight : 600;
             margin-right: .5em;

package/resources/scss/src/apps/portal/learn/ContentComponent.scss

@@ -53,7 +53,7 @@
 
     details summary::before {
         color      : #c4c4c4;
-        font-family: var(--fa-style-family, "Font Awesome 6 Free");
+        font-family: var(--fa-style-family, "Font Awesome 7 Free");
         font-size  : 1em;
         font-weight: var(--fa-style, 900);
         margin     : 0.4em 0.4em 0.4em 0;

package/resources/scss/src/form/field/FileUpload.scss

@@ -44,7 +44,7 @@
         flex            : 0 0 2rem;
         height          : 2rem;
         border-radius   : 50%;
-        font-family     : var(--fa-style-family,"Font Awesome 6 Free");
+        font-family     : var(--fa-style-family,"Font Awesome 7 Free");
         display         : flex;
         align-items     : center;
         justify-content : center;

package/src/DefaultConfig.mjs

@@ -299,12 +299,12 @@ const DefaultConfig = {
     useVdomWorker: true,
     /**
      * buildScripts/injectPackageVersion.mjs will update this value
-     * @default '10.3.0'
+     * @default '10.3.2'
      * @memberOf! module:Neo
      * @name config.version
      * @type String
      */
-    version: '10.3.0'
+    version: '10.3.2'
 };
 
 Object.assign(DefaultConfig, {

package/src/component/Circle.mjs

@@ -248,7 +248,7 @@ class Circle extends Component {
      * @protected
      */
     afterSetMaxItems(value, oldValue) {
-        if (oldValue && this.rendered) {
+        if (oldValue && this.vnodeInitialized) {
             let me      = this,
                 frontEl = me.getFrontEl();
 
@@ -289,7 +289,7 @@ class Circle extends Component {
     afterSetItemSize(value, oldValue) {
         let me = this;
 
-        if (oldValue && me.rendered) {
+        if (oldValue && me.vnodeInitialized) {
             !me.collapsed && me.updateOuterCircle(true);
             me.updateItemPositions()
         }
@@ -302,7 +302,7 @@ class Circle extends Component {
      * @protected
      */
     afterSetRotateX(value, oldValue) {
-        oldValue && this.rendered && this.rotate()
+        oldValue && this.vnodeInitialized && this.rotate()
     }
 
     /**
@@ -312,7 +312,7 @@ class Circle extends Component {
      * @protected
      */
     afterSetRotateY(value, oldValue) {
-        oldValue && this.rendered && this.rotate()
+        oldValue && this.vnodeInitialized && this.rotate()
     }
 
     /**
@@ -322,7 +322,7 @@ class Circle extends Component {
      * @protected
      */
     afterSetRotateZ(value, oldValue) {
-        oldValue && this.rendered && this.rotate()
+        oldValue && this.vnodeInitialized && this.rotate()
     }
 
     /**
@@ -344,7 +344,7 @@ class Circle extends Component {
      * @protected
      */
     afterSetSelectionModel(value, oldValue) {
-        this.rendered && value.register(this);
+        this.vnodeInitialized && value.register(this);
     }
 
     /**

package/src/component/Gallery.mjs

@@ -245,7 +245,7 @@ class Gallery extends Component {
     afterSetMaxItems(value, oldValue) {
         let me = this;
 
-        if (value && me.rendered) {
+        if (value && me.vnodeInitialized) {
             if (oldValue > value) {
                 me.destroyItems(value, oldValue - value)
             } else {
@@ -310,7 +310,7 @@ class Gallery extends Component {
                 len  = Math.min(me.maxItems, me.store.items.length),
                 view = me.getItemsRoot();
 
-            if (me.rendered) {
+            if (me.vnodeInitialized) {
                 me.refreshImageReflection();
 
                 me.timeout(50).then(() => {
@@ -338,7 +338,7 @@ class Gallery extends Component {
      */
     afterSetSelectionModel(value, oldValue) {
         oldValue?.destroy();
-        this.rendered && value.register(this)
+        this.vnodeInitialized && value.register(this)
     }
 
     afterSetTranslateX() {this.moveOrigin()}

package/src/component/Helix.mjs

@@ -348,7 +348,7 @@ class Helix extends Component {
     afterSetMaxItems(value, oldValue) {
         let me = this;
 
-        if (value && me.rendered) {
+        if (value && me.vnodeInitialized) {
             if (oldValue > value) {
                 me.destroyItems(value, oldValue - value)
             } else {
@@ -399,7 +399,7 @@ class Helix extends Component {
      * @protected
      */
     afterSetSelectionModel(value, oldValue) {
-        this.rendered && value.register(this)
+        this.vnodeInitialized && value.register(this)
     }
 
     /**
@@ -411,7 +411,7 @@ class Helix extends Component {
     afterSetUrl(value, oldValue) {
         let me = this;
 
-        if (me.rendered) {
+        if (me.vnodeInitialized) {
             me.destroyItems();
             me.loadData()
         }

package/src/dialog/Base.mjs

@@ -269,7 +269,7 @@ class Dialog extends Panel {
         NeoArray.toggle(me.vdom.cls, 'neo-modal', value);
         me.update();
 
-        me.rendered && me.syncModalMask()
+        me.vnodeInitialized && me.syncModalMask()
     }
 
     /**
@@ -432,7 +432,7 @@ class Dialog extends Panel {
         }
 
         // rendered outside the visible area
-        await me.render(true);
+        await me.initVnode(true);
 
         let [dialogRect, bodyRect] = await me.waitForDomRect({id: [me.id, 'document.body']});
 

package/src/form/field/Text.mjs

@@ -1579,8 +1579,7 @@ class Text extends Field {
     }
 
     /**
-     * Since triggers do not get rendered, assign the relevant props
-     * todo: this could be handled by component.Base
+     * Since triggers do not get vnodeInitialized, assign the relevant props
      */
     updateTriggerVnodes() {
         let me          = this,
@@ -1593,8 +1592,8 @@ class Text extends Field {
 
             trigger && Object.assign(trigger, {
                 vnode,
-                _rendered: true,
-                _mounted : true
+                _mounted         : true,
+                _vnodeInitialized: true
             })
         })
     }

package/src/grid/Body.mjs

@@ -397,7 +397,7 @@ class GridBody extends Component {
      * @protected
      */
     afterSetSelectionModel(value, oldValue) {
-        this.rendered && value.register(this)
+        this.vnodeInitialized && value.register(this)
     }
 
     /**

package/src/layout/Flexbox.mjs

@@ -295,7 +295,7 @@ class Flexbox extends Base {
             {container, prefix} = me,
             {wrapperCls}        = container;
 
-        if (container?.rendered) {
+        if (container?.vnodeInitialized) {
             NeoArray.remove(wrapperCls, prefix + propertyName + '-' + oldValue);
 
             if (value !== null) {

package/src/list/Base.mjs

@@ -351,7 +351,7 @@ class List extends Component {
      * @protected
      */
     afterSetSelectionModel(value, oldValue) {
-        this.rendered && value.register(this)
+        this.vnodeInitialized && value.register(this)
     }
 
     /**

package/src/tab/BodyContainer.mjs

@@ -12,10 +12,10 @@ class BodyContainer extends Container {
          */
         className: 'Neo.tab.BodyContainer',
         /**
-         * @member {String[]} baseCls=['neo-container', 'neo-tab-body-container']
+         * @member {String[]} baseCls=['neo-tab-body-container','neo-container']
          * @protected
          */
-        baseCls: ['neo-container', 'neo-tab-body-container']
+        baseCls: ['neo-tab-body-container', 'neo-container']
     }
 
     /**

package/src/table/Body.mjs

@@ -112,7 +112,7 @@ class TableBody extends Component {
      * @protected
      */
     afterSetSelectionModel(value, oldValue) {
-        this.rendered && value.register(this)
+        this.vnodeInitialized && value.register(this)
     }
 
     /**

package/buildScripts/util/vdomToString.mjs

@@ -1,46 +0,0 @@
-/**
- * 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(',')}}`;
-}