babel-plugin-solarite 0.7.0

package/babel-plugin.js

@@ -0,0 +1,266 @@
+/**
+ * babel-plugin-solarite (Tier 1b).
+ *
+ * Transforms JSX/TSX into the same "precompile" contract Deno emits, so esbuild/Vite/Babel/tsc
+ * users get Tier 1 performance (hoisted module-level static arrays => stable identity => Solarite's
+ * Shell cache and NodeGroup reuse): each element subtree becomes a hoisted `const _tpl = [...]` plus
+ * `jsxTemplate(_tpl, jsxAttr(name, value), jsxEscape(child), ...)`.  Components and elements with a
+ * spread attribute become `jsx(tag, props, key)` calls, routed to the same runtime's Tier 2 factory.
+ *
+ * The plugin needs no HTML parser: @babel/parser already parses JSX, so the job is the reverse —
+ * serialize that AST back into static html strings with holes punched at the dynamic points.
+ *
+ * @param {{types: import('@babel/types')}} babel
+ * @param {{importSource?: string}} options */
+import syntaxJsx from '@babel/plugin-syntax-jsx';
+
+export default function solariteJsx({ types: t }, options = {}) {
+	const importSource = options.importSource || 'solarite/jsx-runtime';
+
+	// HTML void elements never get a closing tag.
+	const VOID = new Set(['area','base','br','col','embed','hr','img','input','link','meta','param','source','track','wbr']);
+
+	const escapeText = s => s.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+	const escapeAttr = s => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+
+	// JSX whitespace cleaning (same rules React/Babel use for literal text children).
+	function cleanJSXText(raw) {
+		const lines = raw.split(/\r\n|\n|\r/);
+		let lastNonEmpty = 0;
+		for (let i = 0; i < lines.length; i++)
+			if (/[^ \t]/.test(lines[i])) lastNonEmpty = i;
+		let str = '';
+		for (let i = 0; i < lines.length; i++) {
+			let line = lines[i].replace(/\t/g, ' ');
+			if (i !== 0) line = line.replace(/^ +/, '');
+			if (i !== lines.length - 1) line = line.replace(/ +$/, '');
+			if (line) {
+				if (i !== lastNonEmpty) line += ' ';
+				str += line;
+			}
+		}
+		return str;
+	}
+
+	function tagName(node) {
+		let n = node.name || node.openingElement?.name;
+		if (t.isJSXIdentifier(n)) return n.name;
+		if (t.isJSXNamespacedName(n)) return n.namespace.name + ':' + n.name.name;
+		return null; // member expression => component
+	}
+
+	// A capitalized identifier or a member expression (Foo.Bar) is a component; lowercase/dashed
+	// names (including custom-element tags like `my-button`) are intrinsic strings.
+	function isComponent(node) {
+		let n = node.openingElement.name;
+		if (t.isJSXMemberExpression(n)) return true;
+		if (t.isJSXIdentifier(n)) return /^[A-Z]/.test(n.name);
+		return false;
+	}
+
+	function componentExpr(name) {
+		if (t.isJSXMemberExpression(name))
+			return t.memberExpression(componentExpr(name.object), t.identifier(name.property.name));
+		if (t.isJSXNamespacedName(name))
+			return t.stringLiteral(name.namespace.name + ':' + name.name.name);
+		return t.identifier(name.name); // capitalized => references the imported component
+	}
+
+	function attrName(attr) {
+		let n = attr.name;
+		return t.isJSXNamespacedName(n) ? n.namespace.name + ':' + n.name.name : n.name;
+	}
+
+	function attrValueExpr(attr) {
+		if (attr.value == null) return t.booleanLiteral(true);          // bare boolean attribute
+		if (t.isStringLiteral(attr.value)) return attr.value;            // name="literal"
+		if (t.isJSXExpressionContainer(attr.value)) return attr.value.expression;
+		return attr.value;
+	}
+
+	// ---- Serializer state for one transformed root ----
+	// strings: accumulated static html chunks; exprs: the hole expressions (jsxAttr/jsxEscape/jsx).
+	function makeBuilder(state) {
+		const strings = [];
+		let current = '';
+		const exprs = [];
+		const used = state.used;
+
+		const helper = name => { used.add(name); return t.cloneNode(state.ids[name]); };
+		const pushHole = expr => { strings.push(current); current = ''; exprs.push(expr); };
+
+		const api = {
+			text: s => { current += s; },
+			jsxAttr: (name, valueNode) => pushHole(t.callExpression(helper('jsxAttr'), [t.stringLiteral(name), valueNode])),
+			jsxEscape: valueNode => pushHole(t.callExpression(helper('jsxEscape'), [valueNode])),
+			finish() {
+				strings.push(current);
+				return { strings, exprs };
+			},
+			helper,
+		};
+		return api;
+	}
+
+	// Serialize one element's children (already inside the open tag) into the builder.
+	function buildChildren(children, b, state) {
+		for (const child of children) {
+			if (t.isJSXText(child)) {
+				const txt = cleanJSXText(child.value);
+				if (txt) b.text(escapeText(txt));
+			}
+			else if (t.isJSXExpressionContainer(child)) {
+				if (t.isJSXEmptyExpression(child.expression)) continue; // a {/* comment */}
+				b.jsxEscape(child.expression); // dynamic child; inner JSX is transformed on Babel's re-visit
+			}
+			else if (t.isJSXSpreadChild(child)) {
+				b.jsxEscape(child.expression);
+			}
+			else if (t.isJSXElement(child) || t.isJSXFragment(child)) {
+				if (t.isJSXElement(child) && (isComponent(child) || hasSpread(child)))
+					b.jsxEscape(buildNode(child, state)); // component/spread child => its own jsx()/jsxTemplate hole
+				else
+					inlineElement(child, b, state); // intrinsic child => merged into the parent statics
+			}
+		}
+	}
+
+	function hasSpread(node) {
+		return node.openingElement.attributes.some(a => t.isJSXSpreadAttribute(a));
+	}
+
+	// Inline an intrinsic element (and its subtree) directly into the parent's static strings.
+	function inlineElement(node, b, state) {
+		if (t.isJSXFragment(node)) {
+			buildChildren(node.children, b, state);
+			return;
+		}
+		const tag = tagName(node);
+		b.text('<' + tag);
+		for (const attr of node.openingElement.attributes) {
+			const name = attrName(attr);
+			const value = attr.value;
+			if (name === 'key') { // key is always a hole; the runtime lifts it onto template.key.
+				b.text(' ');
+				b.jsxAttr('key', attrValueExpr(attr));
+				continue;
+			}
+			if (value == null)                      // bare boolean attribute
+				b.text(' ' + name);
+			else if (t.isStringLiteral(value))      // static value
+				b.text(' ' + name + '="' + escapeAttr(value.value) + '"');
+			else {                                  // dynamic value => whole-attribute hole
+				b.text(' ');
+				b.jsxAttr(name, attrValueExpr(attr));
+			}
+		}
+		b.text('>');
+		if (!VOID.has(tag.toLowerCase())) {
+			buildChildren(node.children, b, state);
+			b.text('</' + tag + '>');
+		}
+	}
+
+	// Build the expression a JSX node becomes (jsxTemplate(...) for intrinsic/fragment, jsx(...) for
+	// components or spread elements).  Hoists the statics array to module scope.
+	function buildNode(node, state) {
+		if (t.isJSXElement(node) && (isComponent(node) || hasSpread(node)))
+			return buildComponent(node, state);
+
+		const b = makeBuilder(state);
+		inlineElement(node, b, state);
+		const { strings, exprs } = b.finish();
+
+		// Hoist `const _tpl = [ ...static strings ]` to the top of the module.
+		const id = t.identifier(state.scope.generateUid('tpl'));
+		state.hoist.push(t.variableDeclaration('const', [
+			t.variableDeclarator(id, t.arrayExpression(strings.map(s => t.stringLiteral(s)))),
+		]));
+		state.used.add('jsxTemplate');
+		return t.callExpression(t.cloneNode(state.ids.jsxTemplate), [id, ...exprs]);
+	}
+
+	// Build a jsx(tag, props, key?) call for a component or spread element.
+	function buildComponent(node, state) {
+		const opening = node.openingElement;
+		const props = [];
+		let keyExpr = null;
+
+		for (const attr of opening.attributes) {
+			if (t.isJSXSpreadAttribute(attr)) {
+				props.push(t.spreadElement(attr.argument));
+				continue;
+			}
+			const name = attrName(attr);
+			if (name === 'key') { keyExpr = attrValueExpr(attr); continue; }
+			props.push(t.objectProperty(
+				/^[a-z][\w$]*$/i.test(name) ? t.identifier(name) : t.stringLiteral(name),
+				attrValueExpr(attr)));
+		}
+
+		// Children -> props.children (single child or array), each transformed.
+		const kids = childExprs(node.children, state);
+		if (kids.length === 1)
+			props.push(t.objectProperty(t.identifier('children'), kids[0]));
+		else if (kids.length > 1)
+			props.push(t.objectProperty(t.identifier('children'), t.arrayExpression(kids)));
+
+		const tagExpr = isComponent(node) ? componentExpr(opening.name) : t.stringLiteral(tagName(node));
+		state.used.add('jsx');
+		const args = [tagExpr, t.objectExpression(props)];
+		if (keyExpr) args.push(keyExpr);
+		return t.callExpression(t.cloneNode(state.ids.jsx), args);
+	}
+
+	function childExprs(children, state) {
+		const out = [];
+		for (const child of children) {
+			if (t.isJSXText(child)) {
+				const txt = cleanJSXText(child.value);
+				if (txt) out.push(t.stringLiteral(txt));
+			}
+			else if (t.isJSXExpressionContainer(child)) {
+				if (!t.isJSXEmptyExpression(child.expression)) out.push(child.expression);
+			}
+			else if (t.isJSXElement(child) || t.isJSXFragment(child))
+				out.push(buildNode(child, state));
+		}
+		return out;
+	}
+
+	return {
+		name: 'babel-plugin-solarite',
+		// Enable JSX parsing so a bare `{ "plugins": ["babel-plugin-solarite"] }` config works on its own.
+		inherits: syntaxJsx,
+		visitor: {
+			Program: {
+				enter(path) {
+					const helpers = ['jsxTemplate', 'jsxAttr', 'jsxEscape', 'jsx', 'jsxs', 'Fragment'];
+					const ids = {};
+					for (const h of helpers)
+						ids[h] = t.identifier(path.scope.generateUid('_' + h));
+					this.solarite = { ids, used: new Set(), hoist: [], scope: path.scope };
+				},
+				exit(path) {
+					const s = this.solarite;
+					if (!s.used.size) return;
+					// Import only the helpers that were used.
+					const specifiers = [...s.used].map(name =>
+						t.importSpecifier(t.cloneNode(s.ids[name]), t.identifier(name)));
+					path.unshiftContainer('body', t.importDeclaration(specifiers, t.stringLiteral(importSource)));
+					// Hoist the static-template consts just after the import.
+					path.node.body.splice(1, 0, ...s.hoist);
+				},
+			},
+			JSXElement(path) {
+				// Only roots: direct intrinsic JSX children are inlined by their ancestor's serializer.
+				if (path.parentPath.isJSXElement() || path.parentPath.isJSXFragment()) return;
+				path.replaceWith(buildNode(path.node, this.solarite));
+			},
+			JSXFragment(path) {
+				if (path.parentPath.isJSXElement() || path.parentPath.isJSXFragment()) return;
+				path.replaceWith(buildNode(path.node, this.solarite));
+			},
+		},
+	};
+}

