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

package/.github/RELEASE_NOTES/v10.0.0-beta.4.md

@@ -13,8 +13,8 @@ The centerpiece of this release is the new reactive config system, internally na
         // In ComponentA
         const componentB = Neo.get('b');
 
-        // Subscribe to changes in componentB's 'items' config
-        this.cleanup = componentB.getConfig('items').subscribe((newValue, oldValue) => {
+        // Subscribe to changes in componentB's 'text' config
+        this.cleanup = componentB.getConfig('text').subscribe((newValue, oldValue) => {
             this.someOtherProperty = newValue; // Reactively update
         });
 

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='10.0.0-beta.4'
+         * @member {String} version='10.0.0-beta.5'
          */
-        version: '10.0.0-beta.4'
+        version: '10.0.0-beta.5'
     }
 
     /**

package/apps/portal/index.html

@@ -16,7 +16,7 @@
         "@type": "Organization",
         "name": "Neo.mjs"
       },
-      "datePublished": "2025-07-04",
+      "datePublished": "2025-07-09",
       "publisher": {
         "@type": "Organization",
         "name": "Neo.mjs"

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

@@ -107,7 +107,7 @@ class FooterContainer extends Container {
             }, {
                 module: Component,
                 cls   : ['neo-version'],
-                text  : 'v10.0.0-beta.4'
+                text  : 'v10.0.0-beta.5'
             }]
         }],
         /**

package/examples/button/effect/MainContainer.mjs

@@ -0,0 +1,207 @@
+import CheckBox              from '../../../src/form/field/CheckBox.mjs';
+import ComboBox              from '../../../src/form/field/ComboBox.mjs';
+import ConfigurationViewport from '../../ConfigurationViewport.mjs';
+import EffectButton          from '../../../src/button/Effect.mjs';
+import NumberField           from '../../../src/form/field/Number.mjs';
+import Radio                 from '../../../src/form/field/Radio.mjs';
+import TextField             from '../../../src/form/field/Text.mjs';
+
+/**
+ * @class Neo.examples.button.effect.MainContainer
+ * @extends Neo.examples.ConfigurationViewport
+ */
+class MainContainer extends ConfigurationViewport {
+    static config = {
+        className           : 'Neo.examples.button.effect.MainContainer',
+        configItemLabelWidth: 160,
+        configItemWidth     : 280,
+        layout              : {ntype: 'hbox', align: 'stretch'}
+    }
+
+    createConfigurationComponents() {
+        let me = this;
+
+        return [{
+            module        : Radio,
+            checked       : me.exampleComponent.badgePosition === 'bottom-left',
+            hideValueLabel: false,
+            labelText     : 'badgePosition',
+            listeners     : {change: me.onRadioChange.bind(me, 'badgePosition', 'bottom-left')},
+            name          : 'badgePosition',
+            valueLabelText: 'bottom-left'
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.badgePosition === 'bottom-right',
+            hideValueLabel: false,
+            labelText     : '',
+            listeners     : {change: me.onRadioChange.bind(me, 'badgePosition', 'bottom-right')},
+            name          : 'badgePosition',
+            valueLabelText: 'bottom-right'
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.badgePosition === 'top-left',
+            hideValueLabel: false,
+            labelText     : '',
+            listeners     : {change: me.onRadioChange.bind(me, 'badgePosition', 'top-left')},
+            name          : 'badgePosition',
+            valueLabelText: 'top-left'
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.badgePosition === 'top-right',
+            hideValueLabel: false,
+            labelText     : '',
+            listeners     : {change: me.onRadioChange.bind(me, 'badgePosition', 'top-right')},
+            name          : 'badgePosition',
+            valueLabelText: 'top-right'
+        }, {
+            module    :  TextField,
+            labelText : 'badgeText',
+            listeners : {change: me.onConfigChange.bind(me, 'badgeText')},
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.badgeText
+        }, {
+            module   : CheckBox,
+            checked  : me.exampleComponent.disabled,
+            labelText: 'disabled',
+            listeners: {change: me.onConfigChange.bind(me, 'disabled')},
+            style    : {marginTop: '10px'}
+        }, {
+            module    :  NumberField,
+            clearable : true,
+            labelText : 'height',
+            listeners : {change: me.onConfigChange.bind(me, 'height')},
+            maxValue  : 300,
+            minValue  : 30,
+            stepSize  : 5,
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.height
+        }, {
+            module    :  TextField, // todo: selectField with options
+            labelText : 'iconCls',
+            listeners : {change: me.onConfigChange.bind(me, 'iconCls')},
+            value     : me.exampleComponent.iconCls
+        }, {
+            module    :  TextField, // todo: colorPickerField
+            clearable : true,
+            labelText : 'iconColor',
+            listeners : {change: me.onConfigChange.bind(me, 'iconColor')},
+            value     : me.exampleComponent.iconColor
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.iconPosition === 'top',
+            hideValueLabel: false,
+            labelText     : 'iconPosition',
+            listeners     : {change: me.onRadioChange.bind(me, 'iconPosition', 'top')},
+            name          : 'iconPosition',
+            style         : {marginTop: '10px'},
+            valueLabelText: 'top'
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.iconPosition === 'right',
+            hideValueLabel: false,
+            labelText     : '',
+            listeners     : {change: me.onRadioChange.bind(me, 'iconPosition', 'right')},
+            name          : 'iconPosition',
+            valueLabelText: 'right'
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.iconPosition === 'bottom',
+            hideValueLabel: false,
+            labelText     : '',
+            listeners     : {change: me.onRadioChange.bind(me, 'iconPosition', 'bottom')},
+            name          : 'iconPosition',
+            valueLabelText: 'bottom'
+        }, {
+            module        : Radio,
+            checked       : me.exampleComponent.iconPosition === 'left',
+            hideValueLabel: false,
+            labelText     : '',
+            listeners     : {change: me.onRadioChange.bind(me, 'iconPosition', 'left')},
+            name          : 'iconPosition',
+            valueLabelText: 'left'
+        }, {
+            module    :  NumberField,
+            clearable : true,
+            labelText : 'rippleEffectDuration',
+            listeners : {change: me.onConfigChange.bind(me, 'rippleEffectDuration')},
+            maxValue  : 5000,
+            minValue  : 100,
+            stepSize  : 100,
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.rippleEffectDuration
+        }, {
+            module    :  TextField,
+            clearable : true,
+            labelText : 'text',
+            listeners : {change: me.onConfigChange.bind(me, 'text')},
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.text
+        }, {
+            module    :  TextField,
+            clearable : true,
+            labelText : 'tooltip',
+            listeners : {change: me.onConfigChange.bind(me, 'tooltip')},
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.tooltip
+        }, {
+            module        : ComboBox,
+            forceSelection: true,
+            labelText     : 'ui',
+            listeners     : {change: me.onConfigRecordChange.bind(me, 'ui')},
+            style         : {marginTop: '10px'},
+            value         : me.exampleComponent.ui,
+
+            store: {
+                data: [
+                    {id: 'primary',   name: 'primary'},
+                    {id: 'secondary', name: 'secondary'},
+                    {id: 'tertiary',  name: 'tertiary'}
+                ]
+            }
+        }, {
+            module   : CheckBox,
+            checked  : me.exampleComponent.useRippleEffect,
+            labelText: 'useRippleEffect',
+            listeners: {change: me.onConfigChange.bind(me, 'useRippleEffect')},
+            style    : {marginTop: '10px'}
+        }, {
+            module    :  NumberField,
+            clearable : true,
+            labelText : 'width',
+            listeners : {change: me.onConfigChange.bind(me, 'width')},
+            maxValue  : 300,
+            minValue  : 100,
+            stepSize  : 5,
+            style     : {marginTop: '10px'},
+            value     : me.exampleComponent.width
+        }];
+    }
+
+    /**
+     * @returns {Neo.component.Base}
+     */
+    createExampleComponent() {
+        return Neo.create({
+            module   : EffectButton,
+            badgeText: 'Badge',
+            flex     : 'none',
+            handler  : data => console.log('button click =>', data.component.id),
+            height   : 50,
+            iconCls  : 'fa fa-home',
+            style    : {marginBottom: '1500px', marginTop: '500px'},
+            text     : 'Hello World',
+            ui       : 'primary',
+            width    : 150
+        })
+    }
+
+    /**
+     * @param {String} config
+     * @param {Object} opts
+     */
+    onConfigRecordChange(config, opts) {
+        this.exampleComponent[config] = opts.value['id']
+    }
+}
+
+export default Neo.setupClass(MainContainer);

package/examples/button/effect/app.mjs

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

package/examples/button/effect/index.html

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

package/examples/button/effect/neo-config.json

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

package/learn/guides/datahandling/StateProviders.md

@@ -321,6 +321,7 @@ class MainContainerController extends Controller {
                 animateTargetId: me.getReference('edit-user-button').id,
                 appName        : me.component.appName,
                 closeAction    : 'hide',
+                modal          : true,
 
                 stateProvider: {
                     parent: me.getStateProvider()

package/learn/guides/fundamentals/DeclarativeVDOMWithEffects.md

@@ -0,0 +1,166 @@
+### 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({fn: () => {
+        // 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/tree.json

@@ -26,6 +26,7 @@
             {"name": "Application Bootstrap",                            "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/ApplicationBootstrap"},
             {"name": "Instance Lifecycle",                               "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/InstanceLifecycle"},
             {"name": "Declarative Component Trees VS Imperative Vdom",   "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/DeclarativeComponentTreesVsImperativeVdom"},
+            {"name": "Declarative VDOM with Effects",                    "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/DeclarativeVDOMWithEffects"},
             {"name": "Config System Deep Dive",                          "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/ConfigSystemDeepDive"},
             {"name": "Extending Neo Classes",                            "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/ExtendingNeoClasses"},
             {"name": "Main Thread Addons: Interacting with the Browser", "parentId": "guides/fundamentals",                                 "id": "guides/fundamentals/MainThreadAddons"},

package/package.json

@@ -1,6 +1,6 @@
 {
     "name"           : "neo.mjs",
-    "version"        : "10.0.0-beta.4",
+    "version"        : "10.0.0-beta.5",
     "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"     : {
@@ -96,7 +96,7 @@
         "siesta-lite"                  : "5.5.2",
         "terser"                       : "^5.43.1",
         "url"                          : "^0.11.4",
-        "webpack"                      : "^5.99.9",
+        "webpack"                      : "^5.100.0",
         "webpack-cli"                  : "^6.0.1",
         "webpack-dev-server"           : "^5.2.2",
         "webpack-hook-plugin"          : "^1.0.7",

package/src/DefaultConfig.mjs

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