@tsrx/vue 0.0.21 → 0.0.23

package/package.json

@@ -3,7 +3,7 @@
   "description": "Vue compiler built on @tsrx/core",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -22,19 +22,20 @@
       "types": "./types/error-boundary.d.ts",
       "default": "./src/error-boundary.js"
     },
-    "./merge-refs": {
-      "types": "./types/merge-refs.d.ts",
-      "default": "./src/merge-refs.js"
+    "./ref": {
+      "types": "./types/ref.d.ts",
+      "default": "./src/ref.js"
     }
   },
   "dependencies": {
     "esrap": "^2.1.0",
+    "is-reference": "^3.0.3",
     "zimmerframe": "^1.1.2",
-    "@tsrx/core": "0.0.26"
+    "@tsrx/core": "0.0.28"
   },
   "peerDependencies": {
     "vue": ">=3.5",
-    "vue-jsx-vapor": ">=3.2.10"
+    "vue-jsx-vapor": ">=3.2.12"
   },
   "devDependencies": {
     "@types/estree": "^1.0.8",

package/src/index.js

@@ -4,6 +4,8 @@
 import { createVolarMappingsResult, dedupeMappings, parseModule } from '@tsrx/core';
 import { transform } from './transform.js';
 
+export { isRefProp } from './ref.js';
+
 /**
  * Parse tsrx-vue source code to an ESTree AST.
  * @param {string} source
@@ -22,7 +24,7 @@ export function parse(source, filename, options) {
  * @param {string} source
  * @param {string} [filename]
  * @param {{ collect?: boolean, loose?: boolean }} [options]
- * @returns {{ code: string, map: any, css: { code: string, hash: string } | null, errors: CompileError[] }}
+ * @returns {{ code: string, map: any, css: string, cssHash: string | null, errors: CompileError[] }}
  */
 export function compile(source, filename, options) {
 	const errors = /** @type {CompileError[]} */ ([]);
@@ -63,6 +65,7 @@ export function compile_to_volar_mappings(source, filename, options) {
 	const transformed = transform(ast, source, filename, {
 		collect: true,
 		loose: !!options?.loose,
+		typeOnly: true,
 		errors,
 		comments,
 	});

package/src/ref.js

@@ -0,0 +1 @@
+export * from '@tsrx/core/runtime/ref';

package/src/transform.js

@@ -1,14 +1,20 @@
 /** @import { JsxPlatform } from '@tsrx/core/types' */
 
+import { walk } from 'zimmerframe';
+import is_reference from 'is-reference';
 import {
 	builders,
 	clone_expression_node,
 	clone_identifier,
+	CREATE_REF_PROP_INTERNAL_NAME,
+	create_generated_identifier,
 	componentToFunctionDeclaration,
 	createJsxTransform,
 	error,
-	identifier_to_jsx_name,
+	MERGE_REFS_INTERNAL_NAME,
+	NORMALIZE_SPREAD_PROPS_INTERNAL_NAME,
 	setLocation,
+	toJsxAttribute,
 } from '@tsrx/core';
 
 /**
@@ -25,12 +31,14 @@ const vue_platform = {
 	imports: {
 		suspense: 'vue',
 		errorBoundary: '@tsrx/vue/error-boundary',
-		mergeRefs: '@tsrx/vue/merge-refs',
+		mergeRefs: '@tsrx/vue/ref',
+		refProp: '@tsrx/vue/ref',
 	},
 	jsx: {
 		rewriteClassAttr: false,
 		acceptedTsxKinds: ['vue'],
 		multiRefStrategy: 'merge-refs',
+		hostSpreadRefStrategy: 'explicit-ref-attr',
 	},
 	validation: {
 		requireUseServerForAwait: true,
@@ -41,6 +49,7 @@ const vue_platform = {
 	hooks: {
 		initialState: () => ({
 			needs_define_vapor_component: false,
+			needs_vapor_for: false,
 		}),
 		isTopLevelSetupCall(call_expression) {
 			return is_vue_setup_call(call_expression);
@@ -55,18 +64,17 @@ const vue_platform = {
 		preprocessElementAttributes(attrs, ctx, element) {
 			return preprocess_ref_attributes(attrs, element, ctx);
 		},
-		renderForOf: (node, loop_params, body_statements) =>
-			render_for_of_as_vapor_template(node, loop_params, body_statements),
+		transformElementAttributes(attrs, ctx, element) {
+			const result = attrs.map((attr) => toJsxAttribute(attr, ctx));
+			if (!ctx.typeOnly || is_component_like_element(element)) {
+				return result;
+			}
+			return result.map(mark_type_only_host_ref_attribute);
+		},
+		renderForOf: (node, loop_params, body_statements, ctx) =>
+			render_for_of_as_vapor_for(node, loop_params, body_statements, ctx),
 		createErrorBoundaryContent(try_content) {
-			return {
-				type: 'ArrowFunctionExpression',
-				params: [],
-				body: try_content.expression,
-				async: false,
-				generator: false,
-				expression: true,
-				metadata: { path: [] },
-			};
+			return builders.arrow([], try_content.expression);
 		},
 		transformElementChildren(node, walked_children, raw_children, attributes, ctx) {
 			return rewrite_host_text_or_html_children(
@@ -98,6 +106,34 @@ const vue_platform = {
 
 export const transform = createJsxTransform(vue_platform);
 
+/**
+ * Vue's `VNodeRef` type is wider than TSRX host refs because it also supports
+ * component instances and null teardown values. In editor-only TSX, keep the ref
+ * expression unchanged but stop TypeScript verification from reporting that
+ * Vue-specific assignability diagnostic on the generated `ref` prop token.
+ *
+ * @param {any} attr
+ * @returns {any}
+ */
+function mark_type_only_host_ref_attribute(attr) {
+	if (
+		!attr ||
+		attr.type !== 'JSXAttribute' ||
+		attr.name?.type !== 'JSXIdentifier' ||
+		attr.name.name !== 'ref'
+	) {
+		return attr;
+	}
+
+	return {
+		...attr,
+		name: {
+			...attr.name,
+			metadata: { ...(attr.name.metadata || {}), disable_verification: true },
+		},
+	};
+}
+
 /**
  * @param {any} component
  * @param {any} transform_context
@@ -128,26 +164,12 @@ function component_to_vapor_component_declaration(component, transform_context,
 	};
 	/** @type {any} */ (component_id.metadata).hover = create_component_hover_replacement(fn.params);
 
-	return setLocation(
-		/** @type {any} */ ({
-			type: 'VariableDeclaration',
-			kind: 'const',
-			declarations: [
-				{
-					type: 'VariableDeclarator',
-					id: component_id,
-					init: call,
-					metadata: { path: [] },
-				},
-			],
-			metadata: {
-				path: [],
-				generated_helpers,
-				generated_statics,
-			},
-		}),
-		component,
-	);
+	const declaration = builders.declaration('const', [builders.declarator(component_id, call)]);
+	Object.assign(/** @type {any} */ (declaration.metadata), {
+		generated_helpers,
+		generated_statics,
+	});
+	return setLocation(/** @type {any} */ (declaration), component);
 }
 
 /**
@@ -158,24 +180,17 @@ function component_to_vapor_component_declaration(component, transform_context,
  */
 function wrap_helper_component(helper_fn, helper_id, source_node) {
 	return setLocation(
-		/** @type {any} */ ({
-			type: 'VariableDeclaration',
-			kind: 'const',
-			declarations: [
-				{
-					type: 'VariableDeclarator',
-					id: clone_identifier(helper_id),
-					init: create_define_vapor_component_call(
-						function_declaration_to_expression(helper_fn),
-						[],
-						[],
-						source_node,
-					),
-					metadata: { path: [] },
-				},
-			],
-			metadata: { path: [] },
-		}),
+		builders.declaration('const', [
+			builders.declarator(
+				clone_identifier(helper_id),
+				create_define_vapor_component_call(
+					function_declaration_to_expression(helper_fn),
+					[],
+					[],
+					source_node,
+				),
+			),
+		]),
 		source_node,
 	);
 }
@@ -193,33 +208,22 @@ function create_define_vapor_component_call(
 	generated_statics,
 	source_node,
 ) {
-	return setLocation(
-		/** @type {any} */ ({
-			type: 'CallExpression',
-			callee: {
-				type: 'Identifier',
-				name: 'defineVaporComponent',
-				metadata: { path: [] },
-			},
-			arguments: [fn_expression],
-			optional: false,
-			metadata: {
-				path: [],
-				generated_helpers,
-				generated_statics,
-			},
-		}),
-		source_node,
-	);
+	const call = builders.call('defineVaporComponent', fn_expression);
+	Object.assign(/** @type {any} */ (call.metadata), {
+		generated_helpers,
+		generated_statics,
+	});
+	return setLocation(call, source_node);
 }
 
 /**
  * @param {any} node
  * @param {any[]} loop_params
  * @param {any[]} body_statements
+ * @param {any} transform_context
  * @returns {any | null}
  */
-function render_for_of_as_vapor_template(node, loop_params, body_statements) {
+function render_for_of_as_vapor_for(node, loop_params, body_statements, transform_context) {
 	if (body_statements.length !== 1) {
 		return null;
 	}
@@ -238,49 +242,43 @@ function render_for_of_as_vapor_template(node, loop_params, body_statements) {
 		? clone_expression_node(node.key)
 		: (find_jsx_key_expression(rendered) ??
 			(node.index ? clone_expression_node(node.index) : null));
-	strip_top_level_jsx_keys(rendered);
-	const children = rendered.type === 'JSXFragment' ? rendered.children : [rendered];
+
+	const slot = key_expression
+		? create_keyed_vapor_for_slot(loop_params, rendered)
+		: { params: loop_params, body: rendered, expression: true };
+	if (!slot) {
+		return null;
+	}
+
+	transform_context.needs_vapor_for = true;
+
+	if (key_expression) {
+		strip_top_level_jsx_keys(slot.body);
+	}
+
 	const attributes = [
-		{
-			type: 'JSXAttribute',
-			name: { type: 'JSXIdentifier', name: 'v-for', metadata: { path: [] } },
-			value: to_jsx_expression_container({
-				type: 'BinaryExpression',
-				operator: 'in',
-				left: create_v_for_left(loop_params),
-				right: clone_expression_node(node.right),
-				metadata: { path: [] },
-			}),
-			metadata: { path: [] },
-		},
+		builders.jsx_attribute(
+			builders.jsx_id('in'),
+			to_jsx_expression_container(clone_expression_node(node.right)),
+		),
 	];
 
 	if (key_expression) {
-		attributes.push({
-			type: 'JSXAttribute',
-			name: { type: 'JSXIdentifier', name: 'key', metadata: { path: [] } },
-			value: to_jsx_expression_container(key_expression),
-			metadata: { path: [] },
-		});
+		attributes.push(
+			builders.jsx_attribute(
+				builders.jsx_id('getKey'),
+				to_jsx_expression_container(create_loop_callback(loop_params, key_expression, true)),
+			),
+		);
 	}
 
-	return to_jsx_expression_container({
-		type: 'JSXElement',
-		openingElement: {
-			type: 'JSXOpeningElement',
-			name: { type: 'JSXIdentifier', name: 'template', metadata: { path: [] } },
-			attributes,
-			selfClosing: false,
-			metadata: { path: [] },
-		},
-		closingElement: {
-			type: 'JSXClosingElement',
-			name: { type: 'JSXIdentifier', name: 'template', metadata: { path: [] } },
-			metadata: { path: [] },
-		},
-		children,
-		metadata: { path: [] },
-	});
+	return to_jsx_expression_container(
+		builders.jsx_element_fresh(
+			builders.jsx_opening_element(builders.jsx_id('VaporFor'), attributes),
+			builders.jsx_closing_element(builders.jsx_id('VaporFor')),
+			[to_jsx_expression_container(create_loop_callback(slot.params, slot.body, slot.expression))],
+		),
+	);
 }
 
 /**
@@ -290,47 +288,20 @@ function render_for_of_as_vapor_template(node, loop_params, body_statements) {
  * @returns {any}
  */
 function render_for_of_as_flat_map(node, loop_params, rendered) {
-	return to_jsx_expression_container({
-		type: 'CallExpression',
-		callee: {
-			type: 'MemberExpression',
-			object: clone_expression_node(node.right),
-			property: { type: 'Identifier', name: 'flatMap', metadata: { path: [] } },
-			computed: false,
-			optional: false,
-			metadata: { path: [] },
-		},
-		arguments: [
-			{
-				type: 'ArrowFunctionExpression',
-				params: loop_params,
-				body: {
-					type: 'BlockStatement',
-					body: [
-						{
-							type: 'ReturnStatement',
-							argument: to_array_render_expression(rendered),
-							metadata: { path: [] },
-						},
-					],
-					metadata: { path: [] },
-				},
-				async: false,
-				generator: false,
-				expression: false,
-				metadata: { path: [] },
-			},
-		],
-		async: false,
-		optional: false,
-		metadata: { path: [] },
-	});
+	return to_jsx_expression_container(
+		builders.call(
+			builders.member(clone_expression_node(node.right), 'flatMap'),
+			builders.arrow(
+				loop_params,
+				builders.block([builders.return(to_array_render_expression(rendered))]),
+			),
+		),
+	);
 }
 
 /**
- * `<template v-for>` preserves one rendered slot per source item in the current
- * Vue runtime path. Loop bodies that can return `null` need the shared callback
- * lowering so `continue` truly skips the iteration.
+ * Loop bodies that can return `null` need the shared callback lowering so
+ * `continue` truly skips the iteration.
  *
  * @param {any} node
  * @returns {boolean}
@@ -386,22 +357,6 @@ function to_array_render_expression(node) {
 	return builders.array([node]);
 }
 
-/**
- * @param {any[]} loop_params
- * @returns {any}
- */
-function create_v_for_left(loop_params) {
-	if (loop_params.length === 1) {
-		return clone_expression_node(loop_params[0]);
-	}
-
-	return {
-		type: 'SequenceExpression',
-		expressions: loop_params.map((param) => clone_expression_node(param)),
-		metadata: { path: [] },
-	};
-}
-
 /**
  * @param {any} node
  * @returns {any | null}
@@ -450,6 +405,360 @@ function strip_top_level_jsx_keys(node) {
 	}
 }
 
+/**
+ * @param {any[]} loop_params
+ * @param {any} body
+ * @param {boolean} expression
+ * @returns {any}
+ */
+function create_loop_callback(loop_params, body, expression) {
+	const callback = builders.arrow(
+		loop_params.map((param) => clone_expression_node(param)),
+		body,
+	);
+	callback.expression = expression;
+	return callback;
+}
+
+/**
+ * @param {any[]} loop_params
+ * @param {any} rendered
+ * @returns {{ params: any[], body: any, expression: boolean } | null}
+ */
+function create_keyed_vapor_for_slot(loop_params, rendered) {
+	if (loop_params[0]?.type === 'Identifier') {
+		return {
+			params: loop_params,
+			body: rewrite_vapor_for_keyed_slot_refs(rendered, loop_params),
+			expression: true,
+		};
+	}
+
+	const item_ref = create_generated_identifier('__vapor_item');
+	const item_ref_value = create_value_member_expression(item_ref);
+	const replacements = create_pattern_replacements(loop_params[0], item_ref_value);
+	if (!replacements) {
+		return null;
+	}
+
+	const params = [item_ref, ...loop_params.slice(1)];
+	const rewritten_rendered = rewrite_vapor_for_keyed_slot_refs(
+		rendered,
+		loop_params.slice(1),
+		replacements,
+	);
+
+	return {
+		params,
+		body: rewritten_rendered,
+		expression: true,
+	};
+}
+
+/**
+ * Vue's `VaporFor` passes plain item values to unkeyed slots, but keyed slots
+ * receive shallow refs so row instances can update in place. Match that runtime
+ * shape by reading loop params through `.value` inside the slot body.
+ *
+ * @param {any} node
+ * @param {any[]} loop_params
+ * @param {Map<string, any>} [replacements]
+ * @returns {any}
+ */
+function rewrite_vapor_for_keyed_slot_refs(node, loop_params, replacements = new Map()) {
+	const loop_param_names = new Set();
+	for (const param of loop_params) {
+		collect_pattern_names(param, loop_param_names);
+	}
+
+	if (loop_param_names.size === 0 && replacements.size === 0) {
+		return node;
+	}
+
+	return walk(
+		node,
+		{ loop_param_names, shadowed_names: new Set() },
+		{
+			Identifier(identifier, { path, state, next }) {
+				const parent = path.at(-1);
+				if (
+					(state.loop_param_names.has(identifier.name) || replacements.has(identifier.name)) &&
+					!state.shadowed_names.has(identifier.name) &&
+					parent &&
+					is_runtime_reference(identifier, parent)
+				) {
+					const replacement = replacements.get(identifier.name);
+					if (replacement) {
+						return clone_expression_node(replacement);
+					}
+					return create_value_member_expression(identifier);
+				}
+
+				return next();
+			},
+			FunctionDeclaration: rewrite_function_shadowed_refs,
+			FunctionExpression: rewrite_function_shadowed_refs,
+			ArrowFunctionExpression: rewrite_function_shadowed_refs,
+			BlockStatement: rewrite_block_shadowed_refs,
+		},
+	);
+}
+
+/**
+ * @param {any} identifier
+ * @param {any} parent
+ * @returns {boolean}
+ */
+function is_runtime_reference(identifier, parent) {
+	if (parent.type === 'JSXExpressionContainer') {
+		return parent.expression === identifier;
+	}
+	if (parent.type === 'JSXAttribute') {
+		return parent.value === identifier || parent.value?.expression === identifier;
+	}
+	return is_reference(identifier, parent);
+}
+
+/**
+ * @param {any} pattern
+ * @param {any} source
+ * @returns {Map<string, any> | null}
+ */
+function create_pattern_replacements(pattern, source) {
+	const replacements = new Map();
+	return collect_pattern_replacements(pattern, source, replacements) ? replacements : null;
+}
+
+/**
+ * @param {any} pattern
+ * @param {any} source
+ * @param {Map<string, any>} replacements
+ * @returns {boolean}
+ */
+function collect_pattern_replacements(pattern, source, replacements) {
+	if (!pattern) return true;
+
+	switch (pattern.type) {
+		case 'Identifier':
+			replacements.set(pattern.name, source);
+			return true;
+		case 'ObjectPattern':
+			for (const property of pattern.properties || []) {
+				if (property.type === 'RestElement' || property.computed) {
+					return false;
+				}
+				if (
+					property.type !== 'Property' ||
+					!collect_pattern_replacements(
+						property.value,
+						create_property_member_expression(source, property.key),
+						replacements,
+					)
+				) {
+					return false;
+				}
+			}
+			return true;
+		case 'ArrayPattern':
+			for (let index = 0; index < (pattern.elements || []).length; index++) {
+				const element = pattern.elements[index];
+				if (
+					element &&
+					!collect_pattern_replacements(
+						element,
+						create_index_member_expression(source, index),
+						replacements,
+					)
+				) {
+					return false;
+				}
+			}
+			return true;
+		default:
+			return false;
+	}
+}
+
+/**
+ * @param {any} node
+ * @param {{ state: { loop_param_names: Set<string>, shadowed_names: Set<string> }, next: (state?: any) => any }} context
+ * @returns {any}
+ */
+function rewrite_function_shadowed_refs(node, { state, next }) {
+	const shadowed_names = new Set(state.shadowed_names);
+	if (node.id) {
+		collect_pattern_names(node.id, shadowed_names);
+	}
+	for (const param of node.params || []) {
+		collect_pattern_names(param, shadowed_names);
+	}
+	collect_function_var_names(node.body, shadowed_names);
+	return next({ ...state, shadowed_names });
+}
+
+/**
+ * @param {any} node
+ * @param {{ state: { loop_param_names: Set<string>, shadowed_names: Set<string> }, next: (state?: any) => any }} context
+ * @returns {any}
+ */
+function rewrite_block_shadowed_refs(node, { state, next }) {
+	const shadowed_names = new Set(state.shadowed_names);
+	collect_block_lexical_names(node.body, shadowed_names);
+	return next({ ...state, shadowed_names });
+}
+
+/**
+ * @param {any[]} statements
+ * @param {Set<string>} names
+ * @returns {void}
+ */
+function collect_block_lexical_names(statements, names) {
+	for (const statement of statements || []) {
+		if (statement.type === 'VariableDeclaration' && statement.kind !== 'var') {
+			for (const declaration of statement.declarations || []) {
+				collect_pattern_names(declaration.id, names);
+			}
+			continue;
+		}
+
+		if (
+			(statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') &&
+			statement.id
+		) {
+			collect_pattern_names(statement.id, names);
+		}
+	}
+}
+
+/**
+ * @param {any} node
+ * @param {Set<string>} names
+ * @returns {void}
+ */
+function collect_function_var_names(node, names) {
+	if (!node || typeof node !== 'object') return;
+
+	if (Array.isArray(node)) {
+		for (const child of node) {
+			collect_function_var_names(child, names);
+		}
+		return;
+	}
+
+	if (
+		node.type === 'FunctionDeclaration' ||
+		node.type === 'FunctionExpression' ||
+		node.type === 'ArrowFunctionExpression' ||
+		node.type === 'ClassDeclaration' ||
+		node.type === 'ClassExpression'
+	) {
+		return;
+	}
+
+	if (node.type === 'VariableDeclaration' && node.kind === 'var') {
+		for (const declaration of node.declarations || []) {
+			collect_pattern_names(declaration.id, names);
+		}
+	}
+
+	for (const key of Object.keys(node)) {
+		if (key === 'loc' || key === 'start' || key === 'end' || key === 'metadata') {
+			continue;
+		}
+		collect_function_var_names(node[key], names);
+	}
+}
+
+/**
+ * @param {any} node
+ * @param {Set<string>} names
+ * @returns {void}
+ */
+function collect_pattern_names(node, names) {
+	if (!node) return;
+
+	switch (node.type) {
+		case 'Identifier':
+			names.add(node.name);
+			break;
+		case 'RestElement':
+			collect_pattern_names(node.argument, names);
+			break;
+		case 'AssignmentPattern':
+			collect_pattern_names(node.left, names);
+			break;
+		case 'ArrayPattern':
+			for (const element of node.elements || []) {
+				collect_pattern_names(element, names);
+			}
+			break;
+		case 'ObjectPattern':
+			for (const property of node.properties || []) {
+				collect_pattern_names(property, names);
+			}
+			break;
+		case 'Property':
+			collect_pattern_names(node.value, names);
+			break;
+	}
+}
+
+/**
+ * @param {any} object
+ * @param {any} key
+ * @returns {any}
+ */
+function create_property_member_expression(object, key) {
+	if (key?.type === 'Identifier') {
+		return create_member_expression(
+			clone_expression_node(object),
+			clone_identifier(key),
+			false,
+			key,
+		);
+	}
+
+	return create_member_expression(
+		clone_expression_node(object),
+		clone_expression_node(key),
+		true,
+		key,
+	);
+}
+
+/**
+ * @param {any} object
+ * @param {number} index
+ * @returns {any}
+ */
+function create_index_member_expression(object, index) {
+	return create_member_expression(
+		clone_expression_node(object),
+		builders.literal(index),
+		true,
+		object,
+	);
+}
+
+/**
+ * @param {any} identifier
+ * @returns {any}
+ */
+function create_value_member_expression(identifier) {
+	return create_member_expression(clone_identifier(identifier), 'value', false, identifier);
+}
+
+/**
+ * @param {any} object
+ * @param {any} property
+ * @param {boolean} computed
+ * @param {any} source_node
+ * @returns {any}
+ */
+function create_member_expression(object, property, computed, source_node) {
+	return builders.member(object, property, computed, false, source_node);
+}
+
 /**
  * @param {any} fn
  * @returns {any}
@@ -549,6 +858,7 @@ function preprocess_ref_attributes(attrs, element, transform_context) {
 	if (!is_component_like_element(element)) {
 		return attrs;
 	}
+	const result = [];
 	for (const attr of attrs) {
 		if (attr?.type === 'RefAttribute') {
 			error(
@@ -559,8 +869,72 @@ function preprocess_ref_attributes(attrs, element, transform_context) {
 				transform_context?.comments,
 			);
 		}
+		if (!transform_context.typeOnly && is_vue_named_ref_attribute(attr)) {
+			result.push(create_vue_named_ref_spread(attr));
+			continue;
+		}
+		result.push(attr);
+	}
+	return result;
+}
+
+/**
+ * Vue's JSX transform treats prop names ending in `ref` as template-ref
+ * sugar on components. Keep named TSRX refs as ordinary runtime props by
+ * hiding the static prop name behind an object spread before Vue sees the JSX.
+ * Type-only virtual TSX skips that spread so Volar can offer completions on
+ * the real component prop name.
+ *
+ * @param {any} attr
+ * @returns {boolean}
+ */
+function is_vue_named_ref_attribute(attr) {
+	const attr_name = get_vue_attribute_name(attr);
+	const value = get_vue_attribute_expression(attr);
+	return !!(
+		attr_name &&
+		attr_name !== 'ref' &&
+		(attr?.type === 'Attribute' || attr?.type === 'JSXAttribute') &&
+		(value?.type === 'RefExpression' ||
+			(value?.type === 'CallExpression' &&
+				value.callee?.type === 'Identifier' &&
+				value.callee.name === CREATE_REF_PROP_INTERNAL_NAME))
+	);
+}
+
+/**
+ * @param {any} attr
+ * @returns {any}
+ */
+function create_vue_named_ref_spread(attr) {
+	const attr_name = get_vue_attribute_name(attr);
+	const value = get_vue_attribute_expression(attr);
+	if (attr_name === null) return attr;
+	const prop = builders.prop('init', builders.key(attr_name), value, false, false);
+	return builders.jsx_spread_attribute(builders.object([prop], attr), attr);
+}
+
+/**
+ * @param {any} attr
+ * @returns {string | null}
+ */
+function get_vue_attribute_name(attr) {
+	if (attr?.type === 'Attribute') {
+		return typeof attr.name === 'string' ? attr.name : (attr.name?.name ?? null);
+	}
+	if (attr?.type === 'JSXAttribute') {
+		return attr.name?.type === 'JSXIdentifier' ? attr.name.name : null;
 	}
-	return attrs;
+	return null;
+}
+
+/**
+ * @param {any} attr
+ * @returns {any}
+ */
+function get_vue_attribute_expression(attr) {
+	const value = attr?.value;
+	return value?.type === 'JSXExpressionContainer' ? value.expression : value;
 }
 
 /**
@@ -652,16 +1026,7 @@ function has_dom_content_attribute(attributes, name) {
  * @returns {any}
  */
 function create_jsx_attribute(name, value, source_node) {
-	return setLocation(
-		/** @type {any} */ ({
-			type: 'JSXAttribute',
-			name: identifier_to_jsx_name(builders.id(name)),
-			value,
-			shorthand: false,
-			metadata: { path: [] },
-		}),
-		source_node,
-	);
+	return builders.jsx_attribute(builders.jsx_id(name), value, false, source_node);
 }
 
 /**
@@ -670,12 +1035,7 @@ function create_jsx_attribute(name, value, source_node) {
  * @returns {any}
  */
 function to_jsx_expression_container(expression, source_node = expression) {
-	void source_node;
-	return {
-		type: 'JSXExpressionContainer',
-		expression,
-		metadata: { path: [] },
-	};
+	return builders.jsx_expression_container(expression, source_node);
 }
 
 /**
@@ -741,6 +1101,10 @@ function inject_vue_imports(program, transform_context) {
 		ensure_named_import(program, 'vue-jsx-vapor', 'defineVaporComponent');
 	}
 
+	if (transform_context.needs_vapor_for) {
+		ensure_named_import(program, 'vue-jsx-vapor', 'VaporFor');
+	}
+
 	if (transform_context.needs_suspense) {
 		ensure_named_import(program, 'vue', 'Suspense');
 	}
@@ -750,7 +1114,20 @@ function inject_vue_imports(program, transform_context) {
 	}
 
 	if (transform_context.needs_merge_refs) {
-		ensure_named_import(program, '@tsrx/vue/merge-refs', 'mergeRefs', '__mergeRefs');
+		ensure_named_import(program, '@tsrx/vue/ref', 'mergeRefs', MERGE_REFS_INTERNAL_NAME);
+	}
+
+	if (transform_context.needs_ref_prop) {
+		ensure_named_import(program, '@tsrx/vue/ref', 'create_ref_prop', CREATE_REF_PROP_INTERNAL_NAME);
+	}
+
+	if (transform_context.needs_normalize_spread_props) {
+		ensure_named_import(
+			program,
+			'@tsrx/vue/ref',
+			'normalize_spread_props',
+			NORMALIZE_SPREAD_PROPS_INTERNAL_NAME,
+		);
 	}
 }
 
@@ -782,7 +1159,7 @@ function ensure_named_import(program, source, name, local = name) {
 		return;
 	}
 
-	program.body.unshift(create_import_declaration(source, [create_import_specifier(name, local)]));
+	program.body.unshift(builders.imports([[name, local, 'value']], source));
 }
 
 /**
@@ -799,19 +1176,3 @@ function create_import_specifier(name, local = name) {
 		metadata: { path: [] },
 	};
 }
-
-/**
- * @param {string} source
- * @param {any[]} specifiers
- * @returns {any}
- */
-function create_import_declaration(source, specifiers) {
-	return {
-		type: 'ImportDeclaration',
-		attributes: [],
-		specifiers,
-		importKind: 'value',
-		source: builders.literal(source),
-		metadata: { path: [] },
-	};
-}

package/types/index.d.ts

@@ -1,21 +1,10 @@
 import type { Program } from 'estree';
-import type { CompileError, ParseOptions, VolarMappingsResult } from '@tsrx/core/types';
+import type { CompileFn, ParseOptions, VolarCompileFn } from '@tsrx/core/types';
 
 export function parse(source: string, filename?: string, options?: ParseOptions): Program;
 
-export function compile(
-	source: string,
-	filename?: string,
-	options?: { collect?: boolean; loose?: boolean },
-): {
-	code: string;
-	map: unknown;
-	css: { code: string; hash: string } | null;
-	errors: CompileError[];
-};
+export { isRefProp } from './ref.js';
 
-export function compile_to_volar_mappings(
-	source: string,
-	filename?: string,
-	options?: ParseOptions,
-): VolarMappingsResult;
+export const compile: CompileFn;
+
+export const compile_to_volar_mappings: VolarCompileFn;

package/types/ref.d.ts

@@ -0,0 +1 @@
+export * from '@tsrx/core/runtime/ref';

package/src/merge-refs.js

@@ -1 +0,0 @@
-export { mergeRefs } from '@tsrx/core/runtime/merge-refs';

package/types/merge-refs.d.ts

@@ -1 +0,0 @@
-export { mergeRefs } from '@tsrx/core/runtime/merge-refs';