eleva 1.0.0-alpha → 1.0.0-rc.10

package/types/modules/TemplateEngine.d.ts

@@ -1,26 +1,166 @@
 /**
- * 🔒 TemplateEngine: Secure interpolation & dynamic attribute parsing.
+ * @typedef {Record<string, unknown>} TemplateData
+ *           Data context for template interpolation
+ */
+/**
+ * @typedef {string} TemplateString
+ *           A string containing {{ expression }} interpolation markers
+ */
+/**
+ * @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.)
+ */
+/**
+ * @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.
+ *
+ * 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
  *
- * This class provides methods to parse template strings by replacing
- * interpolation expressions with dynamic data values and to evaluate expressions
- * within a given data context.
+ * @example
+ * // Basic interpolation
+ * const template = "Hello, {{name}}!";
+ * const data = { name: "World" };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Hello, World!"
+ *
+ * @example
+ * // Nested properties
+ * const template = "Welcome, {{user.name}}!";
+ * const data = { user: { name: "John" } };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Welcome, John!"
+ *
+ * @example
+ * // Expressions
+ * const template = "Status: {{active ? 'Online' : 'Offline'}}";
+ * const data = { active: true };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Status: Online"
+ *
+ * @example
+ * // With Signal values
+ * const template = "Count: {{count.value}}";
+ * const data = { count: { value: 42 } };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Count: 42"
  */
 export class TemplateEngine {
     /**
-     * Parses a template string and replaces interpolation expressions with corresponding values.
+     * Regular expression for matching template expressions in the format {{ expression }}
+     * Matches: {{ anything }} with optional whitespace inside braces
      *
-     * @param {string} template - The template string containing expressions in the format {{ expression }}.
-     * @param {object} data - The data object to use for evaluating expressions.
-     * @returns {string} The resulting string with evaluated values.
+     * @static
+     * @private
+     * @type {RegExp}
      */
-    static parse(template: string, data: object): string;
+    private static expressionPattern;
     /**
-     * Evaluates an expression using the provided data context.
+     * 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.
      *
-     * @param {string} expr - The JavaScript expression to evaluate.
-     * @param {object} data - The data context for evaluating the expression.
-     * @returns {*} The result of the evaluated expression, or an empty string if undefined or on error.
+     * @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 evaluate(expr: string, data: object): any;
+    public static parse(template: TemplateString | unknown, data: TemplateData): string;
+    /**
+     * Evaluates an expression in the context of the provided data object.
+     *
+     * 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.
+     * Only use with trusted templates. User input should never be directly interpolated.
+     *
+     * @public
+     * @static
+     * @param {Expression|unknown} expression - The expression to evaluate.
+     * @param {TemplateData} data - The data context for evaluation.
+     * @returns {EvaluationResult} The result of the evaluation, or an empty string if evaluation fails.
+     *
+     * @example
+     * // Property access
+     * TemplateEngine.evaluate("user.name", { user: { name: "John" } });
+     * // Result: "John"
+     *
+     * @example
+     * // Numeric values
+     * TemplateEngine.evaluate("user.age", { user: { age: 30 } });
+     * // Result: 30
+     *
+     * @example
+     * // Expressions
+     * TemplateEngine.evaluate("items.length > 0", { items: [1, 2, 3] });
+     * // 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: ""
+     */
+    public static evaluate(expression: Expression | unknown, data: TemplateData): EvaluationResult;
 }
+/**
+ * Data context for template interpolation
+ */
+export type TemplateData = Record<string, unknown>;
+/**
+ * A string containing {{ expression }} interpolation markers
+ */
+export type TemplateString = string;
+/**
+ * A JavaScript expression to be evaluated in the data context
+ */
+export type Expression = string;
+/**
+ * The result of evaluating an expression (string, number, boolean, object, etc.)
+ */
+export type EvaluationResult = unknown;
 //# sourceMappingURL=TemplateEngine.d.ts.map

