@tsrx/core 0.0.26 → 0.0.28

package/src/transform/segments.js

@@ -439,7 +439,6 @@ export function convert_source_map_to_mappings(
 	}
 
 	/**
-	 * @typedef {AST.MethodDefinition & {value: {metadata: {is_component: true}}}} MethodIsComponent
 	 * @typedef {AST.Property & {value: AST.FunctionExpression, method: true} & {value: {metadata: {is_component: true}}}} PropertyIsComponent
 	 */
 
@@ -447,7 +446,7 @@ export function convert_source_map_to_mappings(
 	 * Maps `component` to the identifier's location
 	 * e.g. const obj = { component something() { } }
 	 * since there is no function keyword in source maps
-	 * @param {MethodIsComponent | PropertyIsComponent} node
+	 * @param {PropertyIsComponent} node
 	 * @returns {void}
 	 */
 	function set_component_mapping_to_name(node) {
@@ -563,16 +562,17 @@ export function convert_source_map_to_mappings(
 			} else if (node.type === 'JSXIdentifier') {
 				// JSXIdentifiers can also be capitalized (for dynamic components)
 				if (node.loc && node.name) {
-					if (node.metadata?.is_capitalized) {
-						tokens.push({
-							source: node.metadata.source_name,
-							generated: node.name,
-							loc: node.loc,
-							metadata: {},
-						});
-					} else {
-						tokens.push({ source: node.name, generated: node.name, loc: node.loc, metadata: {} });
+					/** @type {Token} */
+					const token = {
+						source: node.metadata?.is_capitalized ? node.metadata.source_name : node.name,
+						generated: node.name,
+						loc: node.loc,
+						metadata: {},
+					};
+					if (node.metadata?.disable_verification) {
+						token.mappingData = { ...mapping_data, verification: false };
 					}
+					tokens.push(token);
 				}
 				return; // Leaf node, don't traverse further
 			} else if (node.type === 'Literal') {
@@ -867,6 +867,15 @@ export function convert_source_map_to_mappings(
 					// but since we already map the opening - start, we just need the proper end
 					// and it was causing some issues with mappings
 					mapping.generatedLengths = [mapping.generatedLengths[0] + 1];
+					if (!closing && opening.selfClosing) {
+						const generated_close_length = '/>;'.length;
+						mapping.sourceOffsets = [/** @type {AST.NodeWithLocation} */ (opening).end - 2];
+						mapping.lengths = ['/>'.length];
+						mapping.generatedOffsets = [
+							mapping.generatedOffsets[0] + mapping.generatedLengths[0] - generated_close_length,
+						];
+						mapping.generatedLengths = [generated_close_length];
+					}
 					mappings.push(mapping);
 				}
 
@@ -1530,15 +1539,8 @@ export function convert_source_map_to_mappings(
 					set_bracket_computed_mapping(node, mappings);
 				}
 
-				if (node.value.metadata.is_component) {
-					set_component_mapping_to_name(/** @type {MethodIsComponent} */ (node));
-				}
-
 				if (node.key.type === 'Literal') {
-					handle_literal(
-						node.key,
-						/** @type {AST.FunctionExpression} */ (node.value).metadata.is_component,
-					);
+					handle_literal(node.key);
 				} else {
 					visit(node.key);
 				}

package/src/transform/stylesheet.js

@@ -543,3 +543,22 @@ export function render_stylesheets(stylesheets, minify = false) {
 
 	return css;
 }
+
+/**
+ * Render the `{ css, cssHash }` slice of a `CompileResult` from a list of
+ * stylesheets. Returns `{ css: '', cssHash: null }` when the list is empty
+ * so consumers can pass the result straight into a flat compile result.
+ *
+ * @param {AST.CSS.StyleSheet[]} stylesheets
+ * @param {boolean} [minify]
+ * @returns {{ css: string, cssHash: string | null }}
+ */
+export function render_css_result(stylesheets, minify = false) {
+	if (stylesheets.length === 0) {
+		return { css: '', cssHash: null };
+	}
+	return {
+		css: render_stylesheets(stylesheets, minify),
+		cssHash: stylesheets.map((s) => s.hash).join(' '),
+	};
+}

package/types/index.d.ts

@@ -213,6 +213,7 @@ declare module 'estree' {
 		Text: TextNode;
 		Attribute: Attribute;
 		RefAttribute: RefAttribute;
+		RefExpression: RefExpression;
 		SpreadAttribute: SpreadAttribute;
 		ParenthesizedExpression: ParenthesizedExpression;
 		ScriptContent: ScriptContent;
@@ -220,6 +221,7 @@ declare module 'estree' {
 
 	interface ExpressionMap {
 		Style: Style;
+		RefExpression: RefExpression;
 		Text: TextNode;
 		JSXEmptyExpression: ESTreeJSX.JSXEmptyExpression;
 		ParenthesizedExpression: ParenthesizedExpression;
@@ -437,6 +439,12 @@ declare module 'estree' {
 		loc?: AST.SourceLocation;
 	}
 
+	interface RefExpression extends AST.BaseNode {
+		type: 'RefExpression';
+		argument: AST.Expression;
+		loc?: AST.SourceLocation;
+	}
+
 	interface SpreadAttribute extends AST.BaseNode {
 		type: 'SpreadAttribute';
 		argument: AST.Expression;
@@ -463,10 +471,6 @@ declare module 'estree' {
 		body: (Program['body'][number] | Component | FunctionExpression)[];
 	}
 
-	interface TSRXMethodDefinition extends Omit<AST.MethodDefinition, 'value'> {
-		value: AST.MethodDefinition['value'] | Component;
-	}
-
 	interface TSRXProperty extends Omit<AST.Property, 'value'> {
 		value: AST.Property['value'] | Component;
 	}
@@ -1575,15 +1579,17 @@ export interface VolarMappingsResult {
  * Result of compilation operation
  */
 export interface CompileResult {
-	/** The transformed AST */
-	ast: AST.Program;
-	/** The generated JavaScript code with source map */
-	js: {
-		code: string;
-		map: import('source-map').RawSourceMap;
-	};
-	/** The generated CSS */
+	/** The generated JavaScript code */
+	code: string;
+	/** Source map for the generated code */
+	map: import('source-map').RawSourceMap;
+	/** Rendered CSS for the module, or `''` when the module emits no styles. */
 	css: string;
+	/**
+	 * Space-separated scope hashes for the rendered CSS, or `null` when the
+	 * module emits no styles.
+	 */
+	cssHash: string | null;
 	/**
 	 * Non-fatal errors collected during compilation. Populated only when the
 	 * caller passes `collect: true` or `loose: true`; empty otherwise.
@@ -1599,6 +1605,46 @@ export interface VolarCompileOptions extends Omit<ParseOptions, 'errors' | 'comm
 	dev?: boolean;
 }
 
+/**
+ * Common base options accepted by every TSRX target's `compile` entry point.
+ * Targets that need extra knobs (e.g. ripple's `mode`/`dev`/`hmr`, preact's
+ * `suspenseSource`) intersect their own option type with this base when
+ * declaring their `compile` export.
+ */
+export interface BaseCompileOptions {
+	collect?: boolean;
+	loose?: boolean;
+}
+
+/**
+ * Shared `compile` signature for every TSRX target package. Per-target
+ * `compile` declarations should be `CompileFn<TOptions, TResult>` so any
+ * drift in the shared contract becomes a typecheck error in every package.
+ *
+ * @template TOptions Per-target options accepted as the third argument.
+ *   Defaults to {@link BaseCompileOptions}.
+ * @template TResult Per-target result type. Must extend {@link CompileResult};
+ *   targets may add fields (e.g. ripple's deprecated `js` back-compat field)
+ *   via intersection.
+ */
+export type CompileFn<
+	TOptions = BaseCompileOptions,
+	TResult extends CompileResult = CompileResult,
+> = (source: string, filename?: string, options?: TOptions) => TResult;
+
+/**
+ * Shared `compile_to_volar_mappings` signature for every TSRX target package.
+ *
+ * @template TOptions Per-target options accepted as the third argument.
+ *   Defaults to {@link ParseOptions}; targets may intersect their own option
+ *   type to add e.g. `suspenseSource`.
+ */
+export type VolarCompileFn<TOptions = ParseOptions> = (
+	source: string,
+	filename?: string,
+	options?: TOptions,
+) => VolarMappingsResult;
+
 /**
  * Source map transformation types
  */

package/types/jsx-platform.d.ts

@@ -14,7 +14,14 @@ export interface JsxTransformResult {
 	 * downstream Vite / Rollup plugins to chain source maps.
 	 */
 	map: RawSourceMap;
-	css: { code: string; hash: string } | null;
+	/** Rendered CSS for the module, or `''` when the module emits no styles. */
+	css: string;
+	/**
+	 * Space-separated scope hashes for the rendered CSS, or `null` when the
+	 * module emits no styles. When multiple `<style>` blocks contribute, the
+	 * hashes appear in source order.
+	 */
+	cssHash: string | null;
 }
 
 /**
@@ -29,7 +36,10 @@ export interface JsxTransformContext {
 	needs_error_boundary: boolean;
 	needs_suspense: boolean;
 	needs_merge_refs: boolean;
+	needs_ref_prop: boolean;
+	needs_normalize_spread_props: boolean;
 	needs_fragment: boolean;
+	module_scoped_hook_components: boolean;
 	helper_state: {
 		base_name: string;
 		next_id: number;
@@ -48,6 +58,8 @@ export interface JsxTransformContext {
 	errors: CompileError[] | undefined;
 	/** Module-level comments used to honor `@tsrx-ignore` / `@tsrx-expect-error`. */
 	comments: AST.CommentWithLocation[] | undefined;
+	/** True when emitting a type-only virtual TSX module; preserves lazy destructuring patterns. */
+	typeOnly: boolean;
 }
 
 /**
@@ -80,6 +92,20 @@ export interface JsxTransformOptions {
 	 * `@tsrx-expect-error` line comments.
 	 */
 	comments?: AST.CommentWithLocation[];
+	/**
+	 * Override whether hook-isolation helper components are emitted directly at
+	 * module scope. React runtime compilation enables this, while editor tooling
+	 * can disable it to preserve lexical `typeof` helper prop types.
+	 */
+	moduleScopedHookComponents?: boolean;
+	/**
+	 * Emit a type-only virtual TSX module — output is fed to TypeScript for
+	 * editor diagnostics / completions and never executed. Skips the lazy
+	 * destructuring rewrite (`&{ a, b }` → `__lazy0: { a: any; b: any }`) so
+	 * destructuring patterns survive and TypeScript can flow real types to the
+	 * bindings.
+	 */
+	typeOnly?: boolean;
 }
 
 /**
@@ -135,6 +161,13 @@ export interface JsxPlatformHooks {
 	 * state behaves like normal component state.
 	 */
 	wrapHelperComponent?: (helperFn: any, helperId: any, ctx: any, sourceNode: any) => any;
+	/**
+	 * Emit hook-isolation helper components as unique module-scope declarations
+	 * instead of lazily creating and caching them from the parent component body.
+	 * React enables this so generated branches stay compatible with the React
+	 * Compiler's Rules of Hooks validation.
+	 */
+	moduleScopedHookComponents?: boolean;
 	/**
 	 * Inject module-level imports after the main walk. Default: import
 	 * `Suspense` from `platform.imports.suspense` and `TsrxErrorBoundary`
@@ -162,7 +195,7 @@ export interface JsxPlatformHooks {
 	 * Optionally replace the default React-style `.map(...)` lowering for a
 	 * `for...of` body after the shared transform has already produced its render
 	 * statements and applied any explicit or implicit keys. Vue uses this to hand
-	 * the loop to the downstream Vapor JSX compiler as a native `v-for` template.
+	 * the loop to the downstream Vapor JSX compiler as a typed `VaporFor` component.
 	 */
 	renderForOf?: (node: any, loopParams: any[], bodyStatements: any[], ctx: any) => any | null;
 	/**
@@ -259,9 +292,14 @@ export interface JsxPlatform {
 		 * Module to import `mergeRefs` from when an element has more than one
 		 * `ref` attribute and the platform uses the `'merge-refs'` strategy.
 		 * Required when `jsx.multiRefStrategy === 'merge-refs'`; ignored
-		 * otherwise. React: `'@tsrx/react/merge-refs'`. Preact: `'@tsrx/preact/merge-refs'`.
+		 * otherwise. React: `'@tsrx/react/ref'`. Preact: `'@tsrx/preact/ref'`.
 		 */
 		mergeRefs?: string;
+		/**
+		 * Module to import named-ref-prop helpers from when compiling
+		 * `prop={ref expr}` or normalizing host spreads containing named refs.
+		 */
+		refProp?: string;
 	};
 
 	jsx: {
@@ -289,6 +327,12 @@ export interface JsxPlatform {
 		 *   unchanged. The platform's runtime is responsible.
 		 */
 		multiRefStrategy?: 'merge-refs' | 'array';
+		/**
+		 * Some JSX runtimes do not apply a `ref` that arrives through a props
+		 * spread. In that case, host spread normalization also emits an
+		 * explicit `ref={normalized.ref}` attribute.
+		 */
+		hostSpreadRefStrategy?: 'explicit-ref-attr';
 	};
 
 	validation: {

package/types/runtime/ref.d.ts

@@ -0,0 +1,32 @@
+export type MergeableRefCallback<T> = {
+	bivarianceHack(node: T | null): void | (() => void);
+}['bivarianceHack'];
+export type MergeableRefObject<T> = { current: T | null };
+export type MergeableVueRef<T> = { value: T | null };
+export type RefProp<T = unknown> = (node: T | null) => void | (() => void);
+
+export type MergeableRef<T> =
+	| MergeableRefCallback<T>
+	| MergeableRefObject<T>
+	| MergeableVueRef<T>
+	| null
+	| undefined;
+
+export function mergeRefs<T = any>(...refs: Array<MergeableRef<T>>): (node: T | null) => () => void;
+export function isRefProp(value: unknown): boolean;
+export function create_ref_prop<T>(
+	get_ref_value: () => T,
+	set_ref_value?: (value: T) => void,
+): RefProp<T>;
+export function apply_ref_value<T>(
+	ref_value: unknown,
+	node: T | null,
+	set_ref_value?: (value: T) => void,
+): void | (() => void);
+export function merge_ref_props<T = any>(
+	...refs: unknown[]
+): undefined | ((node: T | null) => void | (() => void));
+export function normalize_spread_props<T extends Record<PropertyKey, any> | null | undefined>(
+	props: T,
+	...outer_refs: unknown[]
+): T | Record<PropertyKey, any>;

package/src/runtime/merge-refs.js

@@ -1,61 +0,0 @@
-/**
- * Merge multiple refs (function refs and ref objects) into a single
- * callback ref. Used by the tsrx-react, tsrx-preact, and tsrx-vue
- * compilers when an element has more than one `ref` attribute, since
- * those runtimes treat duplicate `ref` props as a regular duplicate-prop
- * collision (last wins) rather than running both. Solid does not use this
- * helper — its native runtime accepts an array of refs and the compiler
- * emits an array literal directly.
- *
- * The returned callback ref handles four cases per input:
- * - `null` / `undefined`: skipped.
- * - function ref: invoked with the node. If it returns a function, that
- *   return value is treated as a React 19 cleanup. Otherwise we record a
- *   cleanup that calls the ref with `null` so the legacy unmount contract
- *   still fires.
- * - React-style ref object (`{ current }`): assigned on mount, cleared
- *   on unmount.
- * - Vue-style ref object (`{ value }`, e.g. `ref()` / `useTemplateRef()`):
- *   assigned on mount, cleared on unmount.
- *
- * The merged ref always returns a cleanup. Under React 19 the cleanup
- * runs on unmount and the inner refs are not separately re-invoked with
- * `null`. Under older React, Preact, and Vue the cleanup return value
- * is ignored, so the runtime instead invokes the merged ref a second
- * time with `null` — which re-runs the loop body, calling each inner
- * with `null` and clearing each ref object. Either way every inner ref
- * sees a balanced mount/unmount.
- *
- * @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 ('current' in ref) {
-				ref.current = node;
-				cleanups.push(() => {
-					ref.current = null;
-				});
-			} else if ('value' in ref) {
-				ref.value = node;
-				cleanups.push(() => {
-					ref.value = null;
-				});
-			}
-		}
-		return () => {
-			for (const cleanup of cleanups) cleanup();
-		};
-	};
-}

package/types/runtime/merge-refs.d.ts

@@ -1,12 +0,0 @@
-export type MergeableRefCallback<T> = (node: T | null) => void | (() => void);
-export type MergeableRefObject<T> = { current: T | null };
-export type MergeableVueRef<T> = { value: T | null };
-
-export type MergeableRef<T> =
-	| MergeableRefCallback<T>
-	| MergeableRefObject<T>
-	| MergeableVueRef<T>
-	| null
-	| undefined;
-
-export function mergeRefs<T = any>(...refs: Array<MergeableRef<T>>): (node: T | null) => () => void;