neo.mjs 10.0.0-beta.6 → 10.0.0

package/src/functional/button/Base.mjs

@@ -0,0 +1,384 @@
+import FunctionalBase from '../../functional/component/Base.mjs';
+import NeoArray       from '../../util/Array.mjs';
+
+/**
+ * @class Neo.functional.button.Base
+ * @extends Neo.functional.component.Base
+ */
+class Button extends FunctionalBase {
+    /**
+     * Valid values for badgePosition
+     * @member {String[]} badgePositions=['bottom-left','bottom-right','top-left','top-right']
+     * @protected
+     * @static
+     */
+    static badgePositions = ['bottom-left', 'bottom-right', 'top-left', 'top-right']
+    /**
+     * Valid values for iconPosition
+     * @member {String[]} iconPositions=['top','right','bottom','left']
+     * @protected
+     * @static
+     */
+    static iconPositions  = ['top', 'right', 'bottom', 'left']
+
+    static config = {
+        /**
+         * @member {String} className='Neo.functional.button.Base'
+         * @protected
+         */
+        className: 'Neo.functional.button.Base',
+        /**
+         * @member {String} ntype='functional-button'
+         * @protected
+         */
+        ntype: 'functional-button',
+        /**
+         * @member {String} badgePosition_='top-right'
+         * @reactive
+         */
+        badgePosition_: 'top-right',
+        /**
+         * @member {String|null} badgeText_=null
+         * @reactive
+         */
+        badgeText_: null,
+        /**
+         * @member {String[]} baseCls=['neo-button']
+         */
+        baseCls: ['neo-button'],
+        /**
+         * false calls Neo.Main.setRoute()
+         * @member {Boolean} editRoute=true
+         */
+        editRoute: true,
+        /**
+         * @member {Function|String|null} handler_=null
+         * @reactive
+         */
+        handler_: null,
+        /**
+         * @member {Object|String|null} handlerScope=null
+         */
+        handlerScope: null,
+        /**
+         * @member {String[]|null} [iconCls_=null]
+         * @reactive
+         */
+        iconCls_: null,
+        /**
+         * @member {String|null} iconColor_=null
+         * @reactive
+         */
+        iconColor_: null,
+        /**
+         * @member {String} iconPosition_='left'
+         * @reactive
+         */
+        iconPosition_: 'left',
+        /**
+         * @member {Object|Object[]|null} menu_=null
+         * @reactive
+         */
+        menu_: null,
+        /**
+         * @member {Boolean} pressed_=false
+         * @reactive
+         */
+        pressed_: false,
+        /**
+         * Internal state for managing the ripple effect animations.
+         * Each object in the array requires a unique `id`.
+         * @member {Array} ripples_=[]
+         * @protected
+         * @reactive
+         */
+        ripples_: [],
+        /**
+         * @member {String|null} route_=null
+         * @reactive
+         */
+        route_: null,
+        /**
+         * @member {String} tag='button'
+         * @reactive
+         */
+        tag: 'button',
+        /**
+         * @member {String|null} text_=null
+         * @reactive
+         */
+        text_: null,
+        /**
+         * @member {String|null} url_=null
+         * @reactive
+         */
+        url_: null,
+        /**
+         * @member {String} urlTarget_='_blank'
+         * @reactive
+         */
+        urlTarget_: '_blank',
+        /**
+         * @member {Boolean} useRippleEffect_=true
+         * @reactive
+         */
+        useRippleEffect_: true
+    }
+
+    /**
+     * @member {Number} rippleEffectDuration=400
+     */
+    rippleEffectDuration = 400
+    /**
+     * @member {Number|null} rippleCleanupTimeout=null
+     * @protected
+     */
+    rippleCleanupTimeout = null
+
+    /**
+     * @param {Object} config
+     */
+    construct(config) {
+        super.construct(config);
+
+        let me = this;
+
+        me.addDomListeners({
+            click: me.onClick,
+            scope: me
+        })
+    }
+
+    /**
+     * The single source of truth for the button's VDOM.
+     * This method is automatically re-run when any of its dependent configs change.
+     * @param {Object} config The component's config object (this instance).
+     * @param {Object} data The hierarchical data from state.Provider.
+     * @returns {Object}
+     */
+    createVdom(config, data) {
+        const me = this,
+              {
+                  badgePosition, badgeText, cls, editRoute, iconCls, iconColor, iconPosition,
+                  pressed, ripples, route, style, tag, text, url, urlTarget, useRippleEffect
+              }  = config;
+
+        const vdomCls = [...me.baseCls, ...cls || []];
+        NeoArray.toggle(vdomCls, 'no-text', !text);
+        NeoArray.toggle(vdomCls, 'pressed', pressed);
+        vdomCls.push('icon-' + iconPosition);
+
+        const link     = !editRoute && route || url;
+        const finalTag = link ? 'a' : tag;
+
+        return {
+            tag   : finalTag,
+            cls   : vdomCls,
+            style,
+            href  : link ? (link.startsWith('#') ? link : '#' + link) : null,
+            target: url ? urlTarget : null,
+            type  : finalTag === 'button' ? 'button' : null,
+            cn    : [
+                // iconNode
+                {
+                    tag      : 'span',
+                    cls      : ['neo-button-glyph', ...iconCls || []],
+                    removeDom: !iconCls,
+                    style    : {color: iconColor || null}
+                },
+                // textNode
+                {
+                    tag      : 'span',
+                    cls      : ['neo-button-text'],
+                    removeDom: !text,
+                    text
+                },
+                // badgeNode
+                {
+                    tag      : 'span',
+                    cls      : ['neo-button-badge', 'neo-' + badgePosition],
+                    removeDom: !badgeText,
+                    text     : badgeText
+                },
+                // rippleWrapper
+                {
+                    cls      : ['neo-button-ripple-wrapper'],
+                    removeDom: !(useRippleEffect && ripples.length > 0),
+                    cn       : ripples.map(ripple => ({
+                        cls  : ['neo-button-ripple'],
+                        id   : ripple.id,
+                        style: {
+                            animation: `ripple ${me.rippleEffectDuration}ms linear`,
+                            height   : `${ripple.diameter}px`,
+                            left     : `${ripple.left}px`,
+                            top      : `${ripple.top}px`,
+                            width    : `${ripple.diameter}px`
+                        }
+                    }))
+                }
+            ]
+        }
+    }
+
+    /**
+     * @param {Object} data
+     */
+    onClick(data) {
+        let me = this;
+
+        me.bindCallback(me.handler, 'handler', me.handlerScope || me);
+        me.handler?.(data);
+
+        me.menu && me.toggleMenu();
+        me.route && me.changeRoute();
+
+        if (me.useRippleEffect) {
+            const buttonRect = data.path[0].rect;
+            const diameter   = Math.max(buttonRect.height, buttonRect.width);
+            const radius     = diameter / 2;
+            const rippleId   = Neo.getId('ripple');
+
+            // Add a new ripple to the state
+            me.ripples = [...me.ripples, {
+                id  : rippleId,
+                diameter,
+                left: data.clientX - buttonRect.left - radius,
+                top : data.clientY - buttonRect.top - radius
+            }];
+
+            // Clear any previously scheduled cleanup to ensure only the last
+            // click's timer will execute the cleanup.
+            clearTimeout(me.rippleCleanupTimeout);
+
+            // Schedule the cleanup for the entire ripples array.
+            me.rippleCleanupTimeout = me.timeout(me.rippleEffectDuration).then(() => {
+                me.ripples = [];
+            });
+        }
+    }
+
+    /**
+     * Triggered after the menu config got changed
+     * @param {Object|Object[]|null} value
+     * @param {Object|Object[]|null} oldValue
+     * @protected
+     */
+    afterSetMenu(value, oldValue) {
+        const me = this;
+
+        if (value) {
+            // Ensure menuList is destroyed before creating a new one
+            me.menuList?.destroy(true, false);
+            me.menuList = null;
+
+            import('../../menu/List.mjs').then(module => {
+                const isArray                    = Array.isArray(value),
+                      items                      = isArray ? value : value.items,
+                      menuConfig                 = isArray ? {} : value,
+                      stateProvider              = me.getStateProvider(),
+                      {appName, theme, windowId} = me,
+
+                      config                     = Neo.merge({
+                          module         : module.default,
+                          align          : {edgeAlign: 't0-b0', target: me.id},
+                          appName,
+                          displayField   : 'text',
+                          floating       : true,
+                          hidden         : true,
+                          parentComponent: me,
+                          theme,
+                          windowId
+                      }, menuConfig);
+
+                if (items) {
+                    config.items = items
+                }
+
+                if (stateProvider) {
+                    config.stateProvider = {parent: stateProvider}
+                }
+
+                me.menuList = Neo.create(config)
+            })
+        } else if (me.menuList) {
+            me.menuList.destroy(true, false);
+            me.menuList = null;
+        }
+    }
+
+    /**
+     * Triggered before the badgePosition config gets changed
+     * @param {String} value
+     * @param {String} oldValue
+     * @returns {String}
+     * @protected
+     */
+    beforeSetBadgePosition(value, oldValue) {
+        // Using `this.constructor.badgePositions` is superior to `Button.badgePositions` for future class extensions
+        return this.beforeSetEnumValue(value, oldValue, 'badgePosition', this.constructor.badgePositions)
+    }
+
+    /**
+     * Triggered before the iconCls config gets changed. Converts the string into an array if needed.
+     * @param {Array|String|null} value
+     * @param {Array|String|null} oldValue
+     * @returns {Array|null}
+     * @protected
+     */
+    beforeSetIconCls(value, oldValue) {
+        if (value && !Array.isArray(value)) {
+            return value.split(' ').filter(Boolean)
+        }
+
+        return value || null
+    }
+
+    /**
+     * Triggered before the iconPosition config gets changed
+     * @param {String} value
+     * @param {String} oldValue
+     * @protected
+     */
+    beforeSetIconPosition(value, oldValue) {
+        // Using `this.constructor.iconPositions` is superior to `Button.iconPositions` for future class extensions
+        return this.beforeSetEnumValue(value, oldValue, 'iconPosition', this.constructor.iconPositions)
+    }
+
+    /**
+     * @protected
+     */
+    changeRoute() {
+        const me = this;
+        me.editRoute && Neo.Main.editRoute(me.route)
+    }
+
+    /**
+     * @param args
+     */
+    destroy(...args) {
+        const me = this;
+
+        clearTimeout(me.rippleCleanupTimeout);
+        me.menuList?.destroy(true, false);
+        super.destroy(...args)
+    }
+
+    /**
+     *
+     */
+    async toggleMenu() {
+        const me       = this;
+        let {menuList} = me,
+            hidden     = !menuList?.hidden;
+
+        if (menuList) {
+            menuList.hidden = hidden;
+
+            if (!hidden) {
+                await me.timeout(50)
+            }
+        }
+    }
+}
+
+export default Neo.setupClass(Button);

