@mintjamsinc/ichigojs 0.1.8 → 0.1.10

package/README.md

@@ -16,9 +16,10 @@ 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`, `v-intersection`
+- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`, `v-intersection`, `v-performance`
 - 📐 **Resize Observer** - Monitor element size changes with `v-resize` directive
 - 👁️ **Intersection Observer** - Detect element visibility with `v-intersection` directive
+- ⚡ **Performance Observer** - Monitor performance metrics with `v-performance` directive
 
 ## Installation
 
@@ -200,8 +201,27 @@ 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
+- Custom box model via `:options.resize` or `:options`
 - Automatic cleanup in destroy phase
 - Access to element, VNode, and userData via `$ctx`
 
@@ -253,6 +273,56 @@ You can also use `:options` for generic options:
 - Perfect for lazy loading, infinite scroll, and animation triggers
 - Access to element, VNode, and userData via `$ctx`
 
+#### v-performance
+
+Monitor performance metrics using PerformanceObserver:
+
+```html
+<div v-performance="onPerformance">
+  Performance monitoring
+</div>
+```
+
+```javascript
+methods: {
+  onPerformance(entries, observer, options, $ctx) {
+    entries.getEntries().forEach(entry => {
+      console.log(`${entry.name}: ${entry.duration}ms`);
+    });
+
+    // Access dropped entries count if available
+    if (options?.droppedEntriesCount) {
+      console.log(`Dropped: ${options.droppedEntriesCount}`);
+    }
+  }
+}
+```
+
+**With custom options:**
+
+```html
+<div v-performance="onPerformance"
+     :options.performance="{entryTypes: ['measure', 'mark']}">
+  Observe only measures and marks
+</div>
+```
+
+You can also use `:options` for generic options:
+
+```html
+<div v-performance="onPerformance"
+     :options="{type: 'navigation', buffered: true}">
+  Performance monitoring
+</div>
+```
+
+**Features:**
+- Native PerformanceObserver API for monitoring performance metrics
+- Custom entry types and options via `:options.performance` or `:options`
+- Automatic cleanup in destroy phase
+- Monitor marks, measures, navigation, resource timing, and more
+- 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. Each hook receives a **lifecycle context** (`$ctx`) with access to the element, VNode, and userData storage.

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,18 +47,33 @@ 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";
+    /** Resize observer directives. */
     StandardDirectiveName["V_RESIZE"] = "v-resize";
+    /** Intersection observer directives. */
     StandardDirectiveName["V_INTERSECTION"] = "v-intersection";
+    /** Performance observer directives. */
+    StandardDirectiveName["V_PERFORMANCE"] = "v-performance";
 })(StandardDirectiveName || (StandardDirectiveName = {}));
 
 // This file was generated. Do not modify manually!
