neo.mjs 10.0.0-beta.5 → 10.0.0

package/src/functional/component/Base.mjs

@@ -0,0 +1,405 @@
+import Abstract from '../../component/Abstract.mjs';
+import Effect   from '../../core/Effect.mjs';
+import NeoArray from '../../util/Array.mjs';
+
+const
+    activeDomListenersSymbol = Symbol.for('activeDomListeners'),
+    hookIndexSymbol          = Symbol.for('hookIndex'),
+    hooksSymbol              = Symbol.for('hooks'),
+    pendingDomEventsSymbol   = Symbol.for('pendingDomEvents'),
+    vdomToApplySymbol        = Symbol('vdomToApply');
+
+/**
+ * @class Neo.functional.component.Base
+ * @extends Neo.component.Abstract
+ */
+class FunctionalBase extends Abstract {
+    static config = {
+        /**
+         * @member {String} className='Neo.functional.component.Base'
+         * @protected
+         */
+        className: 'Neo.functional.component.Base',
+        /**
+         * @member {String} ntype='functional-component'
+         * @protected
+         */
+        ntype: 'functional-component',
+        /**
+         * The vdom markup for this component.
+         * @member {Object} vdom={}
+         */
+        vdom: {}
+    }
+
+    /**
+     * Neo component instances, which got defined inside createVdom()
+     * @member {Map|null} childComponents=null
+     */
+    childComponents = null
+    /**
+     * Internal Map to store the next set of components after the createVdom() Effect has run.
+     * @member {Map|null} nextChildComponents=null
+     * @private
+     */
+    #nextChildComponents = null
+
+    /**
+     * @param {Object} config
+     */
+    construct(config) {
+        super.construct(config);
+
+        let me   = this,
+            opts = {configurable: true, enumerable: false, writable: true};
+
+        Object.defineProperties(me, {
+            [activeDomListenersSymbol]: {...opts, value: []},
+            [hookIndexSymbol]         : {...opts, value: 0},
+            [hooksSymbol]             : {...opts, value: []},
+            [pendingDomEventsSymbol]  : {...opts, value: []},
+            [vdomToApplySymbol]       : {...opts, value: null}
+        });
+
+        // Creates a reactive effect that re-executes createVdom() when dependencies change.
+        me.vdomEffect = new Effect({
+            fn: () => {
+                me[hookIndexSymbol]        = 0;
+                me[pendingDomEventsSymbol] = []; // Clear pending events for new render
+                me[vdomToApplySymbol]      = me.createVdom(me)
+            },
+            componentId: me.id,
+            subscriber : {
+                id   : me.id,
+                fn   : me.onEffectRunStateChange,
+                scope: me
+            }
+        })
+    }
+
+    /**
+     * Triggered after the mounted config got changed
+     * @param {Boolean} value
+     * @param {Boolean} oldValue
+     * @protected
+     */
+    afterSetMounted(value, oldValue) {
+        super.afterSetMounted(value, oldValue);
+
+        if (oldValue !== undefined) {
+            const me = this;
+
+            if (value) { // mount
+                // Initial registration of DOM event listeners when component mounts
+                me.applyPendingDomListeners();
+            }
+        }
+    }
+
+    /**
+     * Triggered after the windowId config got changed
+     * @param {Number|null} value
+     * @param {Number|null} oldValue
+     * @protected
+     */
+    afterSetWindowId(value, oldValue) {
+        super.afterSetWindowId(value, oldValue);
+
+        this.childComponents?.forEach(childData => {
+            childData.instance.windowId = value
+        })
+    }
+
+    /**
+     * Applies the pending DOM event listeners and updates the active list.
+     * @private
+     */
+    applyPendingDomListeners() {
+        const
+            me            = this,
+            activeEvents  = me[activeDomListenersSymbol],
+            pendingEvents = me[pendingDomEventsSymbol];
+
+        if (pendingEvents.length > 0) {
+            if (!Neo.isEqual(activeEvents, pendingEvents)) {
+                if (activeEvents?.length > 0) {
+                    // Remove old dynamic listeners
+                    me.removeDomListeners(me[activeDomListenersSymbol])
+                }
+
+                me.addDomListeners([...pendingEvents]);
+
+                me[activeDomListenersSymbol] = [...pendingEvents]
+            }
+
+            // Clear pending events for next `createVdom()` Effect run
+            me[pendingDomEventsSymbol] = []
+        }
+    }
+
+    /**
+     * 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
+     * @returns {Object} The VDOM structure for the component.
+     */
+    createVdom(config) {
+        // This method should be overridden by subclasses
+        return {}
+    }
+
+    /**
+     *
+     */
+    destroy() {
+        const me = this;
+
+        me.vdomEffect?.destroy();
+
+        // Destroy all classic components instantiated by this functional component
+        me.childComponents?.forEach(childData => {
+            childData.instance.destroy()
+        });
+        me.childComponents?.clear();
+
+        // Remove any pending DOM event listeners that might not have been mounted
+        me[pendingDomEventsSymbol] = null;
+
+        super.destroy()
+    }
+
+    /**
+     * This method recursively compares the new VDOM config with the last applied config
+     * for a given component instance and its sub-instances.
+     * @param {Neo.core.Base} instance The component instance to update.
+     * @param {Object} newConfig The new configuration object from the VDOM.
+     * @param {Object} lastConfig The last applied configuration object.
+     * @private
+     */
+    diffAndSet(instance, newConfig, lastConfig) {
+        const deltaConfig = {};
+
+        for (const key in newConfig) {
+            const newValue = newConfig[key],
+                  oldValue = lastConfig[key];
+
+            if (!Neo.isEqual(newValue, oldValue)) {
+                // If the config property is an object and it maps to a sub-component instance, recurse.
+                if (Neo.typeOf(newValue) === 'Object' && Neo.typeOf(instance[key]) === 'NeoInstance') {
+                    this.diffAndSet(instance[key], newValue, oldValue || {})
+                } else {
+                    // Otherwise, add it to the delta to be set on the current instance.
+                    deltaConfig[key] = newValue
+                }
+            }
+        }
+
+        // Only call set() if there are actual changes for the current instance.
+        if (Object.keys(deltaConfig).length > 0) {
+            instance.set(deltaConfig)
+        }
+    }
+
+    /**
+     * This handler runs when the effect's `isRunning` state changes.
+     * It runs outside the effect's tracking scope, preventing feedback loops.
+     * @param {Boolean} value
+     * @param {Boolean} oldValue
+     */
+    onEffectRunStateChange(value, oldValue) {
+        // When the effect has just finished running...
+        if (value === false) {
+            const me      = this,
+                  newVdom = me[vdomToApplySymbol];
+
+            if (newVdom) {
+                // Create a new map for components instantiated in this render cycle
+                me.#nextChildComponents = new Map();
+
+                // Process the newVdom to instantiate components
+                // The parentId for these components will be the functional component's id
+                const processedVdom = me.processVdomForComponents(newVdom, me.id);
+
+                // Destroy components that are no longer present in the new VDOM
+                if (me.childComponents?.size > 0) {
+                    [...me.childComponents].forEach(([key, childData]) => {
+                        if (!me.#nextChildComponents.has(key)) {
+                            me.childComponents.delete(key);
+                            childData.instance.destroy()
+                        }
+                    })
+                }
+
+                // If this component created other classic or functional components,
+                // include their full vdom into the next update cycle.
+                const oldKeys = me.childComponents ? new Set(me.childComponents.keys()) : new Set();
+                let hasNewChildren = false;
+
+                for (const newKey of me.#nextChildComponents.keys()) {
+                    if (!oldKeys.has(newKey)) {
+                        hasNewChildren = true;
+                        break
+                    }
+                }
+
+                if (hasNewChildren) {
+                    // When new child components are created, we need to send their full VDOM
+                    // to the vdom-worker, so they can get rendered.
+                    // Subsequent updates will be granular via diffAndSet() => set() on the child.
+                    me.updateDepth = -1;
+                }
+
+                // Update the main map of instantiated components
+                me.childComponents = me.#nextChildComponents;
+
+                // Clear the old vdom properties
+                for (const key in me.vdom) {
+                    delete me.vdom[key]
+                }
+
+                // Assign the new properties
+                Object.assign(me.vdom, processedVdom); // Use processedVdom here
+
+                me[vdomToApplySymbol] = null;
+
+                const root = me.getVdomRoot();
+
+                if (me.cls) {
+                    root.cls = NeoArray.union(me.cls, root.cls)
+                }
+
+                if (me.id) {
+                    root.id = me.id
+                }
+
+                // 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) {
+                    me.applyPendingDomListeners()
+                }
+            }
+        }
+    }
+
+    /**
+     * Recursively processes a VDOM node to instantiate components defined within it.
+     * @param {Object} vdomTree The VDOM node to process.
+     * @param {String} parentId The ID of the parent component (the functional component hosting it).
+     * @param {Number} [parentIndex] The index of the vdomNode within its parent's children.
+     * @returns {Object} The processed VDOM node, potentially replaced with a component reference.
+     * @private
+     */
+    processVdomForComponents(vdomTree, parentId, parentIndex) {
+        if (!vdomTree) {
+            return vdomTree
+        }
+
+        // If it's already a component reference, no need to process further
+        if (vdomTree.componentId) {
+            return vdomTree
+        }
+
+        const me = this;
+
+        // Check if it's a component definition (functional or classic)
+        if (vdomTree.className || vdomTree.module || vdomTree.ntype) {
+            // Components are reconciled based on their `id` property in the VDOM definition.
+            // If no `id` is provided, a new instance will be created on every render.
+            const componentKey = vdomTree.id;
+
+            if (!componentKey) {
+                console.error([
+                    'Component definition in functional component VDOM is missing an "id". For stable reconciliation, ',
+                    'especially in dynamic lists, provide a unique "id" property.'
+                    ].join(''),
+                    vdomTree
+                )
+            }
+
+            let childData = me.childComponents?.get(componentKey),
+                newConfig = {...vdomTree}, // Shallow copy
+                instance;
+
+            delete newConfig.className;
+            delete newConfig.id;
+            delete newConfig.module;
+            delete newConfig.ntype;
+
+            if (!childData) {
+                me.childComponents ??= new Map();
+
+                // Instantiate the component
+                instance = Neo[(vdomTree.className || vdomTree.module) ? 'create' : 'ntype']({
+                    ...vdomTree,
+                    parentId,
+                    parentIndex,
+                    windowId: me.windowId
+                });
+            } else {
+                instance = childData.instance;
+
+                // Recursively diff and set configs
+                this.diffAndSet(instance, newConfig, childData.lastConfig);
+            }
+
+            // Add to the new map for tracking in this render cycle
+            me.#nextChildComponents.set(componentKey, {
+                instance,
+                lastConfig: newConfig
+            });
+
+            // Replace the definition with a reference using the component's own method
+            return instance.createVdomReference();
+        }
+
+        // Recursively process children
+        if (vdomTree.cn && Array.isArray(vdomTree.cn)) {
+            vdomTree.cn = vdomTree.cn.map((child, index) =>
+                me.processVdomForComponents(child, parentId, index)
+            )
+        }
+
+        return vdomTree
+    }
+}
+
+export default Neo.setupClass(FunctionalBase);

