neo.mjs 10.0.0-beta.4 → 10.0.0-beta.6

package/learn/guides/datahandling/StateProviders.md

@@ -1,3 +1,5 @@
+# Shared Bindable Data (State Providers)
+
 While Components can manage their own state using the Class Config System,
 you want to use VMs as soon as you want to share data properties with multiple child Components.
 
@@ -8,6 +10,60 @@ Rules of thumb:
 
 Other libraries or frameworks often call state providers "Stores".
 
+## How Reactivity Works: The Effects-Based System
+
+Neo.mjs State Providers implement a powerful effects-based reactivity system,
+which automatically tracks dependencies and re-evaluates computations when
+their underlying data changes. This system is built around two core concepts:
+
+### 1. The `Neo.core.Effect` Class
+
+At the heart of the reactivity is the `Neo.core.Effect` class. An `Effect`
+is a mechanism that encapsulates a function (its "effect function") and
+automatically re-runs this function whenever any of the reactive data
+properties it accesses change.
+
+*   **Implicit Dependency Tracking:** When your effect function (e.g., a formula
+    or a binding formatter) reads a reactive data property (e.g., `data.user.firstName`),
+    the `Effect` automatically "subscribes" to changes in that property.
+*   **Automatic Re-evaluation:** If `data.user.firstName` changes, the `Effect`
+    detects this and automatically re-executes its effect function, ensuring
+    that any dependent computations or UI updates are performed.
+
+### 2. The Hierarchical Data Proxy
+
+When you access data within a State Provider (e.g., in a `bind` configuration
+or a `formula`), you are interacting with a special `Proxy` object. This proxy
+is created by `Neo.state.createHierarchicalDataProxy` and provides a unified
+view of data across the entire State Provider hierarchy (current provider and
+all its parents).
+
+*   **Seamless Data Access:** You can access any data property, whether it lives
+    in the current State Provider or a parent, using simple dot notation (e.g.,
+    `data.myProperty` or `data.user.address.street`).
+*   **Enabling Dependency Tracking:** This proxy works in conjunction with
+    `Neo.core.Effect` to enable implicit dependency tracking. When an `Effect`
+    reads a property through this proxy, the proxy notifies the `Effect` about
+    the access, allowing the `Effect` to register that property as a dependency.
+
+### How Bindings and Formulas Utilize Effects
+
+*   **Bindings (`bind` config):** When you define a `bind` configuration for a
+    component (e.g., `bind: {text: data => data.hello}`), Neo.mjs creates an
+    `Effect`. The effect function is your formatter (`data => data.hello`).
+    Whenever `data.hello` changes, the `Effect` re-runs, re-evaluates the
+    formatter, and updates the component's `text` config.
+
+*   **Formulas (`formulas` config):** These are effect-based computed properties. Each formula function is wrapped in an `Effect`. When the
+    formula accesses data (e.g., `data.a + data.b`), the `Effect` tracks `data.a`
+    and `data.b` as dependencies. If either changes, the `Effect` re-runs the
+    formula, and its computed result is automatically updated in the State Provider's
+    data.
+
+This effects-based system significantly reduces boilerplate, making state
+management intuitive and efficient by handling dependency tracking and updates
+automatically.
+
 ## Inline State Providers
 ### Direct Bindings
 ```javascript live-preview
@@ -111,9 +167,9 @@ Inside the Container are 3 Labels which bind their `text` config to a combinatio
 
 We are showcasing 3 different ways how you can define your binding (resulting in the same output).
 
-In case any of the bound data props changes, all bound Configs will check for an update.
+In case any of the bound data props changes, the underlying `Effect` for that binding will re-evaluate, and all bound Configs will update.
 
-Important: The Config setter will only trigger in case there is a real change for the bound output.
+Important: The Config setter will only trigger in case there is a real change for the bound output, ensuring efficient updates.
 
 We also added 2 Buttons to change the value of each data prop, so that we can see that the bound Label texts
 update right away.
@@ -252,17 +308,82 @@ which contains the nested props `firstname` and `lastname`.
 We can bind to these nested props like before:</br>
 `bind: {text: data => data.user.firstname + ' ' + data.user.lastname}`
 
-Any change of a nested data prop will directly get reflected into the bound components.
+Any change of a nested data prop will directly trigger the associated `Effect` and get reflected into the bound components.
 
 We can update a nested data prop with passing its path:</br>
 `data => data.component.setState({'user.lastname': 'Rahder'})`
 
 Or we can directly pass the object containing the change(s):</br>
-`data => data.component.setState({user: {firstname: 'Max'}})`
+`data => data.component.setState({user: {firstname: 'Max'}})`</br>
+**Hint:** This will not override left out nested data props (lastname in this case).</br>
+**Hint:** This is the recommended way for bulk state changes.
+
+***You can also directly change state data***
+
+`data => data.component.setStateProvider().data.user.firstname = 'Max'`
+
+Shorthand syntax:</br>
+`data => data.component.data.user.firstname = 'Max'`
+
+### Formulas in Action
+
+```javascript live-preview
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../component/Label.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Guides.vmFormula.MainView',
+        stateProvider: {
+            data: {
+                price   : 10,
+                quantity: 2
+            },
+            formulas: {
+                total          : data => data.price * data.quantity,
+                discountedTotal: data => data.total * 0.9 // 10% discount
+            }
+        },
+        itemDefaults: {
+            module: Label,
+            style : {margin: '.5em 1em'}
+        },
+        items: [{
+            bind: {text: data => `Price: ${data.price}`}
+        }, {
+            bind: {text: data => `Quantity: ${data.quantity}`}
+        }, {
+            bind: {text: data => `Total: ${data.total}`}
+        }, {
+            bind: {text: data => `Discounted Total (10% off): ${data.discountedTotal.toFixed(2)}`}
+        }, {
+            module : Button,
+            handler: event => event.component.getStateProvider().data.price++,
+            text   : 'Increase Price'
+        }, {
+            module : Button,
+            // Shorthand syntax. Less descriptive, but works fine too.
+            handler: event => event.component.data.quantity++,
+            text   : 'Increase Quantity'
+        }],
+        layout: {ntype: 'vbox', align: 'start'}
+    }
+}
+MainView = Neo.setupClass(MainView);
+```
+This example demonstrates how formulas automatically react to changes in their dependencies.
+
+* We define `price` and `quantity` in the `data` config.
+  The `total` formula computes `data.price * data.quantity`.
+  The `discountedTotal` formula then computes `data.total * 0.9`.
 
-Hint: This will not override left out nested data props (lastname in this case).
+* When you click the "Increase Price" or "Increase Quantity" buttons, you'll observe that
+  `Total` and `Discounted Total` labels update automatically, showcasing the
+  effect-based reactivity of formulas.
 
 ### Dialog connecting to a Container
+
 ```javascript live-preview
 import Controller from '../controller/Component.mjs';
 import Dialog     from '../dialog/Base.mjs';
