@mintjamsinc/ichigojs 0.1.3 → 0.1.4

package/dist/ichigo.umd.js

@@ -6879,6 +6879,42 @@
         get expression() {
             return this.#expression;
         }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
         /**
          * @inheritdoc
          */
@@ -7637,6 +7673,11 @@
          * This is optional and may be undefined if there are no dependencies.
          */
         #closers;
+        /**
+         * Indicates whether this node has been templatized by a directive.
+         * This is optional and may be undefined if the node has not been templatized.
+         */
+        #templatized;
         /**
          * Creates an instance of the virtual node.
          * @param args The initialization arguments for the virtual node.
@@ -7650,23 +7691,31 @@
             this.#bindings = args.bindings;
             this.#initDependentIdentifiers = args.dependentIdentifiers;
             this.#parentVNode?.addChild(this);
-            // If the node is a text node, check for expressions and create a text evaluator
             if (this.#nodeType === Node.TEXT_NODE) {
+                // If the node is a text node, check for expressions and create a text evaluator
                 const text = this.#node;
                 // Create a text evaluator if the text contains expressions
                 if (VTextEvaluator.containsExpression(text.data)) {
                     this.#textEvaluator = new VTextEvaluator(text.data, this.#vApplication.functionDependencies);
                 }
             }
-            // If the node is an element, initialize directives and child nodes
-            if (this.#nodeType === Node.ELEMENT_NODE && this.#node.nodeType !== Node.DOCUMENT_FRAGMENT_NODE) {
+            else if (this.#nodeType === Node.ELEMENT_NODE) {
+                // If the node is an element, initialize directives and child nodes
                 this.#node;
                 // Initialize child virtual nodes
                 this.#childVNodes = [];
                 // Initialize directive manager
                 this.#directiveManager = new VDirectiveManager(this);
-                // For non-v-for elements, recursively create VNode instances for child nodes
-                if (!this.#directiveManager.directives?.some(d => d.templatize)) {
+                // Determine if any directive requires template preservation
+                this.#templatized = this.#directiveManager.directives?.some(d => d.templatize) ?? false;
+                // If no directive requires template preservation, call onMount for directives that do not templatize
+                if (!this.#templatized) {
+                    this.#directiveManager.directives?.forEach(d => {
+                        d.onMount?.();
+                    });
+                }
+                // Create child virtual nodes if template preservation is not required
+                if (!this.#templatized) {
                     for (const childNode of Array.from(this.#node.childNodes)) {
                         new VNode({
                             node: childNode,
@@ -7675,11 +7724,18 @@
                         });
                     }
                 }
+                // After creating child nodes, call onMounted for directives that do not templatize
+                if (!this.#templatized) {
+                    // animation frame to ensure DOM is updated
+                    requestAnimationFrame(() => {
+                        this.#directiveManager?.directives?.forEach(d => {
+                            d.onMounted?.();
+                        });
+                    });
+                }
             }
-            // If there is a parent virtual node, add this node as a dependency
-            if (this.#parentVNode) {
-                this.#closers = this.#parentVNode.addDependent(this);
-            }
+            // Register this node as a dependent of the parent node, if any
+            this.#closers = this.#parentVNode?.addDependent(this);
         }
         /**
          * The application instance associated with this virtual node.
@@ -7865,8 +7921,8 @@
          */
         update() {
             const changes = this.bindings?.changes || [];
-            // If this is a text node with a text evaluator, update its content if needed
             if (this.#nodeType === Node.TEXT_NODE && this.#textEvaluator) {
+                // If this is a text node with a text evaluator, update its content if needed
                 // Check if any of the identifiers are in the changed identifiers
                 const changed = this.#textEvaluator.identifiers.some(id => changes.includes(id));
                 // If the text node has changed, update its content
@@ -7874,38 +7930,52 @@
                     const text = this.#node;
                     text.data = this.#textEvaluator.evaluate(this.bindings);
                 }
-                return;
             }
