neo.mjs 10.0.0-alpha.2 → 10.0.0-alpha.4

package/learn/tree.json

@@ -0,0 +1,53 @@
+{"data": [
+    {"name": "Using These Topics",                                 "parentId": null,                                 "id": "UsingTheseTopics" },
+    {"name": "Benefits",                                           "parentId": null,                "isLeaf": false, "id": "Benefits"},
+        {"name": "Introduction ",                                  "parentId": "Benefits",                           "id": "benefits.Introduction"},
+        {"name": "Off the Main Thread",                            "parentId": "Benefits",                           "id": "benefits.OffTheMainThread"},
+        {"name": "4 Environments",                                 "parentId": "Benefits",                           "id": "benefits.FourEnvironments"},
+        {"name": "Unified Config System",                          "parentId": "Benefits",                           "id": "benefits.ConfigSystem"},
+        {"name": "Extreme Speed",                                  "parentId": "Benefits",                           "id": "benefits.Speed"},
+        {"name": "Multi-Window Applications",                      "parentId": "Benefits",                           "id": "benefits.MultiWindow"},
+        {"name": "Quick Application Development",                  "parentId": "Benefits",                           "id": "benefits.Quick"},
+        {"name": "Complexity and Effort",                          "parentId": "Benefits",                           "id": "benefits.Effort"},
+        {"name": "Forms Engine",                                   "parentId": "Benefits",                           "id": "benefits.FormsEngine"},
+        {"name": "Features and Benefits Summary",                  "parentId": "Benefits",                           "id": "benefits.Features"},
+    {"name": "Getting Started",                                    "parentId": null,                "isLeaf": false, "id": "GettingStarted", "collapsed": true},
+        {"name": "Setup",                                          "parentId": "GettingStarted",                     "id": "gettingstarted.Setup"},
+        {"name": "Workspaces and Applications",                    "parentId": "GettingStarted",                     "id": "gettingstarted.Workspaces"},
+        {"name": "Describing a View",                              "parentId": "GettingStarted",                     "id": "gettingstarted.DescribingTheUI"},
+        {"name": "Events",                                         "parentId": "GettingStarted",                     "id": "gettingstarted.Events"},
+        {"name": "Component References",                           "parentId": "GettingStarted",                     "id": "gettingstarted.References"},
+        {"name": "Extending Classes",                              "parentId": "GettingStarted",                     "id": "gettingstarted.Extending"},
+        {"name": "Config",                                         "parentId": "GettingStarted",                     "id": "gettingstarted.Config"},
+        {"name": "Shared Bindable Data",                           "parentId": "GettingStarted",                     "id": "gettingstarted.ComponentModels"},
+    {"name": "Guides",                                             "parentId": null,                "isLeaf": false, "id": "InDepth",  "collapsed": true},
+        {"name": "Application Bootstrap",                          "parentId": "InDepth",                            "id": "guides.ApplicationBootstrap"},
+        {"name": "Declarative Component Trees VS Imperative Vdom", "parentId": "InDepth",                            "id": "guides.DeclarativeComponentTreesVsImperativeVdom"},
+        {"name": "Working with VDom",                              "parentId": "InDepth",                            "id": "guides.WorkingWithVDom"},
+        {"name": "Instance Lifecycle",                             "parentId": "InDepth",                            "id": "guides.InstanceLifecycle", "hidden": true},
+        {"name": "User Input (Forms)",                             "parentId": "InDepth",                            "id": "guides.Forms",  "hidden": true},
+        {"name": "Component and Container Basics",                "parentId": "InDepth",                            "id": "guides.ComponentsAndContainers"},
+        {"name": "Layouts",                                        "parentId": "InDepth",           "isLeaf": false, "id": "guides.Layouts", "hidden": true},
+        {"name": "Shared Bindable Data (State Providers)",         "parentId": "InDepth",                            "id": "guides.StateProviders"},
+        {"name": "Custom Components",                              "parentId": "InDepth",                            "id": "guides.CustomComponents", "hidden": true},
+        {"name": "Events",                                         "parentId": "InDepth",           "isLeaf": false, "id": "GuideEvents"},
+            {"name": "Custom Events",                              "parentId": "GuideEvents",                        "id": "guides.events.CustomEvents"},
+            {"name": "DOM Events",                                 "parentId": "GuideEvents",                        "id": "guides.events.DomEvents"},
+        {"name": "Portal App",                                     "parentId": "InDepth",                            "id": "guides.PortalApp"},
+        {"name": "Tables (Stores)",                                "parentId": "InDepth",                            "id": "guides.Tables", "hidden": true},
+        {"name": "Multi-Window Applications",                      "parentId": "InDepth",                            "id": "guides.MultiWindow", "hidden":  true},
+        {"name": "Main Thread Addons",                             "parentId": "InDepth",           "isLeaf": false, "id": "MainThreadAddons", "hidden": true},
+            {"name": "Introduction",                               "parentId": "MainThreadAddons",                   "id": "guides.MainThreadAddonIntro"},
+            {"name": "Example",                                    "parentId": "MainThreadAddons",                   "id": "guides.MainThreadAddonExample"},
+        {"name": "Mixins",                                         "parentId": "InDepth",                            "id": "guides.Mixins", "hidden": true},
+    {"name": "Tutorials",                                          "parentId": null,                "isLeaf": false, "id": "Tutorials",  "collapsed": true},
+        {"name": "Rock Scissors Paper",                            "parentId": "Tutorials",                          "id": "tutorials.RSP", "hidden": true},
+        {"name": "Earthquakes",                                    "parentId": "Tutorials",                          "id": "tutorials.Earthquakes"},
+        {"name": "Todo List",                                      "parentId": "Tutorials",                          "id": "tutorials.TodoList"},
+    {"name": "JavaScript Classes",                                 "parentId": null,                "isLeaf": false, "id": "JavaScript", "hidden": true},
+        {"name": "Classes, Properties, and Methods",               "parentId": "JavaScript",                         "id": "javascript.Classes"},
+        {"name": "Overriding Methods",                             "parentId": "JavaScript",                         "id": "javascript.Overrides"},
+        {"name": "Other JavaScript Class Features",                "parentId": "JavaScript",                         "id": "javascript.ClassFeatures"},
+        {"name": "Super",                                          "parentId": "JavaScript",                         "id": "javascript.Super"},
+        {"name": "New Node",                                       "parentId": "JavaScript",                         "id": "javascript.NewNode"}
+]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name"           : "neo.mjs",
-    "version"        : "10.0.0-alpha.2",
+    "version"        : "10.0.0-alpha.4",
     "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"     : {
@@ -94,7 +94,7 @@
         "postcss"                      : "^8.5.6",
         "sass"                         : "^1.89.2",
         "siesta-lite"                  : "5.5.2",
-        "terser"                       : "^5.43.0",
+        "terser"                       : "^5.43.1",
         "url"                          : "^0.11.4",
         "webpack"                      : "^5.99.9",
         "webpack-cli"                  : "^6.0.1",

package/src/DefaultConfig.mjs

@@ -200,6 +200,31 @@ const DefaultConfig = {
      * @type Boolean
      */
     useCanvasWorker: false,
+    /**
+     * `true` will enable the advanced, secure, and performant direct DOM API rendering strategy (recommended).
+     * In this mode, `Neo.vdom.Helper` will create and send structured VNode object graphs to the Main Thread.
+     * `Neo.main.DeltaUpdates` will then use `Neo.main.render.DomApiRenderer` to directly manipulate the DOM.
+     * Crucially, `Neo.main.render.DomApiRenderer` builds new **DOM subtrees** (from the received VNode object graphs)
+     * as detached DocumentFragments or elements, entirely outside the live DOM tree.
+     * These fully constructed fragments are then inserted into the live document in a **single, atomic operation**.
+     * This approach inherently minimizes costly browser reflows/repaints, drastically reduces Cross-Site Scripting (XSS) risks,
+     * and optimizes for surgical, atomic DOM updates for unparalleled performance.
+     *
+     * `false` will enable the legacy string-based rendering strategy.
+     * In this mode, `Neo.vdom.Helper` will generate complete HTML strings (`outerHTML`) for VNode subtrees.
+     * `Neo.main.DeltaUpdates` will then use `Neo.main.render.StringBasedRenderer` to insert these
+     * strings into the DOM using methods like `parentNode.insertAdjacentHTML()`.
+     * While performant for large insertions, this mode is generally less secure due to potential XSS vectors
+     * and relies on browser HTML parsing, which can be less efficient for granular updates.
+     *
+     * This configuration affects both the initial painting of your applications and the creation
+     * of new component trees at runtime.
+     * @default true
+     * @memberOf! module:Neo
+     * @name config.useDomApiRenderer
+     * @type Boolean
+     */
+    useDomApiRenderer: true,
     /**
      * Flag if vdom ids should get mapped into DOM element ids.
      * false will convert them into a "data-neo-id" attribute.
@@ -246,18 +271,6 @@ const DefaultConfig = {
      * @type Boolean
      */
     useSharedWorkers: false,
-    /**
-     * `true` will let the `vdom.Helper` create a String-based representation of the vnode tree.
-     * Main will then use e.g.`parentNode.insertAdjacentHTML('beforeend', delta.outerHTML);`
-     * This affects the initial painting of your apps, but also the creation of new component trees at run-time.
-     * `false` will skip the creation of the String, and instead use DOM APIs to generate a fragment inside Main,
-     * into which the vnode tree will get applied.
-     * @default false
-     * @memberOf! module:Neo
-     * @name config.useStringBasedMounting
-     * @type Boolean
-     */
-    useStringBasedMounting: false,
     /**
      * True will generate a new task worker, which can get filled with own expensive remote methods
      * @default false
@@ -276,12 +289,12 @@ const DefaultConfig = {
     useVdomWorker: true,
     /**
      * buildScripts/injectPackageVersion.mjs will update this value
-     * @default '10.0.0-alpha.2'
+     * @default '10.0.0-alpha.4'
      * @memberOf! module:Neo
      * @name config.version
      * @type String
      */
-    version: '10.0.0-alpha.2'
+    version: '10.0.0-alpha.4'
 };
 
 Object.assign(DefaultConfig, {

package/src/Main.mjs

@@ -42,7 +42,7 @@ class Main extends core.Base {
         readQueue: [],
         /**
          * Remote method access for other workers
-         * @member {Object} remote={app: [//...]}
+         * @member {Object} remote
          * @protected
          */
         remote: {
@@ -252,12 +252,6 @@ class Main extends core.Base {
 
         DomAccess.onDomContentLoaded();
 
-        // We need different publicPath values for the main thread inside the webpack based dist envs,
-        // depending on the hierarchy level of the app entry point
-        if (environment === 'dist/development' || environment === 'dist/production') {
-            __webpack_require__.p = config.basePath.substring(6)
-        }
-
         // Intended for the online examples where we need an easy way to add GA to every generated app
         if (config.useGoogleAnalytics && !mainThreadAddons.includes('AnalyticsByGoogle')) {
             mainThreadAddons.push('AnalyticsByGoogle')

package/src/Neo.mjs

@@ -436,6 +436,22 @@ Neo = globalThis.Neo = Object.assign({
         return Neo.create(className, config)
     },
 
+    /**
+     * Updates the global Neo.config object across all active workers and connected browser windows.
+     *
+     * This is the unified entry point for changing global framework configurations.
+     * The framework automatically handles the complex multi-threaded and multi-window
+     * synchronization (via App Workers and Shared Workers, if active), ensuring
+     * consistency across the entire application without boilerplate.
+     *
+     * You can pass a partial config object to update specific keys.
+     * For nested objects, Neo.mjs performs a deep merge to preserve existing properties.
+     *
+     * @memberOf module:Neo
+     * @function setGlobalConfig
+     * @param {Object} config The partial or full Neo.config object with changes to apply.
+     */
+
     /**
      * Internally used at the end of each class / module definition
      * @memberOf module:Neo

package/src/button/Base.mjs

@@ -225,8 +225,8 @@ class Button extends Component {
     afterSetBadgeText(value, oldValue) {
         let {badgeNode} = this;
 
-        badgeNode.html      = value;
         badgeNode.removeDom = !Boolean(value);
+        badgeNode.text      = value;
 
         this.update()
     }
@@ -380,7 +380,7 @@ class Button extends Component {
         textNode.removeDom = isEmpty;
 
         if (!isEmpty) {
-            textNode.html = value
+            textNode.text = value
         }
 
         me.update()

package/src/calendar/view/MainContainerStateProvider.mjs

@@ -154,7 +154,7 @@ class MainContainerStateProvider extends StateProvider {
 
         let {data} = this;
 
-        switch(key) {
+        switch (key) {
             case 'locale': {
                 data.intlFormat_time = new Intl.DateTimeFormat(value, data.timeFormat);
                 break

package/src/grid/header/Button.mjs

@@ -96,7 +96,7 @@ class Button extends BaseButton {
             {cls}     = me,
             container = me.up('grid-container');
 
-        switch(value) {
+        switch (value) {
             case null:
                 NeoArray.add(cls, 'neo-sort-hidden');
                 break

package/src/layout/Cube.mjs

@@ -258,7 +258,7 @@ class Cube extends Card {
         if (index < 6) {
             wrapperCls = NeoArray.union(wrapperCls, 'neo-face', Object.keys(Cube.faces)[index]);
 
-            switch(index) {
+            switch (index) {
                 case 0:
                 case 1:
                     wrapperCls = NeoArray.union(wrapperCls, 'neo-face-z');
@@ -341,7 +341,7 @@ class Cube extends Card {
         if (index < 6) {
             NeoArray.remove(wrapperCls, ['neo-face', Object.keys(Cube.faces)[index]]);
 
-            switch(index) {
+            switch (index) {
                 case 0:
                 case 1:
                     NeoArray.remove(wrapperCls, 'neo-face-z');

package/src/main/DeltaUpdates.mjs

@@ -54,7 +54,6 @@ class DeltaUpdates extends Base {
      * @private
      */
     #renderer = null
-
     /**
      * Private property to signal that the renderer module has been loaded.
      * This will be a Promise that resolves when the module is ready.
@@ -69,21 +68,28 @@ class DeltaUpdates extends Base {
     construct(config) {
         super.construct(config);
 
-        let me = this;
+        let me            = this,
+            {environment} = NeoConfig;
 
-        if (Neo.config.renderCountDeltas) {
+        if (NeoConfig.renderCountDeltas) {
             me.renderCountDeltas = true
         }
 
+        // We need different publicPath values for the main thread inside the webpack based dist envs,
+        // depending on the hierarchy level of the app entry point
+        if (environment === 'dist/development' || environment === 'dist/production') {
+            __webpack_require__.p = NeoConfig.basePath.substring(6)
+        }
+
         // Initiate the asynchronous loading of the renderer here.
         me.#_readyPromise = (async () => {
             try {
                 let module;
 
-                if (NeoConfig.useStringBasedMounting) {
-                    module = await import('./render/StringBasedRenderer.mjs')
-                } else {
+                if (NeoConfig.useDomApiRenderer) {
                     module = await import('./render/DomApiRenderer.mjs')
+                } else {
+                    module = await import('./render/StringBasedRenderer.mjs')
                 }
 
                 me.#renderer = module.default
@@ -168,7 +174,7 @@ class DeltaUpdates extends Base {
      * - `insertAdjacentHTML()` is generally faster than creating a node via template,
      *   but it's only available for manipulating children (elements), not `childNodes` (all nodes).
      * - For performance, in cases where there are no comment nodes (i.e., no wrapped text nodes),
-     *   the method prioritizes `insertAdjacentHTML()` when `useStringBasedMounting` is true.
+     *   the method prioritizes `insertAdjacentHTML()` when `useDomApiRenderer` is false.
      *
      * @param {Object}         delta
      * @param {Boolean}        delta.hasLeadingTextChildren Flag to honor leading comments, which require special treatment.
@@ -178,8 +184,10 @@ class DeltaUpdates extends Base {
      * @param {Neo.vdom.VNode} [delta.vnode]                The VNode representation of the new node (for direct DOM API mounting).
      */
     insertNode({hasLeadingTextChildren, index, outerHTML, parentId, vnode}) {
+        let me = this;
+
         // This method is synchronous and *expects* the renderer to be loaded
-        if (!this.#renderer) {
+        if (!me.#renderer) {
             console.error('DeltaUpdates renderer not ready during insertNode!');
             return
         }
@@ -187,10 +195,10 @@ class DeltaUpdates extends Base {
         const parentNode = DomAccess.getElementOrBody(parentId);
 
         if (parentNode) {
-            if (!NeoConfig.useStringBasedMounting) {
-                this.#renderer.createDomTree({index, isRoot: true, parentNode, vnode})
+            if (NeoConfig.useDomApiRenderer) {
+                me.#renderer.createDomTree({index, isRoot: true, parentNode, vnode})
             } else {
-                this.#renderer.insertNodeAsString({hasLeadingTextChildren, index, outerHTML, parentNode})
+                me.#renderer.insertNodeAsString({hasLeadingTextChildren, index, outerHTML, parentNode})
             }
         }
     }
@@ -324,7 +332,7 @@ class DeltaUpdates extends Base {
 
         if (node) {
             Object.entries(delta).forEach(([prop, value]) => {
-                switch(prop) {
+                switch (prop) {
                     case 'attributes':
                         Object.entries(value).forEach(([key, val]) => {
                             if (voidAttributes.has(key)) {

package/src/main/addon/Navigator.mjs

@@ -212,7 +212,7 @@ class Navigator extends Base {
         let {key, target} = keyEvent,
             newActiveElement;
 
-        switch(key) {
+        switch (key) {
             // Move to the previous navigable item
             case data.previousKey:
                 newActiveElement = me.navigateGetAdjacent(-1, data);

package/src/main/addon/WindowPosition.mjs

@@ -156,7 +156,7 @@ class WindowPosition extends Base {
             {screenLeft, screenTop} = win,
             left, top;
 
-        switch(data.dock) {
+        switch (data.dock) {
             case 'bottom':
                 left = screenLeft;
                 top  = win.outerHeight + screenTop - 62;

package/src/main/render/StringBasedRenderer.mjs

@@ -11,7 +11,7 @@ const StringBasedRenderer = {
 
     /**
      * Handles string-based insertion of a new node into the DOM.
-     * This method is called by `insertNode()` when `NeoConfig.useStringBasedMounting` is true.
+     * This method is called by `insertNode()` when `NeoConfig.useDomApiRenderer` is false.
      *
      * @param {Object}      data
      * @param {Boolean}     data.hasLeadingTextChildren Flag to honor leading comments.

package/src/tab/header/Toolbar.mjs

@@ -92,7 +92,7 @@ class Toolbar extends BaseToolbar {
     getLayoutConfig() {
         let layoutConfig;
 
-        switch(this.dock) {
+        switch (this.dock) {
             case 'bottom':
             case 'top':
                 layoutConfig = {

package/src/table/header/Button.mjs

@@ -121,7 +121,7 @@ class Button extends BaseButton {
             {cls}     = me,
             container = me.up('table-container');
 
-        switch(value) {
+        switch (value) {
             case null:
                 NeoArray.add(cls, 'neo-sort-hidden');
                 break

package/src/toolbar/Base.mjs

@@ -177,7 +177,7 @@ class Toolbar extends Container {
             layoutConfig;
 
         if (me.dock) {
-            switch(me.dock) {
+            switch (me.dock) {
                 case 'bottom':
                 case 'top':
                     layoutConfig = {

package/src/util/VDom.mjs

@@ -66,7 +66,7 @@ class VDom extends Base {
 
         optsArray.forEach(([key, value]) => {
             if (vdom.hasOwnProperty(key)) {
-                switch(key) {
+                switch (key) {
                     case 'cls':
                         if (typeof value === 'string' && Neo.isArray(vdom[key])) {
                             if (vdom[key].includes(value)) {

package/src/util/VNode.mjs

@@ -43,7 +43,7 @@ class VNode extends Base {
 
         optsArray.forEach(([key, value]) => {
             if (vnode.hasOwnProperty(key)) {
-                switch(key) {
+                switch (key) {
                     case 'attributes':
                         if (Neo.isObject(value) && Neo.isObject(vnode[key])) {
                             Object.entries(value).forEach(([attrKey, attrValue]) => {