@@ -321,6 +442,7 @@ class MainContainerController extends Controller {
                 animateTargetId: me.getReference('edit-user-button').id,
                 appName        : me.component.appName,
                 closeAction    : 'hide',
+                modal          : true,
 
                 stateProvider: {
                     parent: me.getStateProvider()
@@ -382,9 +504,11 @@ MainView = Neo.setupClass(MainView);
 ```
 
 ## Class based State Providers
+
 When your stateProviders contain many data props or need custom logic, you can easily move them into their own classes.
 
 ### Direct Bindings
+
 ```javascript live-preview
 import Button        from '../button/Base.mjs';
 import Container     from '../container/Base.mjs';
@@ -497,15 +621,10 @@ class MainViewStateProvider extends StateProvider {
     static config = {
         className: 'Guides.vm7.MainViewStateProvider',
         
-        data: {
-            myStoreCount: 0
-        },
-        
         stores: {
             // Define a store using a class reference
             mySharedStore: {
-                module   : MyDataStore,
-                listeners: {countChange: 'onMyStoreCountChange'}
+                module   : MyDataStore
             },
             // Define another store using an inline configuration
             anotherStore: {
@@ -523,10 +642,6 @@ class MainViewStateProvider extends StateProvider {
             }
         }
     }
-
-    onMyStoreCountChange(data) {
-        this.data.myStoreCount = data.value // Reactive
-    }
 }
 MainViewStateProvider = Neo.setupClass(MainViewStateProvider);
 
@@ -556,7 +671,7 @@ class MainView extends Container {
                 module: Label,
                 style : {margin: 'auto'},
                 bind: {
-                    text: data => `Count: ${data.myStoreCount}`
+                    text: data => `Count: ${data.stores.mySharedStore.count}`
                 }
             }, {
                 module: Button,

package/learn/guides/datahandling/Tables.md

@@ -1 +1 @@
-## todo
+# Tables (Stores)

package/learn/guides/fundamentals/ConfigSystemDeepDive.md

@@ -1,3 +1,4 @@
+# Config System Deep Dive
 
 **Pre-requisite:** It is highly recommended to study [The Unified Class Config System](#/learn/benefits.ConfigSystem)
 first to understand the foundational concepts and benefits.

package/learn/guides/fundamentals/DeclarativeComponentTreesVsImperativeVdom.md

@@ -1,3 +1,5 @@
+# Declarative Component Trees VS Imperative Vdom
+
 ## Overview
 
 Neo.mjs employs a unique two-tier architecture that separates **declarative component configuration** from **imperative

package/learn/guides/fundamentals/DeclarativeVDOMWithEffects.md

@@ -0,0 +1,168 @@
+# Declarative VDOM with Effects
+
+## A New Approach: Declarative VDOM with Effects
+
+Neo.mjs v10 introduces a powerful new declarative pattern for defining a component's internal Virtual DOM (VDOM), serving as an alternative to the traditional imperative hook-based system. This approach, which leverages the new `Neo.core.Effect` class, allows developers to define a component's entire VDOM structure in a single, reactive function, similar to the `render()` method in React.
+
+This guide will walk you through the new pattern, compare it to the classic approach, and explain when to use each.
+
+## The Classic Pattern: Imperative Hooks
+
+Let's look at the traditional way a component like `Neo.button.Base` defines and updates its VDOM.
+
+**1. Initial VDOM Structure:**
+The base structure is defined in the `_vdom` config.
+
+```javascript readonly
+// Neo.button.Base
+class Button extends Component {
+    static config = {
+        _vdom: {
+            tag: 'button', type: 'button', cn: [
+                {tag: 'span', cls: ['neo-button-glyph']},
+                {tag: 'span', cls: ['neo-button-text']},
+                // ... and so on
+            ]
+        }
+    }
+}
+```
+
+**2. Imperative Updates:**
+To make the component reactive, developers must implement specific `afterSet` hooks for each config that affects the UI. The logic is imperative and fragmented.
+
+```javascript readonly
+// Neo.button.Base - internal framework code
+afterSetIconCls(value, oldValue) {
+    let {iconNode} = this;
+    // Imperative: Manually add/remove classes
+    NeoArray.remove(iconNode.cls, oldValue);
+    NeoArray.add(iconNode.cls, value);
+    this.update();
+}
+
+afterSetText(value, oldValue) {
+    let {textNode} = this;
+    // Imperative: Manually set properties
+    textNode.removeDom = !value;
+    textNode.text = value;
+    this.update();
+}
+
+afterSetPressed(value, oldValue) {
+    // Imperative: Manually toggle a class
+    NeoArray.toggle(this.cls, 'pressed', value);
+    this.update();
+}
+```
+
+**Pros:**
+*   **Performance:** Updates are surgical and extremely fast. Only the code for the changed property is executed.
+
+**Cons:**
+*   **High Cognitive Load:** To understand the component's full rendering logic, a developer must find and read multiple, separate methods.
+*   **Error-Prone:** Forgetting to implement a hook for a new config is a common source of bugs.
+
+## The New Pattern: Declarative VDOM with `Effect`
+
+The new `EffectButton` PoC demonstrates a more modern, declarative approach.
+
+**1. A Single, Reactive Render Function:**
+Instead of fragmented hooks, the entire VDOM is generated within a `Neo.core.Effect`. This effect automatically tracks its dependencies (like `this.text` or `this.pressed`) and re-runs whenever they change.
+
+```javascript readonly
+// button.Effect - The "Template Method"
+createVdomEffect() {
+    return new Effect(() => {
+        // The effect's only job is to get the config and trigger an update.
+        this._vdom = this.getVdomConfig();
+        this.update();
+    });
+}
+
+// The main VDOM builder
+getVdomConfig() {
+    return {
+        tag: this.pressed ? 'a' : 'button', // Declarative logic
+        cls: this.getVdomCls(),
+        cn: this.getVdomChildren()
+        // ... and so on
+    };
+}
+```
+
+**2. Centralized Logic:**
+All VDOM logic is co-located, making it easy to read and understand at a glance.
+
+```javascript readonly
+// button.Effect - Centralized class and child generation
+getVdomCls() {
+    let vdomCls = [...this.baseCls, ...this.cls];
+    // Declarative: Describe what the classes should be based on state
+    NeoArray.toggle(vdomCls, 'no-text', !this.text);
+    NeoArray.toggle(vdomCls, 'pressed', this.pressed);
+    vdomCls.push('icon-' + this.iconPosition);
+    return vdomCls;
+}
+
+getVdomChildren() {
+    return [
+        // Declarative: Describe the children based on state
+        {tag: 'span', cls: ['neo-button-glyph', ...this._iconCls || []], removeDom: !this.iconCls},
+        {tag: 'span', cls: ['neo-button-text'], removeDom: !this.text, text: this.text},
+        // ... and so on
+    ];
+}
+```
+
+## The Power of Inheritance
+
+A key challenge with a single render function is extensibility. The new pattern solves this by using a "Template Method" design. The main effect calls smaller, overridable builder methods.
+
+This allows a subclass like `tab.header.EffectButton` to easily extend the VDOM without duplicating code.
+
+```javascript readonly
+// tab.header.EffectButton
+class EffectTabButton extends EffectButton {
+    // Override to add the indicator child node
+    getVdomChildren() {
+        // Get the standard button children from the parent class
+        let children = super.getVdomChildren();
+
+        // Add the new indicator node
+        children.push({
+            cls: ['neo-tab-button-indicator'],
+            removeDom: !this.useActiveTabIndicator
+        });
+
+        return children;
+    }
+
+    // Override to add accessibility attributes
+    getVdomConfig() {
+        let vdomConfig = super.getVdomConfig();
+        vdomConfig.role = this.role;
+        if (this.pressed) {
+            vdomConfig['aria-selected'] = true;
+        }
+        return vdomConfig;
+    }
+}
+```
+
+## When to Use Each Pattern: A Hybrid Approach
+
+Neo.mjs v10 does not force you to choose one pattern over the other. Instead, it empowers you to use the right tool for the job.
+
+**Use the Declarative `Effect` Pattern when (Recommended Default):**
+*   Building most of your application components.
+*   You value developer experience, readability, and maintainability.
+*   The component's VDOM structure can be expressed as a pure function of its state.
+
+**Use the Imperative `afterSet` Pattern when:**
+*   You are building a highly complex, performance-critical component (e.g., a virtualized data grid or a canvas-based chart).
+*   You need to perform surgical, hand-tuned VDOM manipulations for maximum performance, bypassing a full recalculation.
+
+## Conclusion
+
+The new declarative VDOM pattern is a major leap forward for component development in Neo.mjs. It provides a more modern, readable, and robust way to build components, while the classic imperative pattern remains a powerful tool for fine-grained performance optimization. By understanding both, you can build sophisticated, high-performance applications with an exceptional developer experience.

package/learn/guides/fundamentals/ExtendingNeoClasses.md

@@ -1,3 +1,4 @@
+# Extending Neo Classes
 
 Neo.mjs is built upon a robust and consistent class system. Understanding how to extend framework classes is fundamental
 to building custom functionality, whether you're creating new UI components, defining data structures, or implementing

package/learn/guides/fundamentals/InstanceLifecycle.md

@@ -1,3 +1,5 @@
+# Instance Lifecycle
+
 Understanding the lifecycle of a class instance in Neo.mjs is crucial for building robust and predictable
 applications. The framework provides a series of well-defined hooks that allow you to tap into different stages of an
 instance's life, from its creation to its destruction.
@@ -292,4 +294,4 @@ With this pattern, the `columnPositions` collection is **not** created during th
 instantiated the very first time some other code calls `this.columnPositions`.
 
 Use the get-driven approach for non-essential or heavy nested instances to optimize performance and memory usage,
-especially if they are only used in specific scenarios.
+especially if they are only used in specific scenarios.

package/learn/guides/fundamentals/MainThreadAddons.md

@@ -1,3 +1,5 @@
+# Main Thread Addons: Interacting with the Browser
+
 Neo.mjs is multi-threaded. There are worker threads that handle data access, application logic, and
 keeping track of DOM updates. Practically all your application logic is run in parallel in these
 threads. However, anything that needs to actually reference or update the DOM (`window.document`),

package/learn/guides/specificfeatures/Mixins.md

@@ -1 +1,3 @@
-## todo
+# Mixins
+
+todo

package/learn/guides/specificfeatures/MultiWindow.md

@@ -1 +1,3 @@
-## todo
+# Multi-Window Applications
+
+todo

package/learn/guides/specificfeatures/PortalApp.md

@@ -1,3 +1,5 @@
+# Portal App
+
 ## Study the Code
 
 As you hopefully have noticed by now, this entire multi-window app is created based on Neo.mjs.

package/learn/guides/uibuildingblocks/ComponentsAndContainers.md

@@ -1,3 +1,5 @@
+# Component and Container Basics
+
 Neo.mjs views are made up of components and containers. 
 
 A component is a visual widget, such as a button, label, or text field. A container is a visual 

package/learn/guides/uibuildingblocks/CustomComponents.md

@@ -1,3 +1,5 @@
+# Custom Components
+
 ## Introduction
 
 A major strength of Neo.mjs is its extensive library of components. In most cases, you can build sophisticated

package/learn/guides/uibuildingblocks/Layouts.md

@@ -1,3 +1,5 @@
+# Layouts
+
 ## Understanding Layouts in Neo.mjs
 
 Layouts are fundamental to arranging components within your application's user interface. In Neo.mjs, layouts are

package/learn/guides/uibuildingblocks/WorkingWithVDom.md

@@ -1,3 +1,5 @@
+# Working with VDom
+
 ## A Comprehensive Guide to Custom Component Development
 
 **Target Audience**: Developers building custom Neo.mjs components who need to work directly with the VDom layer for performance optimization, complex animations, or advanced UI patterns.

package/learn/guides/userinteraction/Forms.md

@@ -1,3 +1,5 @@
+# User Input (Forms)
+
 The Neo.mjs Forms Engine provides a powerful and flexible way to build
 user interfaces for data input and validation. This guide will walk you
 through the core concepts and practical usage of forms in Neo.mjs,

package/learn/guides/userinteraction/events/CustomEvents.md

@@ -1,5 +1,6 @@
-As you read in the <a href="#/learn/Events">Getting Started > Events</a> topic, components, stores, and many other objects fire events.
+# Custom Events
 
+As you read in the <a href="#/learn/Events">Getting Started > Events</a> topic, components, stores, and many other objects fire events.
 
 ```javascript live-preview
 import Container from '../container/Base.mjs';

package/learn/guides/userinteraction/events/DomEvents.md

@@ -1,3 +1,5 @@
+# DOM Events
+
 ## Delegated global DOM Events
 
 By default, Neo.mjs will attach DOM event listeners for all common events to the `document.body`.

package/learn/javascript/ClassFeatures.md

@@ -1,5 +1,6 @@
-Neo.mjs uses standard modular JavaScript, so you're free to use other class 
-features, like private members.
+# Other JavaScript Class Features
+
+Neo.mjs uses standard modular JavaScript, so you're free to use other class features, like private members.
 
 ```javascript readonly
 class Human extends Mammal {
@@ -27,7 +28,7 @@ class Human extends Mammal {
     }
 }
 
-Neo.setupClass(Human);
+Human = Neo.setupClass(Human);
 
 const myPerson = Neo.create(Human, {
     name: 'Herbert'

package/learn/javascript/Classes.md

@@ -1,3 +1,5 @@
+# Classes, Properties, and Methods
+
 Neo.mjs classes are standard JavaScript classes. Every source file
 you write will be a class definition, extending some Neo.mjs
 class. 
@@ -13,8 +15,8 @@ class Mammal extends Base {
 
 const myMammal = Neo.create(Mammal);
 
-Neo.setupClass(Mammal); // Where Neo.mjs initializes the class config. 
-export default Mammal;        // Makes the class available elsewhere.
+// Where Neo.mjs initializes the class and makes the class available elsewhere.
+export default Neo.setupClass(Mammal);
 ```
 
 In the example above, we're extending the Neo.mjs base class. The static
@@ -40,16 +42,14 @@ class Mammal extends Base {
 }
 
 const myMammal = Neo.create(Mammal);
-console.log(myMammal.name);           // Logs "Anonymous"
+console.log(myMammal.name); // Logs "Anonymous"
 myMammal.name = 'Herbert';
-console.log(myMammal.name);           // Logs "Herbert"
-
-Neo.setupClass(Mammal);
+console.log(myMammal.name); // Logs "Herbert"
 
-export default Mammal;
+export default Neo.setupClass(Mammal);
 ```
 
-In Neo.mjs, instance properties are usually added in the `static config` block.
+In Neo.mjs, instance properties are usually added in the `static config` block.</br>
 The `static config` block does two things: 
 - It formally describes the properties API for your class.
 - It lets Neo.mjs manage the initialization and lifecycle of those properties.
@@ -65,10 +65,9 @@ the instance, using the second argument to the `create` method.
 const myMammal = Neo.create(Mammal, {
     name: 'Creature'
 });
-console.log(myMammal.name);           // Logs "Creature"
+console.log(myMammal.name); // Logs "Creature"
 ```
 
-
 Since _you_ define those properties, you can
 look for them in class methods and use them as needed.
 Let's add a `speak()` method that uses the `name` property.
@@ -93,9 +92,7 @@ const myMammal = Neo.create(Mammal, {
 
 myMammal.speak(); // Logs "Creature is grunting."
 
-Neo.setupClass(Mammal);
-
-export default Mammal;
+export default Neo.setupClass(Mammal);
 ```
 
 

package/learn/javascript/Overrides.md

@@ -1,3 +1,5 @@
+# Overriding Methods
+
 In Neo.mjs you sub-class and override methods in the usual way. 
 
 Here, we'll extend `Mammal` and override the `speak()` method. 
@@ -14,7 +16,7 @@ class Mammal extends Base {
         console.log(`(${this.name} is grunting)`);
     }
 }
-Neo.setupClass(Mammal);
+export default Neo.setupClass(Mammal);
 ```
 
 ```javascript readonly
@@ -30,9 +32,9 @@ class Human extends Mammal {
 const myMammal = Neo.create(Human, {
     name: 'Herbert'
 });
-myMammal.speak();        // Logs "Hello! My name is Herbert. I am not married."
+myMammal.speak(); // Logs "Hello! My name is Herbert. I am not married."
 
-Neo.setupClass(Mammal);
+export default Neo.setupClass(Human);
 ```
 
 Any class in the hierarchy is free to add new properties and methods. Let's add
@@ -51,6 +53,7 @@ class Mammal extends Base {
         console.log(`(${this.name} is grunting)`);
     }
 }
+export default Neo.setupClass(Mammal);
 ```
 
 ```javascript readonly
@@ -70,8 +73,9 @@ class Human extends Mammal {
 const myPerson = Neo.create(Human, {
     name: 'Herbert'
 });
-myPerson.speak();        // Logs "Hello! My name is Herbert. I am not married."
-myPerson.yodel();        // Logs "Yodelay hee hoo!"
 
-Neo.setupClass(Human);
+myPerson.speak(); // Logs "Hello! My name is Herbert. I am not married."
+myPerson.yodel(); // Logs "Yodelay hee hoo!"
+
+export default Neo.setupClass(Human);
 ```