@mintjamsinc/ichigojs 0.1.5 → 0.1.7

package/README.md

@@ -11,11 +11,13 @@ A simple and intuitive reactive framework. Lightweight, fast, and user-friendly
 - ⚡ **Reactive Proxy System** - Automatic change detection without manual triggers
 - 🎯 **Computed Properties** - Automatic dependency tracking and re-evaluation
 - 🔄 **Two-way Binding** - `v-model` with modifiers (`.lazy`, `.number`, `.trim`)
-- 🔌 **Lifecycle Hooks** - `@mount`, `@mounted`, `@update`, `@updated`, `@unmount`, `@unmounted`
+- 🔌 **Lifecycle Hooks** - `@mount`, `@mounted`, `@update`, `@updated`, `@unmount`, `@unmounted` with context (`$ctx`)
+- 💾 **userData Storage** - Proxy-free storage for third-party library instances with auto-cleanup
 - 📦 **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`
+- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`
+- 📐 **Resize Observer** - Monitor element size changes with `v-resize` directive
 
 ## Installation
 
@@ -159,9 +161,52 @@ Event handling with modifiers:
 
 Supported modifiers: `.stop`, `.prevent`, `.capture`, `.self`, `.once`
 
+**Event Handlers with Context:**
+
+All event handlers receive the event as the first parameter and `$ctx` as the second parameter:
+
+```javascript
+methods: {
+  handleClick(event, $ctx) {
+    // event - the DOM event object
+    // $ctx.element - the DOM element
+    // $ctx.vnode - the VNode instance
+    // $ctx.userData - Proxy-free storage
+  }
+}
+```
+
+#### v-resize
+
+Monitor element size changes using ResizeObserver:
+
+```html
+<div v-resize="onResize" class="resizable-box">
+  {{ width }}px × {{ height }}px
+</div>
+```
+
+```javascript
+methods: {
+  onResize(entries, $ctx) {
+    const entry = entries[0];
+    this.width = Math.round(entry.contentRect.width);
+    this.height = Math.round(entry.contentRect.height);
+
+    // Access element through $ctx
+    console.log('Element:', $ctx.element);
+  }
+}
+```
+
+**Features:**
+- Native ResizeObserver API for efficient resize detection
+- Automatic cleanup when element is removed
+- Access to element, VNode, and userData via `$ctx`
+
 #### Lifecycle Hooks
 
