@arcmantle/lit-jsx 1.0.0

package/src/compiler/vite-plugin.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Vite plugin for lit-jsx preserve-JSX compilation mode.
+ *
+ * This plugin provides compile-time JSX transformation using Babel to convert
+ * JSX syntax directly into optimized Lit templates. Unlike the React compatibility
+ * mode, this preserves JSX through the entire build pipeline for maximum performance.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { litJsx } from "@arcmantle/lit-jsx/vite-jsx-preserve";
+ *
+ * export default {
+ *   plugins: [litJsx({
+ *     babel: {
+ *       // Custom Babel options
+ *     }
+ *   })]
+ * };
+ * ```
+ */
+
+import * as babel from '@babel/core';
+import { mergeAndConcat } from 'merge-anything';
+import type { PluginOption } from 'vite';
+
+import { litJsxBabelPreset } from './babel-preset.js';
+
+
+type BabelPlugins = NonNullable<NonNullable<babel.TransformOptions['parserOpts']>['plugins']>;
+
+
+/**
+ * Vite plugin for jsx-lit with preserve-JSX compilation.
+ *
+ * This plugin uses Babel to transform JSX directly into Lit templates at build time,
+ * providing optimal performance by eliminating runtime JSX processing entirely.
+ *
+ * @param options - Configuration options for the plugin
+ * @param options.babel - Babel transform options or function returning options
+ * @returns Vite plugin configuration
+ */
+export const litJsx = (options: {
+	/** Options for the Babel transform */
+	babel?:
+		| babel.TransformOptions
+		| ((code: string, id: string) => babel.TransformOptions | Promise<babel.TransformOptions>);
+} = {}): PluginOption => {
+	let projectRoot: string;
+
+	return {
+		name:   'lit-jsx-preserve',
+		config: {
+			order: 'pre',
+			handler(userConfig, env) {
+				projectRoot = userConfig.root ?? process.cwd();
+			},
+		},
+		transform: {
+			filter: {
+				id:   [ '**/*.jsx', '**/*.tsx' ],
+				code: [ '/>', '</' ],
+			},
+			order: 'pre',
+			async handler(source, id) {
+				const plugins: BabelPlugins = [ 'jsx', 'decorators', 'decoratorAutoAccessors' ];
+				if (id.endsWith('.tsx'))
+					plugins.push('typescript');
+
+				// Default value for babel user options
+				let babelUserOptions: babel.TransformOptions = {};
+
+				if (options.babel) {
+					if (typeof options.babel === 'function') {
+						const babelOptions = options.babel(source, id);
+						babelUserOptions = babelOptions instanceof Promise
+							? await babelOptions
+							: babelOptions;
+					}
+					else {
+						babelUserOptions = options.babel;
+					}
+				}
+
+				const babelOptions: babel.TransformOptions = {
+					root:           projectRoot,
+					filename:       id,
+					sourceFileName: id,
+					presets:        [
+						[
+							litJsxBabelPreset,
+							/* merged into the metadata obj through state.opts */
+							{},
+						],
+					],
+					plugins:    [],
+					ast:        false,
+					sourceMaps: true,
+					configFile: false,
+					babelrc:    false,
+					parserOpts: {
+						plugins,
+					},
+				};
+
+				const opts = mergeAndConcat(babelUserOptions, babelOptions);
+				const result = await babel.transformAsync(source, opts);
+
+				if (result?.code)
+					return { code: result.code, map: result.map };
+			},
+		},
+	};
+};

package/src/external.d.ts

@@ -0,0 +1,9 @@
+declare module '@babel/plugin-syntax-jsx' {
+	const module: {
+		default: {
+			(): any;
+			manipulateOptions(opts: any, parserOpts: { plugins: string[]; }): void;
+		};
+	};
+	export default module;
+}

package/src/runtime/choose-component.ts

@@ -0,0 +1,53 @@
+import { nothing } from 'lit-html';
+
+
+type ChooseValue<T> = T extends undefined ? never : T;
+type ChooseChild<T> = [
+	condition: (value: ChooseValue<T>) => boolean,
+	output: (value: ChooseValue<T>) => JSX.JSXElement,
+];
+
+
+/**
+ * Conditionally renders content based on evaluating multiple condition-output pairs against a value.
+ * Similar to lit-html's choose directive, evaluates each condition in order and renders the first match.
+ *
+ * @template T - The type of the value to evaluate against (defaults to undefined for no value)
+ * @param props.value - The value to pass to each condition and output function
+ * @param props.children - Single [condition, output] tuple or multiple tuple children to evaluate
+ * @returns The rendered JSX element from the first matching condition, or nothing if no match
+ *
+ * @example
+ * ```tsx
+ * // Multiple condition-output tuples as separate children
+ * <Choose value={status}>
+ *   {[
+ *     (status) => status === 'loading',
+ *     () => <div>Loading...</div>
+ *   ]}
+ *   {[
+ *     (status) => status === 'error',
+ *     (status) => <div>Error: {status}</div>
+ *   ]}
+ *   {[
+ *     () => true, // default case
+ *     (status) => <div>Status: {status}</div>
+ *   ]}
+ * </Choose>
+ * ```
+ */
+export function Choose<T = undefined>(props: {
+	value?:   T;
+	children: ChooseChild<T> | ChooseChild<T>[];
+}): JSX.JSXElement {
+	const children = Array.isArray(props.children.at(-1))
+		? props.children as ChooseChild<T>[]
+		: [ props.children as ChooseChild<T> ];
+
+	for (const [ condition, output ] of children) {
+		if (condition(props.value as ChooseValue<T>))
+			return output(props.value as ChooseValue<T>);
+	}
+
+	return nothing;
+}

package/src/runtime/compiler-ctors.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Internal lit-html part constructors for jsx-lit compiler.
+ *
+ * This module exports the internal part constructors from lit-html that are used
+ * by the lit-jsx compiler to create optimized template parts. These are low-level
+ * utilities used internally by the compilation process.
+ */
+
+import * as internals from 'lit-html/private-ssr-support.js';
+
+
+/** Boolean attribute part constructor from lit-html internals */
+export const BooleanPart:   typeof internals._$LH.BooleanAttributePart = internals._$LH.BooleanAttributePart;
+
+/** Attribute part constructor from lit-html internals */
+export const AttributePart: typeof internals._$LH.AttributePart = internals._$LH.AttributePart;
+
+/** Property part constructor from lit-html internals */
+export const PropertyPart:  typeof internals._$LH.PropertyPart  = internals._$LH.PropertyPart;
+
+/** Element part constructor from lit-html internals */
+export const ElementPart:   typeof internals._$LH.ElementPart   = internals._$LH.ElementPart;
+
+/** Event part constructor from lit-html internals */
+export const EventPart:     typeof internals._$LH.EventPart     = internals._$LH.EventPart;
+
+/** Child part constructor from lit-html internals */
+export const ChildPart:     typeof internals._$LH.ChildPart     = internals._$LH.ChildPart;

package/src/runtime/for-component.ts

@@ -0,0 +1,54 @@
+import { join } from 'lit-html/directives/join.js';
+import { map } from 'lit-html/directives/map.js';
+import { repeat } from 'lit-html/directives/repeat.js';
+
+
+/**
+ * Renders a list of items with optional keys and separators.
+ *
+ * @template T - The type of items in the array
+ * @template U - The JSX element type returned by the render function
+ * @param props.each - Array of items to render
+ * @param props.key - Optional key function for efficient updates (uses lit-html's repeat directive)
+ * @param props.separator - Optional JSX element to insert between items
+ * @param props.children - Render function that receives each item and its index
+ * @returns An iterator from either the map or repeat directive, depending on whether a key function is provided.
+ *
+ * @example
+ * ```tsx
+ * <For each={users} key={(user) => user.id}>
+ *   {(user, index) => <div key={user.id}>{user.name}</div>}
+ * </For>
+ * ```
+ */
+export function For<T, U extends JSX.JSXElement>(props: {
+	each:       readonly T[];
+	key?:       (item: T, index: number) => any;
+	separator?: JSX.JSXElement;
+	children:   (item: T, index: number) => U;
+}): JSX.JSXElement {
+	if (props.key) {
+		return repeat(
+			props.each,
+			(item, index) => props.key!(item, index),
+			(item, index) => {
+				if (props.separator && index > 0)
+					return [ props.separator, props.children(item, index) ];
+
+				return props.children(item, index);
+			},
+		);
+	}
+
+	if (props.separator) {
+		return join(map(
+			props.each,
+			(item, index) => props.children(item, index),
+		), props.separator);
+	}
+
+	return map(
+		props.each,
+		(item, index) => props.children(item, index),
+	);
+}

package/src/runtime/literal-map.ts

@@ -0,0 +1,37 @@
+import type { StaticValue } from 'lit-html/static.js';
+import { unsafeStatic } from 'lit-html/static.js';
+
+
+/**
+ * Cache for static literal values used in lit-html templates.
+ * Extends Map to automatically create and cache StaticValue instances for string keys.
+ */
+class LiteralMap extends Map<string, StaticValue> {
+
+	/**
+	 * Gets a cached StaticValue for the given key, creating one if it doesn't exist.
+	 *
+	 * @param key - The string key to get or create a StaticValue for
+	 * @returns The cached or newly created StaticValue
+	 */
+	override get(key: string): StaticValue {
+		const value = super.get(key);
+		if (value === undefined) {
+			const literal = unsafeStatic(key);
+			this.set(key, literal);
+
+			return literal;
+		}
+
+		return value;
+	}
+
+}
+
+
+/**
+ * Global cache instance for static literal values used throughout jsx-lit templates.
+ * This is used internally by the jsx-lit compiler to cache StaticValue instances
+ * for efficient template reuse.
+ */
+export const __$literalMap: LiteralMap = new LiteralMap();

package/src/runtime/rest-directive.ts

@@ -0,0 +1,66 @@
+import type { ElementPart } from 'lit-html';
+import { noChange } from 'lit-html';
+import type { DirectiveParameters, DirectiveResult, PartInfo } from 'lit-html/directive.js';
+import { Directive, directive, PartType } from 'lit-html/directive.js';
+
+
+/**
+ * Lit directive for applying rest/spread props to an element.
+ * Efficiently sets properties and attributes from an object of key-value pairs.
+ */
+class RestDirective extends Directive {
+
+	constructor(part: PartInfo) {
+		super(part);
+
+		if (part.type !== PartType.ELEMENT)
+			throw new Error('RestDirective can only be used on ElementParts');
+	}
+
+	override update(part: ElementPart, [ rest ]: DirectiveParameters<this>): unknown {
+		const element = part.element as HTMLElement & Record<string, any>;
+
+		for (const key in rest) {
+			if (!Object.prototype.hasOwnProperty.call(rest, key))
+				continue;
+
+			const value = rest[key]!;
+
+			if (element[key] === value)
+				continue;
+
+			if (typeof value === 'object')
+				element[key] = value;
+			else if (value === null || value === undefined)
+				element.removeAttribute(key);
+			else
+				element.setAttribute(key, String(value));
+		}
+
+		return noChange;
+	}
+
+	override render(rest: Record<keyof any, any>): unknown {
+		console.log('rest parameter stuff', rest);
+
+		return noChange;
+	}
+
+}
+
+
+/**
+ * Lit directive for applying rest/spread props to DOM elements.
+ *
+ * This directive efficiently applies an object of properties and attributes
+ * to a DOM element, handling the differences between properties and attributes
+ * automatically.
+ *
+ * @example
+ * ```tsx
+ * const props = { className: 'my-class', disabled: true };
+ * <div {...__$rest(props)}>Content</div>
+ * ```
+ */
+export const __$rest: DirectiveResult<typeof RestDirective> =
+	directive(RestDirective);

package/src/runtime/show-component.ts

@@ -0,0 +1,48 @@
+import { when as litWhen } from 'lit-html/directives/when.js';
+
+
+type Falsy = null | undefined | false | 0 | -0 | 0n | '';
+export const when = litWhen as <C, T, F>(
+	condition: C,
+	trueCase: (c: NoInfer<Exclude<C, Falsy>>) => T,
+	falseCase?: (c: NoInfer<Exclude<C, Falsy>>) => F,
+) => C extends Falsy ? F : T;
+
+type ShowTrueCase<C, T> = (value: NoInfer<Exclude<C, Falsy>>) => T;
+type ShowFalseCase<C, F> = (value: NoInfer<Exclude<C, Falsy>>) => F;
+type ShowChildren<C, T, F> =
+	| ShowTrueCase<C, T>
+	| [ true: ShowTrueCase<C, T>, false: ShowFalseCase<C, F> ];
+
+
+/**
+ * Conditionally renders content based on a truthy value.
+ *
+ * @template T - The type of the condition value
+ * @template U - The JSX element type returned by the render functions
+ * @param props.when - The condition value to evaluate for truthiness
+ * @param props.children - A single render or tuple containing render functions for true and optionally false cases
+ * @returns The rendered JSX element based on the condition's truthiness
+ *
+ * @example
+ * ```tsx
+ * <Show when={user}>
+ *   {(user) => <div>Welcome, {user.name}!</div>}
+ *   {() => <div>Please log in</div>}
+ * </Show>
+ *
+ * // Or without fallback
+ * <Show when={isVisible}>
+ *   {() => <div>This content is visible</div>}
+ * </Show>
+ * ```
+ */
+export function Show<C, T, F>(props: {
+	when:     C;
+	children: ShowChildren<C, T, F>;
+}): C extends Falsy ? F : T {
+	if (Array.isArray(props.children))
+		return when(props.when, props.children[0], props.children[1]);
+
+	return when(props.when, props.children);
+}

package/src/runtime/tagged-template.ts

@@ -0,0 +1,11 @@
+/**
+ * Identity function for template string arrays used by jsx-lit compiler.
+ *
+ * This function is used as a marker by the jsx-lit compiler to identify
+ * template literals that should be processed for JSX compilation. It simply
+ * returns the input unchanged but signals to the compiler where JSX templates are located.
+ *
+ * @param strings - The template strings array from a template literal
+ * @returns The same template strings array unchanged
+ */
+export const __$t: (strings: TemplateStringsArray) => TemplateStringsArray = s => s;

package/src/runtime/type-helpers.ts

@@ -0,0 +1,91 @@
+/**
+ * Creates a variable which can be used using the Component syntax in JSX.
+ * Also registers the custom element if it hasn't been registered yet.
+ *
+ * @example
+ * ```tsx
+ * import { toJSX } from 'jsx-lit';
+ *
+ * export class MyButton extends LitElement {
+ *   static tagName = 'my-button';
+ *   static tag = toJSX(MyButton);
+ *
+ *   render() {
+ *     return html`<button><slot></slot></button>`;
+ *   }
+ * }
+ *
+ * // Usage in JSX
+ * const jsx = (
+ *   <MyButton.tag
+ *     class="my-button"
+ *     on-click={() => { console.log('Clicked!'); }}
+ *   />
+ * );
+ * ```
+ */
+export const toJSX = <T extends { new(...args: any): any; tagName: string; }>(
+	element: T,
+): (props: JSX.JSXProps<InstanceType<T>>) => string => {
+	queueMicrotask(() => {
+		if ('register' in element && typeof element.register === 'function')
+			element.register();
+		else if (!customElements.get(element.tagName))
+			customElements.define(element.tagName, element);
+	});
+
+	return element.tagName as any;
+};
+
+
+/**
+ * Creates a dynamic tag name object that can be used with jsx-lit's Component syntax.
+ * This function is required for dynamic tag names to compile to static literals.
+ *
+ * **IMPORTANT**: Dynamic tag names must use the `.tag` property pattern to be properly
+ * compiled to lit-html static templates. Without this pattern, jsx-lit cannot detect
+ * and transform the dynamic tag name into efficient static template literals.
+ *
+ * @example
+ * ```tsx
+ * import { toTag } from 'jsx-lit';
+ *
+ * // ✅ Correct usage - creates { tag: 'div' } object
+ * const DynamicDiv = toTag('div');
+ * const DynamicCustomElement = toTag('my-custom-element');
+ *
+ * // Usage in JSX with .tag property (required for compilation)
+ * function renderConditional({ useDiv }) {
+ *   const Tag = toTag(useDiv ? 'div' : 'span');
+ *   return <Tag.tag class="dynamic">Content</Tag.tag>;
+ * }
+ *
+ * // Compiles to efficient static templates:
+ * // const Tag = toTag(useDiv ? 'div' : 'span');
+ * // const __$Tag = __$literalMap.get(Tag.tag);
+ * // htmlStatic`<${__$Tag} class="dynamic">Content</${__$Tag}>`
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // ❌ Incorrect usage - won't compile to static templates
+ * const badTag = 'div';
+ * return <badTag>Content</badTag>; // This won't work with jsx-lit
+ *
+ * // ❌ Incorrect usage - missing .tag property
+ * const BadTag = toTag('div');
+ * return <BadTag>Content</BadTag>; // Won't compile correctly
+ *
+ * // ✅ Correct usage - with .tag property
+ * const GoodTag = toTag('div');
+ * return <GoodTag.tag>Content</GoodTag.tag>; // Compiles to static templates
+ * ```
+ *
+ * @param tag - The HTML tag name (standard HTML elements or custom element names)
+ * @returns An object with a `tag` property containing the tag name, designed for use with jsx-lit's Component syntax
+ */
+export const toTag = <T extends keyof HTMLElementTagNameMap | (string & {})>(
+	tag: T,
+): { tag: T; } => {
+	return { tag } as any;
+};