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

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

@@ -0,0 +1,41 @@
+## Neo.mjs v10.0.0-beta.4 Release Notes
+
+This beta release introduces a powerful, opt-in **Reactive Config System**, a foundational architectural enhancement that enables fine-grained, cross-instance state management and significantly improves the developer experience for building complex, interactive applications.
+
+### Core Framework & Features
+
+The centerpiece of this release is the new reactive config system, internally named "Config Atoms". This system is fully opt-in and backward compatible, ensuring that existing applications continue to work without any changes.
+
+*   **New Reactive Config System ("Config Atoms")**:
+    *   **Opt-in Reactivity**: By adding a trailing underscore (`_`) to a config property in its `static config` block (e.g., `myValue_`), the property becomes "reactive." It is automatically wrapped in a `Neo.core.Config` instance, which acts as an observable container for its value.
+    *   **Cross-Instance State Sharing**: The new system exposes a `subscribe()` method on each reactive config, allowing components to listen for changes to a config on any other component instance. This enables a clean, decoupled, and highly efficient way to implement cross-component state synchronization.
+        ```javascript
+        // In ComponentA
+        const componentB = Neo.get('b');
+
+        // Subscribe to changes in componentB's 'text' config
+        this.cleanup = componentB.getConfig('text').subscribe((newValue, oldValue) => {
+            this.someOtherProperty = newValue; // Reactively update
+        });
+
+        // In ComponentA's destroy() method:
+        this.cleanup?.(); // Simple, clean, and prevents memory leaks.
+        ```
+    *   **Fine-Grained Control (Future Foundation)**: While not fully implemented in this beta, the groundwork is laid for using config descriptors to define custom `mergeStrategy` and `isEqual` functions, which will provide even more control over config behavior in a future release.
+    *   **Transactional Consistency**: The new system fully integrates with Neo.mjs's existing transactional update mechanism (`set()`), ensuring that `afterSet` hooks always have a consistent view of all pending config changes within a single operation.
+
+### Developer Experience
+
+*   **Simplified State Management**: The `subscribe()` API drastically simplifies the logic required for components to react to state changes in other parts of the application, reducing boilerplate and the need for complex event chains.
+*   **Improved Debugging**: The observable nature of reactive configs makes it easier to trace how and when state changes occur throughout your application.
+
+---
+
+This release marks a significant step forward in the evolution of the Neo.mjs architecture. The new reactive config system provides a robust foundation for building the next generation of highly interactive and state-driven web applications.
+
+### Call To Action
+
+We are incredibly excited for you to start experimenting with this powerful new feature!
+
+*   **Try Reactive Configs**: Start by making a config reactive by adding a `_` to its name in the `static config` block and explore the new possibilities with `getConfig().subscribe()`.
+*   **Share Your Feedback**: This is a foundational change, and your feedback is more critical than ever. Please share your experiences, report any issues, or suggest improvements via [GitHub Issues](https://github.com/neomjs/neo/issues) or our [Slack Channel](https://join.slack.com/t/neomjs/shared_invite/zt-6c50ueeu-3E1~M4T9xkNnb~M_prEEOA).

package/ServiceWorker.mjs

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

package/apps/portal/index.html

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

package/apps/portal/view/ViewportController.mjs

@@ -50,7 +50,7 @@ class ViewportController extends Controller {
             '/examples/{itemId}': 'onExamplesRoute',
             '/home'             : 'onHomeRoute',
             '/learn'            : 'onLearnRoute',
-            '/learn/{itemId}'   : 'onLearnRoute',
+            '/learn/{*itemId}'  : 'onLearnRoute',
             '/services'         : 'onServicesRoute'
         },
         /**

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.3'
+                text  : 'v10.0.0-beta.5'
             }]
         }],
         /**

package/apps/portal/view/learn/MainContainerController.mjs

@@ -17,8 +17,8 @@ class MainContainerController extends Controller {
          * @member {Object} routes
          */
         routes: {
-            '/learn'         : 'onRouteDefault',
-            '/learn/{itemId}': 'onRouteLearnItem'
+            '/learn'          : 'onRouteDefault',
+            '/learn/{*itemId}': 'onRouteLearnItem'
         }
     }
 
@@ -118,7 +118,7 @@ class MainContainerController extends Controller {
      */
     onRouteDefault(data) {
         if (!this.getStateProvider().data.currentPageRecord) {
-            this.onRouteLearnItem({itemId: 'benefits.Introduction'})
+            this.onRouteLearnItem({itemId: 'benefits/Introduction'})
         }
     }
 
@@ -126,15 +126,15 @@ class MainContainerController extends Controller {
      * @param {Object} data
      * @param {String} data.itemId
      */
-    onRouteLearnItem(data) {
+    onRouteLearnItem({itemId}) {
         let stateProvider = this.getStateProvider(),
             store         = stateProvider.getStore('contentTree');
 
         if (store.getCount() > 0) {
-            stateProvider.data.currentPageRecord = store.get(data.itemId)
+            stateProvider.data.currentPageRecord = store.get(itemId)
         } else {
             store.on({
-                load : () => {stateProvider.data.currentPageRecord = store.get(data.itemId)},
+                load : () => {stateProvider.data.currentPageRecord = store.get(itemId)},
                 delay: 10,
                 once : true
             })

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/{Collections.md → datahandling/Collections.md}

@@ -95,7 +95,7 @@ The `sourceId` concept provides an elegant solution:
   Set its `sourceId` to the ID of your primary store. This combobox store can then apply its own filters (e.g., based on
   user input in the combobox field) and sorters, completely independently of the grid store or the primary store.
 
-```javascript
+```javascript readonly
 import Collection from '../../src/collection/Base.mjs';
 import Filter     from '../../src/collection/Filter.mjs';
 
@@ -161,7 +161,7 @@ application to work with synchronized data while maintaining their own independe
 
 ### Example: Basic Collection Usage
 
-```javascript
+```javascript readonly
 import Collection from '../../src/collection/Base.mjs';
 
 const myCollection = Neo.create(Collection, {
@@ -198,7 +198,7 @@ instances based on the store's model definition.
 
 ### Example: Adding and Removing
 
-```javascript
+```javascript readonly
 import Collection from '../../src/collection/Base.mjs';
 
 const users = Neo.create(Collection, {
@@ -253,7 +253,7 @@ instances.**
 
 ### Example: Filtering a Collection
 
-```javascript
+```javascript readonly
 import Collection from '../../src/collection/Base.mjs';
 import Filter     from '../../src/collection/Filter.mjs';
 
@@ -323,7 +323,7 @@ instances.**
 
 ### Example: Sorting a Collection
 
-```javascript
+```javascript readonly
 import Collection from '../../src/collection/Base.mjs';
 import Sorter     from '../../src/collection/Sorter.mjs';
 
@@ -364,7 +364,7 @@ any operation that changes the collection's items.
 
 ### Example: Listening to Collection Events
 
-```javascript
+```javascript readonly
 import Collection from '../../src/collection/Base.mjs';
 
 const tasks = Neo.create(Collection, {