-            // Prepare new bindings using directive bindings preparers, if any
-            if (this.#directiveManager?.bindingsPreparers) {
-                // Ensure local bindings are initialized
-                if (!this.#bindings) {
-                    this.#bindings = new VBindings({ parent: this.bindings });
+            else if (this.#nodeType === Node.ELEMENT_NODE) {
+                // If this is an element node, update directives and child nodes
+                // If no directive requires template preservation, call onUpdate for directives that do not templatize
+                if (!this.#templatized) {
+                    this.#directiveManager?.directives?.forEach(d => {
+                        d.onUpdate?.();
+                    });
                 }
-                // Prepare bindings for each preparer if relevant identifiers have changed
-                for (const preparer of this.#directiveManager.bindingsPreparers) {
-                    const changed = preparer.dependentIdentifiers.some(id => changes.includes(id));
-                    if (changed) {
-                        preparer.prepareBindings();
+                // Prepare new bindings using directive bindings preparers, if any
+                if (this.#directiveManager?.bindingsPreparers) {
+                    // Ensure local bindings are initialized
+                    if (!this.#bindings) {
+                        this.#bindings = new VBindings({ parent: this.bindings });
+                    }
+                    // Prepare bindings for each preparer if relevant identifiers have changed
+                    for (const preparer of this.#directiveManager.bindingsPreparers) {
+                        const changed = preparer.dependentIdentifiers.some(id => changes.includes(id));
+                        if (changed) {
+                            preparer.prepareBindings();
+                        }
                     }
                 }
-            }
-            // Apply DOM updaters from directives, if any
-            if (this.#directiveManager?.domUpdaters) {
-                for (const updater of this.#directiveManager.domUpdaters) {
-                    const changed = updater.dependentIdentifiers.some(id => changes.includes(id));
+                // Apply DOM updaters from directives, if any
+                if (this.#directiveManager?.domUpdaters) {
+                    for (const updater of this.#directiveManager.domUpdaters) {
+                        const changed = updater.dependentIdentifiers.some(id => changes.includes(id));
+                        if (changed) {
+                            updater.applyToDOM();
+                        }
+                    }
+                }
+                // Recursively update dependent virtual nodes
+                this.#dependents?.forEach(dependentNode => {
+                    const changed = dependentNode.dependentIdentifiers.some(id => changes.includes(id));
                     if (changed) {
-                        updater.applyToDOM();
+                        dependentNode.update();
                     }
+                });
+                // If no directive requires template preservation, call onUpdated for directives that do not templatize
+                if (!this.#templatized) {
+                    this.#directiveManager?.directives?.forEach(d => {
+                        d.onUpdated?.();
+                    });
                 }
             }
