@tsrx/core 0.0.26 → 0.0.28

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "type": "module",
   "repository": {
     "type": "git",
@@ -27,10 +27,11 @@
     "./types/acorn": {
       "types": "./types/acorn.d.ts"
     },
-    "./runtime/merge-refs": {
-      "types": "./types/runtime/merge-refs.d.ts",
-      "default": "./src/runtime/merge-refs.js"
+    "./runtime/ref": {
+      "types": "./types/runtime/ref.d.ts",
+      "default": "./src/runtime/ref.js"
     },
+    "./runtime/*": "./src/runtime/*.js",
     "./test-harness/source-mappings": "./tests/shared/source-mappings.js",
     "./test-harness/compile": "./tests/shared/compile.js"
   },

package/src/analyze/validation.js

@@ -19,6 +19,10 @@ export const COMPONENT_WHILE_STATEMENT_ERROR =
 	'While loops are not supported in components. Move the while loop into a function.';
 export const COMPONENT_DO_WHILE_STATEMENT_ERROR =
 	'Do...while loops are not supported in components. Move the do...while loop into a function.';
+export const CLASS_COMPONENT_AS_NON_ARROW_PROPERTY_ERROR =
+	'Components declared inside a class must be defined as an arrow function class property (e.g. `Foo = component() => { ... }`). Non-arrow component property values are not allowed.';
+export const COMPONENT_MULTIPLE_PARAMS_ERROR =
+	'Components accept a single props parameter. Move additional inputs into the props object instead.';
 
 const invalid_nestings = {
 	// <p> cannot contain block-level elements
@@ -247,6 +251,61 @@ export function validate_component_unsupported_loop_statement(node, filename, er
 	error(message, filename ?? null, node, errors, comments);
 }
 
+/**
+ * Validates that a component declares at most a single (props) parameter.
+ * Components have one slot for props; additional positional parameters are
+ * silently dropped or naively passed through depending on the target, so
+ * reject them at analysis time. Reports one error per extra parameter so
+ * every offending input gets its own TS diagnostic squiggle. In throwing
+ * mode the first call raises and aborts before the loop continues.
+ *
+ * @param {AST.Component} component
+ * @param {string | null | undefined} filename
+ * @param {CompileError[]} [errors]
+ * @param {AST.CommentWithLocation[]} [comments]
+ */
+export function validate_component_params(component, filename, errors, comments) {
+	const params = /** @type {AST.Pattern[] | undefined} */ (component.params);
+	if (!params || params.length <= 1) {
+		return;
+	}
+
+	for (let i = 1; i < params.length; i++) {
+		error(COMPONENT_MULTIPLE_PARAMS_ERROR, filename ?? null, params[i], errors, comments);
+	}
+}
+
+/**
+ * Validates that components declared at the top level of a class body use the
+ * only allowed form: an arrow function class property (regular or static).
+ * Reports an error for non-arrow component property values such as
+ * `Foo = component() { ... }`. The method form (`component foo() {}` inside
+ * a class body) is rejected at parse time and never reaches this check.
+ *
+ * @param {AST.ClassBody} class_body
+ * @param {string | null | undefined} filename
+ * @param {CompileError[]} [errors]
+ * @param {AST.CommentWithLocation[]} [comments]
+ */
+export function validate_class_component_declarations(class_body, filename, errors, comments) {
+	for (const member of class_body.body) {
+		if (member.type !== 'PropertyDefinition') {
+			continue;
+		}
+
+		const value = /** @type {any} */ (member).value;
+		if (value && value.type === 'Component' && !value.metadata?.arrow) {
+			error(
+				CLASS_COMPONENT_AS_NON_ARROW_PROPERTY_ERROR,
+				filename ?? null,
+				member,
+				errors,
+				comments,
+			);
+		}
+	}
+}
+
 /**
  * @param {AST.Element} element
  * @param {AnalysisContext} context

package/src/index.js

@@ -141,8 +141,14 @@ export { escape, escape_script as escapeScript } from './utils/escaping.js';
 
 // Transform
 export {
+	add_jsx_setup_declaration as addJsxSetupDeclaration,
 	createJsxTransform,
+	CREATE_REF_PROP_INTERNAL_NAME,
+	extract_jsx_setup_declarations as extractJsxSetupDeclarations,
+	is_ref_prop_expression as isRefPropExpression,
+	MERGE_REFS_INTERNAL_NAME,
 	merge_duplicate_refs as mergeDuplicateRefs,
+	NORMALIZE_SPREAD_PROPS_INTERNAL_NAME,
 	rewrite_loop_continues_to_bare_returns as rewriteLoopContinuesToBareReturns,
 	to_jsx_attribute as toJsxAttribute,
 	validate_at_most_one_ref_attribute as validateAtMostOneRefAttribute,
@@ -164,12 +170,16 @@ export {
 	flatten_switch_consequent,
 	get_for_of_iteration_params,
 	identifier_to_jsx_name,
+	is_bare_render_expression,
 	is_dynamic_element_id,
 	is_jsx_child,
 	set_loc,
 	to_text_expression,
 } from './transform/jsx/ast-builders.js';
-export { render_stylesheets as renderStylesheets } from './transform/stylesheet.js';
+export {
+	render_stylesheets as renderStylesheets,
+	render_css_result as renderCssResult,
+} from './transform/stylesheet.js';
 export {
 	prepare_stylesheet_for_render as prepareStylesheetForRender,
 	is_style_element as isStyleElement,
@@ -213,17 +223,21 @@ export {
 // Analyze
 export { analyze_css as analyzeCss } from './analyze/css-analyze.js';
 export {
+	CLASS_COMPONENT_AS_NON_ARROW_PROPERTY_ERROR,
 	COMPONENT_DO_WHILE_STATEMENT_ERROR,
 	COMPONENT_FOR_IN_STATEMENT_ERROR,
 	COMPONENT_FOR_STATEMENT_ERROR,
 	COMPONENT_LOOP_BREAK_ERROR,
 	COMPONENT_LOOP_RETURN_ERROR,
+	COMPONENT_MULTIPLE_PARAMS_ERROR,
 	COMPONENT_RETURN_VALUE_ERROR,
 	COMPONENT_WHILE_STATEMENT_ERROR,
 	get_return_keyword_node as getReturnKeywordNode,
 	get_statement_keyword_node as getStatementKeywordNode,
+	validate_class_component_declarations as validateClassComponentDeclarations,
 	validate_component_loop_break_statement as validateComponentLoopBreakStatement,
 	validate_component_loop_return_statement as validateComponentLoopReturnStatement,
+	validate_component_params as validateComponentParams,
 	validate_component_return_statement as validateComponentReturnStatement,
 	validate_component_unsupported_loop_statement as validateComponentUnsupportedLoopStatement,
 	validate_nesting as validateNesting,

package/src/plugin.js

@@ -559,65 +559,6 @@ export function TSRXPlugin(config) {
 				return super.parseProperty(isPattern, refDestructuringErrors);
 			}
 
-			/**
-			 * Override parseClassElement to support component methods in classes.
-			 * Handles syntax like `class Foo { component something() { <div /> } }`
-			 * Also supports computed names: `class Foo { component ['something']() { <div /> } }`
-			 * @type {Parse.Parser['parseClassElement']}
-			 */
-			parseClassElement(constructorAllowsSuper) {
-				// Check if this is a component method: component name( ... ) { ... }
-				if (this.type === tt.name && this.value === 'component') {
-					// Look ahead to see if this is "component identifier(",
-					// "component identifier<", "component [", or "component 'string'"
-					const lookahead = this.input.slice(this.pos).match(/^\s*(?:(\w+)\s*[(<]|\[|['"])/);
-					if (lookahead) {
-						// This is a component method definition
-						const node = /** @type {AST.MethodDefinition} */ (this.startNode());
-						const isComputed = lookahead[0].trim().startsWith('[');
-						const isStringLiteral = /^['"]/.test(lookahead[0].trim());
-
-						if (isComputed) {
-							// For computed names, consume 'component'
-							// parse the key, then parse component without name
-							this.next(); // consume 'component'
-							this.next(); // consume '['
-							node.key = this.parseExpression();
-							this.expect(tt.bracketR);
-							node.computed = true;
-
-							// Parse component without name (skipName: true)
-							const component_node = this.parseComponent({ skipName: true });
-							/** @type {AST.TSRXMethodDefinition} */ (node).value = component_node;
-						} else if (isStringLiteral) {
-							// For string literal names, consume 'component'
-							// parse the string key, then parse component without name
-							this.next(); // consume 'component'
-							node.key = /** @type {AST.Literal} */ (this.parseExprAtom());
-							node.computed = false;
-
-							// Parse component without name (skipName: true)
-							const component_node = this.parseComponent({ skipName: true });
-							/** @type {AST.TSRXMethodDefinition} */ (node).value = component_node;
-						} else {
-							// Use parseComponent which handles consuming 'component', parsing name, params, and body
-							const component_node = this.parseComponent({ requireName: true });
-
-							node.key = /** @type {AST.Identifier} */ (component_node.id);
-							/** @type {AST.TSRXMethodDefinition} */ (node).value = component_node;
-							node.computed = false;
-						}
-
-						node.static = false;
-						node.kind = 'method';
-
-						return this.finishNode(node, 'MethodDefinition');
-					}
-				}
-
-				return super.parseClassElement(constructorAllowsSuper);
-			}
-
 			/**
 			 * Override parsePropertyValue to support TypeScript generic methods in object literals.
 			 * By default, acorn-typescript doesn't handle `{ method<T>() {} }` syntax.
@@ -1371,15 +1312,15 @@ export function TSRXPlugin(config) {
 			 */
 			checkUnreserved(ref) {
 				if (ref.name === 'component') {
-					// Allow 'component' when it's followed by an identifier and '(' or '<' (component method in object literal or class)
-					// e.g., { component something() { ... } } or class Foo { component something<T>() { ... } }
+					// Allow 'component' when it's followed by an identifier and '(' or '<' (component method in object literal)
+					// e.g., { component something() { ... } }
 					// Also allow computed names: { component ['name']() { ... } }
 					// Also allow string literal names: { component 'name'() { ... } }
 					const nextChars = this.input.slice(this.pos).match(/^\s*(?:(\w+)\s*[(<]|\[|['"])/);
 					if (!nextChars) {
 						this.raise(
 							ref.start,
-							'"component" is a Ripple keyword and cannot be used as an identifier',
+							'"component" is a TSRX keyword and cannot be used as an identifier',
 						);
 					}
 				}
@@ -1404,6 +1345,21 @@ export function TSRXPlugin(config) {
 				let node = /** @type {ESTreeJSX.JSXExpressionContainer} */ (this.startNode());
 				this.next();
 
+				if (this.type === tt.name && this.value === 'ref') {
+					const ref_node = /** @type {AST.RefExpression} */ (this.startNode());
+					this.next();
+					if (this.type === tt.braceR) {
+						this.raise(
+							this.start,
+							'"ref" is a TSRX keyword and must be used in the form {ref item}',
+						);
+					}
+					ref_node.argument = this.parseMaybeAssign();
+					node.expression = /** @type {any} */ (this.finishNode(ref_node, 'RefExpression'));
+					this.expect(tt.braceR);
+					return this.finishNode(node, 'JSXExpressionContainer');
+				}
+
 				if (this.type === tt.name && this.value === 'html') {
 					node.html = true;
 					this.next();

package/src/runtime/language-helpers.js

@@ -0,0 +1,57 @@
+/** @type {typeof Object.getOwnPropertyDescriptor} */
+export var get_descriptor = Object.getOwnPropertyDescriptor;
+/** @type {typeof Object.getOwnPropertyDescriptors} */
+export var get_descriptors = Object.getOwnPropertyDescriptors;
+/** @type {typeof Array.from} */
+export var array_from = Array.from;
+/** @type {typeof Array.isArray} */
+export var is_array = Array.isArray;
+/** @type {typeof Object.defineProperty} */
+export var define_property = Object.defineProperty;
+/** @type {typeof Object.getPrototypeOf} */
+export var get_prototype_of = Object.getPrototypeOf;
+/** @type {typeof Object.values} */
+export var object_values = Object.values;
+/** @type {typeof Object.entries} */
+export var object_entries = Object.entries;
+/** @type {typeof Object.keys} */
+export var object_keys = Object.keys;
+/** @type {typeof Object.getOwnPropertySymbols} */
+export var get_own_property_symbols = Object.getOwnPropertySymbols;
+/** @type {typeof structuredClone} */
+export var structured_clone = structuredClone;
+/** @type {typeof Object.prototype} */
+export var object_prototype = Object.prototype;
+/** @type {typeof Array.prototype} */
+export var array_prototype = Array.prototype;
+/** @type {typeof Object.prototype.hasOwnProperty} */
+export var has_own_property = object_prototype.hasOwnProperty;
+
+/**
+ * @param {object} value
+ * @param {PropertyKey} key
+ * @returns {boolean}
+ */
+export function has_prototype_accessor(value, key) {
+	var proto = get_prototype_of(value);
+	while (proto != null) {
+		var descriptor = get_descriptor(proto, key);
+		if (descriptor !== undefined) {
+			return typeof descriptor.get === 'function' || typeof descriptor.set === 'function';
+		}
+		proto = get_prototype_of(proto);
+	}
+	return false;
+}
+
+/**
+ * Slice helper for arrays and array-like values.
+ * @param {ArrayLike<any>} array_like
+ * @param {...number} args
+ * @returns {any[]}
+ */
+export function array_slice(array_like, ...args) {
+	return is_array(array_like)
+		? array_like.slice(...args)
+		: array_prototype.slice.call(array_like, ...args);
+}

package/src/runtime/ref.js

@@ -0,0 +1,250 @@
+import {
+	has_own_property,
+	get_descriptor,
+	has_prototype_accessor,
+} from '@tsrx/core/runtime/language-helpers';
+
+const REF_VALUE = Symbol();
+
+/**
+ * Merge multiple refs (function refs and ref objects) into a single
+ * callback ref. Used by React, Preact, and Vue targets when an element has
+ * more than one `ref` attribute.
+ * This is a public method and also used by the compiler to unite any refs with
+ * any of the supported syntaxes.  It does not process spreads, that is delegated to
+ * `normalize_spread_props`.
+ *
+ * @param {...((node: any) => void | (() => void)) | { current: any } | { value: any } | null | undefined} refs
+ * @returns {(node: any) => (() => void)}
+ */
+export function mergeRefs(...refs) {
+	return (node) => {
+		/** @type {Array<() => void>} */
+		const cleanups = [];
+		for (const ref of refs) {
+			if (ref == null) continue;
+			if (typeof ref === 'function') {
+				const result = ref(node);
+				if (typeof result === 'function') {
+					cleanups.push(result);
+				} else {
+					cleanups.push(() => ref(null));
+				}
+			} else if (is_ref_object(ref, 'current')) {
+				/** @type {{ current: any }} */ (ref).current = node;
+				cleanups.push(() => {
+					/** @type {{ current: any }} */ (ref).current = null;
+				});
+			} else if (is_ref_object(ref, 'value')) {
+				/** @type {{ value: any }} */ (ref).value = node;
+				cleanups.push(() => {
+					/** @type {{ value: any }} */ (ref).value = null;
+				});
+			}
+		}
+		return () => {
+			for (const cleanup of cleanups) cleanup();
+		};
+	};
+}
+
+export { is_ref_prop as isRefProp };
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function is_ref_prop(value) {
+	return typeof value === 'function' && REF_VALUE in value;
+}
+
+/**
+ * @param {any} ref_value
+ * @param {any} node
+ * @param {(value: any) => void} [set_ref_value]
+ * @returns {void | (() => void)}
+ */
+export function apply_ref_value(ref_value, node, set_ref_value) {
+	if (typeof ref_value === 'function') {
+		return ref_value(node);
+	}
+
+	if (ref_value && typeof ref_value === 'object') {
+		if (is_ref_object(ref_value, 'current')) {
+			ref_value.current = node;
+			return () => {
+				ref_value.current = null;
+			};
+		}
+
+		if (is_ref_object(ref_value, 'value')) {
+			ref_value.value = node;
+			return () => {
+				ref_value.value = null;
+			};
+		}
+	}
+
+	if (set_ref_value !== undefined) {
+		set_ref_value(node);
+	}
+}
+
+/**
+ * @param {() => any} get_ref_value
+ * @param {(value: any) => void} [set_ref_value]
+ * @returns {(node: any) => void | (() => void)}
+ */
+export function create_ref_prop(get_ref_value, set_ref_value) {
+	/**
+	 * @param {any} node
+	 * @returns {void | (() => void)}
+	 */
+	function ref_prop_callback(node) {
+		const ref_value = get_ref_value();
+		const cleanup = apply_ref_value(ref_value, node, set_ref_value);
+		if (typeof cleanup === 'function' || node === null) {
+			return cleanup;
+		}
+		return () => {
+			apply_ref_value(ref_value, null, set_ref_value);
+		};
+	}
+
+	Object.defineProperty(ref_prop_callback, REF_VALUE, {
+		value: 'ref_value',
+		enumerable: false,
+	});
+
+	return ref_prop_callback;
+}
+
+/**
+ * @param {...any} refs
+ * @returns {any}
+ */
+export function merge_ref_props(...refs) {
+	const filtered = refs.filter((ref) => ref != null);
+
+	if (filtered.length === 0) {
+		return undefined;
+	}
+
+	if (filtered.length === 1) {
+		return filtered[0];
+	}
+
+	/**
+	 * @param {any} node
+	 * @returns {void | (() => void)}
+	 */
+	function merged_ref_prop(node) {
+		/** @type {Array<() => void>} */
+		const cleanups = [];
+
+		for (const ref of filtered) {
+			const cleanup = apply_ref_value(ref, node);
+			if (typeof cleanup === 'function') {
+				cleanups.push(cleanup);
+			} else if (typeof ref === 'function' && node !== null) {
+				cleanups.push(() => ref(null));
+			}
+		}
+
+		return () => {
+			for (const cleanup of cleanups) {
+				cleanup();
+			}
+		};
+	}
+
+	return merged_ref_prop;
+}
+
+/**
+ * @param {Record<string | symbol, any> | null | undefined} props
+ * @param {...any} outer_refs
+ * @returns {Record<string | symbol, any> | null | undefined}
+ */
+export function normalize_spread_props(props, ...outer_refs) {
+	if (props == null) {
+		return props;
+	}
+
+	/** @type {any[]} */
+	const refs = [];
+	/** @type {Record<string | symbol, any>} */
+	let next = {};
+	let changed = false;
+	let existing_ref;
+
+	for (const key of Reflect.ownKeys(props)) {
+		const descriptor = get_descriptor(props, key);
+		if (!descriptor?.enumerable) {
+			continue;
+		}
+
+		const value = /** @type {any} */ (props)[key];
+
+		if (key === 'ref') {
+			if (is_ref_prop(value)) {
+				refs.push(value);
+				changed = true;
+			} else {
+				existing_ref = value;
+			}
+			continue;
+		}
+
+		if (is_ref_prop(value)) {
+			refs.push(value);
+			changed = true;
+			continue;
+		}
+
+		next[key] = value;
+	}
+
+	if (!changed && outer_refs.length === 0) {
+		return props;
+	}
+
+	const merged_ref = merge_ref_props(existing_ref, ...refs, ...outer_refs);
+	if (merged_ref !== undefined) {
+		next.ref = merged_ref;
+	}
+
+	return next;
+}
+
+/**
+ * @param {object} value
+ * @param {'current' | 'value'} key
+ * @returns {boolean}
+ */
+function is_ref_object(value, key) {
+	if (is_dom_node(value)) {
+		return false;
+	}
+	if (key === 'value' && '__v_isRef' in value) {
+		return true;
+	}
+	if (has_own_property.call(value, key)) {
+		return true;
+	}
+	return key === 'value' && has_prototype_accessor(value, 'value');
+}
+
+/**
+ * @param {object} value
+ * @returns {boolean}
+ */
+function is_dom_node(value) {
+	return (
+		(typeof Node !== 'undefined' && value instanceof Node) ||
+		('nodeType' in value &&
+			typeof (/** @type {{ nodeType?: unknown }} */ (value).nodeType) === 'number' &&
+			'nodeName' in value &&
+			typeof (/** @type {{ nodeName?: unknown }} */ (value).nodeName) === 'string')
+	);
+}

package/src/transform/jsx/ast-builders.js

@@ -143,7 +143,7 @@ export function identifier_to_jsx_name(id) {
 			/** @type {any} */ ({
 				type: 'JSXIdentifier',
 				name: id.name,
-				metadata: { path: [], is_component: /^[A-Z]/.test(id.name) },
+				metadata: { ...(id.metadata || {}), path: [], is_component: /^[A-Z]/.test(id.name) },
 			}),
 			id,
 		);
@@ -187,6 +187,57 @@ export function is_jsx_child(node) {
 	);
 }
 
+/**
+ * The parser represents `<>{expr}</>` / `<tsx>{expr}</tsx>` as a Tsx node,
+ * and expression-position lowering unwraps that to the inner expression.
+ * When such a node appears directly in a component or statement render body,
+ * the unwrapped expression is still render output rather than an executable
+ * statement.
+ *
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function is_bare_render_expression(node) {
+	if (!node || typeof node !== 'object') {
+		return false;
+	}
+
+	switch (node.type) {
+		case 'ArrayExpression':
+		case 'ArrowFunctionExpression':
+		case 'AssignmentExpression':
+		case 'AwaitExpression':
+		case 'BinaryExpression':
+		case 'CallExpression':
+		case 'ChainExpression':
+		case 'ClassExpression':
+		case 'ConditionalExpression':
+		case 'FunctionExpression':
+		case 'Identifier':
+		case 'ImportExpression':
+		case 'Literal':
+		case 'LogicalExpression':
+		case 'MemberExpression':
+		case 'MetaProperty':
+		case 'NewExpression':
+		case 'ObjectExpression':
+		case 'ParenthesizedExpression':
+		case 'SequenceExpression':
+		case 'TaggedTemplateExpression':
+		case 'TemplateLiteral':
+		case 'ThisExpression':
+		case 'TSAsExpression':
+		case 'TSSatisfiesExpression':
+		case 'TSNonNullExpression':
+		case 'UnaryExpression':
+		case 'UpdateExpression':
+		case 'YieldExpression':
+			return true;
+		default:
+			return false;
+	}
+}
+
 /**
  * A dynamic element id is one whose identifier is `tracked` — i.e. it was
  * introduced by reactive destructuring so its value can change at runtime.
@@ -325,26 +376,26 @@ export function to_text_expression(expression, source_node = expression) {
 }
 
 /**
- * Deep-clone an AST subtree. `loc` / `start` / `end` are shallow-shared by
- * reference rather than recursed into — `loc` objects can contain back-refs
- * to sub-objects that would blow the stack with a naive deep clone, and
- * every other traversal in the targets treats these positional keys as
- * shared.
+ * Deep-clone an AST subtree.
  *
  * @param {any} node
+ * @param {boolean} with_locations
  * @returns {any}
  */
-export function clone_expression_node(node) {
+export function clone_expression_node(node, with_locations = true) {
 	if (!node || typeof node !== 'object') return node;
-	if (Array.isArray(node)) return node.map(clone_expression_node);
-	const clone = { ...node };
-	for (const key of Object.keys(clone)) {
-		if (key === 'loc' || key === 'start' || key === 'end') continue;
+	if (Array.isArray(node)) return node.map((child) => clone_expression_node(child, with_locations));
+	const clone = /** @type {Record<string, any>} */ ({});
+
+	for (const key of Object.keys(node)) {
+		if (!with_locations && (key === 'loc' || key === 'start' || key === 'end')) {
+			continue;
+		}
 		if (key === 'metadata') {
-			clone.metadata = clone.metadata ? { ...clone.metadata } : { path: [] };
+			clone.metadata = node.metadata ? { ...node.metadata } : { path: [] };
 			continue;
 		}
-		clone[key] = clone_expression_node(clone[key]);
+		clone[key] = clone_expression_node(node[key], with_locations);
 	}
 	return clone;
 }