@mintjamsinc/ichigojs 0.1.7 → 0.1.9

package/dist/ichigo.umd.js

@@ -9,6 +9,10 @@
     }
 
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Registry for managing directive parsers.
+     * This class allows registering, unregistering, and finding directive parsers.
+     */
     class VDirectiveParserRegistry {
         /**
          * The list of registered directive parsers.
@@ -49,17 +53,31 @@
     }
 
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Standard directive names used in the framework.
+     */
     var StandardDirectiveName;
     (function (StandardDirectiveName) {
+        /** Conditional rendering directives (if). */
         StandardDirectiveName["V_IF"] = "v-if";
+        /** Conditional rendering directives (else if). */
         StandardDirectiveName["V_ELSE_IF"] = "v-else-if";
+        /** Conditional rendering directives (else). */
         StandardDirectiveName["V_ELSE"] = "v-else";
+        /** Conditional rendering directives (show). */
         StandardDirectiveName["V_SHOW"] = "v-show";
+        /** List rendering directives. */
         StandardDirectiveName["V_FOR"] = "v-for";
+        /** Event handling directives. */
         StandardDirectiveName["V_ON"] = "v-on";
+        /** Attribute binding directives. */
         StandardDirectiveName["V_BIND"] = "v-bind";
+        /** Two-way data binding directives. */
         StandardDirectiveName["V_MODEL"] = "v-model";
+        /** Slot content insertion directives. */
         StandardDirectiveName["V_RESIZE"] = "v-resize";
+        /** Intersection observer directives. */
+        StandardDirectiveName["V_INTERSECTION"] = "v-intersection";
     })(StandardDirectiveName || (StandardDirectiveName = {}));
 
     // This file was generated. Do not modify manually!
@@ -6580,6 +6598,9 @@
     };
 
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Utility class for analyzing JavaScript expressions to extract variable and function dependencies.
+     */
     class ExpressionUtils {
         /**
          * Extracts variable and function names used in the expression.
@@ -6874,6 +6895,19 @@
         get isKey() {
             return (this.#attributeName === 'key');
         }
+        /**
+         * Indicates if this directive is binding the "options" attribute or any of its sub-properties (e.g., "options.intersection").
+         * The "options" attribute is special and is used for passing options to certain directives like VIntersectionDirective.
+         */
+        get isOptions() {
+            return (this.#attributeName === 'options' || this.#attributeName?.startsWith('options.') === true);
+        }
+        /**
+         * Gets the name of the attribute being bound (e.g., "src", "class", "options", "options.intersection").
+         */
+        get attributeName() {
+            return this.#attributeName;
+        }
         /**
          * Gets the original expression string from the directive.
          */
@@ -6926,8 +6960,8 @@
          * Renders the bound attribute by evaluating the expression and updating the DOM element.
          */
         #render() {
-            // If this directive is binding the "key" attribute, do nothing
-            if (this.isKey) {
+            // Do nothing for special attributes
+            if (this.isKey || this.isOptions) {
                 return;
             }
             const element = this.#vNode.node;
@@ -7371,16 +7405,47 @@
     }
 
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Manages directives associated with a virtual node (VNode).
+     * This class is responsible for parsing, storing, and managing the lifecycle of directives.
+     * It also provides access to bindings preparers and DOM updaters from the associated directives.
+     */
     class VDirectiveManager {
         /**
          * The virtual node to which this directive handler is associated.
          */
         #vNode;
+        /**
+         * The list of directives associated with the virtual node.
+         * This may be undefined if there are no directives.
+         */
         #directives;
+        /**
+         * The anchor comment node used for certain directives (e.g., v-if, v-for).
+         * This may be undefined if no directive requires an anchor.
+         */
         #anchorNode;
+        /**
+         * The list of bindings preparers from the associated directives.
+         * This may be undefined if no directive provides a bindings preparer.
+         */
         #bindingsPreparers;
+        /**
+         * The list of DOM updaters from the associated directives.
+         * This may be undefined if no directive provides a DOM updater.
+         */
         #domUpdaters;
+        /**
+         * The directive that binds the ":key" or "v-bind:key" attribute, if any.
+         * This directive is special and is used for optimizing rendering of lists.
+         * If no such directive exists, this is undefined.
+         */
         #keyDirective;
+        /**
+         * A cache of VBindDirectives for options specific to certain directives.
+         * The keys are directive names (e.g., 'options', 'options.intersection').
+         */
+        #optionsDirectives = {};
         constructor(vNode) {
             // Directives can only be associated with element nodes
             if (vNode.nodeType !== Node.ELEMENT_NODE) {
@@ -7438,6 +7503,35 @@
         get keyDirective() {
             return this.#keyDirective;
         }
+        /**
+         * Gets a record of VBindDirectives for options specific to certain directives.
+         * The keys are directive names (e.g., 'options', 'options.intersection').
+         */
+        get optionsDirectives() {
+            return this.#optionsDirectives;
+        }
+        /**
+         * Gets the VBindDirective for options specific to the given directive name.
+         * Searches in order: `:options.{directive}` -> `:options`
+         *
+         * @param directive The directive name (e.g., 'intersection', 'resize')
+         * @returns The VBindDirective instance or undefined
+         */
+        optionsDirective(directive) {
+            if (!this.#directives || this.#directives.length === 0) {
+                return undefined;
+            }
+            // Search for `:options.{directive}` or `v-bind:options.{directive}` first
+            const specificAttrName = `options.${directive}`;
+            if (this.#optionsDirectives[specificAttrName]) {
+                return this.#optionsDirectives[specificAttrName];
+            }
+            // Fallback: search for `:options` or `v-bind:options`
+            if (this.#optionsDirectives['options']) {
+                return this.#optionsDirectives['options'];
+            }
+            return undefined;
+        }
         /**
          * Cleans up any resources used by the directive handler.
          */
@@ -7497,6 +7591,10 @@
                     if (directive.name === StandardDirectiveName.V_BIND && directive.isKey) {
                         this.#keyDirective = directive;
                     }
+                    // If this is an options binding directive, cache it
+                    if (directive.name === StandardDirectiveName.V_BIND && directive.isOptions) {
+                        this.#optionsDirectives[directive.name] = directive;
+                    }
                 }
             }
             // Sort directives by priority: v-for > v-if > v-else-if > v-else > v-show > others
@@ -8239,6 +8337,11 @@
     }
 
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Base class for conditional directives such as v-if, v-else-if, and v-else.
+     * This class manages the rendering of the associated virtual node based on the evaluation of the directive's condition.
+     * It also coordinates with other related conditional directives to ensure only one block is rendered at a time.
+     */
     class VConditionalDirective {
         /**
          * The virtual node to which this directive is applied.
@@ -8984,6 +9087,209 @@
         }
     }
 
+    // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Directive for observing element intersection with viewport or ancestor elements using IntersectionObserver.
+     * The `v-intersection` directive allows you to respond to changes in an element's visibility.
+     *
+     * Example usage:
+     *     <div v-intersection="handleIntersection">Observable content</div>
+     *     <div v-intersection="handleIntersection" :options.intersection="{threshold: 0.5}">Observable content</div>
+     *
+     * The handler receives IntersectionObserverEntry array as the first argument and $ctx as the second:
+     *     handleIntersection(entries, $ctx) {
+     *       const entry = entries[0];
+     *       if (entry.isIntersecting) {
+     *         console.log('Element is visible!');
+     *       }
+     *     }
+     *
+     * Options can be provided via :options or :options.intersection attribute:
+     *     :options="{root: null, threshold: 0.5, rootMargin: '0px'}"
+     *     :options.intersection="{root: null, threshold: 0.5, rootMargin: '0px'}"
+     *
+     * This directive is useful for lazy-loading, infinite scrolling, animation triggers,
+     * and other features that depend on element visibility.
+     */
+    class VIntersectionDirective {
+        /**
+         * The virtual node to which this directive is applied.
+         */
+        #vNode;
+        /**
+         * A list of variable and function names used in the directive's expression.
+         */
+        #dependentIdentifiers;
+        /**
+         * The intersection handler wrapper function.
+         */
+        #handlerWrapper;
+        /**
+         * The IntersectionObserver instance.
+         */
+        #intersectionObserver;
+        /**
+         * @param context The context for parsing the directive.
+         */
+        constructor(context) {
+            this.#vNode = context.vNode;
+            // Parse the expression to extract identifiers and create the handler wrapper
+            const expression = context.attribute.value;
+            if (expression) {
+                this.#dependentIdentifiers = ExpressionUtils.extractIdentifiers(expression, context.vNode.vApplication.functionDependencies);
+                this.#handlerWrapper = this.#createIntersectionHandlerWrapper(expression);
+            }
+            // Remove the directive attribute from the element
+            this.#vNode.node.removeAttribute(context.attribute.name);
+        }
+        /**
+         * @inheritdoc
+         */
+        get name() {
+            return StandardDirectiveName.V_INTERSECTION;
+        }
+        /**
+         * @inheritdoc
+         */
+        get vNode() {
+            return this.#vNode;
+        }
+        /**
+         * @inheritdoc
+         */
+        get needsAnchor() {
+            return false;
+        }
+        /**
+         * @inheritdoc
+         */
+        get bindingsPreparer() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get domUpdater() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get templatize() {
+            return false;
+        }
+        /**
+         * @inheritdoc
+         */
+        get dependentIdentifiers() {
+            return this.#dependentIdentifiers ?? [];
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            if (!this.#handlerWrapper) {
+                return undefined;
+            }
+            const element = this.#vNode.node;
+            const handler = this.#handlerWrapper;
+            return () => {
+                // Get options from :options.intersection or :options directive
+                let optionsDirective = this.#vNode.directiveManager?.optionsDirective('intersection');
+                // Evaluate the options expression
+                let options;
+                if (optionsDirective && optionsDirective.expression) {
+                    // Evaluate the options expression
+                    const identifiers = optionsDirective.dependentIdentifiers;
+                    const values = identifiers.map(id => this.#vNode.bindings?.get(id));
+                    const args = identifiers.join(", ");
+                    const funcBody = `return (${optionsDirective.expression});`;
+                    const func = new Function(args, funcBody);
+                    options = func(...values);
+                }
+                // Create IntersectionObserver and start observing
+                this.#intersectionObserver = new IntersectionObserver((entries) => {
+                    handler(entries);
+                }, options);
+                this.#intersectionObserver.observe(element);
+            };
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        destroy() {
+            // Disconnect the IntersectionObserver when the directive is destroyed
+            if (this.#intersectionObserver) {
+                this.#intersectionObserver.disconnect();
+                this.#intersectionObserver = undefined;
+            }
+        }
+        /**
+         * Creates a wrapper function for intersection handlers.
+         * @param expression The expression string to evaluate.
+         * @returns A function that handles the intersection event.
+         */
+        #createIntersectionHandlerWrapper(expression) {
+            const identifiers = this.#dependentIdentifiers ?? [];
+            const vNode = this.#vNode;
+            // Return a function that handles the intersection event with proper scope
+            return (entries) => {
+                const bindings = vNode.bindings;
+                const $ctx = {
+                    element: vNode.node,
+                    vnode: vNode,
+                    userData: vNode.userData
+                };
+                // 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
+                    // Pass entries as first argument and $ctx as second argument
+                    return originalMethod(entries, $ctx);
+                }
+                // For inline expressions, evaluate normally
+                // Note: inline expressions receive entries and $ctx as parameters
+                const values = identifiers.map(id => vNode.bindings?.get(id));
+                const args = [...identifiers, 'entries', '$ctx'].join(", ");
+                const funcBody = `return (${expression});`;
+                const func = new Function(args, funcBody);
+                return func.call(bindings?.raw, ...values, entries, $ctx);
+            };
+        }
+    }
+
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
     /**
      * Directive for two-way data binding on form input elements.
@@ -9309,7 +9615,7 @@
      *     @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
+     *     @unmount="onUnmount"   - Called before VNode cleanup begins
      *     @unmounted="onUnmounted" - Called after VNode cleanup is complete (element reference still available)
      *
      * This directive is essential for handling user interactions and lifecycle events in your application.
@@ -9628,6 +9934,7 @@
      *
      * Example usage:
      *     <div v-resize="handleResize">Resizable content</div>
+     *     <div v-resize="handleResize" :options.resize="{box: 'border-box'}">Resizable content</div>
      *
      * The handler receives ResizeObserverEntry array as the first argument and $ctx as the second:
      *     handleResize(entries, $ctx) {
@@ -9635,6 +9942,10 @@
      *       console.log(`Size: ${width}x${height}`);
      *     }
      *
+     * Options can be provided via :options or :options.resize attribute:
+     *     :options="{box: 'border-box'}"
+     *     :options.resize="{box: 'content-box'}"
+     *
      * This directive is useful for responsive layouts, charts, and other components
      * that need to adapt to size changes.
      */
@@ -9727,11 +10038,24 @@
             const element = this.#vNode.node;
             const handler = this.#handlerWrapper;
             return () => {
+                // Get options from :options.resize or :options directive
+                let optionsDirective = this.#vNode.directiveManager?.optionsDirective('resize');
+                // Evaluate the options expression
+                let options;
+                if (optionsDirective && optionsDirective.expression) {
+                    // Evaluate the options expression
+                    const identifiers = optionsDirective.dependentIdentifiers;
+                    const values = identifiers.map(id => this.#vNode.bindings?.get(id));
+                    const args = identifiers.join(", ");
+                    const funcBody = `return (${optionsDirective.expression});`;
+                    const func = new Function(args, funcBody);
+                    options = func(...values);
+                }
                 // Create ResizeObserver and start observing
                 this.#resizeObserver = new ResizeObserver((entries) => {
                     handler(entries);
                 });
-                this.#resizeObserver.observe(element);
+                this.#resizeObserver.observe(element, options);
             };
         }
         /**
@@ -10031,7 +10355,9 @@
                 context.attribute.name === StandardDirectiveName.V_MODEL ||
                 context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".") ||
                 // v-resize
-                context.attribute.name === StandardDirectiveName.V_RESIZE) {
+                context.attribute.name === StandardDirectiveName.V_RESIZE ||
+                // v-intersection
+                context.attribute.name === StandardDirectiveName.V_INTERSECTION) {
                 return true;
             }
             return false;
@@ -10074,6 +10400,10 @@
             if (context.attribute.name === StandardDirectiveName.V_RESIZE) {
                 return new VResizeDirective(context);
             }
+            // v-intersection
+            if (context.attribute.name === StandardDirectiveName.V_INTERSECTION) {
+                return new VIntersectionDirective(context);
+            }
             throw new Error(`The attribute "${context.attribute.name}" cannot be parsed by ${this.name}.`);
         }
     }
@@ -10084,13 +10414,13 @@
      */
     var LogLevel;
     (function (LogLevel) {
-        // Debug level
+        /** Debug level */
         LogLevel["DEBUG"] = "debug";
-        // Info level
+        /** Info level */
         LogLevel["INFO"] = "info";
-        // Warning level
+        /** Warning level */
         LogLevel["WARN"] = "warn";
-        // Error level
+        /** Error level */
         LogLevel["ERROR"] = "error";
     })(LogLevel || (LogLevel = {}));