@@ -6575,6 +6594,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.
@@ -8311,6 +8333,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.
@@ -9896,6 +9923,220 @@ class VOnDirective {
     }
 }
 
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Directive for observing performance metrics using PerformanceObserver.
+ * The `v-performance` directive allows you to monitor various performance entries.
+ *
+ * Example usage:
+ *     <div v-performance="handlePerformance">Performance monitoring</div>
+ *     <div v-performance="handlePerformance" :options.performance="{entryTypes: ['measure']}">Performance monitoring</div>
+ *
+ * By default (without options), it observes 'mark' and 'measure' entry types.
+ *
+ * The handler receives PerformanceObserverEntryList, PerformanceObserver, options (with droppedEntriesCount), and $ctx as arguments:
+ *     handlePerformance(entries, observer, options, $ctx) {
+ *       entries.getEntries().forEach(entry => {
+ *         console.log(`${entry.name}: ${entry.duration}ms`);
+ *       });
+ *       if (options?.droppedEntriesCount) {
+ *         console.log(`Dropped entries: ${options.droppedEntriesCount}`);
+ *       }
+ *     }
+ *
+ * Options can be provided via :options or :options.performance attribute:
+ *     :options="{entryTypes: ['measure', 'mark']}"
+ *     :options.performance="{type: 'navigation', buffered: true}"
+ *
+ * This directive is useful for performance monitoring, profiling, and identifying
+ * performance bottlenecks in your application.
+ */
+class VPerformanceDirective {
+    /**
+     * 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 performance handler wrapper function.
+     */
+    #handlerWrapper;
+    /**
+     * The PerformanceObserver instance.
+     */
+    #performanceObserver;
+    /**
+     * @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.#createPerformanceHandlerWrapper(expression);
+        }
+        // Remove the directive attribute from the element
+        this.#vNode.node.removeAttribute(context.attribute.name);
+    }
+    /**
+     * @inheritdoc
+     */
+    get name() {
+        return StandardDirectiveName.V_PERFORMANCE;
+    }
+    /**
+     * @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 handler = this.#handlerWrapper;
+        return () => {
+            // Get options from :options.performance or :options directive
+            let optionsDirective = this.#vNode.directiveManager?.optionsDirective('performance');
+            // 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 PerformanceObserver and start observing
+            // Note: The callback receives a third argument 'options' with droppedEntriesCount in modern browsers
+            // TypeScript's type definition only includes 2 arguments, so we use type assertion
+            this.#performanceObserver = new PerformanceObserver(((...args) => {
+                const [entries, observer, callbackOptions] = args;
+                handler(entries, observer, callbackOptions);
+            }));
+            // If no options provided, use default: observe marks and measures
+            if (!options) {
+                options = { entryTypes: ['mark', 'measure'] };
+            }
+            // Start observing with options
+            this.#performanceObserver.observe(options);
+        };
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdate() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdated() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    destroy() {
+        // Disconnect the PerformanceObserver when the directive is destroyed
+        if (this.#performanceObserver) {
+            this.#performanceObserver.disconnect();
+            this.#performanceObserver = undefined;
+        }
+    }
+    /**
+     * Creates a wrapper function for performance handlers.
+     * @param expression The expression string to evaluate.
+     * @returns A function that handles the performance event.
+     */
+    #createPerformanceHandlerWrapper(expression) {
+        const identifiers = this.#dependentIdentifiers ?? [];
+        const vNode = this.#vNode;
+        // Return a function that handles the performance event with proper scope
+        return (entries, observer, options) => {
+            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, observer, options, and $ctx as arguments
+                return originalMethod(entries, observer, options, $ctx);
+            }
+            // For inline expressions, evaluate normally
+            // Note: inline expressions receive entries, observer, options, and $ctx as parameters
+            const values = identifiers.map(id => vNode.bindings?.get(id));
+            const args = [...identifiers, 'entries', 'observer', 'options', '$ctx'].join(", ");
+            const funcBody = `return (${expression});`;
+            const func = new Function(args, funcBody);
+            return func.call(bindings?.raw, ...values, entries, observer, options, $ctx);
+        };
+    }
+}
+
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * Directive for observing element resize events using ResizeObserver.
@@ -9903,6 +10144,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) {
@@ -9910,6 +10152,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.
  */
@@ -10002,11 +10248,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);
         };
     }
     /**
@@ -10308,7 +10567,9 @@ class VStandardDirectiveParser {
             // v-resize
             context.attribute.name === StandardDirectiveName.V_RESIZE ||
             // v-intersection
-            context.attribute.name === StandardDirectiveName.V_INTERSECTION) {
+            context.attribute.name === StandardDirectiveName.V_INTERSECTION ||
+            // v-performance
+            context.attribute.name === StandardDirectiveName.V_PERFORMANCE) {
             return true;
         }
         return false;
@@ -10355,6 +10616,10 @@ class VStandardDirectiveParser {
         if (context.attribute.name === StandardDirectiveName.V_INTERSECTION) {
             return new VIntersectionDirective(context);
         }
+        // v-performance
+        if (context.attribute.name === StandardDirectiveName.V_PERFORMANCE) {
+            return new VPerformanceDirective(context);
+        }
         throw new Error(`The attribute "${context.attribute.name}" cannot be parsed by ${this.name}.`);
     }
 }
@@ -10365,13 +10630,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 = {}));