neo.mjs 9.16.0 → 10.0.0-alpha.1

package/src/main/DeltaUpdates.mjs

@@ -0,0 +1,382 @@
+import Base             from '../core/Base.mjs';
+import DomAccess        from './DomAccess.mjs';
+import {voidAttributes} from '../vdom/domConstants.mjs';
+
+const NeoConfig = Neo.config;
+
+/**
+ * Logic to apply the deltas generated by vdom.Helper to the real DOM
+ * @class Neo.main.DeltaUpdates
+ * @extends Neo.core.Base
+ * @singleton
+ */
+class DeltaUpdates extends Base {
+    static config = {
+        /**
+         * @member {String} className='Neo.main.DeltaUpdates'
+         * @protected
+         */
+        className: 'Neo.main.DeltaUpdates',
+        /**
+         * @member {Boolean} singleton=true
+         */
+        singleton: true
+    }
+
+    /**
+     * Private property to store the dynamically loaded renderer module.
+     * @member {Neo.main.render.DomApiRenderer|Neo.main.render.DomApiRenderer|null} #renderer=null
+     * @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.
+     * @private
+     * @member {Promise<void>|null} #_readyPromise
+     */
+    #_readyPromise = null
+
+    /**
+     * @param {Object} config
+     */
+    construct(config) {
+        super.construct(config);
+
+        // Initiate the asynchronous loading of the renderer here.
+        this.#_readyPromise = (async () => {
+            try {
+                let module;
+
+                if (NeoConfig.useStringBasedMounting) {
+                    module = await import('./render/StringBasedRenderer.mjs')
+                } else {
+                    module = await import('./render/DomApiRenderer.mjs')
+                }
+
+                this.#renderer = module.default
+            } catch (err) {
+                console.error('DeltaUpdates: Failed to load renderer module:', err);
+                throw err // Re-throw to propagate initialization failures
+            }
+        })()
+    }
+
+    /**
+     * @param {HTMLElement} node
+     * @param {String}      nodeName
+     */
+    changeNodeName(node, nodeName) {
+        let {attributes} = node,
+            clone        = document.createElement(nodeName),
+            i            = 0,
+            len          = attributes.length,
+            attribute;
+
+        if (node) {
+            for (; i < len; i++) {
+                attribute = attributes.item(i);
+                clone.setAttribute(attribute.nodeName, attribute.nodeValue)
+            }
+
+            clone.innerHTML= node.innerHTML;
+
+            node.parentNode.replaceChild(clone, node)
+        }
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {String} delta.id
+     */
+    focusNode({id}) {
+        DomAccess.getElement(id)?.focus()
+    }
+
+    /**
+     * Inserts a new node into the DOM tree based on delta updates.
+     * This method handles both string-based (outerHTML) and direct DOM API (vnode) mounting.
+     * It ensures the node is inserted at the correct index within the parent.
+     *
+     * Implementation Details & Considerations:
+     * - `parentNode.children` contains only element nodes (tags).
+     * - `parentNode.childNodes` contains all nodes, including text and comment nodes.
+     * - Since every `vtype:'text'` is wrapped inside a comment block (as an ID),
+     *   calculating a "realIndex" is necessary for string-based insertions to
+     *   correctly account for non-element nodes.
+     * - `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.
+     *
+     * @param {Object}         delta
+     * @param {Boolean}        delta.hasLeadingTextChildren Flag to honor leading comments, which require special treatment.
+     * @param {Number}         delta.index                  The index at which to insert the new node within its parent.
+     * @param {String}         [delta.outerHTML]            The string representation of the new node (for string-based mounting).
+     * @param {String}         delta.parentId               The ID of the parent DOM node.
+     * @param {Neo.vdom.VNode} [delta.vnode]                The VNode representation of the new node (for direct DOM API mounting).
+     */
+    insertNode({hasLeadingTextChildren, index, outerHTML, parentId, vnode}) {
+        // This method is synchronous and *expects* the renderer to be loaded
+        if (!this.#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})
+            } else {
+                this.#renderer.insertNodeAsString({hasLeadingTextChildren, index, outerHTML, parentNode})
+            }
+        }
+    }
+
+    /**
+     * Moves an existing DOM node to a new position within its parent
+     * or to a new parent.
+     * This method directly manipulates the DOM using the pre-calculated physical index.
+     *
+     * @param {Object} delta
+     * @param {String} delta.id       The ID of the DOM node to move.
+     * @param {Number} delta.index    The physical index at which to insert the node
+     * @param {String} delta.parentId The ID of the target parent DOM node.
+     */
+    moveNode({id, index, parentId}) {
+        let node       = DomAccess.getElement(id),
+            parentNode = DomAccess.getElement(parentId);
+
+        if (node && parentNode) {
+            // If the target index is at or beyond the end of the parent's current childNodes, append the node.
+            if (index >= parentNode.childNodes.length) {
+                parentNode.appendChild(node)
+            } else {
+                // Get the reference node at the target physical index.
+                let referenceNode = parentNode.childNodes[index];
+
+                // Only proceed if the node is not already at its target position.
+                if (node !== referenceNode) {
+                    // Perform a direct swap operation if immediate element siblings.
+                    if (node.nodeType === 1 && node === referenceNode.nextElementSibling) {
+                        node.replaceWith(referenceNode)
+                    }
+
+                    parentNode.insertBefore(node, referenceNode)
+                }
+            }
+        }
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {String} delta.parentId
+     */
+    removeAll({parentId}) {
+        let node = DomAccess.getElement(parentId);
+
+        if (node) {
+            node.innerHTML = ''
+        }
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {String} delta.id
+     * @param {String} delta.parentId
+     */
+    removeNode({id, parentId}) {
+        const node = DomAccess.getElement(id);
+
+        if (node) {
+            node.remove();
+        }
+        // Potentially a vtype: 'text' node (wrapped between 2 comments)
+        else if (parentId) {
+            const
+                parentNode = DomAccess.getElementOrBody(parentId),
+                isComment  = Node.COMMENT_NODE;
+
+            if (parentNode) {
+                // Find the starting comment node using its id marker
+                const startComment = Array.from(parentNode.childNodes).find(n =>
+                    n.nodeType === isComment && n.nodeValue.includes(` ${id} `)
+                );
+
+                if (startComment) {
+                    const
+                        textNode = startComment.nextSibling,
+                        // Ensure endComment is a comment node before attempting to remove
+                        endComment = textNode?.nextSibling?.nodeType === isComment ? textNode.nextSibling : null;
+
+                    // Remove the three parts: start comment, text node, end comment
+                    startComment.remove();
+                    textNode?.remove();
+                    endComment?.remove()
+                }
+            }
+        }
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {String} delta.fromId
+     * @param {String} delta.parentId
+     * @param {String} delta.toId
+     */
+    replaceChild({fromId, parentId, toId}) {
+        let node = DomAccess.getElement(parentId);
+
+        node?.replaceChild(DomAccess.getElement(toId), DomAccess.getElement(fromId))
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {String} [delta.id]
+     * @param {String} [delta.value
+     */
+    setTextContent({id, value}) {
+        let node = DomAccess.getElement(id);
+
+        if (node) {
+            node.textContent = value
+        }
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {Object} [delta.attributes]
+     * @param {String} [delta.cls]
+     * @param {String} [delta.id]
+     * @param {String} [delta.innerHTML]
+     * @param {String} [delta.outerHTML]
+     * @param {Object} [delta.style]
+     */
+    updateNode(delta) {
+        let me   = this,
+            node = DomAccess.getElementOrBody(delta.id);
+
+        if (!node) {
+            console.log('node not found', delta.id);
+        }
+
+        if (node) {
+            Object.entries(delta).forEach(([prop, value]) => {
+                switch(prop) {
+                    case 'attributes':
+                        Object.entries(value).forEach(([key, val]) => {
+                            if (voidAttributes.has(key)) {
+                                node[key] = val === 'true' // vnode attribute values get converted into strings
+                            } else if (val === null || val === '') {
+                                if (key === 'value') {
+                                    node[key] = '' // input fields => pseudo attribute can not be removed
+                                } else {
+                                    node.removeAttribute(key)
+                                }
+                            } else if (key === 'id') {
+                                node[NeoConfig.useDomIds ? 'id' : 'data-neo-id'] = val
+                            } else if (key === 'spellcheck' && val === 'false') {
+                                // see https://github.com/neomjs/neo/issues/1922
+                                node[key] = false
+                            } else {
+                                if (key === 'value') {
+                                    node[key] = val
+                                } else {
+                                    node.setAttribute(key, val)
+                                }
+                            }
+                        });
+                        break
+                    case 'cls':
+                        value.add    && node.classList.add(...value.add);
+                        value.remove && node.classList.remove(...value.remove);
+                        break
+                    case 'innerHTML':
+                        node.innerHTML = value || '';
+                        break
+                    case 'nodeName':
+                        me.changeNodeName(node, value);
+                        break
+                    case 'outerHTML':
+                        node.outerHTML = value || '';
+                        break
+                    case 'style':
+                        if (Neo.isObject(value)) {
+                            Object.entries(value).forEach(([key, val]) => {
+                                let important;
+
+                                if (Neo.isString(val) && val.includes('!important')) {
+                                    val = val.replace('!important', '').trim();
+                                    important = 'important'
+                                }
+
+                                node.style.setProperty(Neo.decamel(key), val, important)
+                            })
+                        }
+                        break
+                }
+            })
+        }
+    }
+
+    /**
+     * @param {Object} delta
+     * @param {String} delta.id
+     * @param {String} delta.parentId
+     * @param {String} delta.value
+     */
+    updateVtext({id, parentId, value}) {
+        let node      = DomAccess.getElement(parentId),
+            innerHTML = node.innerHTML,
+            startTag  = `<!-- ${id} -->`,
+            reg       = new RegExp(startTag + '[\\s\\S]*?<!-- \/neo-vtext -->');
+
+        node.innerHTML = innerHTML.replace(reg, value)
+    }
+
+    /**
+     * @param {Object} data
+     * @param {Object|Object[]} data.deltas
+     * @param {String} data.id
+     * @param {String} [data.origin='app']
+     */
+    update(data) {
+        // This method is synchronous and *expects* the renderer to be loaded
+        if (!this.#renderer) {
+            console.error('DeltaUpdates renderer not ready during insertNode!');
+            return
+        }
+
+        let me       = this,
+            {deltas} = data,
+            i        = 0,
+            len;
+
+        deltas = Array.isArray(deltas) ? deltas : [deltas];
+        len    = deltas.length;
+
+        if (NeoConfig.logDeltaUpdates && len > 0) {
+            me.countDeltas += len;
+            me.countUpdates++;
+            console.log('update ' + me.countUpdates, 'total deltas ', me.countDeltas, Neo.clone(data, true))
+        }
+
+        if (NeoConfig.renderCountDeltas && len > 0) {
+            me.countDeltasPer250ms += len
+        }
+
+        for (; i < len; i++) {
+            me[deltas[i].action || 'updateNode'](deltas[i])
+        }
+
+        Neo.worker.Manager.sendMessage(data.origin || 'app', {
+            action : 'reply',
+            replyId: data.id,
+            success: true
+        })
+    }
+}
+
+export default Neo.setupClass(DeltaUpdates);

package/src/main/DomAccess.mjs

@@ -1,9 +1,7 @@
-import Base         from '../core/Base.mjs';
-import DeltaUpdates from './mixin/DeltaUpdates.mjs';
-import DomUtils     from './DomUtils.mjs';
-import Observable   from '../core/Observable.mjs';
-import Rectangle    from '../util/Rectangle.mjs';
-import StringUtil   from '../util/String.mjs';
+import Base       from '../core/Base.mjs';
+import DomUtils   from './DomUtils.mjs';
+import Rectangle  from '../util/Rectangle.mjs';
+import StringUtil from '../util/String.mjs';
 
 const
     doPreventDefault = e => e.preventDefault(),
@@ -43,6 +41,13 @@ const
  * @singleton
  */
 class DomAccess extends Base {
+    /**
+     * True automatically applies the core.Observable mixin
+     * @member {Boolean} observable=true
+     * @static
+     */
+    static observable = true
+
     static config = {
         /**
          * @member {String} className='Neo.main.DomAccess'
@@ -64,13 +69,6 @@ class DomAccess extends Base {
          * @protected
          */
         countUpdates: 0,
-        /**
-         * @member {Array} mixins=[DeltaUpdates, Observable]
-         */
-        mixins: [
-            DeltaUpdates,
-            Observable
-        ],
         /**
          * Remote method access for other workers
          * @member {Object} remote
@@ -113,16 +111,7 @@ class DomAccess extends Base {
          * @member {Boolean} singleton=true
          * @protected
          */
-        singleton: true,
-        /**
-         * Void attributes inside html tags
-         * @member {String[]} voidAttributes
-         * @protected
-         */
-        voidAttributes: [
-            'checked',
-            'required'
-        ]
+        singleton: true
     }
 
     /**
@@ -865,7 +854,7 @@ class DomAccess extends Base {
      * @protected
      */
     read(data) {
-        typeof data === 'function' && data()
+        Neo.isFunction(data) && data()
     }
 
     /**
@@ -1160,18 +1149,6 @@ class DomAccess extends Base {
             top     : data.top      || 0
         })
     }
-
-    /**
-     * @param {Object} data
-     * @protected
-     */
-    write(data) {
-        this.du_insertNode({
-            index    : data.parentIndex,
-            outerHTML: data.html || data.outerHTML,
-            parentId : data.parentId
-        })
-    }
 }
 
 export default Neo.setupClass(DomAccess);

package/src/main/render/DomApiRenderer.mjs

@@ -0,0 +1,138 @@
+import {voidAttributes} from '../../vdom/domConstants.mjs';
+
+const DomApiRenderer = {
+    /**
+     * Recursively creates a DOM element (or DocumentFragment) from a VNode tree.
+     * This method handles two primary modes based on `isRoot`:
+     * 1. If `isRoot` is true:
+     *   a. Builds a detached DocumentFragment: if `parentNode` is null. Returns the fragment.
+     *   b. Builds and inserts directly into a host DOM: if `parentNode` is provided. Inserts the fragment.
+     * 2. If `isRoot` is false (default for recursive calls):
+     *   Appends created DOM nodes directly to the provided `parentNode` (which is the DOM element of the direct parent VNode).
+     *
+     * @param {Object}      config
+     * @param {Number}      [config.index]           The index within `parentNode` to insert the root fragment (used when `isRoot` is true).
+     * @param {Boolean}     [config.isRoot=false]    If true, this is the root call for the VNode tree.
+     * @param {HTMLElement} [config.parentNode=null] The parent DOM node to insert into. Its role changes based on `isRoot`.
+     * @param {Object}      config.vnode             The VNode object to convert to a real DOM element.
+     * @returns {DocumentFragment|HTMLElement|null}  The created DOM node, the root DocumentFragment, or null.
+     * @private
+     */
+    createDomTree({index, isRoot=false, parentNode, vnode}) {
+        let domNode;
+
+        // No node or just a reference node, opt out
+        if (!vnode || vnode.componentId) {
+            return null
+        }
+
+        // Handle text nodes
+        if (vnode.vtype === 'text') {
+            domNode = document.createTextNode(vnode.textContent || '');
+
+            // Wrap in comment for consistency with delta updates
+            const
+                commentStart = document.createComment(` ${vnode.id} `),
+                commentEnd   = document.createComment(' /neo-vtext '),
+                fragment     = document.createDocumentFragment();
+
+            fragment.append(commentStart, domNode, commentEnd);
+            domNode = fragment
+        }
+        // Handle regular elements
+        else if (vnode.nodeName) {
+            if (vnode.ns) { // For SVG, ensure correct namespace
+                domNode = document.createElementNS(vnode.ns, vnode.nodeName)
+            } else {
+                domNode = document.createElement(vnode.nodeName)
+            }
+
+            // Apply the top-level 'id' property first (guaranteed to exist)
+            domNode[Neo.config.useDomIds ? 'id' : 'data-neo-id'] = vnode.id;
+
+            // Apply Attributes
+            Object.entries(vnode.attributes).forEach(([key, value]) => {
+                if (voidAttributes.has(key)) {
+                    domNode[key] = (value === 'true' || value === true)
+                } else if (key === 'value') {
+                    domNode.value = value
+                } else if (value !== null && value !== undefined) {
+                    domNode.setAttribute(key, value)
+                }
+            });
+
+            // Apply Classes
+            if (vnode.className.length > 0) {
+                domNode.classList.add(...vnode.className)
+            }
+
+            // Apply Styles
+            if (Neo.isObject(vnode.style)) {
+                Object.entries(vnode.style).forEach(([key, value]) => {
+                    let important;
+
+                    if (Neo.isString(value) && value.includes('!important')) {
+                        value = value.replace('!important', '').trim();
+                        domNode.style.setProperty(Neo.decamel(key), value, 'important');
+                        important = 'important'
+                    }
+
+                    domNode.style.setProperty(Neo.decamel(key), value, important)
+                })
+            }
+
+            // Handle innerHTML & textContent
+            // This applies to elements that contain only plain text (e.g., <span>Hello</span>)
+            // If the VNode has childNodes, this block is skipped, and content is handled recursively.
+            if (vnode.childNodes.length < 1) {
+                if (vnode.innerHTML) {
+                    domNode.innerHTML = vnode.innerHTML
+                } else if (vnode.textContent) {
+                    domNode.textContent = vnode.textContent
+                }
+            }
+        } else {
+            console.error('Unhandled VNode type or missing nodeName:', vnode);
+            return null
+        }
+
+        // Recursively process children
+        vnode.childNodes.forEach(childVnode => {
+            this.createDomTree({parentNode: domNode, vnode: childVnode})
+        })
+
+        // Final step: handle insertion based on `isRoot` and `parentNode`
+        if (isRoot) {
+            // This will be either HTMLElement or a DocumentFragment (for text vnodes)
+            let nodeToInsert = domNode;
+
+            if (nodeToInsert && parentNode && index !== -1) {
+                // If a specific host and index are provided, perform the insertion directly
+                if (index < parentNode.childNodes.length) {
+                    parentNode.insertBefore(nodeToInsert, parentNode.childNodes[index])
+                } else {
+                    parentNode.appendChild(nodeToInsert)
+                }
+
+                // Return the actual root DOM node (or fragment for text) that was inserted
+                return domNode
+            } else {
+                // If no specific host or index, return the detached nodeToInsert (HTMLElement or DocumentFragment)
+                return nodeToInsert
+            }
+        } else {
+            // For recursive calls (isRoot is false), append directly to the provided parentNode.
+            if (parentNode) { // parentNode here is the intermediate DOM parent
+                parentNode.append(domNode)
+            }
+
+            // Return the appended node (or null)
+            return domNode
+        }
+    }
+};
+
+const ns = Neo.ns('Neo.main.render', true);
+ns.DomApiRenderer = DomApiRenderer;
+
+export default DomApiRenderer;

package/src/main/render/StringBasedRenderer.mjs

@@ -0,0 +1,58 @@
+const StringBasedRenderer = {
+    /**
+     * @param {String} html representing a single element
+     * @returns {DocumentFragment}
+     */
+    htmlStringToElement(html) {
+        const template = document.createElement('template');
+        template.innerHTML = html;
+        return template.content
+    },
+
+    /**
+     * Handles string-based insertion of a new node into the DOM.
+     * This method is called by `insertNode()` when `NeoConfig.useStringBasedMounting` is true.
+     *
+     * @param {Object}      data
+     * @param {Boolean}     data.hasLeadingTextChildren Flag to honor leading comments.
+     * @param {Number}      data.index                  The index at which to insert the new node.
+     * @param {String}      data.outerHTML              The HTML string of the node to insert.
+     * @param {HTMLElement} data.parentNode             The parent DOM node to insert into.
+     * @private
+     */
+    insertNodeAsString({hasLeadingTextChildren, index, outerHTML, parentNode}) {
+        let me = this;
+
+        // If comments detected, parse HTML string to a node and use insertBefore/appendChild on childNodes.
+        if (hasLeadingTextChildren) {
+            let node = me.htmlStringToElement(outerHTML);
+
+            if (index < parentNode.childNodes.length) {
+                parentNode.insertBefore(node, parentNode.childNodes[index])
+            } else {
+                parentNode.appendChild(node)
+            }
+        }
+        // If no comments detected, use insertAdjacentHTML for element nodes.
+        else {
+            let countChildren = parentNode.children.length; // Use `children` for `insertAdjacentHTML` context
+
+            if (index > 0 && index >= countChildren) {
+                parentNode.insertAdjacentHTML('beforeend', outerHTML);
+                return
+            }
+            if (countChildren > 0 && countChildren > index) {
+                parentNode.children[index].insertAdjacentHTML('beforebegin', outerHTML)
+            } else if (countChildren > 0) {
+                parentNode.children[countChildren - 1].insertAdjacentHTML('afterend', outerHTML)
+            } else {
+                parentNode.insertAdjacentHTML('beforeend', outerHTML)
+            }
+        }
+    }
+};
+
+const ns = Neo.ns('Neo.main.render', true);
+ns.StringBasedRenderer = StringBasedRenderer;
+
+export default StringBasedRenderer;

package/src/table/View.mjs

@@ -231,7 +231,7 @@ class View extends Component {
         }
 
         if (Neo.typeOf(rendererOutput) === 'Object') {
-            cellConfig.innerHTML = rendererOutput.html  || ''
+            cellConfig.html = rendererOutput.html  || ''
         } else {
             cellConfig.cn = rendererOutput
         }

package/src/table/plugin/CellEditing.mjs

@@ -161,7 +161,7 @@ class CellEditing extends Plugin {
         me.mountedEditor = editor;
 
         cellNode.cn = [editor.createVdomReference()];
-        delete cellNode.innerHTML;
+        delete cellNode.html;
 
         view.updateDepth = -1;