@tsrx/core 0.0.8 → 0.0.9

package/src/transform/scoping.js

@@ -1,8 +1,8 @@
 /**
  * Framework-agnostic CSS scoping utilities shared between the `@tsrx/react`
  * and `@tsrx/solid` transforms. These walk the template AST and annotate
- * `Element` nodes with a hash class so scope-qualified selectors
- * (e.g. `.foo.hash`) match after rendering.
+ * template nodes with a hash class so scope-qualified selectors (e.g.
+ * `.foo.hash`) match after rendering.
  */
 
 import { walk } from 'zimmerframe';
@@ -61,15 +61,42 @@ export function is_composite_element(node) {
 	return node.id.type === 'MemberExpression';
 }
 
+/**
+ * @param {any} node
+ * @returns {boolean}
+ */
+function is_style_jsx_element(node) {
+	const name = node?.openingElement?.name;
+	return node?.type === 'JSXElement' && name?.type === 'JSXIdentifier' && name.name === 'style';
+}
+
+/**
+ * @param {any} node
+ * @returns {boolean}
+ */
+function is_composite_jsx_element(node) {
+	const name = node?.openingElement?.name;
+	if (node?.type !== 'JSXElement' || !name) {
+		return false;
+	}
+
+	if (name.type === 'JSXIdentifier') {
+		return /^[A-Z]/.test(name.name);
+	}
+
+	return name.type === 'JSXMemberExpression';
+}
+
 /**
  * Recursively walk `Element` nodes within a component body and add the hash
  * class name so scope-qualified selectors (e.g. `.foo.hash`) match.
  *
  * @param {any} node
  * @param {string} hash
+ * @param {'class' | 'className'} [jsx_class_attr_name='class']
  * @returns {any}
  */
