lui-templates 0.0.6 → 0.1.0

package/.github/LIQUID_SPEC.md

@@ -0,0 +1,101 @@
+# Liquid Template Syntax Specification
+
+This document describes the Liquid template syntax used in this project. AI agents and contributors should follow these specifications when working with Liquid templates.
+
+## Syntax Overview
+
+Liquid uses two types of delimiters:
+
+### 1. Output (Expressions): `{{ }}`
+Used for outputting variables and expressions:
+```liquid
+{{ variable }}
+{{ user.name }}
+{{ "Hello " + name }}
+```
+
+### 2. Tags (Commands): `{% %}`
+Used for logic, control flow, and special commands:
+```liquid
+{% if condition %}
+  Content
+{% endif %}
+
+{% unless condition %}
+  Content
+{% endunless %}
+
+{% for item in items %}
+  {{ item }}
+{% endfor %}
+```
+
+## Supported Commands
+
+### Control Flow Commands
+- `{% if condition %}...{% endif %}` - Conditional rendering
+- `{% unless condition %}...{% endunless %}` - Inverse conditional rendering
+- `{% for item in collection %}...{% endfor %}` - Loop over collections
+
+### Special Commands
+- `{% comment %}...{% endcomment %}` - Comments (not rendered)
+- `{% raw %}...{% endraw %}` - Raw content (no processing)
+- `{% render 'component', prop: value %}` - Render a component
+
+## Component Rendering
+
+The `{% render %}` command is used to instantiate components:
+
+```liquid
+{% render 'button', label: 'Submit', type: 'primary' %}
+{% render 'user-card', name: user.name, age: 25 %}
+{% render 'components/ui/icon', name: 'check', size: 24 %}
+```
+
+### Syntax
+```liquid
+{% render 'path/to/component', prop1: value1, prop2: value2 %}
+```
+
+### Rules
+1. **Path**: The component path (string). Only the last segment is used (e.g., `'ui/button'` → `Button`)
+2. **Component Name**: Converted to PascalCase (e.g., `'user-card'` → `UserCard`)
+3. **Props**: Key-value pairs separated by commas
+4. **Values**: Can be:
+   - String literals: `'text'` or `"text"`
+   - Numbers: `42`, `3.14`
+   - Booleans: `true`, `false`
+   - Variables: `userName`, `count`
+   - Expressions: `user.name`, `items.length`
+
+### Examples
+
+Simple with static values:
+```liquid
+{% render 'button', label: 'Click me', disabled: false %}
+```
+
+With variables:
+```liquid
+{% render 'input', name: fieldName, value: fieldValue %}
+```
+
+With expressions:
+```liquid
+{% render 'user-card', name: user.name, count: items.length %}
+```
+
+Within conditionals:
+```liquid
+{% if showProfile %}
+  {% render 'profile', user: currentUser %}
+{% endif %}
+```
+
+## Important Notes for AI Agents
+
+1. **Always use `{% %}` for the render command**, not `{{ }}`
+2. The render command is a **tag/command**, not an expression
+3. Component names are automatically converted from kebab-case to PascalCase
+4. Only simple variable identifiers are registered as component inputs
+5. Complex expressions (e.g., `user.name`) are passed through but not registered as inputs

package/README.md