-            // Recursively update dependent virtual nodes
-            this.#dependents?.forEach(dependentNode => {
-                const changed = dependentNode.dependentIdentifiers.some(id => changes.includes(id));
-                if (changed) {
-                    dependentNode.update();
-                }
-            });
         }
         /**
          * Forces an update of the virtual node and its children, regardless of changed identifiers.
@@ -7914,33 +7984,47 @@
          * This is useful when an immediate update is needed, bypassing the usual change detection.
          */
         forceUpdate() {
-            // If this is a text node with a text evaluator, update its content if needed
             if (this.#nodeType === Node.TEXT_NODE && this.#textEvaluator) {
+                // If this is a text node with a text evaluator, update its content if needed
                 const text = this.#node;
                 text.data = this.#textEvaluator.evaluate(this.bindings);
-                return;
             }
-            // Prepare new bindings using directive bindings preparers, if any
-            if (this.#directiveManager?.bindingsPreparers) {
-                // Ensure local bindings are initialized
-                if (!this.#bindings) {
-                    this.#bindings = new VBindings({ parent: this.bindings });
+            else if (this.#nodeType === Node.ELEMENT_NODE) {
+                // If this is an element node, update directives and child nodes
+                // If no directive requires template preservation, call onUpdate for directives that do not templatize
+                if (!this.#templatized) {
+                    this.#directiveManager?.directives?.forEach(d => {
+                        d.onUpdate?.();
+                    });
                 }
-                // Prepare bindings for each preparer if relevant identifiers have changed
-                for (const preparer of this.#directiveManager.bindingsPreparers) {
-                    preparer.prepareBindings();
+                // Prepare new bindings using directive bindings preparers, if any
+                if (this.#directiveManager?.bindingsPreparers) {
+                    // Ensure local bindings are initialized
+                    if (!this.#bindings) {
+                        this.#bindings = new VBindings({ parent: this.bindings });
+                    }
+                    // Prepare bindings for each preparer if relevant identifiers have changed
+                    for (const preparer of this.#directiveManager.bindingsPreparers) {
+                        preparer.prepareBindings();
+                    }
                 }
-            }
-            // Apply DOM updaters from directives, if any
-            if (this.#directiveManager?.domUpdaters) {
-                for (const updater of this.#directiveManager.domUpdaters) {
-                    updater.applyToDOM();
+                // Apply DOM updaters from directives, if any
+                if (this.#directiveManager?.domUpdaters) {
+                    for (const updater of this.#directiveManager.domUpdaters) {
+                        updater.applyToDOM();
+                    }
+                }
+                // Recursively update child virtual nodes
+                this.#childVNodes?.forEach(childVNode => {
+                    childVNode.forceUpdate();
+                });
+                // If no directive requires template preservation, call onUpdated for directives that do not templatize
+                if (!this.#templatized) {
+                    this.#directiveManager?.directives?.forEach(d => {
+                        d.onUpdated?.();
+                    });
                 }
             }
-            // Recursively update child virtual nodes
-            this.#childVNodes?.forEach(childVNode => {
-                childVNode.forceUpdate();
-            });
         }
         /**
          * Adds a child virtual node to this virtual node.
@@ -8013,6 +8097,12 @@
          * This method is called when the virtual node is no longer needed.
          */
         destroy() {
+            // If no directive requires template preservation, call onUnmount for directives that do not templatize
+            if (!this.#templatized) {
+                this.#directiveManager?.directives?.forEach(d => {
+                    d.onUnmount?.();
+                });
+            }
             // Recursively destroy child nodes
             if (this.#childVNodes) {
                 for (const childVNode of this.#childVNodes) {
@@ -8037,6 +8127,12 @@
             }
             // Clean up directive handler
             this.#directiveManager?.destroy();
+            // If no directive requires template preservation, call onUnmounted for directives that do not templatize
+            if (!this.#templatized) {
+                this.#directiveManager?.directives?.forEach(d => {
+                    d.onUnmounted?.();
+                });
+            }
         }
     }
 
@@ -8204,6 +8300,42 @@
             }
             return this.#evaluate();
         }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
         /**
          * @inheritdoc
          */
@@ -8258,8 +8390,10 @@
                 // Not rendered, no action needed
                 return;
             }
-            this.#renderedVNode.node.parentNode?.removeChild(this.#renderedVNode.node);
+            // Destroy VNode first (calls @unmount hooks while DOM is still accessible)
             this.#renderedVNode.destroy();
