ripple 0.2.90 → 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.90",
+  "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 === '#[') {
@@ -455,24 +495,30 @@ function RipplePlugin(config) {
 			jsx_parseExpressionContainer() {
 				let node = this.startNode();
 				this.next();
-        let tracked = false;
+				let tracked = false;
 
-        if (this.value === 'html') {
-          node.html = true;
-          this.next();
-          if (this.type.label === '@') {
-            this.next(); // consume @
-            tracked = true;
-          }
-        }
+				if (this.value === 'html') {
+					node.html = true;
+					this.next();
+					if (this.type === tt.braceR) {
+						this.raise(
+							this.start,
+							'"html" is a Ripple keyword and must be used in the form {html some_content}',
+						);
+					}
+					if (this.type.label === '@') {
+						this.next(); // consume @
+						tracked = true;
+					}
+				}
 
 				node.expression =
 					this.type === tt.braceR ? this.jsx_parseEmptyExpression() : this.parseExpression();
 				this.expect(tt.braceR);
 
-        if (tracked && node.expression.type === 'Identifier') {
-          node.expression.tracked = true;
-        }
+				if (tracked && node.expression.type === 'Identifier') {
+					node.expression.tracked = true;
+				}
 
 				return this.finishNode(node, 'JSXExpressionContainer');
 			}
@@ -812,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 = [];
@@ -970,7 +1017,7 @@ function RipplePlugin(config) {
 				if (this.type.label === '{') {
 					const node = this.jsx_parseExpressionContainer();
 					node.type = node.html ? 'Html' : 'Text';
-          delete node.html;
+					delete node.html;
 					body.push(node);
 				} else if (this.type.label === '}') {
 					return;
@@ -1144,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 {
@@ -1239,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;
@@ -1249,7 +1303,7 @@ export function parse(source) {
 			sourceType: 'module',
 			ecmaVersion: 13,
 			locations: true,
-			onComment,
+			onComment: /** @type {any} */ (onComment),
 		});
 	} catch (e) {
 		throw e;
@@ -1257,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

@@ -46,8 +46,7 @@ function add_ripple_internal_import(context) {
 
 function visit_function(node, context) {
 	if (context.state.to_ts) {
-		context.next(context.state);
-		return;
+		return context.next(context.state);
 	}
 	const metadata = node.metadata;
 	const state = context.state;
@@ -545,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);
 
@@ -560,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;
 						}
@@ -571,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 };
@@ -743,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) {
@@ -800,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(
@@ -896,7 +925,11 @@ const visitors = {
 				}),
 			];
 
-			return b.function(node.id, node.params, b.block(body_statements));
+			return b.function(
+				node.id,
+				node.params.map((param) => context.visit(param, { ...context.state, metadata })),
+				b.block(body_statements),
+			);
 		}
 
 		let props = b.id('__props');
@@ -1000,8 +1033,7 @@ const visitors = {
 
 	UpdateExpression(node, context) {
 		if (context.state.to_ts) {
-			context.next();
-			return;
+			return context.next();
 		}
 		const argument = node.argument;
 
@@ -1047,8 +1079,7 @@ const visitors = {
 
 	ForOfStatement(node, context) {
 		if (!is_inside_component(context)) {
-			context.next();
-			return;
+			return context.next();
 		}
 		const is_controlled = node.is_controlled;
 		const index = node.index;
@@ -1090,8 +1121,7 @@ const visitors = {
 
 	IfStatement(node, context) {
 		if (!is_inside_component(context)) {
-			context.next();
-			return;
+			return context.next();
 		}
 		context.state.template.push('<!>');
 
@@ -1174,8 +1204,7 @@ const visitors = {
 
 	TryStatement(node, context) {
 		if (!is_inside_component(context)) {
-			context.next();
-			return;
+			return context.next();
 		}
 		context.state.template.push('<!>');
 
@@ -1310,46 +1339,54 @@ function transform_ts_child(node, context) {
 
 	if (node.type === 'Text') {
 		state.init.push(b.stmt(visit(node.expression, { ...state })));
+	} else if (node.type === 'Html') {
+		// Do we need to do something special here?
+		state.init.push(b.stmt(visit(node.expression, { ...state })));
 	} else if (node.type === 'Element') {
 		const type = node.id.name;
 		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 = visit(attr.value, { ...state, metadata });
-					const jsx_name = b.jsx_id(name.name);
-					if (name.name === 'children') {
-						has_children_props = true;
-					}
-					jsx_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);
@@ -1468,7 +1505,7 @@ function transform_ts_child(node, context) {
 
 		state.init.push(b.try(try_body, catch_handler, finally_block));
 	} else if (node.type === 'Component') {
-		const component = visit(node, context.state);
+		const component = visit(node, state);
 
 		state.init.push(component);
 	} else {
@@ -1592,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 });
@@ -1684,7 +1731,12 @@ function transform_body(body, { visit, state }) {
 	transform_children(body, { visit, state: body_state, root: true });
 
 	if (body_state.update.length > 0) {
-		body_state.init.push(b.stmt(b.call('_$_.render', b.thunk(b.block(body_state.update)))));
+		if (state.to_ts) {
+			// In TypeScript mode, just add the update statements directly
+			body_state.init.push(...body_state.update);
+		} else {
+			body_state.init.push(b.stmt(b.call('_$_.render', b.thunk(b.block(body_state.update)))));
+		}
 	}
 
 	return [...body_state.setup, ...body_state.init, ...body_state.final];