@@ -52,8 +52,8 @@ init(() => {
 ```js
 import lui_templates from 'lui-templates';
 
-const code = await lui_templates('src/templates/Greeting.liquid');
-await fs.writeFile('src/generated/Greeting.js', code, 'utf8');
+const code = await lui_templates('src/templates/greeting.liquid');
+await fs.writeFile('src/components/greeting.js', code, 'utf8');
 
 await bundleApp('src/main.js'); // or whatever
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "lui-templates",
-	"version": "0.0.6",
+	"version": "0.1.0",
 	"description": "transform html templates into lui components",
 	"repository": {
 		"type": "git",

package/src/parsers/liquid.js

@@ -1,4 +1,5 @@
 import {
+	NODE_TYPE_COMPONENT,
 	NODE_TYPE_ELEMENT,
 	NODE_TYPE_IF,
 	VALUE_TYPE_FIELD,
@@ -25,6 +26,7 @@ const COMMAND_FOR = 3;
 const COMMAND_ENDIF = 4;
 const COMMAND_ENDUNLESS = 5;
 const COMMAND_ENDFOR = 6;
+const COMMAND_RENDER = 7;
 
 const command_map = new Map([
 	['if', COMMAND_IF],
@@ -33,6 +35,7 @@ const command_map = new Map([
 	['endif', COMMAND_ENDIF],
 	['endunless', COMMAND_ENDUNLESS],
 	['endfor', COMMAND_ENDFOR],
+	['render', COMMAND_RENDER],
 ]);
 const command_map_reverse = new Map(
 	Array.from(command_map.entries())
@@ -172,6 +175,214 @@ class Tokenizer {
 		};
 	}
 
+	/**
+		Parses a liquid expression (string, number, or variable).
+		Used in {{ }}, command arguments, and other places.
+		@returns {Object} Value object with type and data
+	*/
+	parse_liquid_expression() {
+		const position = this.position_get();
+		
+		// Skip whitespace
+		while (this.index < this.src.length && /\s/.test(this.char_current())) {
+			this.char_step();
+		}
+		
+		const char = this.char_current();
+		
+		// String literal (single or double quoted)
+		if (char === '"' || char === "'") {
+			const quote = char;
+			this.char_step(); // Skip opening quote
+			let value = '';
+			while (this.index < this.src.length) {
+				const c = this.char_current();
+				if (c === quote) {
+					this.char_step(); // Skip closing quote
+					return {
+						type: VALUE_TYPE_STATIC,
+						data: value,
+					};
+				}
+				value += c;
+				this.char_step();
+			}
+			error('Unclosed string literal', position);
+		}
+		
+		// Number literal (base 10 only)
+		if (/[0-9]/.test(char)) {
+			let value = '';
+			while (this.index < this.src.length && /[0-9.]/.test(this.char_current())) {
+				value += this.char_current();
+				this.char_step();
+			}
+			return {
+				type: VALUE_TYPE_STATIC,
+				data: parseFloat(value),
+			};
+		}
+		
+		// Variable name or property access (e.g., variable, variable.prop, variable.prop.subprop)
+		// Also handles boolean literals (true, false) and nil
+		// Only allows valid identifiers separated by dots, no other JavaScript expressions
+		if (/[a-zA-Z_$]/.test(char)) {
+			let value = '';
+			let base_variable = '';
+			let first_identifier = true;
+			
+			while (this.index < this.src.length) {
+				const c = this.char_current();
+				
+				// Start of an identifier
+				if (/[a-zA-Z_$]/.test(c)) {
+					let identifier = '';
+					while (this.index < this.src.length && /[a-zA-Z0-9_$]/.test(this.char_current())) {
+						identifier += this.char_current();
+						this.char_step();
+					}
+					value += identifier;
+					
+					// Track the first identifier as the base variable
+					if (first_identifier) {
+						base_variable = identifier;
+						first_identifier = false;
+					}
+				}
+				// Property access dot
+				else if (c === '.') {
+					// Peek ahead to ensure there's an identifier after the dot
+					if (this.index + 1 < this.src.length && /[a-zA-Z_$]/.test(this.src.charAt(this.index + 1))) {
+						value += c;
+						this.char_step();
+					} else {
+						error('Expected property name after dot', position);
+					}
+				}
+				// Stop at delimiters
+				else if (/[\s,}%)]/.test(c)) {
+					break;
+				}
+				// Invalid character
+				else {
+					error(`Invalid character '${c}' in expression`, position);
+				}
+			}
+			
+			if (!value) {
+				error('Expected expression', position);
+			}
+			
+			// Check for boolean literals and nil
+			if (value === 'true') {
+				return {
+					type: VALUE_TYPE_STATIC,
+					data: true,
+				};
+			}
+			if (value === 'false') {
+				return {
+					type: VALUE_TYPE_STATIC,
+					data: false,
+				};
+			}
+			if (value === 'nil') {
+				return {
+					type: VALUE_TYPE_STATIC,
+					data: null,
+				};
+			}
+			
+			// Register the base variable (not for keywords)
+			if (base_variable) {
+				this.variables.set(base_variable, null);
+			}
+			
+			return {
+				type: VALUE_TYPE_FIELD,
+				data: value,
+			};
+		}
+		
+		error('Expected string, number, or variable', position);
+	}
+
+	/**
+		Parses command arguments in the format: arg1, key1: value1, key2: value2
+		Used for render and potentially other commands.
+		@param {string} args_str - The arguments string
+		@returns {Object} Parsed arguments with path and props
+	*/
+	parse_command_arguments(args_str) {
+		const position = this.position_get();
+		const saved_index = this.index;
+		const saved_src = this.src;
+		
+		// Temporarily set src to args_str for parsing
+		this.src = args_str;
+		this.index = 0;
+		
+		const result = {
+			path: null,
+			props: {},
+		};
+		
+		try {
+			// Parse first argument (path)
+			result.path = this.parse_liquid_expression();
+			
+			// Skip whitespace and comma
+			while (this.index < this.src.length && /[\s,]/.test(this.char_current())) {
+				this.char_step();
+			}
+			
+			// Parse key-value pairs
+			while (this.index < this.src.length) {
+				// Skip whitespace
+				while (this.index < this.src.length && /\s/.test(this.char_current())) {
+					this.char_step();
+				}
+				
+				if (this.index >= this.src.length) break;
+				
+				// Parse key
+				const key_start = this.index;
+				while (this.index < this.src.length && /[a-zA-Z_$0-9]/.test(this.char_current())) {
+					this.char_step();
+				}
+				const key = this.src.slice(key_start, this.index);
+				
+				if (!key) break;
+				
+				// Skip whitespace
+				while (this.index < this.src.length && /\s/.test(this.char_current())) {
+					this.char_step();
+				}
+				
+				// Expect colon
+				if (this.char_current() !== ':') {
+					error(`Expected ':' after property name '${key}'`, position);
+				}
+				this.char_step(); // Skip colon
+				
+				// Parse value
+				const value = this.parse_liquid_expression();
+				result.props[key] = value;
+				
+				// Skip whitespace and comma
+				while (this.index < this.src.length && /[\s,]/.test(this.char_current())) {
+					this.char_step();
+				}
+			}
+		} finally {
+			// Restore original src and index
+			this.src = saved_src;
+			this.index = saved_index;
+		}
+		
+		return result;
+	}
+
 	/**
 		Expects to be in either top level or inside a block.
 		@returns {Array} Array of tokens
@@ -337,6 +548,21 @@ class Tokenizer {
 				value,
 			};
 		}
+		case 'render': {
+			// Parse command arguments and store them in the token
+			const args = this.parse_command_arguments(value);
+			
+			// Variable tracking is now handled inside parse_liquid_expression()
+			
+			return {
+				type: TOKEN_LIQUID,
+				...position,
+				trim_before,
+				trim_after,
+				command: COMMAND_RENDER,
+				args, // Store parsed arguments instead of raw string
+			};
+		}
 		}
 
 		const command = command_map.get(command_str);
@@ -781,6 +1007,26 @@ function build_nodes(tokens, index, index_end, condition_prefix = '') {
 				index = conditional.index;
 				continue;
 			}
+			case COMMAND_RENDER: {
+				const component_node = build_render_node(token);
+				
+				if (condition_prefix) {
+					// Wrap component in conditional
+					nodes.push({
+						type: NODE_TYPE_IF,
+						condition: {
+							type: VALUE_TYPE_FIELD,
+							data: condition_prefix,
+						},
+						child: component_node,
+					});
+				}
+				else {
+					nodes.push(component_node);
+				}
+				index++;
+				continue;
+			}
 			case COMMAND_ENDIF:
 			case COMMAND_ENDUNLESS:
 			case COMMAND_ENDFOR:
@@ -864,8 +1110,8 @@ function build_element_node(tokens, index) {
 				case TOKEN_HTML_END:
 					if (token.tag_name === token_start.tag_name) break loop;
 				case TOKEN_LIQUID:
-					// apart from loops, everything is allowed in text-only
-					if (token.command !== COMMAND_FOR) break;
+					// apart from loops and render commands, everything is allowed in text-only
+					if (token.command !== COMMAND_FOR && token.command !== COMMAND_RENDER) break;
 				case TOKEN_HTML_START:
 					text_only = false;
 					break text_extract;
@@ -939,7 +1185,7 @@ function build_children(tokens, index, tag_parent) {
 				text_only = false;
 				break;
 			case TOKEN_LIQUID:
-				if (token.command === COMMAND_IF || token.command === COMMAND_UNLESS) {
+				if (token.command === COMMAND_IF || token.command === COMMAND_UNLESS || token.command === COMMAND_RENDER) {
 					text_only = false;
 				}
 				break;
@@ -1144,6 +1390,51 @@ function build_value_with_conditionals(tokens, condition_prefix = '') {
 	};
 }
 
+/**
+	Builds a component node from a render command token.
+	@param {Object} token - The render command token with pre-parsed args
+	@returns {Object} Component node
+*/
+function build_render_node(token) {
+	const { args } = token;
+	
+	// Extract path value
+	let path = '';
+	if (args.path.type === VALUE_TYPE_STATIC) {
+		path = args.path.data;
+	} else if (args.path.type === VALUE_TYPE_FIELD) {
+		// If path is a variable, we can't determine the component name at parse time
+		// For now, just use the variable name as component name
+		path = args.path.data;
+	} else {
+		error('Invalid path type in render command', token);
+	}
+	
+	// Extract component name from path (only use last part after splitting by '/')
+	const component_name = path.split('/').pop();
+	if (!component_name) error('Invalid component path in render command', token);
+	
+	// Format component name to PascalCase (kebab-case to PascalCase)
+	// e.g., 'user-card' -> 'UserCard', 'button' -> 'Button'
+	const component = (
+		component_name
+		.charAt(0).toUpperCase() +
+		component_name.slice(1)
+		.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+		.replace(/_([a-z])/g, (_, char) => char.toUpperCase())
+	);
+	
+	// Props are already parsed, just use them directly
+	const props = args.props;
+	
+	return {
+		type: NODE_TYPE_COMPONENT,
+		component,
+		props,
+		children: [],
+	};
+}
+
 /**
 	Builds a value object out of text and expression tokens.
 	Trims whitespace from the start and end.

package/test/templates/render-comprehensive.liquid

@@ -0,0 +1,21 @@
+<div>
+	<!-- Simple render with static values -->
+	{% render 'button', label: 'Submit', type: 'primary' %}
+	
+	<!-- Render with variables -->
+	{% render 'input', name: fieldName, value: fieldValue %}
+	
+	<!-- Render with complex expressions -->
+	{% render 'user-card', name: user.name, age: user.age %}
+	
+	<!-- Render with nested paths (only last part is used) -->
+	{% render 'components/ui/icon', name: 'check', size: 24 %}
+	
+	<!-- Render with boolean and number literals -->
+	{% render 'checkbox', checked: true, count: 5 %}
+	
+	<!-- Render within conditionals -->
+	{% if showProfile %}
+		{% render 'profile', user: currentUser %}
+	{% endif %}
+</div>

package/test/templates/render-conditional.liquid

@@ -0,0 +1,6 @@
+<div>
+	{% if showButton %}
+		{% render 'button', label: buttonLabel %}
+	{% endif %}
+	{% render 'icon', name: 'check' %}
+</div>

package/test/templates/render-expressions.liquid

@@ -0,0 +1,3 @@
+<div>
+	{% render 'button', label: user.name, count: items.length %}
+</div>

package/test/templates/render-test.liquid

@@ -0,0 +1,7 @@
+<div>
+	{% render 'button', label: 'Click me', color: 'blue' %}
+	{% render 'components/nested/icon', name: iconName, size: 24 %}
+	<p>Some text</p>
+	{% render 'link', href: url, text: linkText %}
+	{% render 'card', title: 'Test', enabled: true, count: 5 %}
+</div>