+            // Then remove from DOM
+            this.#renderedVNode.node.parentNode?.removeChild(this.#renderedVNode.node);
             this.#renderedVNode = undefined;
         }
         /**
@@ -8488,16 +8622,56 @@
         get dependentIdentifiers() {
             return this.#dependentIdentifiers ?? [];
         }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
         /**
          * @inheritdoc
          */
         destroy() {
             // Clean up all rendered items
+            // First destroy all VNodes (calls @unmount hooks), then remove from DOM
+            for (const vNode of this.#renderedItems.values()) {
+                vNode.destroy();
+            }
+            // Then remove DOM nodes
             for (const vNode of this.#renderedItems.values()) {
                 if (vNode.node.parentNode) {
                     vNode.node.parentNode.removeChild(vNode.node);
                 }
-                vNode.destroy();
             }
             this.#renderedItems.clear();
             this.#previousIterations = [];
@@ -8554,14 +8728,20 @@
             // Track which keys are still needed
             const neededKeys = new Set(newIterations.map(ctx => ctx.key));
             // Remove items that are no longer needed
+            // First destroy VNodes (calls @unmount hooks while DOM is still accessible)
+            const nodesToRemove = [];
             for (const [key, vNode] of this.#renderedItems) {
                 if (!neededKeys.has(key)) {
-                    if (vNode.node.parentNode) {
-                        vNode.node.parentNode.removeChild(vNode.node);
-                    }
+                    nodesToRemove.push(vNode);
                     vNode.destroy();
                 }
             }
+            // Then remove from DOM
+            for (const vNode of nodesToRemove) {
+                if (vNode.node.parentNode) {
+                    vNode.node.parentNode.removeChild(vNode.node);
+                }
+            }
             // Add or reorder items
             let prevNode = anchor;
             for (const context of newIterations) {
@@ -8874,6 +9054,42 @@
         get dependentIdentifiers() {
             return this.#dependentIdentifiers ?? [];
         }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
         /**
          * @inheritdoc
          */
@@ -9033,7 +9249,7 @@
 
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
     /**
-     * Directive for binding event listeners to DOM elements.
+     * Directive for binding event listeners to DOM elements and lifecycle hooks.
      * The `v-on` directive allows you to listen to DOM events and execute specified methods when those events are triggered.
      * The syntax for using the `v-on` directive is `v-on:event="methodName"`, where `event` is the name of the event to listen for (e.g., `click`, `mouseover`, etc.), and `methodName` is the name of the method to be called when the event occurs.
      * Example usage:
@@ -9042,7 +9258,16 @@
      * You can also use the shorthand `@event` instead of `v-on:event`. For example, `@click="handleClick"` is equivalent to `v-on:click="handleClick"`.
      * The `v-on` directive supports event modifiers such as `.stop`, `.prevent`, `.capture`, `.self`, and `.once` to modify the behavior of the event listener.
      * For example, `v-on:click.stop="handleClick"` will stop the event from propagating up the DOM tree.
-     * This directive is essential for handling user interactions in your application.
+     *
+     * Additionally, this directive supports lifecycle hooks:
+     *     @mount="onMount"       - Called before the element is inserted into the DOM
+     *     @mounted="onMounted"   - Called after the element is inserted into the DOM
+     *     @update="onUpdate"     - Called before the element is updated
+     *     @updated="onUpdated"   - Called after the element is updated
+     *     @unmount="onUnmount"   - Called before the element is removed from the DOM
+     *     @unmounted="onUnmounted" - Called after the element is removed from the DOM
+     *
+     * This directive is essential for handling user interactions and lifecycle events in your application.
      * Note that the methods referenced in the directive should be defined in the component's methods object.
      */
     class VOnDirective {
@@ -9056,10 +9281,12 @@
         #dependentIdentifiers;
         /**
          * The event handler wrapper function, generated once and reused.
+         * For lifecycle hooks, this is a no-argument function.
+         * For DOM events, this accepts an Event parameter.
          */
         #handlerWrapper;
         /**
-         * The event name (e.g., "click", "input", "keydown").
+         * The event name (e.g., "click", "input", "keydown") or lifecycle hook name (e.g., "mount", "mounted").
          */
         #eventName;
         /**
@@ -9067,9 +9294,13 @@
          */
         #modifiers = new Set();
         /**
-         * The event listener function.
+         * The event listener function for DOM events.
          */
         #listener;
+        /**
+         * Map of lifecycle hook names to their handler functions.
+         */
+        #lifecycleHooks = new Map();
         /**
          * @param context The context for parsing the directive.
          */
@@ -9093,10 +9324,22 @@
             const expression = context.attribute.value;
             if (expression) {
                 this.#dependentIdentifiers = ExpressionUtils.extractIdentifiers(expression, context.vNode.vApplication.functionDependencies);
-                this.#handlerWrapper = this.#createHandlerWrapper(expression);
             }
-            // Create and attach the event listener
-            if (this.#eventName) {
+            // Check if this is a lifecycle hook or a regular event
+            if (this.#eventName && this.#isLifecycleHook(this.#eventName)) {
+                // Create handler wrapper for lifecycle hook (no event parameter)
+                if (expression) {
+                    const handler = this.#createLifecycleHandlerWrapper(expression);
+                    this.#handlerWrapper = handler;
+                    this.#lifecycleHooks.set(this.#eventName, handler);
+                }
+            }
+            else if (this.#eventName) {
+                // Create handler wrapper for DOM event (with event parameter)
+                if (expression) {
+                    this.#handlerWrapper = this.#createEventHandlerWrapper(expression);
+                }
+                // Create and attach DOM event listener
                 this.#attachEventListener();
             }
             // Remove the directive attribute from the element
@@ -9144,6 +9387,42 @@
         get dependentIdentifiers() {
             return this.#dependentIdentifiers ?? [];
         }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return this.#lifecycleHooks.get('mount');
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return this.#lifecycleHooks.get('mounted');
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return this.#lifecycleHooks.get('update');
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return this.#lifecycleHooks.get('updated');
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return this.#lifecycleHooks.get('unmount');
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return this.#lifecycleHooks.get('unmounted');
+        }
         /**
          * @inheritdoc
          */
@@ -9220,11 +9499,48 @@
             element.addEventListener(eventName, this.#listener, useCapture);
         }
         /**
-         * Creates a wrapper function for the event handler, generated once and reused.
+         * Checks if the event name is a lifecycle hook.
+         * @param eventName The event name to check.
+         * @returns True if the event name is a lifecycle hook, false otherwise.
+         */
+        #isLifecycleHook(eventName) {
+            return ['mount', 'mounted', 'update', 'updated', 'unmount', 'unmounted'].includes(eventName);
+        }
+        /**
+         * Creates a wrapper function for lifecycle hooks (with element parameter).
+         * @param expression The expression string to evaluate.
+         * @returns A function that handles the lifecycle hook.
+         */
+        #createLifecycleHandlerWrapper(expression) {
+            const identifiers = this.#dependentIdentifiers ?? [];
+            const vNode = this.#vNode;
+            // Return a function that handles the lifecycle hook with proper scope
+            return () => {
+                const bindings = vNode.bindings;
+                const el = vNode.node;
+                // If the expression is just a method name, call it with bindings as 'this'
+                const trimmedExpr = expression.trim();
+                if (identifiers.includes(trimmedExpr) && typeof bindings?.get(trimmedExpr) === 'function') {
+                    const methodName = trimmedExpr;
+                    const originalMethod = bindings?.get(methodName);
+                    // Call the method with bindings as 'this' context and element as parameter
+                    // This allows the method to access the DOM element and bindings
+                    return originalMethod(el);
+                }
+                // For inline expressions, evaluate normally with element parameter
+                const values = identifiers.map(id => vNode.bindings?.get(id));
+                const args = [...identifiers, 'el'].join(", ");
+                const funcBody = `return (${expression});`;
+                const func = new Function(args, funcBody);
+                return func.call(bindings?.raw, ...values, el);
+            };
+        }
+        /**
+         * Creates a wrapper function for DOM event handlers (with event parameter).
          * @param expression The expression string to evaluate.
          * @returns A function that handles the event.
          */
-        #createHandlerWrapper(expression) {
+        #createEventHandlerWrapper(expression) {
             const identifiers = this.#dependentIdentifiers ?? [];
             const vNode = this.#vNode;
             // Return a function that handles the event with proper scope
@@ -9383,6 +9699,42 @@
             // Hide the element
             element.style.display = "none";
         }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
         /**
          * @inheritdoc
          */