package/src/functional/defineComponent.mjs

@@ -0,0 +1,102 @@
+import FunctionalBase from './component/Base.mjs';
+
+/**
+ * Factory function to create a functional component class from a specification object.
+ * This enables a "Beginner Mode" for creating components without writing a class,
+ * while still providing access to the full class-based feature set.
+ *
+ * It's important to understand the two ways of managing state:
+ *
+ * 1.  **Named Configs (Public API):** Defined in the `config` object (e.g., `text_`).
+ *     - **Purpose:** Defines the component's public API for external control, similar to props.
+ *     - **Use Case:** For data that a parent component will set or change.
+ *     - **Features:** Integrates with the full config system (e.g., `afterSetText()` hooks).
+ *
+ * 2.  **`useConfig()` (Internal State):** Used inside `createVdom` or other methods.
+ *     - **Purpose:** Manages private, encapsulated state that is internal to the component.
+ *     - **Use Case:** For state that the component manages itself and is not controlled by the parent.
+ *     - **Features:** Provides a simple, concise way to handle local reactive state.
+ *
+ * @param {Object} spec - The specification object for the component.
+ * @returns {Neo.functional.component.Base} The generated component class.
+ *
+ * @example
+ * import { defineComponent } from 'neo/functional/defineComponent.mjs';
+ * import { useConfig }       from 'neo/functional/useConfig.mjs';
+ *
+ * const MyComponent = defineComponent({
+ *     // 1. Define the Public API via the `config` object.
+ *     config: {
+ *         className: 'MyApp.MyFunctionalComponent',
+ *         ntype    : 'my-functional-component',
+ *
+ *         // `text_` is a NAMED CONFIG. It's part of the component's public API.
+ *         // A parent can create this component with a `text` config.
+ *         // It is reactive and will generate `afterSetText()` and `beforeSetText()` hooks.
+ *         text_: 'Hello World'
+ *     },
+ *
+ *     // 2. Define the component's logic and VDOM.
+ *     createVdom(config) {
+ *         // `useConfig` creates ANONYMOUS, INTERNAL STATE.
+ *         // The `count` state is private to this component and cannot be set by a parent.
+ *         const [count, setCount] = useConfig(0);
+ *
+ *         return {
+ *             tag: 'div',
+ *             cn: [{
+ *                 tag: 'h1',
+ *                 // Access the public, named config via the `config` parameter.
+ *                 text: config.text
+ *             }, {
+ *                 tag: 'p',
+ *                 // Access the private, internal state directly.
+ *                 text: `You clicked ${count} times`
+ *             }, {
+ *                 tag: 'button',
+ *                 text: 'Click me',
+ *                 // The setter from `useConfig` updates the internal state.
+ *                 onclick: () => setCount(count + 1)
+ *             }]
+ *         };
+ *     },
+ *
+ *     // 3. Lifecycle hooks for named configs work automatically.
+ *     afterSetText(newValue, oldValue) {
+ *         console.log(`Text changed from '${oldValue}' to '${newValue}'`);
+ *     }
+ * });
+ *
+ * // The returned MyComponent is a class constructor that can be used with Neo.create()
+ * // const instance = Neo.create(MyComponent, {
+ * //     text: 'Welcome to Neo.mjs!' // Set the public config on creation.
+ * // });
+ */
+export function defineComponent(spec) {
+    const configSpec = spec.config;
+    delete spec.config;
+
+    if (!configSpec?.className) {
+        throw new Error('defineComponent requires a config object with a className.');
+    }
+
+    class FunctionalComponent extends FunctionalBase {
+        static config = {
+            ...configSpec
+            // We can add our own configurations here
+        }
+    }
+
+    // Assign instance methods
+    Object.entries(spec).forEach(([key, value]) => {
+        FunctionalComponent.prototype[key] = value
+    });
+
+    // To support multiple envs (like `devmode`, `dist/esm`, `dist/production` in parallel,
+    // we must re-assign FunctionalComponent to the setupClass() output.
+    FunctionalComponent = Neo.setupClass(FunctionalComponent);
+
+    return FunctionalComponent
+}
+
+export default defineComponent;

