eleva 1.0.0-rc.13 → 1.0.0-rc.14

package/dist/eleva.esm.js

@@ -1,103 +1,47 @@
-/*! Eleva v1.0.0-rc.13 | MIT License | https://elevajs.com */
+/*! Eleva v1.0.0-rc.14 | MIT License | https://elevajs.com */
 // ============================================================================
 // TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
 // ============================================================================
 /**
- * @typedef {Record<string, unknown>} TemplateData
- *           Data context for template interpolation
- */ /**
- * @typedef {string} TemplateString
- *           A string containing {{ expression }} interpolation markers
+ * @typedef {Record<string, unknown>} ContextData
+ *           Data context for expression evaluation
  */ /**
  * @typedef {string} Expression
  *           A JavaScript expression to be evaluated in the data context
  */ /**
  * @typedef {unknown} EvaluationResult
- *           The result of evaluating an expression (string, number, boolean, object, etc.)
+ *           The result of evaluating an expression (string, number, boolean, object, function, etc.)
  */ /**
  * @class 🔒 TemplateEngine
- * @classdesc A secure template engine that handles interpolation and dynamic attribute parsing.
- * Provides a way to evaluate expressions in templates.
- * All methods are static and can be called directly on the class.
+ * @classdesc A minimal expression evaluator for Eleva's directive attributes.
+ * Evaluates JavaScript expressions against a component's context data.
+ * Used internally for `@event` handlers and `:prop` bindings.
  *
- * Template Syntax:
- * - `{{ expression }}` - Interpolate any JavaScript expression
- * - `{{ variable }}` - Access data properties directly
- * - `{{ object.property }}` - Access nested properties
- * - `{{ condition ? a : b }}` - Ternary expressions
- * - `{{ func(arg) }}` - Call functions from data context
+ * All methods are static and can be called directly on the class.
  *
  * @example
- * // Basic interpolation
- * const template = "Hello, {{name}}!";
- * const data = { name: "World" };
- * const result = TemplateEngine.parse(template, data);
- * // Result: "Hello, World!"
+ * // Property access
+ * TemplateEngine.evaluate("user.name", { user: { name: "John" } });
+ * // Result: "John"
  *
  * @example
- * // Nested properties
- * const template = "Welcome, {{user.name}}!";
- * const data = { user: { name: "John" } };
- * const result = TemplateEngine.parse(template, data);
- * // Result: "Welcome, John!"
+ * // Function reference (for @event handlers)
+ * TemplateEngine.evaluate("handleClick", { handleClick: () => console.log("clicked") });
+ * // Result: [Function]
  *
  * @example
- * // Expressions
- * const template = "Status: {{active ? 'Online' : 'Offline'}}";
- * const data = { active: true };
- * const result = TemplateEngine.parse(template, data);
- * // Result: "Status: Online"
+ * // Signal values (for :prop bindings)
+ * TemplateEngine.evaluate("count.value", { count: { value: 42 } });
+ * // Result: 42
  *
  * @example
- * // With Signal values
- * const template = "Count: {{count.value}}";
- * const data = { count: { value: 42 } };
- * const result = TemplateEngine.parse(template, data);
- * // Result: "Count: 42"
+ * // Complex expressions
+ * TemplateEngine.evaluate("items.filter(i => i.active)", { items: [{active: true}, {active: false}] });
+ * // Result: [{active: true}]
  */ class TemplateEngine {
     /**
-   * Parses a template string, replacing expressions with their evaluated values.
-   * Expressions are evaluated in the provided data context.
-   *
-   * @public
-   * @static
-   * @param {TemplateString|unknown} template - The template string to parse.
-   * @param {TemplateData} data - The data context for evaluating expressions.
-   * @returns {string} The parsed template with expressions replaced by their values.
-   *
-   * @example
-   * // Simple variables
-   * TemplateEngine.parse("Hello, {{name}}!", { name: "World" });
-   * // Result: "Hello, World!"
-   *
-   * @example
-   * // Nested properties
-   * TemplateEngine.parse("{{user.name}} is {{user.age}} years old", {
-   *   user: { name: "John", age: 30 }
-   * });
-   * // Result: "John is 30 years old"
-   *
-   * @example
-   * // Multiple expressions
-   * TemplateEngine.parse("{{greeting}}, {{name}}! You have {{count}} messages.", {
-   *   greeting: "Hello",
-   *   name: "User",
-   *   count: 5
-   * });
-   * // Result: "Hello, User! You have 5 messages."
-   *
-   * @example
-   * // With conditionals
-   * TemplateEngine.parse("Status: {{online ? 'Active' : 'Inactive'}}", {
-   *   online: true
-   * });
-   * // Result: "Status: Active"
-   */ static parse(template, data) {
-        if (typeof template !== "string") return template;
-        return template.replace(this.expressionPattern, (_, expression)=>this.evaluate(expression, data));
-    }
-    /**
    * Evaluates an expression in the context of the provided data object.
+   * Used for resolving `@event` handlers and `:prop` bindings.
    *
    * Note: This does not provide a true sandbox and evaluated expressions may access global scope.
    * The use of the `with` statement is necessary for expression evaluation but has security implications.
@@ -106,7 +50,7 @@
    * @public
    * @static
    * @param {Expression|unknown} expression - The expression to evaluate.
-   * @param {TemplateData} data - The data context for evaluation.
+   * @param {ContextData} data - The data context for evaluation.
    * @returns {EvaluationResult} The result of the evaluation, or empty string if evaluation fails.
    *
    * @example
@@ -115,9 +59,19 @@
    * // Result: "John"
    *
    * @example
-   * // Numeric values
-   * TemplateEngine.evaluate("user.age", { user: { age: 30 } });
-   * // Result: 30
+   * // Function reference
+   * TemplateEngine.evaluate("increment", { increment: () => count++ });
+   * // Result: [Function]
+   *
+   * @example
+   * // Nested property with Signal
+   * TemplateEngine.evaluate("count.value", { count: { value: 42 } });
+   * // Result: 42
+   *
+   * @example
+   * // Object reference (no JSON.stringify needed)
+   * TemplateEngine.evaluate("user", { user: { name: "John", age: 30 } });
+   * // Result: { name: "John", age: 30 }
    *
    * @example
    * // Expressions
@@ -125,19 +79,12 @@
    * // Result: true
    *
    * @example
-   * // Function calls
-   * TemplateEngine.evaluate("formatDate(date)", {
-   *   date: new Date(),
-   *   formatDate: (d) => d.toISOString()
-   * });
-   * // Result: "2024-01-01T00:00:00.000Z"
-   *
-   * @example
    * // Failed evaluation returns empty string
    * TemplateEngine.evaluate("nonexistent.property", {});
    * // Result: ""
    */ static evaluate(expression, data) {
         if (typeof expression !== "string") return expression;
+        if (!expression.trim()) return "";
         let fn = this._functionCache.get(expression);
         if (!fn) {
             try {
@@ -154,14 +101,6 @@
         }
     }
 }
-/**
-   * Regular expression for matching template expressions in the format {{ expression }}
-   * Matches: {{ anything }} with optional whitespace inside braces
-   *
-   * @static
-   * @private
-   * @type {RegExp}
-   */ TemplateEngine.expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
 /**
    * Cache for compiled expression functions.
    * Stores compiled Function objects keyed by expression string for O(1) lookup.
@@ -1096,8 +1035,7 @@
        * 3. Updating the DOM
        * 4. Processing events, injecting styles, and mounting child components.
        */ const render = async ()=>{
-                const templateResult = typeof template === "function" ? await template(mergedContext) : template;
-                const html = this.templateEngine.parse(templateResult, mergedContext);
+                const html = typeof template === "function" ? await template(mergedContext) : template;
                 // Execute before hooks
                 if (!isMounted) {
                     await mergedContext.onBeforeMount?.({
@@ -1113,7 +1051,7 @@
                 this.renderer.patchDOM(container, html);
                 this._processEvents(container, mergedContext, listeners);
                 if (style) this._injectStyles(container, compId, style, mergedContext);
-                if (children) await this._mountComponents(container, children, childInstances);
+                if (children) await this._mountComponents(container, children, childInstances, mergedContext);
                 // Execute after hooks
                 if (!isMounted) {
                     await mergedContext.onMount?.({
@@ -1206,7 +1144,7 @@
    * @param {ComponentContext} context - The current component context for style interpolation.
    * @returns {void}
    */ _injectStyles(container, compId, styleDef, context) {
-        /** @type {string} */ const newStyle = typeof styleDef === "function" ? this.templateEngine.parse(styleDef(context), context) : styleDef;
+        /** @type {string} */ const newStyle = typeof styleDef === "function" ? styleDef(context) : styleDef;
         /** @type {HTMLStyleElement|null} */ let styleEl = container.querySelector(`style[data-e-style="${compId}"]`);
         if (styleEl && styleEl.textContent === newStyle) return;
         if (!styleEl) {
@@ -1217,17 +1155,20 @@
         styleEl.textContent = newStyle;
     }
     /**
-   * Extracts props from an element's attributes that start with the specified prefix.
-   * This method is used to collect component properties from DOM elements.
+   * Extracts and evaluates props from an element's attributes that start with `:`.
+   * Prop values are evaluated as expressions against the component context,
+   * allowing direct passing of objects, arrays, and other complex types.
    *
    * @private
    * @param {HTMLElement} element - The DOM element to extract props from
-   * @returns {Record<string, string>} An object containing the extracted props
+   * @param {ComponentContext} context - The component context for evaluating prop expressions
+   * @returns {Record<string, string>} An object containing the evaluated props
    * @example
    * // For an element with attributes:
-   * // <div :name="John" :age="25">
-   * // Returns: { name: "John", age: "25" }
-   */ _extractProps(element) {
+   * // <div :name="user.name" :data="items">
+   * // With context: { user: { name: "John" }, items: [1, 2, 3] }
+   * // Returns: { name: "John", data: [1, 2, 3] }
+   */ _extractProps(element, context) {
         if (!element.attributes) return {};
         const props = {};
         const attrs = element.attributes;
@@ -1235,7 +1176,7 @@
             const attr = attrs[i];
             if (attr.name.startsWith(":")) {
                 const propName = attr.name.slice(1);
-                props[propName] = attr.value;
+                props[propName] = this.templateEngine.evaluate(attr.value, context);
                 element.removeAttribute(attr.name);
             }
         }
@@ -1253,6 +1194,7 @@
    * @param {HTMLElement} container - The container element to mount components in
    * @param {Object<string, ComponentDefinition>} children - Map of selectors to component definitions for explicit children
    * @param {Array<MountResult>} childInstances - Array to store all mounted component instances
+   * @param {ComponentContext} context - The parent component context for evaluating prop expressions
    * @returns {Promise<void>}
    *
    * @example
@@ -1261,12 +1203,12 @@
    *   'UserProfile': UserProfileComponent,
    *   '#settings-panel': "settings-panel"
    * };
-   */ async _mountComponents(container, children, childInstances) {
+   */ async _mountComponents(container, children, childInstances, context) {
         for (const [selector, component] of Object.entries(children)){
             if (!selector) continue;
             for (const el of container.querySelectorAll(selector)){
                 if (!(el instanceof HTMLElement)) continue;
-                /** @type {Record<string, string>} */ const props = this._extractProps(el);
+                /** @type {Record<string, string>} */ const props = this._extractProps(el, context);
                 /** @type {MountResult} */ const instance = await this.mount(el, component, props);
                 if (instance && !childInstances.includes(instance)) {
                     childInstances.push(instance);