ripple 0.3.8 → 0.3.9

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ripple
 
+## 0.3.9
+
+### Patch Changes
+
+- Updated dependencies []:
+  - ripple@0.3.9
+
 ## 0.3.8
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -105,6 +105,6 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "ripple": "0.3.8"
+    "ripple": "0.3.9"
   }
 }

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

@@ -413,7 +413,9 @@ function RipplePlugin(config) {
 						/** @type {AST.Property} */ (prop).method = true;
 						/** @type {AST.Property} */ (prop).kind = 'init';
 						/** @type {AST.Property} */ (prop).value = this.parseMethod(false, false);
-						/** @type {AST.Property} */ (prop).value.typeParameters = typeParameters;
+						/** @type {AST.FunctionExpression} */ (
+							/** @type {AST.Property} */ (prop).value
+						).typeParameters = typeParameters;
 						return;
 					}
 				}
@@ -666,99 +668,9 @@ function RipplePlugin(config) {
 						}
 					}
 				}
-				if (code === 64) {
-					// @ character
-					// Look ahead to see if this is followed by an opening paren
-					if (this.pos + 1 < this.input.length) {
-						const nextChar = this.input.charCodeAt(this.pos + 1);
-
-						// Check if this is @( for unboxing expression syntax
-						if (nextChar === 40) {
-							// ( character
-							this.pos += 2; // skip '@('
-							return this.finishToken(tt.parenL, '@(');
-						}
-					}
-				}
 				return super.getTokenFromCode(code);
 			}
 
-			/**
-			 * Override parseSubscripts to handle `.@[expression]` syntax for reactive computed member access
-			 * @type {Parse.Parser['parseSubscripts']}
-			 */
-			parseSubscripts(
-				base,
-				startPos,
-				startLoc,
-				noCalls,
-				maybeAsyncArrow,
-				optionalChained,
-				forInit,
-			) {
-				// Check for `.@[` pattern for reactive computed member access
-				const isDotOrOptional = this.type === tt.dot || this.type === tt.questionDot;
-
-				if (isDotOrOptional) {
-					// Check the next two characters without consuming tokens
-					// this.pos currently points AFTER the dot token
-					const nextChar = this.input.charCodeAt(this.pos);
-					const charAfter = this.input.charCodeAt(this.pos + 1);
-
-					// Check for @[ pattern (@ = 64, [ = 91)
-					if (nextChar === 64 && charAfter === 91) {
-						const node = /** @type {AST.MemberExpression} */ (this.startNodeAt(startPos, startLoc));
-						node.object = base;
-						node.computed = true;
-						node.optional = this.type === tt.questionDot;
-						node.tracked = true;
-
-						// Consume the dot/questionDot token
-						this.next();
-
-						// Manually skip the @ character
-						this.pos += 1;
-
-						// Now call finishToken to properly consume the [ bracket
-						this.finishToken(tt.bracketL);
-
-						// Now we're positioned correctly to parse the expression
-						this.next(); // Move to first token inside brackets
-
-						// Parse the expression inside brackets
-						node.property = this.parseExpression();
-
-						// Expect closing bracket
-						this.expect(tt.bracketR);
-
-						// Finish this MemberExpression node
-						base = /** @type {AST.MemberExpression} */ (this.finishNode(node, 'MemberExpression'));
-
-						// Recursively handle any further subscripts (chaining)
-						return this.parseSubscripts(
-							base,
-							startPos,
-							startLoc,
-							noCalls,
-							maybeAsyncArrow,
-							optionalChained,
-							forInit,
-						);
-					}
-				}
-
-				// Fall back to default parseSubscripts implementation
-				return super.parseSubscripts(
-					base,
-					startPos,
-					startLoc,
-					noCalls,
-					maybeAsyncArrow,
-					optionalChained,
-					forInit,
-				);
-			}
-
 			/**
 			 * Override isLet to recognize `let &{` and `let &[` as variable declarations.
 			 * Acorn's isLet checks the char after `let` and only recognizes `{`, `[`, or identifiers.
@@ -795,7 +707,7 @@ function RipplePlugin(config) {
 						// & directly followed by { or [ — lazy destructuring
 						this.next(); // consume &, now current token is { or [
 						const pattern = super.parseBindingAtom();
-						pattern.lazy = true;
+						/** @type {AST.ObjectPattern | AST.ArrayPattern} */ (pattern).lazy = true;
 						return pattern;
 					}
 				}