package/src/functional/useConfig.mjs

@@ -0,0 +1,52 @@
+import Config        from '../core/Config.mjs';
+import EffectManager from '../core/EffectManager.mjs';
+
+const
+    hookIndexSymbol = Symbol.for('hookIndex'),
+    hooksSymbol     = Symbol.for('hooks');
+
+/**
+ * A hook for managing reactive state within a functional component's `createVdom` method.
+ * It mirrors the behavior of React's `useState` but is powered by `Neo.core.Config` for reactivity.
+ * @param {*} initialValue The initial value for the state.
+ * @returns {Array<any>} A tuple containing the current value and a setter function.
+ */
+export function useConfig(initialValue) {
+    EffectManager.pause();
+
+    const
+        effect    = EffectManager.getActiveEffect(),
+        component = effect && Neo.getComponent(effect.componentId);
+
+    if (!component) {
+        throw new Error('useConfig must be called from within a functional component\'s createVdom method.')
+    }
+
+    const currentIndex = component[hookIndexSymbol];
+
+    // Increment the index for the next hook call within the same component render cycle.
+    component[hookIndexSymbol]++;
+
+    // If this is the first time this hook is being called for this component, initialize its state.
+    if (!component[hooksSymbol][currentIndex]) {
+        const config = new Config(initialValue);
+
+        const customSetter = (newValue) => {
+            if (typeof newValue === 'function') {
+                newValue = newValue(config.get())
+            }
+            config.set(newValue)
+        };
+
+        component[hooksSymbol][currentIndex] = [config, customSetter]
+    }
+
+    const [config, setter] = component[hooksSymbol][currentIndex];
+
+    EffectManager.resume();
+
+    // Call config.get() to ensure this component's effect tracks this config as a dependency.
+    return [config.get(), setter]
+}
+
+export default useConfig;

