@webmate-studio/builder 0.2.112 → 0.2.113

package/src/template-evaluator.js

@@ -0,0 +1,379 @@
+/**
+ * Template Evaluator — Evaluates a Template AST with data to produce HTML.
+ *
+ * Takes the AST from TemplateParser and a data context, walks the tree,
+ * and produces the final HTML string.
+ *
+ * Key design principles:
+ * - Every node type is handled by exactly one method
+ * - Context is passed through via scope chain (spread), never mutated
+ * - Nested loops work automatically because parent scope is preserved
+ * - No regex, no string scanning — pure AST traversal
+ *
+ * @module template-evaluator
+ */
+
+class TemplateEvaluator {
+	/**
+	 * @param {import('./expression-evaluator.js').ExpressionEvaluator} expressionEvaluator
+	 */
+	constructor(expressionEvaluator) {
+		this.expr = expressionEvaluator;
+	}
+
+	/**
+	 * Evaluate an AST node with a data context and produce HTML
+	 * @param {Object} ast - AST node from TemplateParser
+	 * @param {Object} context - Data context
+	 * @returns {string} HTML output
+	 */
+	evaluate(ast, context) {
+		if (!ast) return '';
+		return this.evalNode(ast, context);
+	}
+
+	/**
+	 * Main dispatch — evaluates a single AST node
+	 */
+	evalNode(node, ctx) {
+		switch (node.type) {
+			case 'Fragment':
+				return this.evalFragment(node, ctx);
+			case 'Text':
+				return node.value;
+			case 'Expression':
+				return this.evalExpression(node, ctx);
+			case 'HtmlExpression':
+				return this.evalHtmlExpression(node, ctx);
+			case 'ConstTag':
+				return this.evalConstTag(node, ctx);
+			case 'DebugTag':
+				return this.evalDebugTag(node, ctx);
+			case 'IfBlock':
+				return this.evalIfBlock(node, ctx);
+			case 'EachBlock':
+				return this.evalEachBlock(node, ctx);
+			case 'Tag':
+				return this.evalTag(node, ctx);
+			default:
+				return '';
+		}
+	}
+
+	/**
+	 * Fragment — sequence of children
+	 */
+	evalFragment(node, ctx) {
+		let result = '';
+		for (const child of node.children) {
+			result += this.evalNode(child, ctx);
+		}
+		return result;
+	}
+
+	/**
+	 * {expression} — evaluate and escape for safe HTML output
+	 */
+	evalExpression(node, ctx) {
+		const value = this.expr.evaluate(node.expression, ctx);
+
+		if (value === undefined || value === null) return '';
+		if (typeof value === 'boolean') return '';
+
+		// Handle special objects
+		const resolved = this.resolveValue(value);
+		return this.escapeHtml(String(resolved));
+	}
+
+	/**
+	 * {@html expression} — evaluate without escaping
+	 */
+	evalHtmlExpression(node, ctx) {
+		const value = this.expr.evaluate(node.expression, ctx);
+		if (value === undefined || value === null) return '';
+		return String(value);
+	}
+
+	/**
+	 * {@const name = expression} — adds to context, outputs nothing
+	 * Returns empty string but modifies the mutable context wrapper
+	 */
+	evalConstTag(node, ctx) {
+		const value = this.expr.evaluate(node.expression, ctx);
+		// We need to mutate ctx here so subsequent nodes can access the const.
+		// This is intentional — @const is a side-effect.
+		ctx[node.name] = value;
+		return '';
+	}
+
+	/**
+	 * {@debug var1, var2} — logs to console, outputs nothing
+	 */
+	evalDebugTag(node, ctx) {
+		const values = {};
+		for (const varName of node.variables) {
+			values[varName] = this.expr.evaluate(varName, ctx);
+		}
+		console.log('[Debug]', values);
+		return '';
+	}
+
+	/**
+	 * {#if condition}...{:else if}...{:else}...{/if}
+	 */
+	evalIfBlock(node, ctx) {
+		// Check main condition
+		if (this.expr.isTruthy(node.condition, ctx)) {
+			return this.evalNode(node.consequent, ctx);
+		}
+
+		// Check else-if branches
+		for (const branch of node.elseIfBranches) {
+			if (this.expr.isTruthy(branch.condition, ctx)) {
+				return this.evalNode(branch.body, ctx);
+			}
+		}
+
+		// Else branch
+		if (node.alternate) {
+			return this.evalNode(node.alternate, ctx);
+		}
+
+		return '';
+	}
+
+	/**
+	 * {#each expression as item, index (key)}...{:else}...{/each}
+	 *
+	 * The key insight for correct nesting: we spread the parent context
+	 * and add the loop variables on top. This means a 3-level deep loop
+	 * has access to all parent loop variables automatically.
+	 */
+	evalEachBlock(node, ctx) {
+		// Evaluate the iterable expression
+		const iterable = this.expr.evaluate(node.expression, ctx);
+
+		// Handle non-array or empty
+		if (!Array.isArray(iterable) || iterable.length === 0) {
+			if (node.else) {
+				return this.evalNode(node.else, ctx);
+			}
+			return '';
+		}
+
+		// Render each item
+		let result = '';
+		for (let i = 0; i < iterable.length; i++) {
+			// Create new scope: parent context + loop variable + index
+			const loopCtx = { ...ctx, [node.itemVar]: iterable[i] };
+			if (node.indexVar) {
+				loopCtx[node.indexVar] = i;
+			}
+
+			result += this.evalNode(node.body, loopCtx);
+		}
+
+		return result;
+	}
+
+	/**
+	 * HTML Tag — reconstruct the tag with evaluated attributes
+	 */
+	evalTag(node, ctx) {
+		// Check for PascalCase tag (Island component)
+		// PascalCase tags like <Counter />, <ProductCard /> are treated as Islands:
+		// - Tag name converted to kebab-case with wm- prefix
+		// - All props serialized as data-island-props JSON
+		if (/^[A-Z]/.test(node.tagName)) {
+			return this.evalIslandTag(node, ctx);
+		}
+
+		let result = `<${node.tagName}`;
+
+		// Collect all class names (static + conditional)
+		let staticClasses = '';
+		const conditionalClasses = [];
+
+		// Process static attributes
+		for (const attr of node.attributes) {
+			if (attr.type === 'StaticAttribute') {
+				if (attr.name === 'class') {
+					staticClasses = attr.value;
+				} else if (attr.value === true) {
+					// Boolean attribute
+					result += ` ${attr.name}`;
+				} else {
+					result += ` ${attr.name}="${this.escapeAttr(attr.value)}"`;
+				}
+			} else if (attr.type === 'DynamicAttribute') {
+				const value = this.expr.evaluate(attr.expression, ctx);
+				const resolved = this.resolveValueForAttr(value);
+				result += ` ${attr.name}="${this.escapeAttr(String(resolved ?? ''))}"`;
+			} else if (attr.type === 'DynamicQuotedAttribute') {
+				// Attribute with mixed static and dynamic parts: "Hello {name}"
+				let value = '';
+				for (const part of attr.parts) {
+					if (part.type === 'text') {
+						value += part.value;
+					} else {
+						const evaluated = this.expr.evaluate(part.value, ctx);
+						const resolved = this.resolveValueForAttr(evaluated);
+						value += String(resolved ?? '');
+					}
+				}
+				result += ` ${attr.name}="${this.escapeAttr(value)}"`;
+			}
+		}
+
+		// Process class: directives
+		for (const directive of node.classDirectives) {
+			const conditionResult = this.expr.isTruthy(directive.condition, ctx);
+			if (conditionResult) {
+				conditionalClasses.push(directive.name);
+			}
+		}
+
+		// Merge class attribute
+		const allClasses = [staticClasses, ...conditionalClasses].filter(Boolean).join(' ');
+		if (allClasses) {
+			result += ` class="${this.escapeAttr(allClasses)}"`;
+		}
+
+		if (node.selfClosing) {
+			result += ' />';
+		} else {
+			result += '>';
+		}
+
+		return result;
+	}
+
+	/**
+	 * Island Tag — PascalCase components like <Counter />, <ProductCard item={item} />
+	 * Transforms to: <wm-counter data-island-props='{"item":...}'></wm-counter>
+	 *
+	 * This runs inside the evaluator, so it works correctly inside {#each} loops:
+	 * {#each items as item}<Counter data={item} />{/each}
+	 * → <wm-counter data-island-props='{"data":{"name":"A"}}'></wm-counter>
+	 *   <wm-counter data-island-props='{"data":{"name":"B"}}'></wm-counter>
+	 */
+	evalIslandTag(node, ctx) {
+		// Convert PascalCase to kebab-case with wm- prefix
+		const kebabTag = 'wm-' + node.tagName
+			.replace(/([A-Z])/g, '-$1')
+			.toLowerCase()
+			.replace(/^-/, '');
+
+		// Collect all props (evaluate dynamic ones)
+		const props = {};
+
+		for (const attr of node.attributes) {
+			if (attr.type === 'StaticAttribute') {
+				if (attr.value === true) {
+					props[attr.name] = true;
+				} else {
+					props[attr.name] = attr.value;
+				}
+			} else if (attr.type === 'DynamicAttribute') {
+				props[attr.name] = this.expr.evaluate(attr.expression, ctx);
+			} else if (attr.type === 'DynamicQuotedAttribute') {
+				let value = '';
+				for (const part of attr.parts) {
+					if (part.type === 'text') {
+						value += part.value;
+					} else {
+						const evaluated = this.expr.evaluate(part.value, ctx);
+						value += String(evaluated ?? '');
+					}
+				}
+				props[attr.name] = value;
+			}
+		}
+
+		// Build tag with data-island-props
+		const hasProps = Object.keys(props).length > 0;
+		const propsAttr = hasProps
+			? ` data-island-props='${JSON.stringify(props).replace(/'/g, '&apos;')}'`
+			: '';
+
+		return `<${kebabTag}${propsAttr}></${kebabTag}>`;
+	}
+
+	// ========================================
+	// Value resolution helpers
+	// ========================================
+
+	/**
+	 * Resolve special object types to display values
+	 * Handles CMS-specific types like links and images
+	 */
+	resolveValue(value) {
+		if (typeof value !== 'object' || value === null) return value;
+
+		// Link objects (from LinkField) — extract path
+		if (value.type === 'page' && value.pageUuid) {
+			return value.path || `/preview/${value.pageUuid}`;
+		}
+
+		// Image objects — extract URL
+		if (value.src || value.filename) {
+			return value.src || value.filename || '';
+		}
+
+		// Arrays — don't stringify
+		if (Array.isArray(value)) return '';
+
+		// Other objects — try to stringify
+		try {
+			return JSON.stringify(value);
+		} catch {
+			return '[Object]';
+		}
+	}
+
+	/**
+	 * Resolve values for attribute context (slightly different from text)
+	 */
+	resolveValueForAttr(value) {
+		if (value === undefined || value === null) return '';
+		if (typeof value !== 'object') return value;
+
+		// Link objects
+		if (value.type === 'page' && value.pageUuid) {
+			return value.path || `/preview/${value.pageUuid}`;
+		}
+
+		// Image objects
+		if (value.src || value.filename) {
+			return value.src || value.filename || '';
+		}
+
+		// Arrays/objects — stringify for data attributes
+		try {
+			return JSON.stringify(value);
+		} catch {
+			return '';
+		}
+	}
+
+	// ========================================
+	// HTML escaping
+	// ========================================
+
+	escapeHtml(str) {
+		return str
+			.replace(/&/g, '&amp;')
+			.replace(/</g, '&lt;')
+			.replace(/>/g, '&gt;')
+			.replace(/"/g, '&quot;');
+	}
+
+	escapeAttr(str) {
+		return str
+			.replace(/&/g, '&amp;')
+			.replace(/"/g, '&quot;');
+	}
+}
+
+export { TemplateEvaluator };
+export default TemplateEvaluator;