package/src/functional/component/Base.mjs

@@ -1,10 +1,6 @@
-import Base             from '../../core/Base.mjs';
-import ComponentManager from '../../manager/Component.mjs';
-import DomEvents        from '../../mixin/DomEvents.mjs';
-import Effect           from '../../core/Effect.mjs';
-import NeoArray         from '../../util/Array.mjs';
-import Observable       from '../../core/Observable.mjs';
-import VdomLifecycle    from '../../mixin/VdomLifecycle.mjs';
+import Abstract from '../../component/Abstract.mjs';
+import Effect   from '../../core/Effect.mjs';
+import NeoArray from '../../util/Array.mjs';
 
 const
     activeDomListenersSymbol = Symbol.for('activeDomListeners'),
@@ -15,12 +11,9 @@ const
 
 /**
  * @class Neo.functional.component.Base
- * @extends Neo.core.Base
- * @mixes Neo.component.mixin.DomEvents
- * @mixes Neo.core.Observable
- * @mixes Neo.component.mixin.VdomLifecycle
+ * @extends Neo.component.Abstract
  */
-class FunctionalBase extends Base {
+class FunctionalBase extends Abstract {
     static config = {
         /**
          * @member {String} className='Neo.functional.component.Base'
@@ -32,40 +25,11 @@ class FunctionalBase extends Base {
          * @protected
          */
         ntype: 'functional-component',
-        /**
-         * Custom CSS selectors to apply to the root level node of this component
-         * @member {String[]} cls=null
-         * @reactive
-         */
-        cls: null,
-        /**
-         * @member {Neo.core.Base[]} mixins=[DomEvents, Observable, VdomLifecycle]
-         */
-        mixins: [DomEvents, Observable, VdomLifecycle],
-        /**
-         * True after the component render() method was called. Also fires the rendered event.
-         * @member {Boolean} mounted_=false
-         * @protected
-         * @reactive
-         */
-        mounted_: false,
-        /**
-         * @member {String|null} parentId_=null
-         * @protected
-         * @reactive
-         */
-        parentId_: null,
         /**
          * The vdom markup for this component.
          * @member {Object} vdom={}
          */
-        vdom: {},
-        /**
-         * The custom windowIs (timestamp) this component belongs to
-         * @member {Number|null} windowId_=null
-         * @reactive
-         */
-        windowId_: null
+        vdom: {}
     }
 
     /**
@@ -73,12 +37,6 @@ class FunctionalBase extends Base {
      * @member {Map|null} childComponents=null
      */
     childComponents = null
-    /**
-     * Internal flag which will get set to true while a component is waiting for its mountedPromise
-     * @member {Boolean} isAwaitingMount=false
-     * @protected
-     */
-    isAwaitingMount = false
     /**
      * Internal Map to store the next set of components after the createVdom() Effect has run.
      * @member {Map|null} nextChildComponents=null
@@ -86,41 +44,6 @@ class FunctionalBase extends Base {
      */
     #nextChildComponents = null
 
-    /**
-     * A Promise that resolves when the component is mounted to the DOM.
-     * This provides a convenient way to wait for the component to be fully
-     * available and interactive before executing subsequent logic.
-     *
-     * It also handles unmounting by resetting the promise, so it can be safely
-     * awaited again if the component is remounted.
-     * @returns {Promise<Neo.component.Base>}
-     */
-    get mountedPromise() {
-        let me = this;
-
-        if (!me._mountedPromise) {
-            me._mountedPromise = new Promise(resolve => {
-                if (me.mounted) {
-                    resolve(me);
-                } else {
-                    me.mountedPromiseResolve = resolve
-                }
-            })
-        }
-
-        return me._mountedPromise
-    }
-
-    /**
-     * Convenience method to access the parent component
-     * @returns {Neo.component.Base|null}
-     */
-    get parent() {
-        let me = this;
-
-        return me.parentComponent || (me.parentId === 'document.body' ? null : Neo.getComponent(me.parentId))
-    }
-
     /**
      * @param {Object} config
      */
@@ -143,7 +66,7 @@ class FunctionalBase extends Base {
             fn: () => {
                 me[hookIndexSymbol]        = 0;
                 me[pendingDomEventsSymbol] = []; // Clear pending events for new render
-                me[vdomToApplySymbol]      = me.createVdom(me, me.data)
+                me[vdomToApplySymbol]      = me.createVdom(me)
             },
             componentId: me.id,
             subscriber : {
@@ -154,19 +77,6 @@ class FunctionalBase extends Base {
         })
     }
 
-    /**
-     * Triggered after the id config got changed
-     * @param {String|null} value
-     * @param {String|null} oldValue
-     * @protected
-     */
-    afterSetId(value, oldValue) {
-        super.afterSetId(value, oldValue);
-
-        oldValue && ComponentManager.unregister(oldValue);
-        value    && ComponentManager.register(this)
-    }
-
     /**
      * Triggered after the mounted config got changed
      * @param {Boolean} value
@@ -174,19 +84,14 @@ class FunctionalBase extends Base {
      * @protected
      */
     afterSetMounted(value, oldValue) {
+        super.afterSetMounted(value, oldValue);
+
         if (oldValue !== undefined) {
             const me = this;
 
             if (value) { // mount
-                me.initDomEvents();
-
                 // Initial registration of DOM event listeners when component mounts
                 me.applyPendingDomListeners();
-
-                me.mountedPromiseResolve?.(this);
-                delete me.mountedPromiseResolve
-            } else { // unmount
-                delete me._mountedPromise
             }
         }
     }
@@ -198,21 +103,11 @@ class FunctionalBase extends Base {
      * @protected
      */
     afterSetWindowId(value, oldValue) {
-        const me = this;
-
-        if (value) {
-            Neo.currentWorker.insertThemeFiles(value, me.__proto__)
-        }
+        super.afterSetWindowId(value, oldValue);
 
-        me.childComponents?.forEach(childData => {
+        this.childComponents?.forEach(childData => {
             childData.instance.windowId = value
         })
-
-        // If a component gets moved into a different window, an update cycle might still be running.
-        // Since the update might no longer get mapped, we want to re-enable this instance for future updates.
-        if (oldValue) {
-            me.isVdomUpdating = false
-        }
     }
 
     /**
@@ -242,14 +137,44 @@ class FunctionalBase extends Base {
         }
     }
 
+    /**
+     * A lifecycle hook that runs after a state change has been detected but before the
+     * VDOM update is dispatched. It provides a dedicated place for logic that needs to
+     * execute before rendering, such as calculating derived data or caching values.
+     *
+     * You can prevent the VDOM update by returning `false` from this method. This is
+     * useful for advanced cases where you might want to manually trigger a different
+     * update after modifying other component configs.
+     *
+     * **IMPORTANT**: Do not change the value of any config that is used as a dependency
+     * within the `createVdom` method from inside this hook, as it will cause an
+     * infinite update loop. This hook is for one-way data flow, not for triggering
+     * cascading reactive changes.
+     *
+     * @returns {Boolean|undefined} Return `false` to cancel the upcoming VDOM update.
+     * @example
+     * beforeUpdate() {
+     *     // Perform an expensive calculation and cache the result on the instance
+     *     this.processedData = this.processRawData(this.rawData);
+     *
+     *     // Example of conditionally cancelling an update
+     *     if (this.processedData.length === 0 && this.vdom.cn?.length === 0) {
+     *         return false; // Don't re-render if there's nothing to show
+     *     }
+     * }
+     */
+    beforeUpdate() {
+        // This method can be overridden by subclasses
+    }
+
     /**
      * Override this method in your functional component to return its VDOM structure.
      * This method will be automatically re-executed when any of the component's configs change.
+     * To access data from a state provider, use `config.data`.
      * @param {Neo.functional.component.Base} config - Mental model: while it contains the instance, it makes it clear to access configs
-     * @param {Object}                        data   - Convenience shortcut for accessing `state.Provider` data
      * @returns {Object} The VDOM structure for the component.
      */
-    createVdom(config, data) {
+    createVdom(config) {
         // This method should be overridden by subclasses
         return {}
     }
@@ -268,13 +193,9 @@ class FunctionalBase extends Base {
         });
         me.childComponents?.clear();
 
-        me.removeDomEvents();
-
         // Remove any pending DOM event listeners that might not have been mounted
         me[pendingDomEventsSymbol] = null;
 
-        ComponentManager.unregister(me);
-
         super.destroy()
     }
 
@@ -382,7 +303,14 @@ class FunctionalBase extends Base {
                     root.id = me.id
                 }
 
-                me.updateVdom();
+                // Re-hydrate the new vdom with stable IDs from the previous vnode tree.
+                // This is crucial for functional components where the vdom is recreated on every render,
+                // ensuring the diffing algorithm can track nodes correctly.
+                me.syncVdomIds();
+
+                if (me.beforeUpdate() !== false) {
+                    me.updateVdom()
+                }
 
                 // Update DOM event listeners based on the new render
                 if (me.mounted) {
@@ -472,28 +400,6 @@ class FunctionalBase extends Base {
 
         return vdomTree
     }
-
-    /**
-     * Change multiple configs at once, ensuring that all afterSet methods get all new assigned values
-     * @param {Object} values={}
-     * @param {Boolean} silent=false
-     * @returns {Promise<*>}
-     */
-    set(values={}, silent=false) {
-        let me = this;
-
-        me.silentVdomUpdate = true;
-
-        super.set(values);
-
-        me.silentVdomUpdate = false;
-
-        if (silent || !me.needsVdomUpdate) {
-            return Promise.resolve()
-        }
-
-        return me.promiseUpdate()
-    }
 }
 
 export default Neo.setupClass(FunctionalBase);

package/src/layout/Cube.mjs

@@ -114,11 +114,15 @@ class Cube extends Card {
 
         me.nestVdom();
 
-        container.mounted && container.update();
-
-        me.timeout(50).then(() => {
-            container.addCls('neo-animate')
+        me.observeConfig(container, 'mounted', value => {
+            value && container.addCls('neo-animate')
         })
+
+        if (container.mounted) {
+            container.promiseUpdate().then(() => {
+                container.addCls('neo-animate')
+            })
+        }
     }
 
     /**