@tsrx/core 0.0.8 → 0.0.9

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,7 +26,9 @@
     },
     "./types/acorn": {
       "types": "./types/acorn.d.ts"
-    }
+    },
+    "./test-harness/source-mappings": "./tests/shared/source-mappings.js",
+    "./test-harness/compile": "./tests/shared/compile.js"
   },
   "dependencies": {
     "@jridgewell/sourcemap-codec": "^1.5.5",

package/src/index.js

@@ -131,6 +131,28 @@ export { sanitize_template_string as sanitizeTemplateString } from './utils/sani
 export { escape } from './utils/escaping.js';
 
 // Transform
+export { createJsxTransform } from './transform/jsx/index.js';
+export {
+	ensure_function_metadata as ensureFunctionMetadata,
+	in_jsx_child_context as inJsxChildContext,
+	tsx_node_to_jsx_expression as tsxNodeToJsxExpression,
+	tsx_with_ts_locations as tsxWithTsLocations,
+} from './transform/jsx/helpers.js';
+export {
+	clone_expression_node,
+	clone_identifier,
+	clone_jsx_name,
+	create_compile_error,
+	create_generated_identifier,
+	create_null_literal,
+	flatten_switch_consequent,
+	get_for_of_iteration_params,
+	identifier_to_jsx_name,
+	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 {
 	prepare_stylesheet_for_render as prepareStylesheetForRender,

package/src/plugin.js

@@ -1006,7 +1006,7 @@ export function TSRXPlugin(config) {
 					if (this.type === tt.braceR) {
 						this.raise(
 							this.start,
-							'"html" is a Ripple keyword and must be used in the form {html some_content}',
+							'"html" is a TSRX keyword and must be used in the form {html some_content}',
 						);
 					}
 				} else if (this.type === tt.name && this.value === 'text') {
@@ -1015,7 +1015,7 @@ export function TSRXPlugin(config) {
 					if (this.type === tt.braceR) {
 						this.raise(
 							this.start,
-							'"text" is a Ripple keyword and must be used in the form {text some_value}',
+							'"text" is a TSRX keyword and must be used in the form {text some_value}',
 						);
 					}
 				}

package/src/source-map-utils.js

@@ -278,6 +278,8 @@ export function build_line_offsets(text) {
 }
 
 /**
+ * DO NOT EXPORT THIS FUNCTION!
+ * THE FIX NEEDS TO HAPPEN IN THE TRANSFORMER, SEGMENTS OR PARSER
  * @param {AST.Node | AST.NodeWithLocation} node
  * @param {CodeToGeneratedMap} src_to_gen_map
  * @param {number[]} gen_line_offsets
@@ -286,7 +288,7 @@ export function build_line_offsets(text) {
  * @param {number} [gen_max_len]
  * @returns {CodeMapping | Error}
  */
-export function maybe_get_mapping_from_node(
+function __maybe_get_mapping_from_node(
 	node,
 	src_to_gen_map,
 	gen_line_offsets,
@@ -341,7 +343,7 @@ export function get_mapping_from_node(
 	src_max_len,
 	gen_max_len,
 ) {
-	const mapping = maybe_get_mapping_from_node(
+	const mapping = __maybe_get_mapping_from_node(
 		node,
 		src_to_gen_map,
 		gen_line_offsets,

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

@@ -0,0 +1,321 @@
+/** @import * as AST from 'estree' */
+/** @import * as ESTreeJSX from 'estree-jsx' */
+
+import { set_location } from '../../utils/builders.js';
+
+/**
+ * AST-building utilities shared across every JSX target (React, Preact,
+ * Solid). These are pure, platform-agnostic helpers — anything that ends up
+ * branching on target semantics belongs elsewhere.
+ */
+
+/**
+ * Attach `source_node`'s `loc` to `node` (deep), defaulting `node.metadata`
+ * so downstream walks / serializers don't trip on it being undefined.
+ *
+ * @template T
+ * @param {T} node
+ * @param {any} source_node
+ * @returns {T}
+ */
+export function set_loc(node, source_node) {
+	/** @type {any} */ (node).metadata ??= { path: [] };
+	if (source_node?.loc) {
+		return /** @type {T} */ (set_location(/** @type {any} */ (node), source_node, true));
+	}
+	return node;
+}
+
+/**
+ * Shallow-clone an Identifier (keeps name, copies loc via `set_loc`, fresh
+ * metadata). Used when the same identifier must appear in both a declaration
+ * and a reference without sharing mutable metadata.
+ *
+ * @param {AST.Identifier} identifier
+ * @returns {AST.Identifier}
+ */
+export function clone_identifier(identifier) {
+	return set_loc(
+		/** @type {any} */ ({
+			type: 'Identifier',
+			name: identifier.name,
+			metadata: { path: [] },
+		}),
+		identifier,
+	);
+}
+
+/**
+ * Clone a JSX element name (handles `JSXIdentifier`, `JSXMemberExpression`,
+ * and plain `Identifier`).
+ *
+ * @param {any} name
+ * @param {any} [source_node]
+ * @returns {any}
+ */
+export function clone_jsx_name(name, source_node = name) {
+	if (!name) return name;
+	if (name.type === 'JSXIdentifier') {
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXIdentifier',
+				name: name.name,
+				metadata: name.metadata || { path: [] },
+			}),
+			source_node,
+		);
+	}
+	if (name.type === 'JSXMemberExpression') {
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXMemberExpression',
+				object: clone_jsx_name(name.object, source_node.object || name.object),
+				property: clone_jsx_name(name.property, source_node.property || name.property),
+				metadata: name.metadata || { path: [] },
+			}),
+			source_node,
+		);
+	}
+	if (name.type === 'Identifier') {
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXIdentifier',
+				name: name.name,
+				metadata: name.metadata || { path: [] },
+			}),
+			source_node,
+		);
+	}
+	return name;
+}
+
+/**
+ * @returns {AST.Literal}
+ */
+export function create_null_literal() {
+	return /** @type {any} */ ({
+		type: 'Literal',
+		value: null,
+		raw: 'null',
+		metadata: { path: [] },
+	});
+}
+
+/**
+ * @param {string} name
+ * @returns {AST.Identifier}
+ */
+export function create_generated_identifier(name) {
+	return /** @type {any} */ ({
+		type: 'Identifier',
+		name,
+		metadata: { path: [] },
+	});
+}
+
+/**
+ * @param {any} node
+ * @param {string} message
+ * @returns {Error & { pos: number, end: number }}
+ */
+export function create_compile_error(node, message) {
+	const error = /** @type {Error & { pos: number, end: number }} */ (new Error(message));
+	error.pos = node.start ?? 0;
+	error.end = node.end ?? error.pos + 1;
+	return error;
+}
+
+/**
+ * Convert an Identifier / MemberExpression into a JSX element name. The
+ * top-level `Identifier` → `JSXIdentifier` case flags capitalised names as
+ * `is_component` so `segments.js` can extend the JSX element name's source
+ * mapping backwards to cover the `component ` keyword and attach the
+ * component hover label — without that flag those source-map adjustments
+ * and editor hover features silently drop for any composite element.
+ *
+ * @param {any} id
+ * @returns {any}
+ */
+export function identifier_to_jsx_name(id) {
+	if (!id) return id;
+	if (id.type === 'Identifier') {
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXIdentifier',
+				name: id.name,
+				metadata: { path: [], is_component: /^[A-Z]/.test(id.name) },
+			}),
+			id,
+		);
+	}
+	if (id.type === 'MemberExpression') {
+		return set_loc(
+			/** @type {any} */ ({
+				type: 'JSXMemberExpression',
+				object: identifier_to_jsx_name(id.object),
+				property: identifier_to_jsx_name(id.property),
+				metadata: id.metadata || { path: [] },
+			}),
+			id,
+		);
+	}
+	return id;
+}
+
+/**
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function is_jsx_child(node) {
+	if (!node) return false;
+	const t = node.type;
+	return (
+		t === 'JSXElement' ||
+		t === 'JSXFragment' ||
+		t === 'JSXExpressionContainer' ||
+		t === 'JSXText' ||
+		t === 'Tsx' ||
+		t === 'TsxCompat' ||
+		t === 'Element' ||
+		t === 'Text' ||
+		t === 'TSRXExpression' ||
+		t === 'Html' ||
+		t === 'IfStatement' ||
+		t === 'ForOfStatement' ||
+		t === 'SwitchStatement' ||
+		t === 'TryStatement'
+	);
+}
+
+/**
+ * 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.
+ *
+ * @param {any} id
+ * @returns {boolean}
+ */
+export function is_dynamic_element_id(id) {
+	if (!id || typeof id !== 'object') {
+		return false;
+	}
+	if (id.type === 'Identifier') {
+		return !!id.tracked;
+	}
+	if (id.type === 'MemberExpression') {
+		return is_dynamic_element_id(id.object);
+	}
+	return false;
+}
+
+/**
+ * Gather the params a `for (x of y; index i)` loop should expose to its body
+ * JSX (value first, optional index second).
+ *
+ * @param {any} left
+ * @param {any} [index]
+ * @returns {any[]}
+ */
+export function get_for_of_iteration_params(left, index) {
+	/** @type {any[]} */
+	const params = [];
+	if (left?.type === 'VariableDeclaration' && left.declarations?.[0]) {
+		params.push(left.declarations[0].id);
+	} else {
+		params.push(left);
+	}
+	if (index) {
+		params.push(index);
+	}
+	return params;
+}
+
+/**
+ * Flatten a switch case's `consequent` so statements inside a top-level
+ * `BlockStatement` are treated as siblings of statements declared directly
+ * under the case. This lets `case` arms use `{ ... }` for readability
+ * without the block becoming a fresh scope at the JSX level.
+ *
+ * @param {any[]} consequent
+ * @returns {any[]}
+ */
+export function flatten_switch_consequent(consequent) {
+	const result = [];
+	for (const node of consequent) {
+		if (node.type === 'BlockStatement') {
+			result.push(...node.body);
+		} else {
+			result.push(node);
+		}
+	}
+	return result;
+}
+
+/**
+ * Build `expr == null ? '' : expr + ''` — the text-coerce form used when a
+ * Ripple `{expr}` child must render as a string in JSX (React/Preact drop
+ * booleans; Solid's default child semantics don't either). Solid uses this
+ * via `to_jsx_child`; React/Preact wrap it in a JSXExpressionContainer.
+ *
+ * @param {AST.Expression} expression
+ * @param {any} [source_node]
+ * @returns {AST.Expression}
+ */
+export function to_text_expression(expression, source_node = expression) {
+	return set_loc(
+		/** @type {AST.Expression} */ ({
+			type: 'ConditionalExpression',
+			test: {
+				type: 'BinaryExpression',
+				operator: '==',
+				left: clone_expression_node(expression),
+				right: create_null_literal(),
+				metadata: { path: [] },
+			},
+			consequent: {
+				type: 'Literal',
+				value: '',
+				raw: "''",
+				metadata: { path: [] },
+			},
+			alternate: {
+				type: 'BinaryExpression',
+				operator: '+',
+				left: clone_expression_node(expression),
+				right: {
+					type: 'Literal',
+					value: '',
+					raw: "''",
+					metadata: { path: [] },
+				},
+				metadata: { path: [] },
+			},
+			metadata: { path: [] },
+		}),
+		source_node,
+	);
+}
+
+/**
+ * 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.
+ *
+ * @param {any} node
+ * @returns {any}
+ */
+export function clone_expression_node(node) {
+	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 (key === 'metadata') {
+			clone.metadata = clone.metadata ? { ...clone.metadata } : { path: [] };
+			continue;
+		}
+		clone[key] = clone_expression_node(clone[key]);
+	}
+	return clone;
+}