package/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/** Standalone CLI: `solarite-jsx <file.tsx>` prints Tier 1 precompile JS to stdout (TS types
+ * stripped).  Lets non-Node-bundler hosts — e.g. a PHP/Apache wrapper mapping .tsx/.jsx requests —
+ * shell out for Tier 1 output, which esbuild's binary CLI can't produce. */
+import fs from 'node:fs';
+import { transform } from './transform.js';
+
+const args = process.argv.slice(2);
+const file = args.find(a => !a.startsWith('-'));
+if (!file) {
+	process.stderr.write('usage: solarite-jsx <file.jsx|.tsx> [--import-source=solarite/jsx-runtime]\n');
+	process.exit(1);
+}
+const importSourceArg = args.find(a => a.startsWith('--import-source='));
+const source = fs.readFileSync(file, 'utf8');
+const { code } = transform(source, {
+	filename: file,
+	importSource: importSourceArg ? importSourceArg.split('=')[1] : undefined,
+});
+process.stdout.write(code);

package/index.js

@@ -0,0 +1,7 @@
+/** babel-plugin-solarite — compiles JSX/TSX to Solarite precompile output.
+ *
+ * The default export is the Babel plugin, so `{ "plugins": ["babel-plugin-solarite"] }` works in a
+ * Babel config.  The named `transform` runs Babel for you (it adds JSX/TS parsing and returns the
+ * compiled code); vite-plugin-solarite and esbuild-plugin-solarite both build on it. */
+export { default } from './babel-plugin.js';
+export { transform } from './transform.js';

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "babel-plugin-solarite",
+  "version": "0.7.0",
+  "description": "Babel plugin that compiles JSX/TSX to Solarite precompile output (jsxTemplate/jsxAttr/jsxEscape), giving JSX the same runtime speed as h tagged templates. Also the shared engine behind vite-plugin-solarite and esbuild-plugin-solarite.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Eric Frost",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "solarite-jsx": "./cli.js"
+  },
+  "files": [
+    "index.js",
+    "babel-plugin.js",
+    "transform.js",
+    "cli.js",
+    "readme.md"
+  ],
+  "keywords": [
+    "solarite",
+    "jsx",
+    "tsx",
+    "babel",
+    "babel-plugin",
+    "precompile"
+  ],
+  "dependencies": {
+    "@babel/core": "^8.0.1",
+    "@babel/plugin-syntax-jsx": "^8.0.1",
+    "@babel/preset-typescript": "^8.0.1"
+  },
+  "peerDependencies": {
+    "solarite": "^0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "solarite": { "optional": true }
+  },
+  "scripts": {
+    "test": "node test.js"
+  }
+}