@@ -810,11 +722,6 @@ function RipplePlugin(config) {
 				const lookahead_type = this.lookahead().type;
 				const is_next_call_token = lookahead_type === tt.parenL || lookahead_type === tt.relational;
 
-				// Check if this is @(expression) for unboxing tracked values
-				if (this.type === tt.parenL && this.value === '@(') {
-					return this.parseTrackedExpression();
-				}
-
 				// Check if this is #server identifier for server function calls
 				if (this.type === tt.name && this.value === '#server') {
 					const node = this.startNode();
@@ -855,31 +762,6 @@ function RipplePlugin(config) {
 				return expr;
 			}
 
-			/**
-			 * Parse `@(expression)` syntax for unboxing tracked values
-			 * Creates a TrackedExpression node with the argument property
-			 * @type {Parse.Parser['parseTrackedExpression']}
-			 */
-			parseTrackedExpression() {
-				const node = /** @type {AST.TrackedExpression} */ (this.startNode());
-				this.next(); // consume '@(' token
-				node.argument = this.parseExpression();
-				this.expect(tt.parenR); // expect ')'
-				return this.finishNode(node, 'TrackedExpression');
-			}
-
-			/**
-			 * Override to allow TrackedExpression as a valid lvalue for update expressions
-			 * @type {Parse.Parser['checkLValSimple']}
-			 */
-			checkLValSimple(expr, bindingType, checkClashes) {
-				// Allow TrackedExpression as a valid lvalue for ++/-- operators
-				if (expr.type === 'TrackedExpression') {
-					return;
-				}
-				return super.checkLValSimple(expr, bindingType, checkClashes);
-			}
-
 			/**
 			 * Override checkLocalExport to check all scopes in the scope stack.
 			 * This is needed because server blocks create nested scopes, but exports
@@ -1018,6 +900,7 @@ function RipplePlugin(config) {
 					return this.parseFor(node, null);
 				}
 
+				// @ts-ignore — acorn internal: isLet accepts 0 args at runtime
 				let isLet = this.isLet();
 				if (this.type === tt._var || this.type === tt._const || isLet) {
 					let init = /** @type {AST.VariableDeclaration} */ (this.startNode()),
@@ -1060,7 +943,9 @@ function RipplePlugin(config) {
 				}
 
 				let containsEsc = this.containsEsc;
-				let refDestructuringErrors = new DestructuringErrors();
+				let refDestructuringErrors = new /** @type {new () => Parse.DestructuringErrors} */ (
+					/** @type {unknown} */ (DestructuringErrors)
+				)();
 				let initPos = this.start;
 				let init_expr =
 					awaitAt > -1
@@ -1391,38 +1276,8 @@ function RipplePlugin(config) {
 						)
 					);
 					memberExpr.object = node;
-
-					// Check for .@[expression] syntax for tracked computed member access
-					// After eating the dot, check if the current token is @ followed by [
-					if (this.type.label === '@') {
-						// Check if the next character after @ is [
-						const nextChar = this.input.charCodeAt(this.pos);
-
-						if (nextChar === 91) {
-							// [ character
-							memberExpr.computed = true;
-
-							// Consume the @ token
-							this.next();
-
-							// Now this.type should be bracketL
-							// Consume the [ and parse the expression inside
-							this.expect(tt.bracketL);
-
-							// Parse the expression inside brackets
-							memberExpr.property = /** @type {ESTreeJSX.JSXIdentifier} */ (this.parseExpression());
-							/** @type {AST.TrackedNode} */ (memberExpr.property).tracked = true;
-
-							// Expect closing bracket
-							this.expect(tt.bracketR);
-						} else {
-							this.unexpected();
-						}
-					} else {
-						// Regular dot notation
-						memberExpr.property = this.jsx_parseIdentifier();
-						memberExpr.computed = false;
-					}
+					memberExpr.property = this.jsx_parseIdentifier();
+					memberExpr.computed = false;
 					memberExpr = this.finishNode(memberExpr, 'JSXMemberExpression');
 					while (this.eat(tt.dot)) {
 						let newMemberExpr = /** @type {ESTreeJSX.JSXMemberExpression} */ (
@@ -1707,8 +1562,9 @@ function RipplePlugin(config) {
 								if (expression.type === 'Literal') {
 									expression.was_expression = true;
 								}
-								/** @type {ESTreeJSX.JSXExpressionContainer['expression']} */ (attr.value) =
-									expression;
+								// @ts-ignore — intentional AST node conversion from JSX to Ripple
+								/** @type {ESTreeJSX.JSXAttribute} */ (attr).value =
+									/** @type {ESTreeJSX.JSXExpressionContainer['expression']} */ (expression);
 							}
 						}
 					}

package/src/compiler/phases/2-analyze/index.js

@@ -4,6 +4,7 @@
 	AnalysisResult,
 	AnalysisState,
 	AnalysisContext,
+	Context,
 	ScopeInterface,
 	Visitors,
 	TopScopedClasses,
@@ -329,14 +330,185 @@ function setup_lazy_array_transforms(pattern, source_id, state, writable) {
 }
 
 /**
- * Checks if a function parameter has a Tracked<T> type annotation imported from ripple.
+ * @param {AST.Pattern} pattern
+ * @returns {AST.TypeNode | undefined}
+ */
+function get_pattern_type_annotation(pattern) {
+	return pattern.typeAnnotation?.typeAnnotation;
+}
+
+/**
+ * @param {AST.TypeNode | undefined} type_annotation
+ * @returns {AST.TypeNode | undefined}
+ */
+function unwrap_type_annotation(type_annotation) {
+	/** @type {AST.TypeNode | undefined} */
+	let annotation = type_annotation;
+
+	while (annotation) {
+		if (annotation.type === 'TSParenthesizedType') {
+			annotation = annotation.typeAnnotation;
+			continue;
+		}
+		if (annotation.type === 'TSOptionalType') {
+			annotation = annotation.typeAnnotation;
+			continue;
+		}
+		break;
+	}
+
+	return annotation;
+}
+
+/**
+ * @param {AST.TypeNode} type_annotation
+ * @returns {AST.TypeNode}
+ */
+function normalize_tuple_element_type(type_annotation) {
+	/** @type {AST.TypeNode} */
+	let annotation = type_annotation;
+
+	while (true) {
+		if (annotation.type === 'TSNamedTupleMember') {
+			annotation = annotation.elementType;
+			continue;
+		}
+		if (annotation.type === 'TSParenthesizedType') {
+			annotation = annotation.typeAnnotation;
+			continue;
+		}
+		if (annotation.type === 'TSOptionalType') {
+			annotation = annotation.typeAnnotation;
+			continue;
+		}
+		break;
+	}
+
+	return annotation;
+}
+
+/**
+ * @param {AST.Expression} key
+ * @returns {string | null}
+ */
+function get_object_pattern_key_name(key) {
+	if (key.type === 'Identifier') {
+		return key.name;
+	}
+	if (key.type === 'Literal' && (typeof key.value === 'string' || typeof key.value === 'number')) {
+		return String(key.value);
+	}
+	return null;
+}
+
+/**
+ * @param {AST.PropertyNameNonComputed} key
+ * @returns {string | null}
+ */
+function get_type_property_key_name(key) {
+	if (key.type === 'Identifier') {
+		return key.name;
+	}
+	if (key.type === 'Literal' && (typeof key.value === 'string' || typeof key.value === 'number')) {
+		return String(key.value);
+	}
+	return null;
+}
+
+/**
+ * @param {AST.TypeNode | undefined} type_annotation
+ * @param {AST.Property | AST.RestElement} property
+ * @returns {AST.TypeNode | undefined}
+ */
+function get_object_property_type_annotation(type_annotation, property) {
+	if (property.type === 'RestElement' || property.computed) {
+		return undefined;
+	}
+
+	const object_type_annotation = unwrap_type_annotation(type_annotation);
+	if (object_type_annotation?.type !== 'TSTypeLiteral') {
+		return undefined;
+	}
+
+	const key_name = get_object_pattern_key_name(property.key);
+	if (key_name === null) {
+		return undefined;
+	}
+
+	for (const member of object_type_annotation.members) {
+		if (member.type !== 'TSPropertySignature' || member.computed) {
+			continue;
+		}
+		const member_key_name = get_type_property_key_name(member.key);
+		if (member_key_name === key_name) {
+			return member.typeAnnotation?.typeAnnotation;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * @param {AST.TypeNode | undefined} type_annotation
+ * @param {number} index
+ * @param {boolean} is_rest
+ * @returns {AST.TypeNode | undefined}
+ */
+function get_array_element_type_annotation(type_annotation, index, is_rest) {
+	const array_type_annotation = unwrap_type_annotation(type_annotation);
+
+	if (array_type_annotation?.type === 'TSArrayType') {
+		return array_type_annotation.elementType;
+	}
+	if (array_type_annotation?.type !== 'TSTupleType') {
+		return undefined;
+	}
+
+	if (is_rest) {
+		for (let i = array_type_annotation.elementTypes.length - 1; i >= 0; i -= 1) {
+			const element_type = normalize_tuple_element_type(array_type_annotation.elementTypes[i]);
+			if (element_type.type === 'TSRestType') {
+				return element_type.typeAnnotation;
+			}
+		}
+		return undefined;
+	}
+
+	if (index < array_type_annotation.elementTypes.length) {
+		const element_type = normalize_tuple_element_type(array_type_annotation.elementTypes[index]);
+		if (element_type.type === 'TSRestType') {
+			const rest_type_annotation = unwrap_type_annotation(element_type.typeAnnotation);
+			return rest_type_annotation?.type === 'TSArrayType'
+				? rest_type_annotation.elementType
+				: element_type.typeAnnotation;
+		}
+		return element_type;
+	}
+
+	const last_element = array_type_annotation.elementTypes.at(-1);
+	if (!last_element) {
+		return undefined;
+	}
+	const normalized_last_element = normalize_tuple_element_type(last_element);
+	if (normalized_last_element.type === 'TSRestType') {
+		const rest_type_annotation = unwrap_type_annotation(normalized_last_element.typeAnnotation);
+		return rest_type_annotation?.type === 'TSArrayType'
+			? rest_type_annotation.elementType
+			: normalized_last_element.typeAnnotation;
+	}
+
+	return undefined;
+}
+
+/**
+ * Checks if a parameter source has a Tracked<T> type annotation imported from ripple.
  * This is used to determine if lazy array destructuring should use the track tuple fast path.
- * @param {AST.ArrayPattern} param - The parameter pattern node
+ * @param {AST.TypeNode | undefined} type_annotation - The source type annotation
  * @param {AnalysisContext} context - The analysis context
  * @returns {boolean}
  */
-function is_param_tracked_type(param, context) {
-	const annotation = param.typeAnnotation?.typeAnnotation;
+function is_param_tracked_type(type_annotation, context) {
+	const annotation = unwrap_type_annotation(type_annotation);
 
 	if (
 		annotation?.type === 'TSTypeReference' &&
@@ -357,6 +529,75 @@ function is_param_tracked_type(param, context) {
 	return false;
 }
 
+/**
+ * Sets up lazy transforms for any lazy subpatterns nested inside a function or component param.
+ * @param {AST.Pattern} pattern
+ * @param {AnalysisContext} context
+ * @param {AST.TypeNode | undefined} [type_annotation]
+ */
+function setup_nested_lazy_param_transforms(pattern, context, type_annotation = undefined) {
+	const pattern_type_annotation = get_pattern_type_annotation(pattern) ?? type_annotation;
+
+	switch (pattern.type) {
+		case 'AssignmentPattern':
+			setup_nested_lazy_param_transforms(pattern.left, context, pattern_type_annotation);
+			return;
+
+		case 'RestElement':
+			setup_nested_lazy_param_transforms(pattern.argument, context, pattern_type_annotation);
+			return;
+
+		case 'ObjectPattern':
+		case 'ArrayPattern': {
+			if (pattern.lazy) {
+				const param_id = b.id(context.state.scope.generate('lazy'));
+				const is_tracked_type =
+					pattern.type === 'ArrayPattern' &&
+					is_param_tracked_type(pattern_type_annotation, context);
+
+				setup_lazy_transforms(pattern, param_id, context.state, true, is_tracked_type);
+				pattern.metadata = { ...pattern.metadata, lazy_id: param_id.name };
+				return;
+			}
+
+			if (pattern.type === 'ObjectPattern') {
+				for (const property of pattern.properties) {
+					const property_type_annotation = get_object_property_type_annotation(
+						pattern_type_annotation,
+						property,
+					);
+					if (property.type === 'RestElement') {
+						setup_nested_lazy_param_transforms(
+							property.argument,
+							context,
+							property_type_annotation,
+						);
+					} else {
+						setup_nested_lazy_param_transforms(property.value, context, property_type_annotation);
+					}
+				}
+			} else {
+				for (let i = 0; i < pattern.elements.length; i += 1) {
+					const element = pattern.elements[i];
+					if (element !== null) {
+						setup_nested_lazy_param_transforms(
+							element,
+							context,
+							get_array_element_type_annotation(
+								pattern_type_annotation,
+								i,
+								element.type === 'RestElement',
+							),
+						);
+					}
+				}
+			}
+
+			return;
+		}
+	}
+}
+
 /**
  * @param {AST.Function} node
  * @param {AnalysisContext} context
@@ -371,16 +612,11 @@ function visit_function(node, context) {
 	for (let i = 0; i < node.params.length; i++) {
 		const param_node = node.params[i];
 		const param = param_node.type === 'AssignmentPattern' ? param_node.left : param_node;
+		const param_type_annotation =
+			get_pattern_type_annotation(param) ?? param_node.typeAnnotation?.typeAnnotation;
 
-		if ((param.type === 'ObjectPattern' || param.type === 'ArrayPattern') && param.lazy) {
-			const param_id = b.id(context.state.scope.generate('param'));
-			// For ArrayPattern params with a Tracked<T> type annotation from ripple,
-			// use the track tuple fast path (get/set instead of source[0]/source[1])
-			const is_tracked_type =
-				param.type === 'ArrayPattern' && is_param_tracked_type(param, context);
-			setup_lazy_transforms(param, param_id, context.state, true, is_tracked_type);
-			// Store the generated identifier name on the pattern for the transform phase
-			param.metadata = { ...param.metadata, lazy_id: param_id.name };
+		if (param.type === 'ObjectPattern' || param.type === 'ArrayPattern') {
+			setup_nested_lazy_param_transforms(param, context, param_type_annotation);
 		}
 	}
 
@@ -484,19 +720,14 @@ function unwrap_template_expression(expression) {
 
 /**
  * @param {AST.Expression} expression
- * @param {AnalysisState} state
+ * @param {Context<AST.Node, AnalysisState>} context
  * @returns {boolean}
  */
-function is_children_template_expression(expression, state) {
+function is_children_template_expression(expression, context) {
+	const component = context.path.findLast((node) => node.type === 'Component');
+	const component_scope = component ? context.state.scopes.get(component) : null;
 	const unwrapped = unwrap_template_expression(expression);
 
-	if (unwrapped.type === 'TrackedExpression') {
-		return is_children_template_expression(
-			/** @type {AST.Expression} */ (unwrapped.argument),
-			state,
-		);
-	}
-
 	if (unwrapped.type === 'MemberExpression') {
 		let property_name = null;
 
@@ -514,13 +745,25 @@ function is_children_template_expression(expression, state) {
 			const target = unwrap_template_expression(/** @type {AST.Expression} */ (unwrapped.object));
 
 			if (target.type === 'Identifier') {
-				const binding = state.scope.get(target.name);
-				return binding?.declaration_kind === 'param';
+				const binding = context.state.scope.get(target.name);
+				return binding?.declaration_kind === 'param' && binding.scope === component_scope;
 			}
 		}
 	}
 
-	return unwrapped.type === 'Identifier' && unwrapped.name === 'children';
+	if (unwrapped.type !== 'Identifier' || unwrapped.name !== 'children') {
+		return false;
+	}
+
+	const binding = context.state.scope.get(unwrapped.name);
+	return (
+		(binding?.declaration_kind === 'param' ||
+			binding?.kind === 'prop' ||
+			binding?.kind === 'prop_fallback' ||
+			binding?.kind === 'lazy' ||
+			binding?.kind === 'lazy_fallback') &&
+		binding.scope === component_scope
+	);
 }
 
 /** @type {Visitors<AST.Node, AnalysisState>} */
@@ -632,16 +875,6 @@ const visitors = {
 	MemberExpression(node, context) {
 		const parent = context.path.at(-1);
 
-		if (
-			context.state.metadata?.tracking === false &&
-			parent?.type !== 'AssignmentExpression' &&
-			(node.tracked ||
-				((node.property.type === 'Identifier' || node.property.type === 'Literal') &&
-					/** @type {AST.TrackedNode} */ (node.property).tracked))
-		) {
-			context.state.metadata.tracking = true;
-		}
-
 		// Track #style.className or #style['className'] references
 		if (node.object.type === 'StyleIdentifier') {
 			const component = is_inside_component(context, true);
@@ -761,6 +994,19 @@ const visitors = {
 
 		const callee = node.callee;
 
+		if (
+			!context.path.some((path_node) => path_node.type === 'TsxCompat') &&
+			is_children_template_expression(/** @type {AST.Expression} */ (callee), context)
+		) {
+			error(
+				'`children` cannot be called like a regular function. Use element syntax instead, e.g. `<children />` or `<props.children />`.',
+				context.state.analysis.module.filename,
+				callee,
+				context.state.loose ? context.state.analysis.errors : undefined,
+				context.state.analysis.comments,
+			);
+		}
+
 		if (context.state.function_depth === 0 && is_ripple_track_call(callee, context)) {
 			error(
 				'`track` can only be used within a reactive context, such as a component, function or class that is used or created from a component',
@@ -913,9 +1159,13 @@ const visitors = {
 		if (node.params.length > 0) {
 			const props = node.params[0];
 
-			if ((props.type === 'ObjectPattern' || props.type === 'ArrayPattern') && props.lazy) {
+			if (props.type === 'ObjectPattern' || props.type === 'ArrayPattern') {
 				// Lazy destructuring: &{...} or &[...] — set up lazy transforms
-				setup_lazy_transforms(props, b.id('__props'), context.state, true, false);
+				if (props.lazy) {
+					setup_lazy_transforms(props, b.id('__props'), context.state, true, false);
+				} else {
+					setup_nested_lazy_param_transforms(props, context, get_pattern_type_annotation(props));
+				}
 			} else if (props.type === 'AssignmentPattern') {
 				error(
 					'Props are always an object, use destructured props with default values instead',
@@ -1463,6 +1713,7 @@ const visitors = {
 
 		const { state, visit, path } = context;
 		const is_dom_element = is_element_dom_element(node);
+		/** @type {Set<AST.Identifier>} */
 		const attribute_names = new Set();
 
 		mark_control_flow_has_template(path);
@@ -1718,12 +1969,7 @@ const visitors = {
 	Text(node, context) {
 		mark_control_flow_has_template(context.path);
 
-		if (
-			is_children_template_expression(
-				/** @type {AST.Expression} */ (node.expression),
-				context.state,
-			)
-		) {
+		if (is_children_template_expression(/** @type {AST.Expression} */ (node.expression), context)) {
 			error(
 				'`children` cannot be rendered using text interpolation. Use `<children />` instead.',
 				context.state.analysis.module.filename,