neo.mjs 10.2.1 → 10.3.1

package/.github/CONCEPT.md

@@ -178,13 +178,11 @@ Pros:
 (no source-maps needed, no webpack interferences etc.)
 2. Browsers can cache JS modules and native packaging is in development
 3. Your code base is modular
+4. The development mode runs in all major browsers (Chrome, Edge, Firefox, Safari)
 
 Cons:
 1. neo.mjs is not using TypeScript (you could do it for your own app code, in case you want to use a build process)
-2. Firefox does not support JS modules inside workers yet, so the development mode only runs in Chromium (Chrome & Edge),
-as well as Safari. Mozilla is actively working on it.
-Of course the dist (dev&prod) versions do run fine in Firefox as well.
-3. Several npm dependencies can not easily get used, since they do not use a correct ES6 import syntax (e.g. missing file names)
+2. Several npm dependencies can not easily get used, since they do not use a correct ES6 import syntax (e.g. missing file names)
 
 ## No string based pseudo XML templates
 One example from the <a href="https://reactjs.org/">React Website</a>:

package/.github/GETTING_STARTED.md

@@ -1,55 +1,76 @@
 # neo.mjs: Getting Started Guide
-The following guide is intended to get this repository running locally.<br>
-In case you want to create a neo.mjs App, you have 3 different options:
-
-1. Use <a href="https://github.com/neomjs/create-app">npx neo-app</a>
-2. Fork the <a href="https://github.com/neomjs/workspace">neo.mjs workspace</a>
-3. Follow this guide (Step 6 creates a new App inside neo/apps)
-
-## Get this repository running locally
-1. Clone this repo to your system to get the project files
-   ```sh
-   git clone https://github.com/neomjs/neo.git
-   ```
-
-2. Open the checked out top level folder inside your terminal
-   ```sh
-   cd neo
-   ```
-
-3. Install the required node modules
-   ```sh
-   npm install
-   ```
-
-4. Run all relevant build scripts at once
-   ```sh
-   npm run build-all
-   ```
-
-(See the <a href="https://github.com/neomjs/neo/blob/dev/buildScripts/README.md">Command-Line Interface</a> for further details.)
-
-5. Make sure to use a local WebServer!
-   * Use a local webserver of your choice (E.g. Webstorm)
-   * OR `npm run server-start` 
-     1. A browser tab showing your app opens automatically.
-     2. You can also manually access it: http://localhost:8080/
-
-   (JS module imports can not work on the local file system (security).)
-   
-6. Optional: `npm run create-app`
-
-#### You can run the examples & docs app **without** any JS build directly in Chromium (Chrome, Edge) or Safari Tech Preview:  
-> localhost/neo/docs/
->
-> localhost/neo/examples/component/helix/
-
-### You can run the dist version examples like this:
-These versions also work in Firefox & Safari
-
-> localhost/neo/dist/development/examples/component/helix/
->
-> localhost/neo/dist/production/examples/component/helix/
+
+This guide covers two main paths for working with neo.mjs:
+1.  **Creating your own application**: The recommended approach for all developers building apps with the framework.
+2.  **Contributing to the framework**: For those who want to contribute code directly to the neo.mjs core.
+
+---
+
+## 1. Creating your own application (Recommended)
+For most use cases, creating a dedicated workspace with `npx neo-app` is the best way to start. This script scaffolds a new project, automatically installs dependencies, runs the initial build, and can even start the development server for you.
+
+A workspace provides the same structure as the main neo.mjs repository, but includes the framework as an NPM dependency, making it easier to manage.
+
+### Create a Workspace
+1.  Open your terminal and navigate to the directory where you want to create your project.
+2.  Run the following command:
+    ```sh
+    npx neo-app@latest
+    ```
+3.  Follow the interactive prompts. The script will guide you through setting up your workspace and creating your first application.
+
+This single command handles the entire setup process, allowing you to start developing immediately.
+
+---
+
+## 2. Contributing to the framework or running examples
+If you want to contribute to the development of neo.mjs itself, or if you want to run the many demo applications and examples included in the main repository, you will need to set up the core repository locally. The examples are not included in workspaces created with `npx neo-app`.
+
+### Fork and Clone the Repository
+1.  **Fork the repository**: First, create a fork of the `neomjs/neo` repository on GitHub to your own account.
+2.  **Clone your fork**: Clone your forked repository to your local machine.
+    ```sh
+    git clone https://github.com/YOUR_USERNAME/neo.git
+    ```
+
+### Local Setup
+1.  Navigate into the cloned repository folder:
+    ```sh
+    cd neo
+    ```
+2.  Install the required node modules:
+    ```sh
+    npm install
+    ```
+3.  Run all relevant build scripts at once:
+    ```sh
+    npm run build-all
+    ```
+    (See the <a href="https://github.com/neomjs/neo/blob/dev/buildScripts/README.md">Command-Line Interface</a> for further details.)
+
+### Running the Examples
+1.  **Start the web server**:
+    ```sh
+    npm run server-start
+    ```
+    A browser tab will open automatically. You can also manually access it at `http://localhost:8080/`. A local web server is required because modern browser security policies prevent JavaScript modules from loading directly from the local file system.
+
+2.  **Explore the apps**:
+    *   **Development Mode**: You can run the docs and examples apps **without** any JS build directly in all major browsers (Chrome, Edge, Firefox, Safari).
+        > http://localhost:8080/neo/docs/
+        >
+        > http://localhost:8080/neo/examples/
+    *   **Distribution Versions**: These versions also work in all major browsers and represent the built state of the examples.
+        > http://localhost:8080/neo/dist/development/examples/
+        >
+        > http://localhost:8080/neo/dist/production/examples/
+
+---
+
+## Dive Deeper with Learning Resources
+Once you have your environment set up, you can dive deeper into the concepts and architecture of the framework. The learning resources provide a structured path to mastering neo.mjs.
+
+**[Explore the Learning Resources](../learn/README.md)**
 
 <br><br>
 Copyright (c) 2015 - today, <a href="https://www.linkedin.com/in/tobiasuhlig/">Tobias Uhlig</a>

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