package/readme.md

@@ -0,0 +1,54 @@
+# babel-plugin-solarite
+
+Compiles JSX/TSX into **Solarite precompile output** — the static HTML of each element is hoisted to
+a module-level array and emitted as `jsxTemplate`/`jsxAttr`/`jsxEscape` calls (the same contract
+Deno's `jsx: "precompile"` produces). That gives JSX the **same runtime speed as `h` tagged
+templates**. Components and elements with a spread become `jsx(tag, props, key)` calls, handled by
+Solarite's runtime.
+
+This package is also the shared engine for [`vite-plugin-solarite`](../vite-plugin-solarite) and
+[`esbuild-plugin-solarite`](../esbuild-plugin-solarite). Use those if you're on Vite or esbuild; use
+this package directly for Babel, or programmatically.
+
+It runs only at build time and is never shipped to the browser. The JSX runtime it targets lives in
+the core `solarite` package (`solarite/jsx-runtime`).
+
+## Babel
+
+```sh
+npm install --save-dev babel-plugin-solarite
+```
+
+```jsonc
+// babel.config.json   (add @babel/preset-typescript if you use .tsx)
+{ "plugins": ["babel-plugin-solarite"] }
+```
+
+The plugin enables JSX parsing itself, so no separate `@babel/plugin-syntax-jsx` is needed. Babel's
+shorthand also works: `{ "plugins": ["solarite"] }`.
+
+## Programmatic
+
+```js
+import { transform } from 'babel-plugin-solarite';
+const { code, map } = transform(src, { filename: 'app.tsx' });
+```
+
+## CLI
+
+Prints compiled JS to stdout (TypeScript types stripped) — handy for non-Node hosts shelling out:
+
+```sh
+npx solarite-jsx app.tsx > app.js
+```
+
+## Options
+
+- `importSource` — runtime module specifier (default `"solarite/jsx-runtime"`).
+
+## Notes
+
+- Use native HTML attribute/event names (`class`, `onclick`), not React's `className`/`onClick`.
+- `style={{…}}` objects are serialized to CSS text by the runtime.
+- `key={…}` becomes the keyed-list key, never a rendered attribute.
+- Static `id`/`data-id` stay in the static HTML so Solarite's `this.x` element references resolve.

package/transform.js

@@ -0,0 +1,36 @@
+/**
+ * Core transform: JSX/TSX source -> Tier 1 precompile JS, using the babel-plugin-solarite plugin.
+ * Strips TypeScript types too, so .tsx works without a separate tsc pass. */
+import { transformSync } from '@babel/core';
+import solariteJsx from './babel-plugin.js';
+
+/**
+ * @param {string} code Source code.
+ * @param {object} [opts]
+ * @param {string} [opts.filename] Used to pick ts/tsx parsing and for sourcemaps.
+ * @param {string} [opts.importSource] Runtime module specifier (default "solarite/jsx-runtime").
+ * @param {boolean} [opts.sourceMaps] Emit a sourcemap.
+ * @returns {{code: string, map: object|null}} */
+export function transform(code, opts = {}) {
+	const filename = opts.filename || 'input.tsx';
+	const isTs = /\.(ts|tsx|mts|cts)$/.test(filename);
+
+	// preset-typescript strips TS types (parsing alone keeps them); it also sets up JSX parsing.
+	// For plain .jsx we add the jsx parser plugin ourselves.
+	// preset-typescript strips TS types (parsing alone keeps them).  We always enable the jsx parser
+	// plugin so both .jsx and .tsx parse JSX; the preset removes the TypeScript syntax for .ts/.tsx.
+	const presets = isTs ? ['@babel/preset-typescript'] : [];
+
+	const result = transformSync(code, {
+		filename,
+		babelrc: false,
+		configFile: false,
+		sourceMaps: opts.sourceMaps || false,
+		parserOpts: { plugins: ['jsx'] },
+		presets,
+		plugins: [[solariteJsx, { importSource: opts.importSource }]],
+	});
+	return { code: result.code, map: result.map || null };
+}
+
+export default transform;