@decky.fx/raven-tsx 0.1.0 → 0.1.1

package/src/solid/plugin.ts

@@ -0,0 +1,108 @@
+/// <reference path="./babel-preset-solid.d.ts" />
+/**
+ * The Bun plugin that runs an application of `@decky.fx/raven-tsx/solid`. Bun compiles JSX as
+ * React does; Solid compiles it to calls of its renderer, with Babel (`babel-preset-solid`, in its
+ * universal mode, for the renderer of `@decky.fx/raven-tsx/solid/renderer`). And on Bun, `solid-js`
+ * resolves to its build for servers, which does not react: the plugin loads the one for clients.
+ *
+ * To run: `preload = ["@decky.fx/raven-tsx/solid/preload"]` in bunfig.toml. To build:
+ *
+ *     await Bun.build({ entrypoints: ["src/index.tsx"], plugins: [solidPlugin()], compile: true });
+ */
+
+import type { BunPlugin } from "bun";
+import { readFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+/** What the plugin can be told. */
+export interface SolidPluginOptions {
+	/** The files it compiles for Solid. All `.tsx` and `.jsx` files outside node_modules by default. */
+	readonly filter?: RegExp | undefined;
+	/** Takes the development builds of Solid, which warn of mistakes. */
+	readonly development?: boolean | undefined;
+}
+
+/** The files compiled by default: `.tsx` and `.jsx`, but those of node_modules, which come compiled. */
+const SOURCES = /^(?!.*[\\/]node_modules[\\/]).*\.[jt]sx$/;
+
+/** What `exports` of a package.json gives for a subpath, or a choice of conditions. */
+type ExportsEntry = string | null | { readonly [condition: string]: ExportsEntry };
+
+/** The entry of the first condition that is one of these, as Node picks one. */
+function pick(entry: ExportsEntry | undefined, conditions: readonly string[]): string | undefined {
+	if (typeof entry === "string") {
+		return entry;
+	}
+	for (const [condition, value] of Object.entries(entry ?? {})) {
+		const found = conditions.includes(condition) ? pick(value, conditions) : undefined;
+		if (found) {
+			return found;
+		}
+	}
+	return undefined;
+}
+
+/** The files of Solid for servers, by package folder and build, each with the file for clients that replaces it. */
+const clientFiles = new Map<string, ReadonlyMap<string, string>>();
+
+/**
+ * What replaces each build of a solid-js for servers: the one a client would take for the same
+ * import, as Node picks them from `exports` (Bun takes `node` and finds the server's).
+ */
+function clientFilesOf(root: string, development: boolean): ReadonlyMap<string, string> {
+	const key = `${root}\0${development}`;
+	let files = clientFiles.get(key);
+	if (!files) {
+		const { exports } = JSON.parse(readFileSync(`${root}/package.json`, "utf8")) as { readonly exports: Readonly<Record<string, ExportsEntry>> };
+		const map = new Map<string, string>();
+		for (const entry of Object.values(exports)) {
+			for (const style of ["import", "require"]) {
+				const server = pick(entry, ["node", style, "default"]);
+				const client = pick(entry, development ? ["browser", "development", style, "default"] : ["browser", style, "default"]);
+				if (server && client && server !== client) {
+					map.set(resolve(root, server), resolve(root, client));
+				}
+			}
+		}
+		files = map;
+		clientFiles.set(key, files);
+	}
+	return files;
+}
+
+/** The folder of the solid-js package a file of it is in. */
+const solidRoot = (path: string): string => path.slice(0, path.lastIndexOf(`${sep}solid-js${sep}`) + `${sep}solid-js`.length);
+
+/** The plugin: compiles TSX for Solid, and takes Solid's build for clients. */
+export function solidPlugin(options: SolidPluginOptions = {}): BunPlugin {
+	const development = options.development ?? false;
+	return {
+		name: "raven-tsx-solid",
+		setup(build) {
+			// (Bun runs no onResolve of a plugin for a package: the server's file is read as the client's)
+			build.onLoad({ filter: /[\\/]solid-js[\\/].*server\.c?js$/ }, ({ path }) => {
+				const client = clientFilesOf(solidRoot(path), development).get(path);
+				return { contents: readFileSync(client ?? path, "utf8"), loader: "js" };
+			});
+			build.onLoad({ filter: options.filter ?? SOURCES }, async ({ path }) => {
+				// (loaded here, so that an application of React never needs Babel)
+				const [{ transformAsync }, { default: solid }] = await Promise.all([import("@babel/core"), import("babel-preset-solid")]);
+				const typescript = /\.tsx$/.test(path);
+				const result = await transformAsync(await Bun.file(path).text(), {
+					filename: path,
+					babelrc: false,
+					configFile: false,
+					// (an error says the line of the source: Bun does not read Babel's source maps)
+					retainLines: true,
+					// (the types stay, for Bun to take away: Babel only compiles the JSX)
+					parserOpts: { plugins: typescript ? ["jsx", "typescript"] : ["jsx"] },
+					presets: [[solid, { generate: "universal", moduleName: "@decky.fx/raven-tsx/solid/renderer" }]],
+				});
+				if (typeof result?.code !== "string") {
+					throw new Error(`raven-tsx: Babel compiled nothing from ${path}`);
+				}
+				return { contents: result.code, loader: typescript ? "ts" : "js" };
+			});
+		},
+	};
+}

package/src/solid/portal.ts

@@ -0,0 +1,27 @@
+import { untrack, type JSX } from "solid-js";
+import type * as r from "../core/raven";
+import { SolidNode } from "./node";
+import { onTeardown } from "./teardown";
+import { insert } from "./renderer";
+
+/**
+ * Renders its children into a widget outside this part of the tree, as `<Portal>` of solid-js/web:
+ * context goes on as if they were here, which a second `RavenRoot` cannot do. For a widget given
+ * to Raven by hand, the content of a graph node for one:
+ *
+ *     const box = raven.Rwidget_create_from_xml("<VBox/>");
+ *     onMount(() => raven.Rnode_graph_set_node_content(graph.widget, node, box));
+ *     return <Portal widget={box}><Button>Run</Button></Portal>;
+ *
+ * What holds the widget owns it: the portal only adds and removes the children. The widget is the
+ * one it was first given.
+ */
+export function Portal(props: { readonly widget: r.Rid; readonly children?: JSX.Element | undefined }): JSX.Element {
+	const container = SolidNode.container(untrack(() => props.widget));
+	// (what it showed goes with its own owner: an element kept in a variable can be shown again. Set
+	// first: children that fail after some were placed take those away too. With the root as well:
+	// a cleanup beside it that throws stops Solid's others)
+	onTeardown(() => container.releaseAll());
+	insert(container, () => props.children);
+	return undefined;
+}

package/src/solid/preload.ts

@@ -0,0 +1,14 @@
+/**
+ * Registers the plugin of `@decky.fx/raven-tsx/solid/plugin` for what Bun runs and tests:
+ *
+ *     # bunfig.toml
+ *     preload = ["@decky.fx/raven-tsx/solid/preload"]
+ *
+ *     [test]
+ *     preload = ["@decky.fx/raven-tsx/solid/preload"]
+ */
+
+import { plugin } from "bun";
+import { solidPlugin } from "./plugin";
+
+plugin(solidPlugin());

package/src/solid/primitives.ts

@@ -0,0 +1,43 @@
+/**
+ * What React has as hooks, for Solid: each lasts as long as the component (or the root) that
+ * calls it, and goes with its cleanup.
+ */
+
+import { createEffect } from "solid-js";
+import type * as r from "../core/raven";
+import type { FrameHandler } from "../core/frame";
+import { onAction, onFrame, onShortcut } from "../core/subscriptions";
+import type { WindowInstance } from "../core/window-instance";
+import { onTeardown } from "./teardown";
+
+/**
+ * Gives a name to a function, for what fires actions by name: `Rwidget_set_action`, the
+ * `Action` of a widget made from XML, `Raction_fire`. It receives the widget that fired the action.
+ */
+export function createAction(name: string, handler: (sender: r.Rid) => void): void {
+	onTeardown(onAction(name, handler));
+}
+
+/**
+ * A keyboard shortcut of a window: `createShortcut(() => window, "Ctrl+S", save)`, with `window`
+ * set by the `ref` of a `<Window>`. It starts once the window is open. With a signal for the ref
+ * (`<Window ref={setWindow}>`, `createShortcut(window, ...)`), it follows a window that comes later.
+ */
+export function createShortcut(window: () => WindowInstance | null | undefined, keys: string, handler: () => void): void {
+	createEffect(() => {
+		const owner = window();
+		if (owner) {
+			// (each time the window opens: a window taken out of the tree closes, and opens when shown again)
+			onTeardown(owner.whenOpen(() => onShortcut(owner.window, keys, handler)));
+		}
+	});
+}
+
+/**
+ * A function called once per frame, before the layout, with the seconds since the last frame. It
+ * also runs when nothing is happening, about 60 times a second: `runApp` wakes that often so that
+ * Bun's timers run beside Raven. Any number of them can live side by side, and with `Rset_frame_callback`.
+ */
+export function createFrame(handler: FrameHandler): void {
+	onTeardown(onFrame(handler));
+}

package/src/solid/renderer.ts

@@ -0,0 +1,37 @@
+/**
+ * Solid's renderer for Raven: what TSX compiled for Solid calls (`createElement`, `insert`,
+ * `spread`...). The plugin of `@decky.fx/raven-tsx/solid/plugin` compiles it to import from here;
+ * an application imports `@decky.fx/raven-tsx/solid`.
+ */
+
+import { createRenderer } from "solid-js/universal";
+import { SolidNode } from "./node";
+
+export const {
+	render,
+	effect,
+	memo,
+	createComponent,
+	createElement,
+	createTextNode,
+	insertNode,
+	insert,
+	spread,
+	setProp,
+	mergeProps,
+	use,
+} = createRenderer<SolidNode>({
+	createElement: (tag) => SolidNode.element(tag),
+	createTextNode: (value) => SolidNode.text(value),
+	replaceText: (node, value) => node.setText(value),
+	isTextNode: (node) => node.isText,
+	setProperty: (node, name, value) => node.setProp(name, value),
+	insertNode: (parent, node, anchor) => parent.insert(node, anchor ?? null),
+	removeNode: (parent, node) => parent.release(node),
+	getParentNode: (node) => node.parent ?? undefined,
+	getFirstChild: (node) => node.children[0],
+	getNextSibling(node) {
+		const siblings = node.parent?.children ?? [];
+		return siblings[siblings.indexOf(node) + 1];
+	},
+});

package/src/solid/root.ts

@@ -0,0 +1,137 @@
+import { createComponent, createRoot, getOwner, type JSX, type Owner } from "solid-js";
+import * as r from "../core/raven";
+import { RavenError } from "../core/errors";
+import { resolveProps, type RavenProps } from "../core/props";
+import type { WindowOptions } from "../core/props.generated";
+import { makeWindow } from "../core/window-instance";
+import { Window } from "./components.generated";
+import { SolidNode } from "./node";
+import { insert } from "./renderer";
+import { stopLeft, trackRoot } from "./teardown";
+
+/**
+ * A tree of Solid, as `render` of solid-js/web. Given a widget, it renders into it.
+ * Without one, it renders `<Window>` elements, each its own window.
+ */
+export class RavenRoot {
+	private readonly node: SolidNode;
+	private dispose: (() => void) | null = null;
+	/** The owner of the tree, which keeps what it subscribed to in Raven: see `teardown`. */
+	private owner: Owner | null = null;
+
+	constructor(parent: r.Rid = r.R_INVALID_ID) {
+		this.node = SolidNode.container(parent);
+	}
+
+	/**
+	 * Renders a tree, in place of the one it had. If the tree throws, what it made goes (its cleanups
+	 * run, its widgets go) and the error goes on. (as Solid's `render`, but the root is kept before the
+	 * code runs: `render` gives it back only once the code has returned)
+	 */
+	render(code: () => JSX.Element): void {
+		this.unmount();
+		// (a cleanup may have rendered a tree again: this render replaces that one too)
+		while (this.dispose !== null) {
+			this.unmount();
+		}
+		let own: (() => void) | null = null;
+		try {
+			createRoot((dispose) => {
+				own = dispose;
+				this.dispose = dispose;
+				this.owner = getOwner();
+				if (this.owner) {
+					trackRoot(this.owner);
+				}
+				const view = code();
+				// (a render in the code replaced this one, its root with it: what it made went then)
+				if (this.dispose === dispose) {
+					insert(this.node, view);
+				}
+			});
+		} catch (error) {
+			try {
+				// (a render in the code that failed replaced it: that tree stays, this one went then)
+				if (this.dispose === own) {
+					this.unmount();
+				}
+			} catch (cleanup) {
+				console.error("raven-tsx: cleaning up a tree that failed:", cleanup);
+			}
+			throw error;
+		}
+	}
+
+	/** Removes the tree: its cleanups run, and its widgets and windows go. */
+	unmount(): void {
+		const dispose = this.dispose;
+		const owner = this.owner;
+		this.dispose = null;
+		this.owner = null;
+		try {
+			dispose?.();
+		} finally {
+			// (what it subscribed to stops, also what a cleanup that threw kept from stopping)
+			if (owner) {
+				stopLeft(owner);
+			}
+			// (the widgets and windows go, also when a cleanup threw. Unless a cleanup rendered a tree
+			// again: that one stays, and it took this one away first)
+			if (this.dispose === null) {
+				this.node.clear();
+			}
+		}
+	}
+}
+
+/** Makes a window with a place for a tree, and returns the handle of the window with its root. */
+export function createWindow(options: WindowOptions = {}): { window: r.Rid; root: RavenRoot } {
+	const { window, content } = makeWindow(resolveProps(options as RavenProps).attributes);
+	return { window, root: new RavenRoot(content) };
+}
+
+/** How `runApp` starts Raven. */
+export interface RunOptions {
+	/** The name of the application: `RInitDesc::app_name`, which system notifications show. */
+	readonly appName?: string | undefined;
+	/** Runs after Raven started and before the first render: for a look, a theme, a registered tag. */
+	readonly setup?: (() => void) | undefined;
+	/** Raven's allocator: functions of C only, as it allocates on several threads. See `Rset_allocator`. */
+	readonly allocator?: Parameters<typeof r.Rset_allocator>[0] | undefined;
+}
+
+/**
+ * Starts Raven, shows a tree and runs until the last window closes, the event loop of Bun
+ * running beside it. Then the tree is cleaned up and Raven stops, also when the run ends with an
+ * error, so that it can start again.
+ *
+ * With options, the tree goes in one window made from them. Without, the tree says what windows
+ * there are, with `<Window>` elements.
+ *
+ *     await runApp(() => <App />, { Title: "Hello", Width: 480, Height: 240 });
+ */
+export async function runApp(code: () => JSX.Element, options?: WindowOptions, start?: RunOptions): Promise<void> {
+	if (start?.allocator) {
+		r.Rset_allocator(start.allocator);
+	}
+	const desc = new r.RInitDesc();
+	desc.backend = r.R_BACKEND_VULKAN;
+	desc.app_name = start?.appName ?? null;
+	if (!r.Rinit_ex(desc)) {
+		RavenError.fromLibrary("Raven cannot start");
+	}
+	let root: RavenRoot | null = null;
+	try {
+		start?.setup?.();
+		root = new RavenRoot();
+		root.render(options ? () => createComponent(Window, { ...options, get children() { return code(); } }) : code);
+		// (Rwait_frame ends once the last window closed: until there was one, it goes on)
+		await r.runLoop();
+	} finally {
+		try {
+			root?.unmount();
+		} finally {
+			r.Rshutdown();
+		}
+	}
+}

package/src/solid/tag.ts

@@ -0,0 +1,37 @@
+/** How a tag of Raven becomes a Solid component: what the generated components are made with. */
+
+import { getOwner, runWithOwner, splitProps, type JSX } from "solid-js";
+import { WidgetInstance, type HostNode } from "../core/widget-instance";
+import { SolidNode } from "./node";
+import { spread } from "./renderer";
+
+/** The props every component has from Solid. */
+export interface SolidProps<R> {
+	/** Receives the widget (or the window) as React's `ref` does: `WidgetInstance`, `WindowInstance`. */
+	readonly ref?: R | ((instance: R) => void) | undefined;
+	readonly children?: JSX.Element | undefined;
+}
+
+/**
+ * A component for a tag of Raven, or one given to `Rxml_register_tag` with its props.
+ * JSX takes a capitalized name for a component, not for a tag.
+ */
+export function tag<P extends object, R = WidgetInstance>(name: string): (props: P & SolidProps<R>) => JSX.Element {
+	return (props) => {
+		const node = SolidNode.element(name);
+		const [local, others] = splitProps(props, ["ref"]);
+		spread(node, others);
+		// (Solid compiles `ref={variable}` to a function that sets the variable. As React's, it comes
+		// once Raven has the widget, placed: a window comes at once, as it opens only when placed)
+		const ref = local.ref;
+		if (typeof ref === "function") {
+			// (under the owner of the element, also when it comes later: what it makes goes with the
+			// element, and what it throws reaches the ErrorBoundary around it)
+			const owner = getOwner();
+			const give = (instance: HostNode): void => void runWithOwner(owner, () => (ref as (instance: R) => void)(instance as R));
+			node.withInstance((instance) => (instance instanceof WidgetInstance ? instance.whenPlaced(give) : give(instance)));
+		}
+		// (a node of Raven: Solid's JSX types know only the nodes of the DOM)
+		return node as unknown as JSX.Element;
+	};
+}

package/src/solid/tags.ts

@@ -0,0 +1,101 @@
+/**
+ * Solid components as tags of Raven: what `<Widget Name="...">` does in XML, with a component.
+ * The core does the part that speaks to Raven; this renders the component, a root of its own per
+ * element, whose props follow what the element in XML gives.
+ */
+
+import { $PROXY, createComponent, createRoot, createSignal, getOwner, runWithOwner, type Component, type JSX, type Owner } from "solid-js";
+import type * as r from "../core/raven";
+import { registerTagWith, type TagAdapter, type TagContent, type TagOptions as CoreTagOptions } from "../core/tags";
+import { RavenError } from "../core/errors";
+import { SolidNode } from "./node";
+import { RavenRoot } from "./root";
+
+/** What a tag takes from its element. */
+export type TagOptions<P> = CoreTagOptions<P, JSX.Element>;
+
+/** What a registered component is given: its attributes, and its places with their widgets. */
+type TagProps = Readonly<Record<string, string | number | boolean | JSX.Element>>;
+
+/**
+ * The props of a component, read from what its element gives now: a prop read in an effect or in
+ * JSX follows the element. The widgets of its children are placed where it renders them.
+ * Their nodes belong to `owner`, which lasts as long as the element: hiding one does not delete it.
+ */
+function propsOf(content: () => TagContent, owner: Owner | null): TagProps {
+	// (a widget keeps its node, so that Solid sees the same child and does not move it)
+	const nodes = new Map<r.Rid, SolidNode>();
+	const adopted = (widgets: readonly r.Rid[]): JSX.Element => {
+		if (widgets.length === 0) {
+			return undefined;
+		}
+		return widgets.map((widget) => {
+			let node = nodes.get(widget);
+			if (!node) {
+				// (not the owner of what reads `children`: `{shown() && props.children}` would delete it when hidden)
+				const made = runWithOwner(owner, () => SolidNode.adopted(widget));
+				// (Solid gives nothing back when what it ran threw to a boundary of the owner, which has none)
+				if (!made) {
+					RavenError.throw("raven-tsx: the child of a registered tag could not be adopted");
+				}
+				node = made;
+				nodes.set(widget, node);
+			}
+			return node as unknown as JSX.Element;
+		});
+	};
+	const read = (): Record<string, string | number | boolean | JSX.Element> => {
+		const { attributes, slots, children } = content();
+		const places = Object.fromEntries(Object.entries(slots).map(([name, widgets]) => [name, adopted(widgets)]));
+		return { ...attributes, ...places, children: adopted(children) };
+	};
+	// (`$PROXY` says to Solid that the keys can change: `splitProps` then reads through, and sees a key added later)
+	return new Proxy({} as TagProps, {
+		get: (_, key, receiver) => (key === $PROXY ? receiver : typeof key === "string" ? read()[key] : undefined),
+		has: (_, key) => key === $PROXY || (typeof key === "string" && key in read()),
+		ownKeys: () => Object.keys(read()),
+		getOwnPropertyDescriptor: (_, key) => (typeof key === "string" && key in read() ? { configurable: true, enumerable: true, get: () => read()[key] } : undefined),
+	});
+}
+
+/** Renders a registered component in a root of its own. */
+const solidAdapter: TagAdapter<Component<TagProps>> = {
+	mount(component, content, container) {
+		const [current, setCurrent] = createSignal(content, { equals: false });
+		// (the nodes of its children: they go after the tree, those it holds deleted with it, the others then)
+		const [owner, disposeNodes] = createRoot((dispose) => [getOwner(), dispose] as const);
+		const props = propsOf(current, owner);
+		const root = new RavenRoot(container);
+		try {
+			root.render(() => createComponent(component, props));
+		} catch (error) {
+			// (the render cleaned up its tree; the nodes of the children have a root of their own)
+			try {
+				disposeNodes();
+			} catch (cleanup) {
+				console.error("raven-tsx: cleaning up a tag that failed:", cleanup);
+			}
+			throw error;
+		}
+		return {
+			update: (next) => setCurrent(next),
+			unmount: () => {
+				try {
+					root.unmount();
+				} finally {
+					disposeNodes();
+				}
+			},
+		};
+	},
+};
+
+/**
+ * Makes a component a tag Raven knows, built from XML as its own tags are: in documents, in
+ * `Markup`, in files. Its attributes become props of the kinds given; the widgets of its children
+ * are placed where it renders `children`, and those of `<Into Name="...">` where it renders the
+ * prop of that name. Registering a name again replaces it. Returns what unregisters it.
+ */
+export function registerTag<P extends object>(name: string, component: Component<P>, options: TagOptions<P> = {}): () => void {
+	return registerTagWith<Component<TagProps>, P, JSX.Element>(solidAdapter, name, component as unknown as Component<TagProps>, options);
+}

package/src/solid/teardown.ts

@@ -0,0 +1,50 @@
+/**
+ * What the primitives subscribe to in Raven, kept by the root of the tree as well as by Solid's
+ * cleanup. Solid runs the cleanups of an owner without catching: one that throws stops the others,
+ * and an action would still be bound after its component went. The root stops what is left.
+ */
+
+import { getOwner, onCleanup, type Owner } from "solid-js";
+
+/** What each root of a tree keeps, to stop at its end what its cleanups did not. */
+const roots = new WeakMap<Owner, Set<() => void>>();
+
+/** Says that an owner is the root of a tree, which keeps what is subscribed under it. */
+export function trackRoot(owner: Owner): void {
+	roots.set(owner, new Set());
+}
+
+/**
+ * Stops a subscription with the cleanup of the current owner, or with the end of its root if a
+ * cleanup that throws comes first. It stops once.
+ */
+export function onTeardown(stop: () => void): void {
+	let kept: Set<() => void> | undefined;
+	let done = false;
+	const run = (): void => {
+		if (done) {
+			return;
+		}
+		done = true;
+		kept?.delete(run);
+		stop();
+	};
+	for (let owner = getOwner(); owner && !kept; owner = owner.owner) {
+		kept = roots.get(owner);
+	}
+	kept?.add(run);
+	onCleanup(run);
+}
+
+/** Stops what a root still keeps, after its cleanups ran: those a cleanup that threw left. */
+export function stopLeft(owner: Owner): void {
+	const kept = roots.get(owner);
+	roots.delete(owner);
+	for (const run of [...(kept ?? [])]) {
+		try {
+			run();
+		} catch (error) {
+			console.error("raven-tsx: stopping what a tree subscribed to:", error);
+		}
+	}
+}

package/src/solid/web.ts

@@ -0,0 +1,5 @@
+import type { WebViewProps } from "../core/web";
+import { tag } from "./tag";
+
+/** A page of the web, after `registerWebView`. */
+export const WebView = tag<WebViewProps>("WebView");