ripple 0.2.91 → 0.2.92

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.91",
+  "version": "0.2.92",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",

package/src/compiler/index.js

@@ -1,6 +1,4 @@
-/** @import { RawSourceMap } from 'source-map' */
 /** @import { Program } from 'estree' */
-/** @import { ParseError } from './phases/1-parse/index.js' */
 
 import { parse as parse_module } from './phases/1-parse/index.js';
 import { analyze } from './phases/2-analyze/index.js';
@@ -9,18 +7,20 @@ import { transform_server } from './phases/3-transform/server/index.js';
 import { convert_source_map_to_mappings } from './phases/3-transform/segments.js';
 
 /**
- * @param {string} source 
- * @returns {{ ast: Program, errors: ParseError[] }}
+ * Parse Ripple source code to ESTree AST
+ * @param {string} source
+ * @returns {Program}
  */
 export function parse(source) {
   return parse_module(source);
 }
 
 /**
- * @param {string} source 
- * @param {string} filename 
- * @param {{ mode?: 'client' | 'server' }} options 
- * @returns {{ js: { code: string, map: RawSourceMap }, css: { code: string, map: RawSourceMap } | null }}
+ * Compile Ripple source code to JS/CSS output
+ * @param {string} source
+ * @param {string} filename
+ * @param {{ mode?: 'client' | 'server' }} [options]
+ * @returns {object}
  */
 export function compile(source, filename, options = {}) {
   const ast = parse_module(source);
@@ -32,6 +32,12 @@ export function compile(source, filename, options = {}) {
   return result;
 }
 
+/**
+ * Compile Ripple source to Volar mappings for editor integration
+ * @param {string} source
+ * @param {string} filename
+ * @returns {object} Volar mappings object
+ */
 export function compile_to_volar_mappings(source, filename) {
   // Parse and transform to get the esrap sourcemap
   const ast = parse_module(source);

package/src/compiler/phases/1-parse/index.js

@@ -1,3 +1,9 @@
+/** @import { Program } from 'estree' */
+/** @import {
+ *   CommentWithLocation,
+ *   RipplePluginConfig
+ * } from '#compiler' */
+
 import * as acorn from 'acorn';
 import { tsPlugin } from 'acorn-typescript';
 import { parse_style } from './style.js';
@@ -6,6 +12,11 @@ import { regex_newline_characters } from '../../../utils/patterns.js';
 
 const parser = acorn.Parser.extend(tsPlugin({ allowSatisfies: true }), RipplePlugin());
 
+/**
+ * Convert JSX node types to regular JavaScript node types
+ * @param {any} node - The JSX node to convert
+ * @returns {any} The converted node
+ */
 function convert_from_jsx(node) {
 	if (node.type === 'JSXIdentifier') {
 		node.type = 'Identifier';
@@ -17,16 +28,26 @@ function convert_from_jsx(node) {
 	return node;
 }
 
+/**
+ * Acorn parser plugin for Ripple syntax extensions
+ * @param {RipplePluginConfig} [config] - Plugin configuration
+ * @returns {function(any): any} Parser extension function
+ */
 function RipplePlugin(config) {
-	return (Parser) => {
+	return (/** @type {any} */ Parser) => {
 		const original = acorn.Parser.prototype;
 		const tt = Parser.tokTypes || acorn.tokTypes;
 		const tc = Parser.tokContexts || acorn.tokContexts;
 
 		class RippleParser extends Parser {
+			/** @type {any[]} */
 			#path = [];
 
-			// Helper method to get the element name from a JSX identifier or member expression
+			/**
+			 * Helper method to get the element name from a JSX identifier or member expression
+			 * @param {any} node - The node to get the name from
+			 * @returns {string | null} Element name or null
+			 */
 			getElementName(node) {
 				if (!node) return null;
 				if (node.type === 'Identifier' || node.type === 'JSXIdentifier') {
@@ -38,6 +59,11 @@ function RipplePlugin(config) {
 				return null;
 			}
 
+			/**
+			 * Get token from character code - handles Ripple-specific tokens
+			 * @param {number} code - Character code
+			 * @returns {any} Token or calls super method
+			 */
 			getTokenFromCode(code) {
 				if (code === 60) {
 					// < character
@@ -135,7 +161,10 @@ function RipplePlugin(config) {
 				return super.getTokenFromCode(code);
 			}
 
-			// Read an @ prefixed identifier
+			/**
+			 * Read an @ prefixed identifier
+			 * @returns {any} Token with @ identifier
+			 */
 			readAtIdentifier() {
 				const start = this.pos;
 				this.pos++; // skip '@'
@@ -166,7 +195,11 @@ function RipplePlugin(config) {
 				return this.finishToken(tt.name, '@' + word);
 			}
 
-			// Override parseIdent to mark @ identifiers as tracked
+			/**
+			 * Override parseIdent to mark @ identifiers as tracked
+			 * @param {any} [liberal] - Whether to allow liberal parsing
+			 * @returns {any} Parsed identifier node
+			 */
 			parseIdent(liberal) {
 				const node = super.parseIdent(liberal);
 				if (node.name && node.name.startsWith('@')) {
@@ -181,6 +214,13 @@ function RipplePlugin(config) {
 				return node;
 			}
 
+			/**
+			 * Parse expression atom - handles TrackedArray and TrackedObject literals
+			 * @param {any} [refDestructuringErrors]
+			 * @param {any} [forNew]
+			 * @param {any} [forInit]
+			 * @returns {any} Parsed expression atom
+			 */
 			parseExprAtom(refDestructuringErrors, forNew, forInit) {
 				// Check if this is a tuple literal starting with #[
 				if (this.type === tt.bracketL && this.value === '#[') {
@@ -818,6 +858,7 @@ function RipplePlugin(config) {
 				const element = this.startNode();
 				element.start = position.index;
 				element.loc.start = position;
+        element.metadata = {};
 				element.type = 'Element';
 				this.#path.push(element);
 				element.children = [];
@@ -1150,7 +1191,8 @@ function RipplePlugin(config) {
  * in JS code and so that `prettier-plugin-ripple` doesn't remove all comments when formatting.
  * @param {string} source
  * @param {CommentWithLocation[]} comments
- * @param {number} index
+ * @param {number} [index=0] - Starting index
+ * @returns {{ onComment: Function, add_comments: Function }} Comment handler functions
  */
 function get_comment_handlers(source, comments, index = 0) {
 	return {
@@ -1245,7 +1287,13 @@ function get_comment_handlers(source, comments, index = 0) {
 	};
 }
 
+/**
+ * Parse Ripple source code into an AST
+ * @param {string} source
+ * @returns {Program}
+ */
 export function parse(source) {
+	/** @type {CommentWithLocation[]} */
 	const comments = [];
 	const { onComment, add_comments } = get_comment_handlers(source, comments);
 	let ast;
@@ -1255,7 +1303,7 @@ export function parse(source) {
 			sourceType: 'module',
 			ecmaVersion: 13,
 			locations: true,
-			onComment,
+			onComment: /** @type {any} */ (onComment),
 		});
 	} catch (e) {
 		throw e;
@@ -1263,5 +1311,5 @@ export function parse(source) {
 
 	add_comments(ast);
 
-	return ast;
+	return /** @type {Program} */ (ast);
 }

package/src/compiler/phases/3-transform/client/index.js

@@ -544,6 +544,7 @@ const visitors = {
 
 		if (is_dom_element) {
 			let class_attribute = null;
+			let style_attribute = null;
 			const local_updates = [];
 			const is_void = is_void_element(node.id.name);
 
@@ -559,7 +560,7 @@ const visitors = {
 							continue;
 						}
 
-						if (attr.value.type === 'Literal' && name !== 'class') {
+						if (attr.value.type === 'Literal' && name !== 'class' && name !== 'style') {
 							handle_static_attr(name, attr.value.value);
 							continue;
 						}
@@ -570,6 +571,12 @@ const visitors = {
 							continue;
 						}
 
+						if (name === 'style') {
+							style_attribute = attr;
+
+							continue;
+						}
+
 						if (name === 'value') {
 							const id = state.flush_node();
 							const metadata = { tracking: false, await: false };
@@ -742,6 +749,25 @@ const visitors = {
 				handle_static_attr(is_spreading ? '#class' : 'class', value);
 			}
 
+			if (style_attribute !== null) {
+				if (style_attribute.value.type === 'Literal') {
+					handle_static_attr(style_attribute.name.name, style_attribute.value.value);
+				} else {
+					const id = state.flush_node();
+					const metadata = { tracking: false, await: false };
+					const expression = visit(style_attribute.value, { ...state, metadata });
+					const name = style_attribute.name.name;
+
+					const statement = b.stmt(b.call('_$_.set_attribute', id, b.literal(name), expression));
+
+					if (metadata.tracking) {
+						local_updates.push(statement);
+					} else {
+						state.init.push(statement);
+					}
+				}
+			}
+
 			state.template.push('>');
 
 			if (spread_attributes !== null && spread_attributes.length > 0) {
@@ -799,13 +825,17 @@ const visitors = {
 							}
 
 							props.push(
-								b.prop('get', attr.name, b.function(null, [], b.block([b.return(property)]))),
+								b.prop(
+									'get',
+									b.key(attr.name.name),
+									b.function(null, [], b.block([b.return(property)])),
+								),
 							);
 						} else {
-							props.push(b.prop('init', attr.name, property));
+							props.push(b.prop('init', b.key(attr.name.name), property));
 						}
 					} else {
-						props.push(b.prop('init', attr.name, visit(attr.value, state)));
+						props.push(b.prop('init', b.key(attr.name.name), visit(attr.value, state)));
 					}
 				} else if (attr.type === 'SpreadAttribute') {
 					props.push(
@@ -1317,54 +1347,46 @@ function transform_ts_child(node, context) {
 		const children = [];
 		let has_children_props = false;
 
-		// Filter out RefAttributes and handle them separately
 		const ref_attributes = [];
-		const attributes = node.attributes
-			.filter((attr) => {
-				if (attr.type === 'RefAttribute') {
-					ref_attributes.push(attr);
-					return false;
+		const attributes = node.attributes.map((attr) => {
+			if (attr.type === 'Attribute') {
+				const metadata = { await: false };
+				const name = visit(attr.name, { ...state, metadata });
+				const value =
+					attr.value === null ? b.literal(true) : visit(attr.value, { ...state, metadata });
+
+				// Handle both regular identifiers and tracked identifiers
+				let prop_name;
+				if (name.type === 'Identifier') {
+					prop_name = name.name;
+				} else if (name.type === 'MemberExpression' && name.object.type === 'Identifier') {
+					// For tracked attributes like {@count}, use the original name
+					prop_name = name.object.name;
+				} else {
+					prop_name = attr.name.name || 'unknown';
 				}
-				return true;
-			})
-			.map((attr) => {
-				if (attr.type === 'Attribute') {
-					const metadata = { await: false };
-					const name = visit(attr.name, { ...state, metadata });
-					const value =
-						attr.value === null ? b.literal(true) : visit(attr.value, { ...state, metadata });
-
-					// Handle both regular identifiers and tracked identifiers
-					let prop_name;
-					if (name.type === 'Identifier') {
-						prop_name = name.name;
-					} else if (name.type === 'MemberExpression' && name.object.type === 'Identifier') {
-						// For tracked attributes like {@count}, use the original name
-						prop_name = name.object.name;
-					} else {
-						prop_name = attr.name.name || 'unknown';
-					}
 
-					const jsx_name = b.jsx_id(prop_name);
-					if (prop_name === 'children') {
-						has_children_props = true;
-					}
-					jsx_name.loc = attr.name.loc || name.loc;
-
-					return b.jsx_attribute(jsx_name, b.jsx_expression_container(value));
-				} else if (attr.type === 'SpreadAttribute') {
-					const metadata = { await: false };
-					const argument = visit(attr.argument, { ...state, metadata });
-					return b.jsx_spread_attribute(argument);
+				const jsx_name = b.jsx_id(prop_name);
+				if (prop_name === 'children') {
+					has_children_props = true;
 				}
-			});
-
-		// Add RefAttribute references separately for sourcemap purposes
-		for (const ref_attr of ref_attributes) {
-			const metadata = { await: false };
-			const argument = visit(ref_attr.argument, { ...state, metadata });
-			state.init.push(b.stmt(argument));
-		}
+				jsx_name.loc = attr.name.loc || name.loc;
+
+				return b.jsx_attribute(jsx_name, b.jsx_expression_container(value));
+			} else if (attr.type === 'SpreadAttribute') {
+				const metadata = { await: false };
+				const argument = visit(attr.argument, { ...state, metadata });
+				return b.jsx_spread_attribute(argument);
+			} else if (attr.type === 'RefAttribute') {
+				if (!context.state.imports.has(`import { createRefKey } from 'ripple'`)) {
+					context.state.imports.add(`import { createRefKey } from 'ripple'`);
+				}
+				const metadata = { await: false };
+				const argument = visit(attr.argument, { ...state, metadata });
+				const wrapper = b.object([b.prop('init', b.call('createRefKey'), argument, true)]);
+				return b.jsx_spread_attribute(wrapper);
+			}
+		});
 
 		if (!node.selfClosing && !has_children_props && node.children.length > 0) {
 			const is_dom_element = is_element_dom_element(node);
@@ -1607,7 +1629,17 @@ function transform_children(children, context) {
 				context.state.template.push('<!>');
 
 				const id = flush_node();
-				state.update.push(b.stmt(b.call('_$_.html', id, b.thunk(expression))));
+				state.update.push(
+					b.stmt(
+						b.call(
+							'_$_.html',
+							id,
+							b.thunk(expression),
+							state.namespace === 'svg' && b.true,
+							state.namespace === 'mathml' && b.true,
+						),
+					),
+				);
 			} else if (node.type === 'Text') {
 				const metadata = { tracking: false, await: false };
 				const expression = visit(node.expression, { ...state, metadata });

package/src/compiler/phases/3-transform/segments.js

@@ -76,6 +76,19 @@ function isValidMapping(sourceContent, generatedContent) {
 	if (cleanGenerated.includes(cleanSource)) return true;
 	if (cleanSource.includes(cleanGenerated) && cleanGenerated.length > 2) return true;
 	
+	// Special handling for ref callback parameters and types in createRefKey context
+	if (sourceContent.match(/\w+:\s*\w+/) && generatedContent.match(/\w+:\s*\w+/)) {
+		// This looks like a parameter with type annotation, allow mapping
+		return true;
+	}
+	
+	// Allow mapping of identifiers that appear in both source and generated
+	if (sourceContent.match(/^[a-zA-Z_$][a-zA-Z0-9_$]*$/) && 
+		generatedContent.match(/^[a-zA-Z_$][a-zA-Z0-9_$]*$/) &&
+		sourceContent === generatedContent) {
+		return true;
+	}
+	
 	return false;
 }
 
@@ -175,6 +188,20 @@ export function convert_source_map_to_mappings(source_map, source, generated_cod
 				}
 			}
 			
+			// Special handling for type annotations in ref callbacks
+			if (!best_match) {
+				// Look for type annotations like "HTMLButtonElement" 
+				const sourceTypeMatch = source.substring(source_offset).match(/^[A-Z][a-zA-Z0-9]*(?:Element|Type|Interface)?/);
+				const generatedTypeMatch = generated_code.substring(current_generated_offset).match(/^[A-Z][a-zA-Z0-9]*(?:Element|Type|Interface)?/);
+				
+				if (sourceTypeMatch && generatedTypeMatch && sourceTypeMatch[0] === generatedTypeMatch[0]) {
+					best_match = {
+						source: sourceTypeMatch[0],
+						generated: generatedTypeMatch[0]
+					};
+				}
+			}
+			
 		// Handle special cases for Ripple keywords that might not have generated equivalents
 		if (!best_match || best_match.source.length === 0) {
 			continue;
@@ -198,10 +225,37 @@ export function convert_source_map_to_mappings(source_map, source, generated_cod
 			continue;
 		}
 		
+		// Handle special ref syntax mapping for createRefKey() pattern
+		const sourceAtRefOffset = source.substring(Math.max(0, source_offset - 20), source_offset + 20);
+		const generatedAtRefOffset = generated_code.substring(Math.max(0, current_generated_offset - 20), current_generated_offset + 20);
+		
+		// Check if we're dealing with ref callback syntax in source and createRefKey in generated
+		if (sourceAtRefOffset.includes('{ref ') && generatedAtRefOffset.includes('createRefKey')) {
+			// Look for the ref callback pattern in source: {ref (param: Type) => { ... }}
+			const refMatch = source.substring(source_offset - 50, source_offset + 50).match(/\{ref\s*\(([^)]+)\)\s*=>/);
+			if (refMatch) {
+				const paramMatch = refMatch[1].match(/(\w+):\s*(\w+)/);
+				if (paramMatch) {
+					const paramName = paramMatch[1];
+					const typeName = paramMatch[2];
+					
+					// Map the parameter name to the generated callback parameter
+					if (best_match.source === paramName || best_match.source.includes(paramName)) {
+						// This is a ref callback parameter, allow the mapping
+					}
+					// Map the type annotation
+					else if (best_match.source === typeName || best_match.source.includes(typeName)) {
+						// This is a type annotation in ref callback, allow the mapping
+					}
+				}
+			}
+		}
+		
 		// Skip mappings for complex RefAttribute syntax to avoid overlapping sourcemaps,
-		// but allow simple 'ref' keyword mappings for IntelliSense
-		if (best_match.source.includes('{ref ') && best_match.source.length > 10) {
-			// Skip complex ref expressions like '{ref (node) => { ... }}'
+		// but allow mappings that are part of the createRefKey pattern
+		if (best_match.source.includes('{ref ') && best_match.source.length > 10 && 
+		    !generatedAtRefOffset.includes('createRefKey')) {
+			// Skip complex ref expressions like '{ref (node) => { ... }}' only if not using createRefKey
 			continue;
 		}