package/src/functional/useEvent.mjs

@@ -0,0 +1,43 @@
+import EffectManager from '../core/EffectManager.mjs';
+
+const pendingDomEventsSymbol = Symbol.for('pendingDomEvents');
+
+/**
+ * A hook for registering DOM event listeners within a functional component.
+ * Event listeners registered via this hook will be managed by Neo.mjs's
+ * delegated DOM event system, ensuring efficient and proper lifecycle handling.
+ *
+ * @param {String} eventType - The type of DOM event to listen for (e.g., 'click', 'input').
+ * @param {Function} handler - The event handler function. It will receive the event data as its argument.
+ * @param {String} [delegate] - An optional CSS selector for event delegation. If provided,
+ *                               the handler will only fire if the event target matches this selector.
+ */
+export function useEvent(eventType, handler, delegate) {
+    const
+        activeEffect = EffectManager.getActiveEffect(),
+        componentId  = activeEffect?.componentId;
+
+    if (!componentId) {
+        throw new Error('useEvent must be called from within a functional component\'s createVdom method.')
+    }
+
+    EffectManager.pause();
+    const component = Neo.getComponent(componentId);
+    EffectManager.resume();
+
+    if (!component) {
+        throw new Error(`Component with id ${componentId} not found for useEvent hook.`);
+    }
+
+    // Ensure pendingDomEventsSymbol exists on the component instance
+    component[pendingDomEventsSymbol] ??= [];
+
+    // Add the event listener configuration to the component's pending list
+    component[pendingDomEventsSymbol].push({
+        [eventType]: handler,
+        delegate,
+        scope      : component // The component instance itself will be the scope
+    })
+}
+
+export default useEvent;