package/types/modules/TemplateEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../src/modules/TemplateEngine.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH;IACE;;;;;;OAMG;IACH,uBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,sBAJW,MAAM,QACN,MAAM,GACJ,GAAC,CAgBb;CACF"}
+{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../src/modules/TemplateEngine.js"],"names":[],"mappings":"AAMA;;;GAGG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IACE;;;;;;;OAOG;IACH,iCAAkD;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,8BAhCW,cAAc,GAAC,OAAO,QACtB,YAAY,GACV,MAAM,CAmClB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,mCAhCW,UAAU,GAAC,OAAO,QAClB,YAAY,GACV,gBAAgB,CAqC5B;CACF;;;;2BArKY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;6BAKvB,MAAM;;;;yBAKN,MAAM;;;;+BAKN,OAAO"}

package/types/plugins/Attr.d.ts

@@ -0,0 +1,28 @@
+export namespace AttrPlugin {
+    let name: string;
+    let version: string;
+    let description: string;
+    /**
+     * Installs the plugin into the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     * @param {Object} options - Plugin configuration options
+     * @param {boolean} [options.enableAria=true] - Enable ARIA attribute handling
+     * @param {boolean} [options.enableData=true] - Enable data attribute handling
+     * @param {boolean} [options.enableBoolean=true] - Enable boolean attribute handling
+     * @param {boolean} [options.enableDynamic=true] - Enable dynamic property detection
+     */
+    function install(eleva: Object, options?: {
+        enableAria?: boolean | undefined;
+        enableData?: boolean | undefined;
+        enableBoolean?: boolean | undefined;
+        enableDynamic?: boolean | undefined;
+    }): void;
+    /**
+     * Uninstalls the plugin from the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     */
+    function uninstall(eleva: Object): void;
+}
+//# sourceMappingURL=Attr.d.ts.map

package/types/plugins/Attr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Attr.d.ts","sourceRoot":"","sources":["../../src/plugins/Attr.js"],"names":[],"mappings":";cAyCY,MAAM;iBAMN,MAAM;qBAMN,MAAM;IAIhB;;;;;;;;;OASG;IACH,wBAPW,MAAM,YAEd;QAA0B,UAAU;QACV,UAAU;QACV,aAAa;QACb,aAAa;KACzC,QAmKA;IAED;;;;OAIG;IACH,0BAFW,MAAM,QAgBhB"}

package/types/plugins/Props.d.ts

@@ -0,0 +1,48 @@
+export namespace PropsPlugin {
+    let name: string;
+    let version: string;
+    let description: string;
+    /**
+     * Installs the plugin into the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     * @param {Object} options - Plugin configuration options
+     * @param {boolean} [options.enableAutoParsing=true] - Enable automatic type detection and parsing
+     * @param {boolean} [options.enableReactivity=true] - Enable reactive prop updates using Eleva's signal system
+     * @param {Function} [options.onError=null] - Error handler function called when parsing fails
+     *
+     * @example
+     * // Basic installation
+     * app.use(PropsPlugin);
+     *
+     * // Installation with custom options
+     * app.use(PropsPlugin, {
+     *   enableAutoParsing: true,
+     *   enableReactivity: false,
+     *   onError: (error, value) => {
+     *     console.error('Props parsing error:', error, value);
+     *   }
+     * });
+     */
+    function install(eleva: Object, options?: {
+        enableAutoParsing?: boolean | undefined;
+        enableReactivity?: boolean | undefined;
+        onError?: Function | undefined;
+    }): void;
+    /**
+     * Uninstalls the plugin from the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     *
+     * @description
+     * Restores the original Eleva methods and removes all plugin-specific
+     * functionality. This method should be called when the plugin is no
+     * longer needed.
+     *
+     * @example
+     * // Uninstall the plugin
+     * PropsPlugin.uninstall(app);
+     */
+    function uninstall(eleva: Object): void;
+}
+//# sourceMappingURL=Props.d.ts.map

package/types/plugins/Props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Props.d.ts","sourceRoot":"","sources":["../../src/plugins/Props.js"],"names":[],"mappings":";cAuDY,MAAM;iBAMN,MAAM;qBAMN,MAAM;IAKhB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,wBAnBW,MAAM,YAEd;QAA0B,iBAAiB;QACjB,gBAAgB;QACf,OAAO;KAElC,QAodF;IAED;;;;;;;;;;;;;OAaG;IACH,0BAXW,MAAM,QAkChB"}