Neo.config.useStringBasedMounting => useDomApiRenderer #6842

Author: tobiu

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

src/main/DeltaUpdates.mjs

@@ -87,10 +87,10 @@ class DeltaUpdates extends Base {
             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
@@ -175,7 +175,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.
@@ -185,19 +185,21 @@ 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
         }
 
         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})
             }
         }
     }

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.

src/vdom/Helper.mjs

@@ -148,7 +148,7 @@ class Helper extends Base {
     /**
      * Creates a Neo.vdom.VNode tree for the given vdom template.
      * The top level vnode contains the outerHTML as a string,
-     * in case Neo.config.useStringBasedMounting === true
+     * in case Neo.config.useDomApiRenderer === false
      * @param {Object} opts
      * @param {String} opts.appName
      * @param {Boolean} [opts.autoMount]
@@ -170,7 +170,7 @@ class Helper extends Base {
 
         delete returnValue.vdom;
 
-        if (NeoConfig.useStringBasedMounting) {
+        if (!NeoConfig.useDomApiRenderer) {
             returnValue.outerHTML = Neo.vdom.util.StringFromVnode.create(vnode)
         }
 
@@ -474,7 +474,7 @@ class Helper extends Base {
      * @protected
      */
     async importDomApiVnodeCreator() {
-        if (!NeoConfig.useStringBasedMounting && !Neo.vdom.util?.DomApiVnodeCreator) {
+        if (NeoConfig.useDomApiRenderer && !Neo.vdom.util?.DomApiVnodeCreator) {
             await import('./util/DomApiVnodeCreator.mjs')
         }
     }
@@ -485,7 +485,7 @@ class Helper extends Base {
      * @protected
      */
     async importStringFromVnode() {
-        if (NeoConfig.useStringBasedMounting && !Neo.vdom.util?.StringFromVnode) {
+        if (!NeoConfig.useDomApiRenderer && !Neo.vdom.util?.StringFromVnode) {
             await import('./util/StringFromVnode.mjs')
         }
     }
@@ -511,12 +511,12 @@ class Helper extends Base {
 
         Object.assign(delta, {hasLeadingTextChildren, index: physicalIndex});
 
-        if (NeoConfig.useStringBasedMounting) {
-            // For string-based mounting, pass a string excluding moved nodes
-            delta.outerHTML = Neo.vdom.util.StringFromVnode.create(vnode, movedNodes)
-        } else {
+        if (NeoConfig.useDomApiRenderer) {
             // For direct DOM API mounting, pass the pruned VNode tree
             delta.vnode = Neo.vdom.util.DomApiVnodeCreator.create(vnode, movedNodes)
+        } else {
+            // For string-based mounting, pass a string excluding moved nodes
+            delta.outerHTML = Neo.vdom.util.StringFromVnode.create(vnode, movedNodes)
         }
 
         deltas.default.push(delta);

src/vdom/VNode.mjs

@@ -88,7 +88,7 @@ class VNode {
 
             // We only apply textContent, in case it has content
             else if (Object.hasOwn(config, 'textContent')) {
-                me.textContent = Neo.config.useStringBasedMounting ? StringUtil.escapeHtml(textContent) : textContent
+                me.textContent = Neo.config.useDomApiRenderer ? textContent : StringUtil.escapeHtml(textContent)
             }
         }