package/src/transform/jsx/helpers.js

@@ -0,0 +1,131 @@
+/** @import * as AST from 'estree' */
+/** @import { Visitors } from 'zimmerframe' */
+
+import tsx from 'esrap/languages/tsx';
+
+/**
+ * Zimmerframe provides `path` as the ancestor chain (in original pre-transform
+ * types, since visitors run bottom-up). A Tsx node whose parent is a ripple
+ * `Element` will render as a JSX child of that element; anywhere else it
+ * renders as a standalone expression (e.g. a return value).
+ *
+ * @param {any[]} path
+ * @returns {boolean}
+ */
+export function in_jsx_child_context(path) {
+	const parent = path[path.length - 1];
+	return !!parent && parent.type === 'Element';
+}
+
+/**
+ * Flatten a `<tsx>` / fragment node's children into a single expression. In a
+ * JSX-child position, a JSXExpressionContainer `{expr}` is valid and must stay
+ * wrapped. In an expression position (e.g. `return ...`), `{expr}` parses as
+ * a block/object literal, so unwrap to `expr`.
+ *
+ * @param {any} node
+ * @param {boolean} [in_jsx_child]
+ * @returns {any}
+ */
+export function tsx_node_to_jsx_expression(node, in_jsx_child = false) {
+	const children = (node.children || []).filter(
+		(/** @type {any} */ child) => child.type !== 'JSXText' || child.value.trim() !== '',
+	);
+
+	if (children.length === 1 && children[0].type !== 'JSXText') {
+		const only = children[0];
+		if (only.type === 'JSXExpressionContainer' && !in_jsx_child) {
+			return only.expression;
+		}
+		return only;
+	}
+
+	return /** @type {any} */ ({
+		type: 'JSXFragment',
+		openingFragment: { type: 'JSXOpeningFragment', metadata: { path: [] } },
+		closingFragment: { type: 'JSXClosingFragment', metadata: { path: [] } },
+		children,
+		metadata: { path: [] },
+	});
+}
+
+/**
+ * Default `node.metadata` to `{ path: [] }` if missing, then continue the
+ * walk. Use as the `FunctionDeclaration` / `FunctionExpression` /
+ * `ArrowFunctionExpression` visitor in a zimmerframe walk so that downstream
+ * consumers (e.g. `segments.js` reading `node.value.metadata.is_component`
+ * on class methods) don't trip on an undefined metadata object.
+ *
+ * Ripple's analyze phase does this via `visit_function`; the tsrx-* targets
+ * have no analyze phase, so we default metadata during the main walk.
+ *
+ * @param {any} node
+ * @param {{ next: () => any }} ctx
+ */
+export function ensure_function_metadata(node, { next }) {
+	if (!node.metadata) {
+		node.metadata = { path: [] };
+	}
+	return next();
+}
+
+/**
+ * Wrap esrap's `tsx()` printer with location markers for nodes whose spans
+ * (e.g. the leading `new ` of a NewExpression or the angle-bracket delimiters
+ * around generic arguments) are otherwise invisible to the source map.
+ * Without these markers, Volar mapping collection in `segments.js` throws
+ * when looking up the node's start/end positions.
+ *
+ * Shared across all JSX-producing targets (React, Preact, Solid).
+ *
+ * @returns {any}
+ */
+export function tsx_with_ts_locations() {
+	const base = /** @type {any} */ (tsx());
+
+	/**
+	 * @param {any} node
+	 * @param {any} context
+	 * @param {any} visitor
+	 */
+	const wrap_with_locations = (node, context, visitor) => {
+		if (!node.loc) {
+			visitor(node, context);
+			return;
+		}
+		context.location(node.loc.start.line, node.loc.start.column);
+		visitor(node, context);
+		context.location(node.loc.end.line, node.loc.end.column);
+	};
+
+	/** @type {Record<string, (node: any, context: any) => void>} */
+	const wrappers = {};
+	for (const type of [
+		// JS nodes whose esrap printer emits no location marker, causing
+		// segments.js get_mapping_from_node() to throw when it asks for the
+		// generated position of the node's start (or end).
+		'NewExpression',
+		'MemberExpression',
+		'ObjectExpression',
+		'ReturnStatement',
+		'ForStatement',
+		'ForInStatement',
+		'TemplateLiteral',
+		'AwaitExpression',
+		'TaggedTemplateExpression',
+		// JSX wrapper nodes: esrap writes `<`, `>`, `</`, `{`, `}` without
+		// locations, so the opening/closing element's and expression
+		// container's start and end don't resolve.
+		'JSXOpeningElement',
+		'JSXClosingElement',
+		'JSXExpressionContainer',
+		// TS wrapper nodes with the same issue.
+		'TSTypeParameterInstantiation',
+		'TSTypeParameterDeclaration',
+		'TSTypeParameter',
+	]) {
+		wrappers[type] = (node, context) => wrap_with_locations(node, context, base[type]);
+	}
+
+	return { ...base, ...wrappers };
+}