-export function annotate_with_hash(node, hash) {
+export function annotate_with_hash(node, hash, jsx_class_attr_name = 'class') {
 	if (!node || typeof node !== 'object') return node;
 	if (
 		node.type === 'Component' ||
@@ -87,7 +114,19 @@ export function annotate_with_hash(node, hash) {
 		if (Array.isArray(node.children)) {
 			node.children = node.children
 				.filter((/** @type {any} */ child) => !is_style_element(child))
-				.map((/** @type {any} */ child) => annotate_with_hash(child, hash));
+				.map((/** @type {any} */ child) => annotate_with_hash(child, hash, jsx_class_attr_name));
+		}
+		return node;
+	}
+
+	if (node.type === 'JSXElement') {
+		if (!is_style_jsx_element(node) && !is_composite_jsx_element(node)) {
+			add_hash_class_to_jsx_element(node, hash, jsx_class_attr_name);
+		}
+		if (Array.isArray(node.children)) {
+			node.children = node.children.map((/** @type {any} */ child) =>
+				annotate_with_hash(child, hash, jsx_class_attr_name),
+			);
 		}
 		return node;
 	}
@@ -99,9 +138,11 @@ export function annotate_with_hash(node, hash) {
 
 		const value = node[key];
 		if (Array.isArray(value)) {
-			node[key] = value.map((/** @type {any} */ child) => annotate_with_hash(child, hash));
+			node[key] = value.map((/** @type {any} */ child) =>
+				annotate_with_hash(child, hash, jsx_class_attr_name),
+			);
 		} else if (value && typeof value === 'object') {
-			node[key] = annotate_with_hash(value, hash);
+			node[key] = annotate_with_hash(value, hash, jsx_class_attr_name);
 		}
 	}
 
@@ -111,14 +152,15 @@ export function annotate_with_hash(node, hash) {
 /**
  * @param {any} component
  * @param {string} hash
+ * @param {'class' | 'className'} [jsx_class_attr_name='class']
  * @returns {void}
  */
-export function annotate_component_with_hash(component, hash) {
+export function annotate_component_with_hash(component, hash, jsx_class_attr_name = 'class') {
 	/** @type {any[]} */
 	const body = component.body;
 	component.body = body
 		.filter((/** @type {any} */ child) => !is_style_element(child))
-		.map((/** @type {any} */ child) => annotate_with_hash(child, hash));
+		.map((/** @type {any} */ child) => annotate_with_hash(child, hash, jsx_class_attr_name));
 }
 
 /**
@@ -178,3 +220,73 @@ export function add_hash_class(element, hash) {
 		],
 	};
 }
+
+/**
+ * @param {any} element
+ * @param {string} hash
+ * @param {'class' | 'className'} jsx_class_attr_name
+ * @returns {void}
+ */
+function add_hash_class_to_jsx_element(element, hash, jsx_class_attr_name) {
+	const attrs = element.openingElement?.attributes || (element.openingElement.attributes = []);
+	const existing = attrs.find(
+		(/** @type {any} */ attr) =>
+			attr?.type === 'JSXAttribute' &&
+			attr.name?.type === 'JSXIdentifier' &&
+			(attr.name.name === 'class' || attr.name.name === 'className'),
+	);
+
+	if (!existing) {
+		attrs.push({
+			type: 'JSXAttribute',
+			name: { type: 'JSXIdentifier', name: jsx_class_attr_name, metadata: { path: [] } },
+			value: { type: 'Literal', value: hash, raw: JSON.stringify(hash) },
+			shorthand: false,
+			metadata: { path: [] },
+		});
+		return;
+	}
+
+	if (existing.name.name !== jsx_class_attr_name) {
+		existing.name = {
+			type: 'JSXIdentifier',
+			name: jsx_class_attr_name,
+			metadata: existing.name.metadata || { path: [] },
+		};
+	}
+
+	const value = existing.value;
+	if (!value) {
+		existing.value = { type: 'Literal', value: hash, raw: JSON.stringify(hash) };
+		return;
+	}
+
+	if (value.type === 'Literal' && typeof value.value === 'string') {
+		const merged = `${value.value} ${hash}`;
+		existing.value = { type: 'Literal', value: merged, raw: JSON.stringify(merged) };
+		return;
+	}
+
+	const expression = value.type === 'JSXExpressionContainer' ? value.expression : value;
+	existing.value = {
+		type: 'JSXExpressionContainer',
+		expression: {
+			type: 'TemplateLiteral',
+			expressions: [expression],
+			quasis: [
+				{
+					type: 'TemplateElement',
+					value: { raw: '', cooked: '' },
+					tail: false,
+				},
+				{
+					type: 'TemplateElement',
+					value: { raw: ` ${hash}`, cooked: ` ${hash}` },
+					tail: true,
+				},
+			],
+			metadata: { path: [] },
+		},
+		metadata: { path: [] },
+	};
+}

package/src/transform/segments.js

@@ -52,7 +52,6 @@ import {
 	mapping_data_verify_complete,
 	build_line_offsets,
 	get_mapping_from_node,
-	maybe_get_mapping_from_node,
 } from '../source-map-utils.js';
 
 const LABEL_TO_COMPONENT_REPLACE_REGEX = /(function|\((property|method)\))/;
@@ -670,21 +669,9 @@ export function convert_source_map_to_mappings(
 				return;
 			} else if (node.type === 'JSXExpressionContainer') {
 				if (node.loc) {
-					// Use maybe_get_mapping_from_node because a transform may set the
-					// container's loc to the source range of the original `{...}`
-					// construct (e.g. a Ripple TSRXExpression or Text node), while
-					// esrap only emits a segment for the inner expression. In that
-					// case the container's start/end won't resolve — skip rather
-					// than hard-failing, and rely on the inner expression's mapping.
-					const mapping = maybe_get_mapping_from_node(
-						node,
-						src_to_gen_map,
-						gen_line_offsets,
-						mapping_data_verify_only,
+					mappings.push(
+						get_mapping_from_node(node, src_to_gen_map, gen_line_offsets, mapping_data_verify_only),
 					);
-					if (!(mapping instanceof Error)) {
-						mappings.push(mapping);
-					}
 				}
 				// Visit the expression inside {}
 				if (node.expression) {
@@ -742,36 +729,22 @@ export function convert_source_map_to_mappings(
 
 				if ((closing?.loc || opening.loc) && (closing || opening.selfClosing)) {
 					// Add the whole closing tag or the self-closing.
-					// For self-closing elements, use maybe_get_mapping_from_node because
-					// attribute transforms (e.g. class→className, {ref fn}→ref={fn}) can shift
-					// the position of `/>` in the generated output, making the source map
-					// entry for the opening element's end position unresolvable.
 					const target_node = closing ? closing : opening;
-					const mapping = closing
-						? get_mapping_from_node(
-								target_node,
-								src_to_gen_map,
-								gen_line_offsets,
-								mapping_data_verify_only,
-							)
-						: maybe_get_mapping_from_node(
-								target_node,
-								src_to_gen_map,
-								gen_line_offsets,
-								mapping_data_verify_only,
-							);
-
-					if (!(mapping instanceof Error)) {
-						// The generated code includes a semicolon after the closing or self-closed tag
-						// We're extending the mapping to include the semicolon
-						// because the diagnostics errors can include the whole element
-						// and we need to account for the semicolon as it's a part of the diagnostic
-						// At the same time, we could've instead applied this logic to the whole `node` element
-						// 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];
-						mappings.push(mapping);
-					}
+					const mapping = get_mapping_from_node(
+						target_node,
+						src_to_gen_map,
+						gen_line_offsets,
+						mapping_data_verify_only,
+					);
+					// The generated code includes a semicolon after the closing or self-closed tag
+					// We're extending the mapping to include the semicolon
+					// because the diagnostics errors can include the whole element
+					// and we need to account for the semicolon as it's a part of the diagnostic
+					// At the same time, we could've instead applied this logic to the whole `node` element
+					// 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];
+					mappings.push(mapping);
 				}
 
 				if (closing) {
@@ -1621,7 +1594,7 @@ export function convert_source_map_to_mappings(
 					// Generic spans can be emitted by downstream transforms with sparse source-map
 					// coverage around the angle-bracket delimiters. Skip missing whole-node mappings
 					// instead of crashing Volar, and rely on child type-node mappings instead.
-					const mapping = maybe_get_mapping_from_node(
+					const mapping = get_mapping_from_node(
 						node,
 						src_to_gen_map,
 						gen_line_offsets,
@@ -2070,6 +2043,15 @@ export function convert_source_map_to_mappings(
 					visit(node.typeArguments);
 				}
 				return;
+			} else if (node.type === 'TSTypePredicate') {
+				// Type predicate: `x is T` / `asserts x is T` / `asserts x`
+				if (node.parameterName) {
+					visit(node.parameterName);
+				}
+				if (node.typeAnnotation) {
+					visit(node.typeAnnotation);
+				}
+				return;
 			}
 
 			throw new Error(`Unhandled AST node type in mapping walker: ${node.type}`);

package/types/index.d.ts

@@ -5,8 +5,16 @@ import type { Parse } from './parse.js';
 import type * as ESRap from 'esrap';
 import type { Position } from 'acorn';
 import type { RequireAllOrNone } from '../src/helpers.js';
+import type {
+	JsxPlatform,
+	JsxPlatformHooks,
+	JsxTransformOptions,
+	JsxTransformResult,
+	createJsxTransform,
+} from './jsx-platform';
 
-export type { Parse };
+export type { Parse, JsxPlatform, JsxPlatformHooks, JsxTransformOptions, JsxTransformResult };
+export { createJsxTransform };
 
 /**
  * Compile error interface
@@ -76,7 +84,7 @@ interface FunctionLikeTS {
 	typeAnnotation?: AST.TSTypeAnnotation;
 }
 
-// Ripple augmentation for ESTree function nodes
+// TSRX augmentation for ESTree function nodes
 declare module 'estree' {
 	interface Program {
 		innerComments?: Comment[] | undefined;
@@ -164,7 +172,7 @@ declare module 'estree' {
 		was_expression?: boolean;
 	}
 
-	// Include TypeScript node types and Ripple-specific nodes in NodeMap
+	// Include TypeScript node types and TSRX-specific nodes in NodeMap
 	interface NodeMap {
 		Component: Component;
 		Tsx: Tsx;
@@ -291,7 +299,7 @@ declare module 'estree' {
 	}
 
 	/**
-	 * Ripple custom interfaces and types section
+	 * TSRX custom interfaces and types section
 	 */
 	interface Component extends AST.BaseNode {
 		type: 'Component';
@@ -398,7 +406,7 @@ declare module 'estree' {
 	}
 
 	/**
-	 * Ripple attribute nodes
+	 * TSRX attribute nodes
 	 */
 	interface Attribute extends AST.BaseNode {
 		type: 'Attribute';
@@ -424,20 +432,20 @@ declare module 'estree' {
 	}
 
 	/**
-	 * Ripple's extended Declaration type that includes Component
+	 * TSRX's extended Declaration type that includes Component
 	 * Use this instead of Declaration when you need Component support
 	 */
 	export type TSRXDeclaration = AST.Declaration | Component | AST.TSDeclareFunction;
 
 	/**
-	 * Ripple's extended ExportNamedDeclaration with Component support
+	 * TSRX's extended ExportNamedDeclaration with Component support
 	 */
 	interface TSRXExportNamedDeclaration extends Omit<AST.ExportNamedDeclaration, 'declaration'> {
 		declaration?: TSRXDeclaration | null | undefined;
 	}
 
 	/**
-	 * Ripple's extended Program with Component support
+	 * TSRX's extended Program with Component support
 	 */
 	interface TSRXProgram extends Omit<Program, 'body'> {
 		body: (Program['body'][number] | Component | FunctionExpression)[];
@@ -1046,7 +1054,13 @@ declare module 'estree' {
 	> {
 		params: TypeNode[];
 	}
-	interface TSTypePredicate extends AcornTSNode<TSESTree.TSTypePredicate> {}
+	interface TSTypePredicate extends Omit<
+		AcornTSNode<TSESTree.TSTypePredicate>,
+		'parameterName' | 'typeAnnotation'
+	> {
+		parameterName: AST.Identifier | AST.TSThisType;
+		typeAnnotation: AST.TSTypeAnnotation | null;
+	}
 	interface TSTypeQuery extends Omit<
 		AcornTSNode<TSESTree.TSTypeQuery>,
 		'exprName' | 'typeArguments'
@@ -1148,7 +1162,7 @@ export interface AnalysisResult {
 }
 
 /**
- * Configuration for Ripple parser plugin
+ * Configuration for the TSRX parser plugin
  */
 export interface TSRXPluginConfig {
 	allowSatisfies?: boolean;

package/types/jsx-platform.d.ts

@@ -0,0 +1,193 @@
+import type * as AST from 'estree';
+import type { RawSourceMap } from 'source-map';
+
+/**
+ * Result returned by a JSX platform transform (React, Preact, Solid).
+ */
+export interface JsxTransformResult {
+	ast: AST.Program;
+	code: string;
+	/**
+	 * Esrap-shaped source map over the generated TSX. Consumed by
+	 * `create_volar_mappings_result` to build Volar code mappings and by
+	 * downstream Vite / Rollup plugins to chain source maps.
+	 */
+	map: RawSourceMap;
+	css: { code: string; hash: string } | null;
+}
+
+/**
+ * Optional per-call compile options passed to a created JSX transform.
+ */
+export interface JsxTransformOptions {
+	/**
+	 * Override the import source used for `Suspense` in try-block transforms.
+	 * Falls back to `platform.imports.suspense`. Preact uses this to let the
+	 * host pick `preact/compat` vs. another compat entry point.
+	 */
+	suspenseSource?: string;
+}
+
+/**
+ * Override hooks for the parts of the transform that differ substantially
+ * between platforms. Every hook is optional — when omitted, the factory
+ * uses its React/Preact-style default.
+ *
+ * Solid uses all of these: control-flow statements become `<Show>` /
+ * `<For>` / `<Switch>/<Match>` / `<Errored>/<Loading>` JSX; component
+ * bodies are hoisted to preserve setup-once semantics; module imports
+ * come from `solid-js` instead of `react`; element attributes support
+ * composite-element / textContent shortcuts.
+ *
+ * The `ctx` parameter is the active `TransformContext` — see the
+ * target's transform.js for its shape; platform-owned fields can be
+ * read and written freely.
+ */
+export interface JsxPlatformHooks {
+	/**
+	 * Per-statement control-flow rewrites. Each hook receives the original
+	 * Ripple statement (with children already walked) and returns a JSX
+	 * child (or an expression container wrapping one).
+	 */
+	controlFlow?: {
+		ifStatement?: (node: any, ctx: any) => any;
+		forOf?: (node: any, ctx: any) => any;
+		switchStatement?: (node: any, ctx: any) => any;
+		tryStatement?: (node: any, ctx: any) => any;
+	};
+	/**
+	 * Lower a `component` declaration to a FunctionDeclaration. React / Preact
+	 * use a default that extracts hooks, hoists statics, and handles async
+	 * bodies. Solid replaces this with a setup-once implementation that
+	 * hoists post-early-return JSX into a reactive `<Show>`.
+	 */
+	componentToFunction?: (component: any, ctx: any, helperState?: any) => any;
+	/**
+	 * Inject module-level imports after the main walk. Default: import
+	 * `Suspense` from `platform.imports.suspense` and `TsrxErrorBoundary`
+	 * from `platform.imports.errorBoundary` if the walk flagged them.
+	 * Solid injects `Show`, `For`, `Switch`, `Match`, `Errored`, `Loading`
+	 * from `solid-js`.
+	 */
+	injectImports?: (program: AST.Program, ctx: any, suspenseSource: string) => void;
+	/**
+	 * Transform a Ripple element's attributes to JSX attributes. Default
+	 * is "map over `to_jsx_attribute`". Solid replaces this to route
+	 * attributes through its composite-element handling.
+	 */
+	transformElementAttributes?: (attrs: any[], ctx: any, element: any) => any[];
+	/**
+	 * Lower a Ripple `Element` node to a JSXElement. Default is the
+	 * factory's `to_jsx_element`. The hook receives the walker-transformed
+	 * node (`inner`, with children already lowered) plus the element's
+	 * raw pre-walk children — Solid uses the latter to detect a lone
+	 * `Text` child it can hoist to a `textContent` attribute before the
+	 * generic text→JSXExpressionContainer transform runs.
+	 */
+	transformElement?: (inner: any, ctx: any, rawChildren: any[]) => any;
+	/**
+	 * Custom validation for a component body that uses top-level `await`.
+	 * Default: enforce `validation.requireUseServerForAwait`. Solid rejects
+	 * component-level await outright with a keyword-precise location.
+	 */
+	validateComponentAwait?: (
+		awaitNode: any,
+		component: any,
+		ctx: any,
+		moduleUsesServerDirective: boolean,
+		source: string,
+	) => void;
+	/**
+	 * Factory-managed state extra fields. Returns a record merged into the
+	 * initial `transform_context`. Lets solid seed its `needs_show` /
+	 * `needs_for` / etc. flags without forking the factory.
+	 */
+	initialState?: () => Record<string, unknown>;
+}
+
+/**
+ * A JSX platform descriptor is the parameter to `createJsxTransform`. It
+ * declares how to render a Ripple AST as valid TSX for the target platform
+ * (React, Preact, Solid). The shared transformer in `@tsrx/core` reads this
+ * descriptor at each platform-specific decision point instead of branching
+ * on the platform name.
+ */
+export interface JsxPlatform {
+	/**
+	 * Human-readable platform name, used in error messages
+	 * (e.g. "React TSRX does not support …").
+	 */
+	name: string;
+
+	imports: {
+		/**
+		 * Module to import `Suspense` from when a `try { ... } pending { ... }`
+		 * block appears. React: `'react'`. Preact: `'preact/compat'`.
+		 */
+		suspense: string;
+		/**
+		 * Module to import `TsrxErrorBoundary` from when a `try { ... } catch (...)`
+		 * block appears. Usually `'@tsrx/<platform>/error-boundary'`.
+		 */
+		errorBoundary: string;
+	};
+
+	jsx: {
+		/**
+		 * Rewrite Ripple's `class` attribute to React's `className`. React: true.
+		 * Preact and Solid accept `class` natively, so: false.
+		 */
+		rewriteClassAttr: boolean;
+		/**
+		 * Accepted values of `kind` in `<tsx:kind>` compat blocks. React accepts
+		 * only `'react'`. Preact accepts both `'preact'` and `'react'`.
+		 */
+		acceptedTsxKinds: readonly string[];
+	};
+
+	validation: {
+		/**
+		 * Require a top-level `"use server"` directive before a component may
+		 * contain top-level `await`. Preact/Solid: true. React: false.
+		 *
+		 * Solid keeps this enabled as a fallback invariant (if its custom await
+		 * validator hook is removed, the default factory validation still rejects
+		 * component-level `await` without `"use server"`).
+		 */
+		requireUseServerForAwait: boolean;
+		/**
+		 * When `false`, skip scanning for a top-level `"use server"` directive
+		 * while a custom `validateComponentAwait` hook is present.
+		 *
+		 * This is useful for platforms whose custom validator never uses the
+		 * directive signal (for example Solid, which always rejects component-level
+		 * `await`), while still keeping `requireUseServerForAwait: true` as a
+		 * fallback if the custom validator is removed.
+		 *
+		 * Default: `true`.
+		 */
+		scanUseServerDirectiveForAwaitWithCustomValidator?: boolean;
+	};
+
+	/**
+	 * Optional overrides for parts of the transform that diverge substantially
+	 * between platforms (control flow, component lowering, imports, element
+	 * attributes). When absent, each hook falls back to the React/Preact-style
+	 * default baked into the factory.
+	 */
+	hooks?: JsxPlatformHooks;
+}
+
+/**
+ * Build a `transform()` function for a specific JSX platform. The returned
+ * function takes a parsed Ripple AST and produces a TSX module plus source
+ * map and optional CSS.
+ */
+export function createJsxTransform(
+	platform: JsxPlatform,
+): (
+	ast: AST.Program,
+	source: string,
+	filename?: string,
+	options?: JsxTransformOptions,
+) => JsxTransformResult;

package/types/parse.d.ts

@@ -1,8 +1,8 @@
 /**
- * Type definitions for Ripple's extended Acorn parser
+ * Type definitions for TSRX's extended Acorn parser
  *
  * These types cover internal properties and static class members that aren't
- * included in Acorn's official type definitions but are used by Ripple's parser.
+ * included in Acorn's official type definitions but are used by the TSRX parser.
  *
  * Based on acorn source code: https://github.com/acornjs/acorn
  * and @sveltejs/acorn-typescript: https://github.com/sveltejs/acorn-typescript
@@ -433,7 +433,7 @@ export namespace Parse {
 	 * Extended Parser instance with internal properties
 	 *
 	 * These properties are used internally by Acorn but not exposed in official types.
-	 * They are accessed by Ripple's custom parser plugin for whitespace handling,
+	 * They are accessed by the TSRX parser plugin for whitespace handling,
 	 * JSX parsing, and other advanced features.
 	 */
 	export interface Parser {
@@ -1705,7 +1705,7 @@ export namespace Parse {
 	}
 
 	/**
-	 * The constructor/class type for the extended Ripple parser.
+	 * The constructor/class type for the extended TSRX parser.
 	 * This represents the static side of the parser class after extending with plugins.
 	 */
 	export interface ParserConstructor {
@@ -1716,7 +1716,7 @@ export namespace Parse {
 		tokContexts: TokContexts;
 		/** TypeScript extensions when using acorn-typescript */
 		acornTypeScript: AcornTypeScriptExtensions;
-		/** Static parse method that returns Ripple's extended Program type */
+		/** Static parse method that returns TSRX's extended Program type */
 		parse(input: string, options: Options): AST.Program;
 		/** Static parseExpressionAt method */
 		parseExpressionAt(input: string, pos: number, options: Options): AST.Expression;