@@ -0,0 +1,71 @@
+# Neo.mjs v10.3.0: Introducing HTML Templates
+
+This release marks a major milestone in the evolution of Neo.mjs, introducing an intuitive, HTML-like syntax for building component VDOMs. This has been a significant undertaking, designed to lower the barrier to entry for new developers while holding true to the framework's core principles of performance and adherence to web standards.
+
+This feature is the culmination of the work tracked in our public epic: [#7130](https://github.com/neomjs/neo/issues/7130).
+
+## Key Feature: HTML Templates
+
+You can now define a component's VDOM using familiar HTML-like syntax, powered by standard JavaScript Tagged Template Literals. This provides an alternative to the traditional JSON-based VDOM structure, making UI development more approachable.
+
+```javascript
+import { html } from '../../src/functional/util/html.mjs';
+import Button   from '../../src/button/Base.mjs';
+
+// Inside a component's render() method:
+return html`
+    <div class="my-container">
+        <p>${this.myText}</p>
+        <${Button} text="Click Me" onClick="${this.onButtonClick}" />
+    </div>
+`;
+```
+
+### The Philosophy: Why Not JSX?
+
+This new feature is built on a core Neo.mjs principle: **a commitment to a zero-builds development experience.**
+
+-   **Standard JavaScript:** Unlike JSX, which requires a compiler, `html` templates are a standard JavaScript feature. Your code runs directly in the browser without a mandatory build step, providing an instant feedback loop.
+-   **No Hidden Magic:** Logic is handled with plain JavaScript (`if/else`, `.map()`), not special template directives. What you write is what you get.
+
+### The Dual-Mode Architecture
+
+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. 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
+
+The introduction of HTML templates was made possible by a series of significant enhancements to the framework's core and build scripts:
+
+-   **Component Lifecycle Integration (`src/functional/component/Base.mjs`):** The functional component base class was updated to recognize and process the new `HtmlTemplate` return type from `render()`, seamlessly integrating the parsing process into the component lifecycle.
+-   **Runtime Parsing (`src/functional/util/HtmlTemplateProcessor.mjs`):** A new runtime processor that intelligently flattens nested templates, handles dynamic values, and uses `parse5` to convert the HTML string into a VDOM structure.
+-   **Build-Time AST Processing (`buildScripts/util/astTemplateProcessor.mjs`):** A new, robust build-time processor that uses `acorn` to parse source code into an Abstract Syntax Tree (AST), replaces template literals with their VDOM object counterparts, and generates new, optimized code with `astring`.
+-   **Webpack Integration (`buildScripts/webpack/loader/template-loader.mjs`):** A new Webpack loader that hooks the AST processor into the `dist/dev` and `dist/prod` build pipelines, applied only to the app worker where components live.
+
+## New Documentation
+
+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.
+
+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.