@tsrx/core 0.1.45 → 0.1.47

package/types/index.d.ts

@@ -24,11 +24,23 @@ export type {
 };
 export { createJsxTransform };
 
-export function collectStyleRefAttributes(node: any, refs?: any[]): any[];
-export function createStyleClassMap(component: any, css: any): AST.ObjectExpression;
-export function createStyleClassMapFromStylesheet(css: any): AST.ObjectExpression;
+/** Result of extracting a branch body into a generated helper component. */
+export interface JsxHelperComponent {
+	setup_statements: AST.Statement[];
+	component_element: ESTreeJSX.JSXElement;
+}
+
+export function collectStyleRefAttributes(
+	node: AST.Node | AST.Node[],
+	refs?: ESTreeJSX.JSXAttribute[],
+): ESTreeJSX.JSXAttribute[];
+export function createStyleClassMap(
+	component: AST.Node,
+	css: AST.CSS.StyleSheet,
+): AST.ObjectExpression;
+export function createStyleClassMapFromStylesheet(css: AST.CSS.StyleSheet): AST.ObjectExpression;
 export function createStyleRefSetupStatements(
-	refAttributes: any[],
+	refAttributes: ESTreeJSX.JSXAttribute[],
 	styleMap: AST.Expression,
 	options?: {
 		allowMutableRefTarget?: boolean;
@@ -36,7 +48,9 @@ export function createStyleRefSetupStatements(
 		visitExpression?: (expression: AST.Expression) => AST.Expression;
 	},
 ): AST.Statement[];
-export function getStyleElementStylesheet(styleElement: any): any | null;
+export function getStyleElementStylesheet(
+	styleElement: AST.JSXStyleElement,
+): AST.CSS.StyleSheet | null;
 
 /**
  * Compile error interface
@@ -119,11 +133,11 @@ interface BaseNodeMetaData {
 	/** Memoized `<> … </>` wrapper for a value-position directive (see get_directive_value_wrapper). */
 	tsrx_value_wrapper?: AST.TSRXJSXFragment;
 	ts_name?: string;
-	delegated?: any;
+	delegated?: boolean;
 	returned_tsrx_return?: AST.ReturnStatement;
 	styleScopeHash?: string;
 	css?: {
-		scopedClasses: Map<string, { start: number; end: number; selector: any }>;
+		scopedClasses: TopScopedClasses;
 		hash: string;
 	};
 	elementLeadingComments?: AST.Comment[];
@@ -139,6 +153,12 @@ interface BaseNodeMetaData {
 	generated_loop_skip_if?: boolean;
 	lazy_id?: string;
 	disable_verification?: boolean;
+	extra_source_mappings?: AST.NodeWithLocation[];
+	generated_setup_declarations?: AST.Statement[];
+	has_unmappable_value?: boolean;
+	synthetic_ref?: boolean;
+	tsrx_reactive_block?: boolean;
+	vapor_pending_fallback?: ESTreeJSX.JSXRenderNode;
 	lazy_param_binding_mappings?: Array<{
 		source: AST.Identifier;
 		generated: AST.Identifier | AST.Literal;
@@ -156,8 +176,8 @@ interface FunctionMetaData extends BaseNodeMetaData {
 	/** Top-level scoped classes collected while pruning the component's CSS. */
 	topScopedClasses?: TopScopedClasses;
 	synthetic_children?: boolean;
-	generated_helpers?: any[];
-	generated_statics?: any[];
+	generated_helpers?: AST.Statement[];
+	generated_statics?: AST.Statement[];
 }
 
 // Strip parent, loc, and range from TSESTree nodes to match @sveltejs/acorn-typescript output
@@ -445,6 +465,36 @@ declare module 'estree' {
 		| JSXSwitchExpression
 		| JSXTryExpression;
 
+	/** A statement-form template directive after its parser node has been retyped. */
+	type JSXTemplateStatement =
+		| (AST.IfStatement & { statementType: 'IfStatement' })
+		| (AST.ForOfStatement & { statementType: 'ForOfStatement' })
+		| (AST.SwitchStatement & { statementType: 'SwitchStatement' })
+		| (AST.TryStatement & { statementType: 'TryStatement' });
+
+	/** A source node that the shared JSX transform can lower into a JSX child. */
+	type TSRXRenderChild =
+		| ESTreeJSX.JSXElement
+		| ESTreeJSX.JSXFragment
+		| ESTreeJSX.JSXExpressionContainer
+		| ESTreeJSX.JSXText
+		| JSXTemplateDirective
+		| JSXTemplateStatement;
+
+	/** An AST node that represents component-level `await` during validation. */
+	type TSRXAwaitNode = AST.AwaitExpression | AST.ForOfStatement | JSXForOfExpression;
+
+	/** Any node that can be the rendered output of a TSRX template or statement container. */
+	type TSRXRenderOutput =
+		| ESTreeJSX.JSXElement
+		| ESTreeJSX.JSXFragment
+		| JSXStyleElement
+		| JSXCodeBlock
+		| JSXTemplateDirective;
+
+	/** A parser node whose body uses native TSRX template semantics. */
+	type NativeTSRXNode = TSRXJSXElement | TSRXJSXFragment | JSXStyleElement | JSXCodeBlock;
+
 	interface ParenthesizedExpression extends AST.BaseNode {
 		type: 'ParenthesizedExpression';
 		expression: AST.Expression;
@@ -472,14 +522,24 @@ declare module 'estree' {
 	type CommentWithLocation = AST.Comment & NodeWithLocation;
 
 	interface TryStatement {
+		statementType?: 'TryStatement';
 		pending?: AST.BlockStatement | null;
 	}
 
+	interface IfStatement {
+		statementType?: 'IfStatement';
+	}
+
+	interface SwitchStatement {
+		statementType?: 'SwitchStatement';
+	}
+
 	interface CatchClause {
 		resetParam?: AST.Pattern | null;
 	}
 
 	interface ForOfStatement {
+		statementType?: 'ForOfStatement';
 		index?: AST.Identifier | null;
 		key?: AST.Expression | null;
 		empty?: AST.BlockStatement | null;
@@ -725,6 +785,27 @@ declare module 'estree' {
 }
 
 declare module 'estree-jsx' {
+	/** A node that can be returned from a platform hook into a JSX render slot. */
+	type JSXRenderNode = AST.Expression | JSXExpressionContainer | JSXText | JSXSpreadChild;
+
+	/** A JSX child produced by the transform's render-body lowering. */
+	type JSXRenderChild = JSXElement | JSXFragment | JSXExpressionContainer | JSXText;
+
+	/** An attribute accepted by and emitted from the shared JSX transformer. */
+	type JSXAttributeNode = JSXAttribute | JSXSpreadAttribute;
+
+	/** A `ref` attribute whose value has been narrowed to a non-empty expression. */
+	interface JSXRefAttribute extends JSXAttribute {
+		name: JSXIdentifier;
+		value: JSXExpressionContainer & { expression: AST.Expression };
+	}
+
+	/** A child accepted while TSRX JSX is being lowered to standard ESTree JSX. */
+	type JSXTransformChild =
+		| JSXElement['children'][number]
+		| AST.TSRXJSXElement
+		| AST.TSRXJSXFragment;
+
 	interface JSXAttribute {
 		shorthand: boolean;
 	}
@@ -777,7 +858,8 @@ declare module 'estree-jsx' {
 			| JSXIdentifier
 			| JSXNamespacedName
 			| JSXExpressionContainer
-			| import('estree').MemberExpression;
+			| AST.Identifier
+			| AST.MemberExpression;
 	}
 
 	interface TSRXJSXClosingElement extends Omit<JSXClosingElement, 'name'> {
@@ -787,7 +869,8 @@ declare module 'estree-jsx' {
 			| JSXIdentifier
 			| JSXNamespacedName
 			| JSXExpressionContainer
-			| import('estree').MemberExpression;
+			| AST.Identifier
+			| AST.MemberExpression;
 	}
 
 	interface ExpressionMap {
@@ -1269,6 +1352,30 @@ export interface AnalyzeOptions extends ParseOptions, Pick<CompileOptions, 'mode
 	to_ts?: boolean;
 }
 
+/** Options for the target-neutral TSRX semantic analysis pass. */
+export interface TSRXAnalysisOptions extends ParseOptions {
+	typeOnly?: boolean;
+	to_ts?: boolean;
+}
+
+/** Traversal state used by the target-neutral TSRX semantic analysis pass. */
+export interface TSRXAnalysisState {
+	filename: string | null;
+	collect: boolean;
+	errors: CompileError[];
+	comments: AST.CommentWithLocation[];
+	function: AST.Function | null;
+	function_body_is_code_block: boolean;
+	inside_template_output: boolean;
+}
+
+/** Result of target-neutral TSRX semantic analysis. */
+export interface TSRXAnalysisResult {
+	ast: AST.Program;
+	errors: CompileError[];
+	comments: AST.CommentWithLocation[];
+}
+
 /**
  * Result of parsing operation
  */

package/types/jsx-platform.d.ts

@@ -1,6 +1,7 @@
 import type * as AST from 'estree';
+import type * as ESTreeJSX from 'estree-jsx';
 import type { RawSourceMap } from 'source-map';
-import type { CompileError } from './index';
+import type { CompileError, JsxHelperComponent } from './index';
 
 /**
  * Result returned by a JSX platform transform (React, Preact, Solid).
@@ -25,10 +26,8 @@ export interface JsxTransformResult {
 }
 
 /**
- * Shared base for the per-call transform context that the JSX factory passes
- * into every visitor and helper. Platform-specific transforms (e.g. Solid)
- * extend this with their own `needs_*` flags via `hooks.initialState`; helpers
- * defined in `@tsrx/core` only ever rely on these base fields.
+ * Per-call transform context that the JSX factory passes into every visitor
+ * and platform hook.
  */
 export interface JsxTransformContext {
 	platform: JsxPlatform;
@@ -43,14 +42,22 @@ export interface JsxTransformContext {
 	needs_dynamic_factory: boolean;
 	needs_for_of_iterable: boolean;
 	needs_iteration_value_type: boolean;
+	needs_show: boolean;
+	needs_for: boolean;
+	needs_switch: boolean;
+	needs_match: boolean;
+	needs_errored: boolean;
+	needs_loading: boolean;
+	needs_define_vapor_component: boolean;
+	needs_vapor_for: boolean;
 	stylesheets: AST.CSS.StyleSheet[];
 	type_only_style_anchors: AST.Statement[];
 	module_scoped_hook_components: boolean;
 	helper_state: {
 		base_name: string;
 		next_id: number;
-		helpers: any[];
-		statics: any[];
+		helpers: AST.Statement[];
+		statics: AST.Statement[];
 	} | null;
 	hook_helpers_enabled: boolean;
 	available_bindings: Map<string, AST.Identifier>;
@@ -138,10 +145,13 @@ export interface JsxPlatformHooks {
 	 * 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;
+		ifStatement?: (node: AST.IfStatement, ctx: JsxTransformContext) => ESTreeJSX.JSXRenderNode;
+		forOf?: (node: AST.ForOfStatement, ctx: JsxTransformContext) => ESTreeJSX.JSXRenderNode;
+		switchStatement?: (
+			node: AST.SwitchStatement,
+			ctx: JsxTransformContext,
+		) => ESTreeJSX.JSXRenderNode;
+		tryStatement?: (node: AST.TryStatement, ctx: JsxTransformContext) => ESTreeJSX.JSXRenderNode;
 	};
 	/**
 	 * Mark a top-level call expression inside a control-flow branch as requiring
@@ -149,14 +159,19 @@ export interface JsxPlatformHooks {
 	 * branch instead of once per parent rerender. Vue uses this for branch-local
 	 * Composition API state like `ref()`.
 	 */
-	isTopLevelSetupCall?: (callExpression: any, ctx: any) => boolean;
+	isTopLevelSetupCall?: (callExpression: AST.CallExpression, ctx: JsxTransformContext) => boolean;
 	/**
 	 * Wrap a hoisted helper component declaration emitted by the shared control-
 	 * flow splitter. The default is the plain function declaration; Vue uses
 	 * this to wrap helpers in `defineVaporComponent(...)` so branch-local setup
 	 * state behaves like normal component state.
 	 */
-	wrapHelperComponent?: (helperFn: any, helperId: any, ctx: any, sourceNode: any) => any;
+	wrapHelperComponent?: (
+		helperFn: AST.FunctionDeclaration,
+		helperId: AST.Identifier,
+		ctx: JsxTransformContext,
+		sourceNode: AST.NodeWithLocation | undefined,
+	) => AST.Statement;
 	/**
 	 * Emit hook-isolation helper components as unique module-scope declarations
 	 * instead of lazily creating and caching them from the parent component body.
@@ -171,27 +186,38 @@ export interface JsxPlatformHooks {
 	 * Solid injects `Show`, `For`, `Switch`, `Match`, `Errored`, `Loading`
 	 * from `solid-js`.
 	 */
-	injectImports?: (program: AST.Program, ctx: any, suspenseSource: string) => void;
+	injectImports?: (program: AST.Program, ctx: JsxTransformContext, suspenseSource: string) => void;
 	/**
-	 * Transform a Ripple element's attributes to JSX attributes. Default
-	 * is "map over `to_jsx_attribute`" plus the shared multi-`ref` merge
-	 * pass. Platforms that own a `transformElement` hook (e.g. Solid) bypass
-	 * this entirely — they never reach the dispatch path that would call
-	 * it — and run their own attribute pass inside their `transformElement`.
+	 * Transform a Ripple element's parser-native JSX attributes. The result
+	 * is passed through the shared multi-`ref` merge. Platforms that own a
+	 * `transformElement` hook (e.g. Solid) run their own attribute pass inside
+	 * that hook.
 	 */
-	transformElementAttributes?: (attrs: any[], ctx: any, element: any) => any[];
+	transformElementAttributes?: (
+		attrs: ESTreeJSX.JSXAttributeNode[],
+		ctx: JsxTransformContext,
+		element: AST.TSRXJSXElement,
+	) => ESTreeJSX.JSXAttributeNode[];
 	/**
-	 * Rewrite or normalize raw Ripple attributes before the shared
-	 * `to_jsx_attribute()` mapping runs.
+	 * Rewrite parser-native JSX attributes before platform transformation.
 	 */
-	preprocessElementAttributes?: (attrs: any[], ctx: any, element: any) => any[];
+	preprocessElementAttributes?: (
+		attrs: ESTreeJSX.JSXAttributeNode[],
+		ctx: JsxTransformContext,
+		element: AST.TSRXJSXElement,
+	) => ESTreeJSX.JSXAttributeNode[];
 	/**
 	 * 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 typed `VaporFor` component.
 	 */
-	renderForOf?: (node: any, loopParams: any[], bodyStatements: any[], ctx: any) => any | null;
+	renderForOf?: (
+		node: AST.ForOfStatement,
+		loopParams: AST.Pattern[],
+		bodyStatements: AST.Statement[],
+		ctx: JsxTransformContext,
+	) => ESTreeJSX.JSXExpressionContainer | null;
 	/**
 	 * Optionally replace the default React-style pending lowering for
 	 * `@try { ... } @pending { ... }`. The default emits
@@ -200,35 +226,35 @@ export interface JsxPlatformHooks {
 	 * `v-slots`.
 	 */
 	createPendingBoundary?: (
-		tryContent: any,
-		fallbackContent: any,
-		ctx: any,
-		node: any,
-	) => any | null;
+		tryContent: ESTreeJSX.JSXRenderNode,
+		fallbackContent: ESTreeJSX.JSXRenderNode,
+		ctx: JsxTransformContext,
+		node: AST.TryStatement,
+	) => ESTreeJSX.JSXRenderNode | null;
 	/**
 	 * Optionally create a generated component for a catch fallback body while
 	 * the catch parameters are still in scope. Platforms can use this to reuse
 	 * one mapped catch-body component from multiple runtime catch sites.
 	 */
 	createErrorFallbackComponent?: (
-		catchBodyNodes: any[],
-		catchParams: any[],
-		ctx: any,
-		node: any,
-	) => any | null;
+		catchBodyNodes: AST.Statement[],
+		catchParams: AST.Pattern[],
+		ctx: JsxTransformContext,
+		node: AST.TryStatement,
+	) => JsxHelperComponent | null;
 	/**
 	 * Optionally replace the default `try/catch` boundary wrapper. The hook
 	 * receives the current render content, the original try-body content before
 	 * any pending wrapper, and the generated catch fallback function.
 	 */
 	createErrorBoundary?: (
-		tryContent: any,
-		rawTryContent: any,
-		fallbackFn: any,
-		ctx: any,
-		node: any,
-		info?: { fallbackComponent?: any },
-	) => any | null;
+		tryContent: ESTreeJSX.JSXRenderNode,
+		rawTryContent: ESTreeJSX.JSXRenderNode,
+		fallbackFn: AST.ArrowFunctionExpression,
+		ctx: JsxTransformContext,
+		node: AST.TryStatement,
+		info?: { fallbackComponent?: JsxHelperComponent | null },
+	) => ESTreeJSX.JSXRenderNode | null;
 	/**
 	 * Optionally move the primary `try { ... }` render content into an explicit
 	 * error-boundary prop instead of rendering it as the boundary's JSX children.
@@ -236,7 +262,11 @@ export interface JsxPlatformHooks {
 	 * zero-argument function. If a `pending` block exists, `tryContent` is the
 	 * already-created pending boundary so catch wrappers still enclose it.
 	 */
-	createErrorBoundaryContent?: (tryContent: any, ctx: any, node: any) => any | null;
+	createErrorBoundaryContent?: (
+		tryContent: ESTreeJSX.JSXRenderNode,
+		ctx: JsxTransformContext,
+		node: AST.TryStatement,
+	) => AST.Expression | null;
 	/**
 	 * Customize lowering for a native JSX element. Default is the
 	 * factory's `to_jsx_element`. The hook receives the walker-transformed
@@ -245,7 +275,11 @@ export interface JsxPlatformHooks {
 	 * `JSXText` child it can hoist to a `textContent` attribute before the
 	 * generic text→JSXExpressionContainer transform runs.
 	 */
-	transformElement?: (inner: any, ctx: any, rawChildren: any[]) => any;
+	transformElement?: (
+		inner: AST.TSRXJSXElement,
+		ctx: JsxTransformContext,
+		rawChildren: AST.Node[],
+	) => ESTreeJSX.JSXRenderNode;
 	/**
 	 * Optionally rewrite a host element's children into attributes or another
 	 * specialized child shape after generic attribute lowering but before the
@@ -258,27 +292,27 @@ export interface JsxPlatformHooks {
 	 * back to the default child handling.
 	 */
 	transformElementChildren?: (
-		element: any,
-		walkedChildren: any[],
-		rawChildren: any[],
-		attrs: any[],
-		ctx: any,
-	) => { children: any[]; selfClosing?: boolean } | null;
+		element: AST.TSRXJSXElement,
+		walkedChildren: AST.Node[],
+		rawChildren: AST.Node[],
+		attrs: ESTreeJSX.JSXAttributeNode[],
+		ctx: JsxTransformContext,
+	) => { children: ESTreeJSX.JSXElement['children']; selfClosing?: boolean } | null;
 	/**
 	 * Decide whether a JSX subtree may be hoisted to module scope when it is
 	 * otherwise statically safe. Targets can use this to keep runtime-sensitive
 	 * JSX, such as component invocations, inside render/setup execution.
 	 */
-	canHoistStaticNode?: (node: any, ctx: any) => boolean;
+	canHoistStaticNode?: (node: ESTreeJSX.JSXElement, ctx: JsxTransformContext) => boolean;
 	/**
 	 * 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,
+		awaitNode: AST.TSRXAwaitNode,
+		component: AST.Function,
+		ctx: JsxTransformContext,
 		moduleUsesServerDirective: boolean,
 		source: string,
 	) => void;
@@ -287,7 +321,7 @@ export interface JsxPlatformHooks {
 	 * initial `transform_context`. Lets solid seed its `needs_show` /
 	 * `needs_for` / etc. flags without forking the factory.
 	 */
-	initialState?: () => Record<string, unknown>;
+	initialState?: () => Partial<JsxTransformContext>;
 }
 
 /**