@mintjamsinc/ichigojs 0.1.7 → 0.1.9

package/README.md

@@ -16,8 +16,9 @@ A simple and intuitive reactive framework. Lightweight, fast, and user-friendly
 - 📦 **Lightweight** - Minimal bundle size
 - 🚀 **High Performance** - Efficient batched updates via microtask queue
 - 💪 **TypeScript** - Written in TypeScript with full type support
-- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`
+- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`, `v-intersection`
 - 📐 **Resize Observer** - Monitor element size changes with `v-resize` directive
+- 👁️ **Intersection Observer** - Detect element visibility with `v-intersection` directive
 
 ## Installation
 
@@ -199,9 +200,76 @@ methods: {
 }
 ```
 
+**With custom options:**
+
+```html
+<div v-resize="onResize"
+     :options.resize="{box: 'border-box'}">
+  Observe border-box dimensions
+</div>
+```
+
+You can also use `:options` for generic options:
+
+```html
+<div v-resize="onResize"
+     :options="{box: 'content-box'}">
+  Resizable content
+</div>
+```
+
 **Features:**
 - Native ResizeObserver API for efficient resize detection
-- Automatic cleanup when element is removed
+- Custom box model via `:options.resize` or `:options`
+- Automatic cleanup in destroy phase
+- Access to element, VNode, and userData via `$ctx`
+
+#### v-intersection
+
+Detect element visibility using IntersectionObserver:
+
+```html
+<div v-intersection="onIntersection" class="observable-box">
+  I'm {{ isVisible ? 'VISIBLE' : 'NOT VISIBLE' }}
+</div>
+```
+
+```javascript
+methods: {
+  onIntersection(entries, $ctx) {
+    const entry = entries[0];
+    this.isVisible = entry.isIntersecting;
+    this.intersectionRatio = entry.intersectionRatio;
+
+    // Access element through $ctx
+    console.log('Element:', $ctx.element);
+  }
+}
+```
+
+**With custom options:**
+
+```html
+<div v-intersection="onIntersection"
+     :options.intersection="{threshold: 0.5, rootMargin: '0px'}">
+  Triggers at 50% visibility
+</div>
+```
+
+You can also use `:options` for generic options:
+
+```html
+<div v-intersection="onIntersection"
+     :options="{threshold: 0.5}">
+  Observable content
+</div>
+```
+
+**Features:**
+- Native IntersectionObserver API for efficient visibility detection
+- Custom threshold and rootMargin options via `:options.intersection` or `:options`
+- Automatic cleanup in destroy phase
+- Perfect for lazy loading, infinite scroll, and animation triggers
 - Access to element, VNode, and userData via `$ctx`
 
 #### Lifecycle Hooks
@@ -226,7 +294,7 @@ Lifecycle hooks allow you to run code at specific stages of an element's lifecyc
 - `@mounted` - Called after the element is inserted into the DOM
 - `@update` - Called before the element is updated
 - `@updated` - Called after the element is updated
-- `@unmount` - Called before the element is removed from the DOM
+- `@unmount` - Called before VNode cleanup begins
 - `@unmounted` - Called after VNode cleanup is complete (element reference still available)
 
 **Lifecycle Context (`$ctx`):**
@@ -292,7 +360,7 @@ methods: {
     };
 
     $ctx.userData.set('myResource', resource);
-    // resource.close() will be called automatically on unmount
+    // resource.close() will be called automatically during destroy phase
   }
 }
 ```

package/dist/ichigo.esm.js

@@ -3,6 +3,10 @@ class VComponentRegistry {
 }
 
 // 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.
@@ -43,17 +47,31 @@ class VDirectiveParserRegistry {
 }
 
 // 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!
@@ -6574,6 +6592,9 @@ base.MethodDefinition = base.PropertyDefinition = base.Property = function (node
 };
 
 // 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.
@@ -6868,6 +6889,19 @@ class VBindDirective {
     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.
      */
@@ -6920,8 +6954,8 @@ class VBindDirective {
      * 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;
@@ -7365,16 +7399,47 @@ class VBindings {
 }
 
 // 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) {
@@ -7432,6 +7497,35 @@ class VDirectiveManager {
     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.
      */
@@ -7491,6 +7585,10 @@ class VDirectiveManager {
                 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
@@ -8233,6 +8331,11 @@ class VConditionalDirectiveContext {
 }
 
 // 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.
@@ -8978,6 +9081,209 @@ class VIfDirective extends VConditionalDirective {
     }
 }
 
+// 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.
@@ -9303,7 +9609,7 @@ class VModelDirective {
  *     @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.
@@ -9622,6 +9928,7 @@ class VOnDirective {
  *
  * 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) {
@@ -9629,6 +9936,10 @@ class VOnDirective {
  *       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.
  */
@@ -9721,11 +10032,24 @@ class VResizeDirective {
         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);
         };
     }
     /**
@@ -10025,7 +10349,9 @@ class VStandardDirectiveParser {
             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;
@@ -10068,6 +10394,10 @@ class VStandardDirectiveParser {
         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}.`);
     }
 }
@@ -10078,13 +10408,13 @@ class VStandardDirectiveParser {
  */
 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 = {}));