-Lifecycle hooks allow you to run code at specific stages of an element's lifecycle:
+Lifecycle hooks allow you to run code at specific stages of an element's lifecycle. Each hook receives a **lifecycle context** (`$ctx`) with access to the element, VNode, and userData storage.
 
 ```html
 <div v-if="show"
@@ -182,31 +227,85 @@ Lifecycle hooks allow you to run code at specific stages of an element's lifecyc
 - `@update` - Called before the element is updated
 - `@updated` - Called after the element is updated
 - `@unmount` - Called before the element is removed from the DOM
-- `@unmounted` - Called after the element is removed from the DOM
+- `@unmounted` - Called after VNode cleanup is complete (element reference still available)
+
+**Lifecycle Context (`$ctx`):**
 
-**Use cases:**
+Every lifecycle hook receives a context object with:
+
+- `$ctx.element` - The DOM element
+- `$ctx.vnode` - The VNode instance
+- `$ctx.userData` - Proxy-free storage Map for user data
+
+**userData Storage:**
+
+`$ctx.userData` is a safe space to store data associated with the element's lifecycle. It's not affected by the reactive proxy system, making it perfect for storing third-party library instances.
 
 ```javascript
 methods: {
-  onMounted(el) {
-    // Initialize third-party library (el is the DOM element)
-    const canvas = el.querySelector('canvas');
-    canvas._chartInstance = new Chart(canvas.getContext('2d'), { /* ... */ });
+  onMounted($ctx) {
+    // Initialize third-party library
+    const canvas = $ctx.element.querySelector('canvas');
+    const chart = new Chart(canvas.getContext('2d'), {
+      type: 'line',
+      data: { /* ... */ }
+    });
+
+    // Store in userData (Proxy-free storage)
+    $ctx.userData.set('chart', chart);
   },
-  onUpdated(el) {
-    // Update chart with new data
-    const canvas = el.querySelector('canvas');
-    canvas._chartInstance?.update();
+
+  onUpdated($ctx) {
+    // Retrieve from userData
+    const chart = $ctx.userData.get('chart');
+    if (chart) {
+      chart.data.labels = [...this.labels];
+      chart.update();
+    }
   },
-  onUnmounted(el) {
-    // Clean up resources
-    const canvas = el.querySelector('canvas');
-    canvas._chartInstance?.destroy();
-    delete canvas._chartInstance;
+
+  onUnmount($ctx) {
+    // Clean up before removal
+    const chart = $ctx.userData.get('chart');
+    if (chart) {
+      chart.destroy();
+      $ctx.userData.delete('chart');
+    }
+  }
+}
+```
+
+**Automatic Cleanup:**
+
+Objects with a `close()` method stored in `userData` are automatically cleaned up during the destroy phase:
+
+```javascript
+methods: {
+  onMounted($ctx) {
+    // Object with close() method
+    const resource = {
+      data: someData,
+      close() {
+        // Custom cleanup logic
+        console.log('Resource cleaned up');
+      }
+    };
+
+    $ctx.userData.set('myResource', resource);
+    // resource.close() will be called automatically on unmount
   }
 }
 ```
 
+**Cleanup Order:**
+
+1. `@unmount` hook fires (element still in DOM)
+2. `userData` auto-cleanup (close() methods called)
+3. Child nodes destroyed recursively
+4. Dependencies unregistered
+5. Directive manager cleanup
+6. `@unmounted` hook fires (element removed from DOM, but reference still available in `$ctx.element`)
+
 **Works with v-if and v-for:**
 
 ```html

package/dist/ichigo.esm.js

@@ -53,6 +53,7 @@ var StandardDirectiveName;
     StandardDirectiveName["V_ON"] = "v-on";
     StandardDirectiveName["V_BIND"] = "v-bind";
     StandardDirectiveName["V_MODEL"] = "v-model";
+    StandardDirectiveName["V_RESIZE"] = "v-resize";
 })(StandardDirectiveName || (StandardDirectiveName = {}));
 
 // This file was generated. Do not modify manually!
@@ -7672,6 +7673,13 @@ class VNode {
      * This is optional and may be undefined if the node has not been templatized.
      */
     #templatized;
+    /**
+     * User data storage for lifecycle directives.
+     * This provides a Proxy-free space where developers can store arbitrary data
+     * associated with this VNode. The data is automatically cleaned up when the
+     * VNode is destroyed.
+     */
+    #userData;
     /**
      * Creates an instance of the virtual node.
      * @param args The initialization arguments for the virtual node.
@@ -7883,6 +7891,18 @@ class VNode {
         this.#preparableIdentifiers = preparableIdentifiers.length === 0 ? [] : [...new Set(preparableIdentifiers)];
         return this.#preparableIdentifiers;
     }
+    /**
+     * Gets the user data storage for this virtual node.
+     * This is lazily initialized and provides a Proxy-free space for storing
+     * arbitrary data associated with lifecycle directives.
+     * @returns A Map for storing user data.
+     */
+    get userData() {
+        if (!this.#userData) {
+            this.#userData = new Map();
+        }
+        return this.#userData;
+    }
     /**
      * The DOM path of this virtual node.
      * This is a string representation of the path from the root to this node,
@@ -8089,6 +8109,14 @@ class VNode {
     /**
      * Cleans up any resources used by this virtual node.
      * This method is called when the virtual node is no longer needed.
+     *
+     * Cleanup order:
+     * 1. Call onUnmount lifecycle hooks
+     * 2. Auto-cleanup userData (close() on Closeable objects)
+     * 3. Recursively destroy child nodes
+     * 4. Unregister dependencies
+     * 5. Clean up directive manager
+     * 6. Call onUnmounted lifecycle hooks
      */
     destroy() {
         // If no directive requires template preservation, call onUnmount for directives that do not templatize
@@ -8097,6 +8125,23 @@ class VNode {
                 d.onUnmount?.();
             });
         }
+        // Clean up user data, calling close() on any Closeable objects
+        // This happens after onUnmount but before other cleanup, allowing users to
+        // perform custom cleanup in onUnmount while having automatic cleanup of userData
+        if (this.#userData) {
+            for (const [key, value] of this.#userData.entries()) {
+                try {
+                    // If the value has a close() method (Closeable pattern), call it
+                    if (value && typeof value === 'object' && typeof value.close === 'function') {
+                        value.close();
+                    }
+                }
+                catch (error) {
+                    this.#vApplication.logManager.getLogger(this.constructor.name).error(`Error closing user data '${key}': ${error}`);
+                }
+            }
+            this.#userData.clear();
+        }
         // Recursively destroy child nodes
         if (this.#childVNodes) {
             for (const childVNode of this.#childVNodes) {
@@ -9259,7 +9304,7 @@ class VModelDirective {
  *     @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
+ *     @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.
  * Note that the methods referenced in the directive should be defined in the component's methods object.
@@ -9501,7 +9546,7 @@ class VOnDirective {
         return ['mount', 'mounted', 'update', 'updated', 'unmount', 'unmounted'].includes(eventName);
     }
     /**
-     * Creates a wrapper function for lifecycle hooks (with element parameter).
+     * Creates a wrapper function for lifecycle hooks (with context parameter).
      * @param expression The expression string to evaluate.
      * @returns A function that handles the lifecycle hook.
      */
@@ -9511,26 +9556,31 @@ class VOnDirective {
         // Return a function that handles the lifecycle hook with proper scope
         return () => {
             const bindings = vNode.bindings;
-            const el = vNode.node;
+            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 and element as parameter
-                // This allows the method to access the DOM element and bindings
-                return originalMethod(el);
+                // Call the method with bindings as 'this' context and context as parameter
+                // This allows the method to access the DOM element, VNode, and userData
+                return originalMethod($ctx);
             }
-            // For inline expressions, evaluate normally with element parameter
+            // For inline expressions, evaluate normally with $ctx parameter
+            // Note: $ctx is a reserved variable name for lifecycle context
             const values = identifiers.map(id => vNode.bindings?.get(id));
-            const args = [...identifiers, 'el'].join(", ");
+            const args = [...identifiers, '$ctx'].join(", ");
             const funcBody = `return (${expression});`;
             const func = new Function(args, funcBody);
-            return func.call(bindings?.raw, ...values, el);
+            return func.call(bindings?.raw, ...values, $ctx);
         };
     }
     /**
-     * Creates a wrapper function for DOM event handlers (with event parameter).
+     * Creates a wrapper function for DOM event handlers (with event and $ctx parameters).
      * @param expression The expression string to evaluate.
      * @returns A function that handles the event.
      */
@@ -9540,21 +9590,210 @@ class VOnDirective {
         // Return a function that handles the event with proper scope
         return (event) => {
             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
-                // This allows the method to access and modify bindings properties via 'this'
-                return originalMethod(event);
+                // Pass event as first argument and $ctx as second argument
+                return originalMethod(event, $ctx);
             }
             // For inline expressions, evaluate normally
+            // Note: inline expressions receive event and $ctx as parameters
             const values = identifiers.map(id => vNode.bindings?.get(id));
-            const args = identifiers.join(", ");
+            const args = [...identifiers, 'event', '$ctx'].join(", ");
             const funcBody = `return (${expression});`;
             const func = new Function(args, funcBody);
-            return func.call(bindings?.raw, ...values, event);
+            return func.call(bindings?.raw, ...values, event, $ctx);
+        };
+    }
+}
+
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Directive for observing element resize events using ResizeObserver.
+ * The `v-resize` directive allows you to respond to changes in an element's size.
+ *
+ * Example usage:
+ *     <div v-resize="handleResize">Resizable content</div>
+ *
+ * The handler receives ResizeObserverEntry array as the first argument and $ctx as the second:
+ *     handleResize(entries, $ctx) {
+ *       const { width, height } = entries[0].contentRect;
+ *       console.log(`Size: ${width}x${height}`);
+ *     }
+ *
+ * This directive is useful for responsive layouts, charts, and other components
+ * that need to adapt to size changes.
+ */
+class VResizeDirective {
+    /**
+     * 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 resize handler wrapper function.
+     */
+    #handlerWrapper;
+    /**
+     * The ResizeObserver instance.
+     */
+    #resizeObserver;
+    /**
+     * @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.#createResizeHandlerWrapper(expression);
+        }
+        // Remove the directive attribute from the element
+        this.#vNode.node.removeAttribute(context.attribute.name);
+    }
+    /**
+     * @inheritdoc
+     */
+    get name() {
+        return StandardDirectiveName.V_RESIZE;
+    }
+    /**
+     * @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 () => {
+            // Create ResizeObserver and start observing
+            this.#resizeObserver = new ResizeObserver((entries) => {
+                handler(entries);
+            });
+            this.#resizeObserver.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 ResizeObserver when the directive is destroyed
+        if (this.#resizeObserver) {
+            this.#resizeObserver.disconnect();
+            this.#resizeObserver = undefined;
+        }
+    }
+    /**
+     * Creates a wrapper function for resize handlers.
+     * @param expression The expression string to evaluate.
+     * @returns A function that handles the resize event.
+     */
+    #createResizeHandlerWrapper(expression) {
+        const identifiers = this.#dependentIdentifiers ?? [];
+        const vNode = this.#vNode;
+        // Return a function that handles the resize 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);
         };
     }
 }
@@ -9784,7 +10023,9 @@ class VStandardDirectiveParser {
             context.attribute.name.startsWith(":") ||
             // v-model, v-model.<modifier>
             context.attribute.name === StandardDirectiveName.V_MODEL ||
-            context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".")) {
+            context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".") ||
+            // v-resize
+            context.attribute.name === StandardDirectiveName.V_RESIZE) {
             return true;
         }
         return false;
@@ -9823,6 +10064,10 @@ class VStandardDirectiveParser {
             context.attribute.name.startsWith(StandardDirectiveName.V_MODEL + ".")) {
             return new VModelDirective(context);
         }
+        // v-resize
+        if (context.attribute.name === StandardDirectiveName.V_RESIZE) {
+            return new VResizeDirective(context);
+        }
         throw new Error(`The attribute "${context.attribute.name}" cannot be parsed by ${this.name}.`);
     }
 }