@decky.fx/raven-tsx 0.0.0-stage → 0.1.0

package/src/react/root.ts

@@ -0,0 +1,119 @@
+import { createElement, type ReactNode, type ReactPortal } from "react";
+import { ConcurrentRoot } from "react-reconciler/constants";
+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 { WidgetInstance } from "../core/widget-instance";
+import { makeWindow } from "../core/window-instance";
+import { Window } from "./components.generated";
+import { reconciler } from "./host-config";
+
+/** Says what a component threw during a render or an effect. */
+function report(error: unknown): void {
+	console.error("raven-tsx: error in a component:", error);
+}
+
+/**
+ * A tree of React, as `createRoot` of ReactDOM. Given a widget, it renders into it.
+ * Without one, it renders `<Window>` elements, each its own window.
+ */
+export class RavenRoot {
+	private readonly root: ReturnType<typeof reconciler.createContainer>;
+
+	constructor(parent: r.Rid = r.R_INVALID_ID) {
+		this.root = reconciler.createContainer(
+			WidgetInstance.forContainer(parent), ConcurrentRoot, null, false, null, "raven-tsx", report, report, report, () => {}, null,
+		);
+	}
+
+	/** Renders or updates the tree. */
+	render(element: ReactNode): void {
+		reconciler.updateContainer(element, this.root, null, null);
+	}
+
+	/** Removes the tree and runs the cleanups of its effects, now. */
+	unmount(): void {
+		reconciler.updateContainerSync(null, this.root, null, null);
+		reconciler.flushSyncWork();
+		reconciler.flushPassiveEffects();
+	}
+}
+
+/** What portals render into, by handle: React takes a container that changes as another place. */
+const portalContainers = new Map<r.Rid, WidgetInstance>();
+
+/**
+ * Renders children into a widget outside this part of the tree, as `createPortal` of ReactDOM:
+ * 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] = useState(() => raven.Rwidget_create_from_xml("<VBox/>"));
+ *     useLayoutEffect(() => raven.Rnode_graph_set_node_content(graph, node, box), [graph, node, box]);
+ *     return createPortal(<Button>Run</Button>, box);
+ *
+ * What holds the widget owns it: the portal only adds and removes the children.
+ */
+export function createPortal(children: ReactNode, widget: r.Rid, key: string | null = null): ReactPortal {
+	for (const id of portalContainers.keys()) {
+		if (!r.Rwidget_is_valid(id)) {
+			portalContainers.delete(id);
+		}
+	}
+	let container = portalContainers.get(widget);
+	if (!container) {
+		container = WidgetInstance.forContainer(widget);
+		portalContainers.set(widget, container);
+	}
+	return reconciler.createPortal(children, container, null, key);
+}
+
+/** 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 effects are 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.
+ */
+export async function runApp(element: ReactNode, 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 ? createElement(Window, options, element) : element);
+		// (React commits in the loop, and makes the windows then. Rwait_frame ends once the last one closed: until there was one, it goes on)
+		await r.runLoop();
+	} finally {
+		try {
+			root?.unmount();
+		} finally {
+			r.Rshutdown();
+		}
+	}
+}

package/src/react/tags.ts

@@ -0,0 +1,50 @@
+/**
+ * React 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, so context does not reach it from the tree around it.
+ */
+
+import { createElement, type ComponentType, type ReactNode } from "react";
+import * as r from "../core/raven";
+import { registerTagWith, type TagAdapter, type TagContent, type TagOptions as CoreTagOptions } from "../core/tags";
+import { ADOPTED_TAG } from "../core/widget-instance";
+import { RavenRoot } from "./root";
+
+/** What a tag takes from its element. */
+export type TagOptions<P> = CoreTagOptions<P, ReactNode>;
+
+/** What a registered component is given: its attributes, and its places with their widgets. */
+type TagProps = Readonly<Record<string, string | number | boolean | ReactNode>>;
+
+/** The elements of adopted widgets, in their order. */
+function adopted(widgets: readonly r.Rid[]): ReactNode {
+	return widgets.length === 0 ? undefined : widgets.map((widget) => createElement(ADOPTED_TAG, { key: widget, widget }));
+}
+
+/** The element of a component, with what its element in XML gives it. */
+function elementOf(component: ComponentType<TagProps>, content: TagContent): ReactNode {
+	const slots = Object.fromEntries(Object.entries(content.slots).map(([name, widgets]) => [name, adopted(widgets)]));
+	return createElement(component, { ...content.attributes, ...slots, children: adopted(content.children) });
+}
+
+/** Renders a registered component in a root of its own. */
+const reactAdapter: TagAdapter<ComponentType<TagProps>> = {
+	mount(component, props, container) {
+		const root = new RavenRoot(container);
+		root.render(elementOf(component, props));
+		return {
+			update: (next) => root.render(elementOf(component, next)),
+			unmount: () => root.unmount(),
+		};
+	},
+};
+
+/**
+ * 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: ComponentType<P>, options: TagOptions<P> = {}): () => void {
+	return registerTagWith<ComponentType<TagProps>, P, ReactNode>(reactAdapter, name, component as ComponentType<TagProps>, options);
+}

package/src/react/web.ts

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