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

package/src/core/props.ts

@@ -0,0 +1,158 @@
+import type { ThemeColor } from "./theme";
+
+/** A function given to an `On...` prop. What it receives depends on the widget and the event. */
+export type EventHandler = (...values: never[]) => void;
+
+/** A row of a `TreeView` given by its `Items` prop, with the rows inside it. */
+export interface TreeItem {
+	readonly Text: string;
+	readonly Expanded?: boolean | undefined;
+	readonly Children?: readonly TreeItem[] | undefined;
+}
+
+/** Numbers given to Raven as they are: a list, or a typed array when there are many. */
+export type PlotNumbers = Float64Array | readonly number[];
+
+/** A curve of a `Plot`: what `<Series>` is in XML. Curves are known by their place in the list. */
+export interface PlotSeries {
+	/** Its name in the legend. Without one it is not in the legend. */
+	readonly Name?: string | undefined;
+	/** The Y of its points; NaN leaves a gap. New values are a new array: the same array is taken for the same values. */
+	readonly Y?: PlotNumbers | undefined;
+	/** The X of its points, as many as Y. Without it they are numbered 0, 1, 2... */
+	readonly X?: PlotNumbers | undefined;
+	readonly Color?: ThemeColor | undefined;
+	/** `None` leaves only the markers: a scatter plot. */
+	readonly Line?: "Solid" | "Dashed" | "Dotted" | "DashDot" | "None" | undefined;
+	readonly LineWidth?: number | undefined;
+	readonly Marker?: "None" | "Circle" | "Square" | "Diamond" | "TriangleUp" | "TriangleDown" | "Cross" | "Plus" | "Asterisk" | undefined;
+	readonly MarkerSize?: number | undefined;
+	readonly MarkerFilled?: boolean | undefined;
+	/** Draws the line in steps. */
+	readonly Step?: boolean | undefined;
+	/** The opacity of the area between the line and zero, from 0 to 1. */
+	readonly Fill?: number | undefined;
+	readonly XAxis?: "X" | "X2" | undefined;
+	readonly YAxis?: "Y" | "Y2" | undefined;
+	/** The user also hides a series, from the legend. */
+	readonly Visible?: boolean | undefined;
+	/** Keeps only the last points, for data that streams in with `Rplot_add_point`. */
+	readonly MaxPoints?: number | undefined;
+}
+
+/** A line across the data of a `Plot` that the user drags: what `<DragLine>` is in XML. */
+export interface PlotDragLine {
+	readonly Value: number;
+	/** `X` or `X2` makes it vertical, `Y` or `Y2` horizontal. `X` by default. */
+	readonly Axis?: "X" | "Y" | "X2" | "Y2" | undefined;
+	/** Written on the line, before its value. */
+	readonly Label?: string | undefined;
+	readonly Color?: ThemeColor | undefined;
+}
+
+/** A prop given to Raven by calling it, as it is, and never as text. */
+export type DataValue = readonly PlotSeries[] | readonly PlotDragLine[];
+
+/** One value of an attribute, in the forms a component accepts. */
+export type AttributeValue = string | number | boolean | readonly string[] | readonly number[] | readonly TreeItem[];
+
+/** `Slot={{ Padding: 24 }}`: JSX has no dots in names, so `Slot.Padding` is written as a group. */
+export type AttributeGroup = { readonly [key: string]: AttributeValue | null | undefined };
+
+/** What an attribute holds for `null` in a group: `Color={{ Text: null }}` takes the override away. */
+export const CLEARED = "\0cleared";
+
+/**
+ * A prop of a component. `Child` is what an adapter's framework gives as children: the core only
+ * looks in it for text (`childrenText`), so it has no need to know that type.
+ */
+export type PropValue<Child = never> = AttributeValue | AttributeGroup | EventHandler | DataValue | Child | null | undefined;
+
+/** The props of a widget, as an adapter gives them. */
+export type RavenProps<Child = never> = { readonly [name: string]: PropValue<Child> };
+
+/** What props mean for a widget once they are read. */
+export interface ResolvedProps {
+	/** Attribute name to its text, as XML would hold it. */
+	readonly attributes: ReadonlyMap<string, string>;
+	/** `On...` name to its function. */
+	readonly handlers: ReadonlyMap<string, EventHandler>;
+	/** The props of `dataProps`, by name, as they were given. */
+	readonly data: ReadonlyMap<string, DataValue>;
+}
+
+/** Tells whether a prop is a function. */
+function isHandler<Child>(value: PropValue<Child>): value is EventHandler {
+	return typeof value === "function";
+}
+
+/** Tells whether a prop is a group of attributes, as opposed to a list or an element of a framework, which marks itself with a symbol. */
+function isGroup<Child>(value: PropValue<Child>): value is AttributeGroup {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && !Object.values(value).some((item) => typeof item === "symbol");
+}
+
+/** An attribute value as text: lists of numbers are comma separated, and lists of texts `|` separated. */
+function toText(value: AttributeValue): string {
+	if (typeof value === "string") {
+		return value;
+	}
+	if (typeof value === "number" || typeof value === "boolean") {
+		return String(value);
+	}
+	if (value.some((item) => typeof item === "object")) {
+		return JSON.stringify(value);
+	}
+	return value.every((item) => typeof item === "number") ? value.join(",") : value.join("|");
+}
+
+/**
+ * The text held by the children of a widget, or null when they are not only text:
+ * `<Label>Clicked {count} times</Label>` has the children `["Clicked ", 3, " times"]`.
+ */
+export function childrenText<Child>(children: PropValue<Child>): string | null {
+	if (typeof children === "string" || typeof children === "number") {
+		return String(children);
+	}
+	if (Array.isArray(children) && children.length > 0 && children.every((item) => typeof item === "string" || typeof item === "number")) {
+		return children.join("");
+	}
+	return null;
+}
+
+/**
+ * Reads props into attributes and handlers. Text in the children means the attribute `Text`.
+ * The props named in `dataProps` are kept as they are: they do not go through XML.
+ */
+export function resolveProps<Child>(props: RavenProps<Child>, dataProps: readonly string[] = []): ResolvedProps {
+	const attributes = new Map<string, string>();
+	const handlers = new Map<string, EventHandler>();
+	const data = new Map<string, DataValue>();
+	for (const [name, value] of Object.entries(props)) {
+		if (name === "children" || name === "key" || name === "ref" || value === undefined || value === null) {
+			continue;
+		}
+		if (dataProps.includes(name)) {
+			data.set(name, value as DataValue);
+		} else if (isHandler(value)) {
+			handlers.set(name, value);
+		} else if (isGroup(value)) {
+			for (const [key, item] of Object.entries(value)) {
+				if (item !== undefined) {
+					attributes.set(`${name}.${key}`, item === null ? CLEARED : toText(item));
+				}
+			}
+		} else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value)) {
+			attributes.set(name, toText(value));
+		}
+	}
+	const text = childrenText(props["children"]);
+	if (text !== null) {
+		attributes.set("Text", text);
+	}
+	return { attributes, handlers, data };
+}
+
+/** Text with what XML would take for markup escaped, for an attribute value. */
+export function escapeXml(text: string): string {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}

package/src/core/raven.ts

@@ -0,0 +1,10 @@
+/**
+ * The binding of Raven. It opens the library as soon as it is imported, so `./native`
+ * comes first. Everything in this package imports Raven from here.
+ */
+
+import "./native";
+
+export * from "../vendor/raven";
+// (shared with onFrame: a name given here has priority over the one of `export *`)
+export { Rset_frame_callback } from "./frame";

package/src/core/subscriptions.ts

@@ -0,0 +1,78 @@
+/**
+ * What Raven tells the application, as plain subscriptions: each returns the function that stops
+ * it. An adapter wraps these in what its framework offers, the hooks of React for one.
+ */
+
+import * as r from "./raven";
+import { RavenError } from "./errors";
+import { actionEvents, eventScope } from "./events";
+import { frameSlot, type FrameHandler } from "./frame";
+
+const MODIFIERS: Readonly<Record<string, number>> = {
+	ctrl: r.R_MOD_CTRL,
+	control: r.R_MOD_CTRL,
+	shift: r.R_MOD_SHIFT,
+	alt: r.R_MOD_ALT,
+	super: r.R_MOD_SUPER,
+	cmd: r.R_MOD_SUPER,
+};
+
+/** Keys that are not spelled as in `R_KEY_...`. */
+const KEY_NAMES: Readonly<Record<string, string>> = { esc: "ESCAPE", del: "DELETE", return: "ENTER", pgup: "PAGE_UP", pgdn: "PAGE_DOWN" };
+
+/** Reads `"Ctrl+Shift+S"` or `"F5"` into a key and its modifiers. */
+export function parseKeys(keys: string): { key: r.RKey; modifiers: number } {
+	let modifiers = 0;
+	let key: r.RKey | undefined;
+	for (const part of keys.split("+")) {
+		const name = part.trim().toLowerCase();
+		const modifier = MODIFIERS[name];
+		if (modifier !== undefined) {
+			modifiers |= modifier;
+		} else {
+			key = r.RKey[`R_KEY_${KEY_NAMES[name] ?? name.toUpperCase()}` as keyof typeof r.RKey];
+		}
+	}
+	if (key === undefined) {
+		RavenError.throw(`raven-tsx: no key in the shortcut "${keys}"`);
+	}
+	return { key, modifiers };
+}
+
+/**
+ * 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. Returns what takes the name away.
+ */
+export function onAction(name: string, handler: (sender: r.Rid) => void): () => void {
+	// (a function of its own: the same handler given twice is two registrations)
+	const registered = (sender: r.Rid): void => handler(sender);
+	actionEvents.bind(name, registered);
+	return () => actionEvents.unbind(name, registered);
+}
+
+let nextShortcut = 0;
+
+/** A keyboard shortcut of a window: `onShortcut(window, "Ctrl+S", save)`. Returns what takes it away. */
+export function onShortcut(window: r.Rid, keys: string, handler: () => void): () => void {
+	const { key, modifiers } = parseKeys(keys);
+	const name = `raven-tsx.shortcut.${++nextShortcut}`;
+	actionEvents.bind(name, () => handler());
+	r.Rwindow_register_shortcut(window, key, modifiers, name);
+	return () => {
+		// (the window can be gone already: without an `OnClose`, the user closes it at any time)
+		if (r.Rwindow_is_valid(window) !== 0) {
+			r.Rwindow_unregister_shortcut(window, key, modifiers);
+		}
+		actionEvents.unbind(name);
+	};
+}
+
+/**
+ * A function called once per frame, before the layout, with the seconds since the last frame:
+ * what it changes is committed in time for that frame. Any number of them can live side by side,
+ * and with `Rset_frame_callback`. Returns what takes it away.
+ */
+export function onFrame(handler: FrameHandler): () => void {
+	return frameSlot.subscribe((delta) => eventScope.run(() => handler(delta)));
+}

package/src/core/tags.ts

@@ -0,0 +1,307 @@
+/**
+ * Components as tags of Raven: what a `<Widget Name="...">` declaration of XML does, with a
+ * component instead. Raven then builds the component from XML (a document, `Markup`, a file of
+ * someone else) as it builds `<Button>`:
+ *
+ *     registerTag("Card", Card, { attributes: { Title: "string", Wide: "boolean" }, slots: ["footer"] });
+ *     // <Card Title="Sales"><Stat/><Into Name="footer"><Button/></Into></Card>
+ *
+ * This is the half that speaks to Raven: the callbacks, the attributes, the widgets of the children.
+ * A framework comes in through a `TagAdapter`, which only knows how to render a component into a widget.
+ */
+
+import { CString, JSCallback, type Pointer } from "bun:ffi";
+import { RavenError } from "./errors";
+import * as r from "./raven";
+
+/** How the text of an attribute becomes a prop. */
+export type AttributeKind = "string" | "number" | "boolean";
+
+/** The kind of attribute a prop can be given from, or never for a prop text cannot give. */
+type KindOf<T> = T extends string ? "string" : T extends number ? "number" : T extends boolean ? "boolean" : never;
+
+/**
+ * The props of a component that take widgets, by the `Node` of its framework: its places for the
+ * children of `<Into>`. (in brackets, so that a prop taking only a part of `Node`, a `string`, is not one)
+ */
+type SlotOf<P, Node> = { [K in keyof P]-?: K extends "children" ? never : [Node] extends [P[K]] ? K : never }[keyof P];
+
+/** What a tag takes from its element. `Node` is what its framework renders. */
+export interface TagOptions<P, Node> {
+	/** The attributes it takes, each with the kind of its prop. The others stay the widget's: `Name`, `Width`, `Slot`... */
+	readonly attributes?: { readonly [K in keyof P]?: KindOf<NonNullable<P[K]>> | undefined } | undefined;
+	/** Its props that take widgets, by name: the children of `<Into Name="...">` go there; the other children go to `children`. */
+	readonly slots?: readonly SlotOf<P, Node>[] | undefined;
+}
+
+/** What an element gives its component: its attributes, and the widgets Raven made for its children. */
+export interface TagContent {
+	/** The props taken from attributes. */
+	readonly attributes: Readonly<Record<string, string | number | boolean>>;
+	/** The widgets of its children, for an adapter to show as adopted (`WidgetInstance.adopt`). */
+	readonly children: readonly r.Rid[];
+	/** The widgets of its named places, by name. */
+	readonly slots: Readonly<Record<string, readonly r.Rid[]>>;
+}
+
+/** A component rendered in a widget of a tag, as an adapter gives it back. */
+export interface TagMount {
+	/** Renders the component again, with what it has now. */
+	update(props: TagContent): void;
+	/** Takes the component away. Its widget stays: Raven destroys that. */
+	unmount(): void;
+}
+
+/** How a framework shows a registered component in a widget. `Component` is its kind of component. */
+export interface TagAdapter<Component> {
+	/** Renders a component into a widget, which it fills, and returns how to change it and take it away. */
+	mount(component: Component, props: TagContent, container: r.Rid): TagMount;
+}
+
+/** A registered tag. */
+interface Registration {
+	readonly mount: (props: TagContent, container: r.Rid) => TagMount;
+	readonly attributes: Readonly<Record<string, AttributeKind>>;
+	readonly slots: ReadonlySet<string>;
+}
+
+/** An element of a registered tag, as Raven built it. */
+interface Element {
+	readonly tag: string;
+	readonly widget: r.Rid;
+	props: Record<string, string | number | boolean>;
+	/** The widgets of the children of the element, once Raven added them all. */
+	children: readonly r.Rid[];
+	slots: Record<string, readonly r.Rid[]>;
+	/** Rendered once its children are known: until then, attributes are only kept. */
+	ready: boolean;
+	/** The widgets of its children, which the adapter only places: those it does not show are destroyed with the element. */
+	adopted: readonly r.Rid[];
+	/** Its component, with the registration it came from: a tag registered again renders the new one. */
+	mounted: { readonly registration: Registration; readonly mount: TagMount } | null;
+}
+
+/** The tag that sends its children to a named place of the component around it. */
+const INTO = "Into";
+
+const registrations = new Map<string, Registration>();
+const elements = new Map<r.Rid, Element>();
+/** The widgets of `<Into>` elements, with the name of their place. */
+const intos = new Set<r.Rid>();
+
+/** The children of a widget, in order. */
+function childrenOf(widget: r.Rid): r.Rid[] {
+	return Array.from({ length: r.Rwidget_get_child_count(widget) }, (_, index) => r.Rwidget_get_child(widget, index));
+}
+
+/** Renders an element with what it has now, through the adapter of its tag. */
+function render(element: Element): void {
+	const registration = registrations.get(element.tag);
+	if (!registration || !element.ready) {
+		return;
+	}
+	const content: TagContent = { attributes: element.props, children: element.children, slots: element.slots };
+	if (element.mounted?.registration === registration) {
+		element.mounted.mount.update(content);
+		return;
+	}
+	// (forgotten first: taken away once, even if this or the new mount throws)
+	const previous = element.mounted;
+	element.mounted = null;
+	previous?.mount.unmount();
+	element.mounted = { registration, mount: registration.mount(content, element.widget) };
+}
+
+/**
+ * Raven adds the children of an element after making it, and before its attributes: once the
+ * call that built it returns, they are all there, and go to their places.
+ */
+function place(widget: r.Rid, element: Element): void {
+	const registration = registrations.get(element.tag);
+	const children: r.Rid[] = [];
+	const slots: Record<string, r.Rid[]> = {};
+	// (each one taken out is the element's at once: destroyed with it, even if this stops half way)
+	const taken: r.Rid[] = [];
+	element.adopted = taken;
+	for (const child of childrenOf(widget)) {
+		if (!intos.has(child)) {
+			// (taken out, as those of <Into>: only what the component renders is shown)
+			r.Rwidget_remove_child(widget, child);
+			taken.push(child);
+			children.push(child);
+			continue;
+		}
+		const name = r.Rwidget_get_name(child) ?? "";
+		const inside = childrenOf(child);
+		if (registration?.slots.has(name)) {
+			slots[name] = [...(slots[name] ?? []), ...inside];
+		} else {
+			console.error(`raven-tsx: <${element.tag}>: <Into Name="${name}">: no place of this name; its widgets go with the others`);
+			children.push(...inside);
+		}
+		// (the widgets it held are taken out of it first: the adapter places them)
+		for (const held of inside) {
+			r.Rwidget_remove_child(child, held);
+			taken.push(held);
+		}
+		intos.delete(child);
+		r.Rwidget_destroy(child);
+	}
+	element.adopted = [...children, ...Object.values(slots).flat()];
+	element.children = children;
+	element.slots = slots;
+	element.ready = true;
+	render(element);
+}
+
+/** Makes the widget of an element: a box the adapter renders the component into. */
+function create(tag: string): r.Rid {
+	const widget = r.Rwidget_create_from_xml("<VBox/>");
+	if (tag === INTO) {
+		intos.add(widget);
+		r.Rwidget_set_destroy_callback(widget, nativeCallbacks().destroy);
+		return widget;
+	}
+	const element: Element = { tag, widget, props: {}, children: [], slots: {}, ready: false, adopted: [], mounted: null };
+	elements.set(widget, element);
+	r.Rwidget_set_destroy_callback(widget, nativeCallbacks().destroy);
+	queueMicrotask(() => {
+		try {
+			if (elements.get(widget) === element) {
+				place(widget, element);
+			}
+		} catch (error) {
+			console.error(`raven-tsx: error placing the children of <${tag}>:`, error);
+		}
+	});
+	return widget;
+}
+
+/** The prop of an attribute, or null when the text is not of its kind. */
+function parse(kind: AttributeKind, value: string): string | number | boolean | null {
+	if (kind === "string") {
+		return value;
+	}
+	if (kind === "number") {
+		const number = Number(value);
+		return value.trim() !== "" && Number.isFinite(number) ? number : null;
+	}
+	return value === "true" ? true : value === "false" ? false : null;
+}
+
+/** Takes an attribute of an element, if its component has a prop for it. */
+function setAttribute(widget: r.Rid, name: string, value: string): boolean {
+	const element = elements.get(widget);
+	const kind = element ? registrations.get(element.tag)?.attributes[name] : undefined;
+	if (!element || !kind) {
+		return false;
+	}
+	const prop = parse(kind, value);
+	if (prop === null) {
+		return false;
+	}
+	element.props = { ...element.props, [name]: prop };
+	render(element);
+	return true;
+}
+
+/** Unmounts the component of an element whose widget Raven destroys. */
+function destroyed(widget: r.Rid): void {
+	const element = elements.get(widget);
+	elements.delete(widget);
+	intos.delete(widget);
+	try {
+		element?.mounted?.mount.unmount();
+	} finally {
+		// (those in its tree went with it; those the component did not show are held by nothing)
+		for (const child of element?.adopted ?? []) {
+			if (r.Rwidget_is_valid(child) && r.Rwidget_get_parent(child) === r.R_INVALID_ID) {
+				r.Rwidget_destroy(child);
+			}
+		}
+	}
+}
+
+/** The pointers of the functions Raven calls for every registered tag and element. */
+interface NativeCallbacks {
+	readonly create: Pointer;
+	readonly attribute: Pointer;
+	readonly destroy: Pointer;
+}
+
+/** Made once and shared by every tag and element: a callback given to Raven stays alive for good. */
+let callbacks: NativeCallbacks | null = null;
+
+/** The pointers of the callbacks, made on first use. */
+function nativeCallbacks(): NativeCallbacks {
+	if (!callbacks) {
+		const make = new JSCallback((tag: Pointer | null): number => {
+			try {
+				return create(tag ? new CString(tag).toString() : "");
+			} catch (error) {
+				console.error("raven-tsx: error making a registered tag:", error);
+				return r.R_INVALID_ID;
+			}
+		}, { args: ["ptr", "ptr"], returns: "u32" });
+		const attribute = new JSCallback((widget: number, name: Pointer | null, value: Pointer | null): number => {
+			try {
+				return name && value && setAttribute(widget, new CString(name).toString(), new CString(value).toString()) ? 1 : 0;
+			} catch (error) {
+				console.error("raven-tsx: error giving an attribute to a registered tag:", error);
+				return 0;
+			}
+		}, { args: ["u32", "ptr", "ptr", "ptr"], returns: "i32" });
+		const destroy = new JSCallback((widget: number): void => {
+			try {
+				destroyed(widget);
+			} catch (error) {
+				console.error("raven-tsx: error unmounting a registered tag:", error);
+			}
+		}, { args: ["u32", "ptr"], returns: "void" });
+		if (!make.ptr || !attribute.ptr || !destroy.ptr) {
+			RavenError.throw("raven-tsx: cannot make the callbacks of registered tags");
+		}
+		callbacks = { create: make.ptr, attribute: attribute.ptr, destroy: destroy.ptr };
+	}
+	return callbacks;
+}
+
+/** Registers `<Into>`, which every registered tag uses for its named places. */
+function registerInto(): void {
+	if (!r.Rxml_is_tag_registered(INTO)) {
+		const { create: make, attribute } = nativeCallbacks();
+		if (!r.Rxml_register_tag(INTO, make, attribute)) {
+			RavenError.fromLibrary("registerTag: <Into>");
+		}
+	}
+}
+
+/**
+ * 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. An
+ * adapter calls this with what renders its components, and gives the application its own `registerTag`.
+ */
+export function registerTagWith<Component, P extends object, Node>(adapter: TagAdapter<Component>, name: string, component: Component, options: TagOptions<P, Node> = {}): () => void {
+	if (name === INTO) {
+		RavenError.throw(`registerTag: <${INTO}> is the tag of the named places of registered tags`);
+	}
+	registerInto();
+	const { create: make, attribute } = nativeCallbacks();
+	if (!r.Rxml_register_tag(name, make, attribute)) {
+		RavenError.fromLibrary(`registerTag(${JSON.stringify(name)})`);
+	}
+	const registration: Registration = {
+		mount: (props, container) => adapter.mount(component, props, container),
+		attributes: Object.fromEntries(Object.entries(options.attributes ?? {}).filter((entry): entry is [string, AttributeKind] => typeof entry[1] === "string")),
+		slots: new Set(options.slots?.map(String)),
+	};
+	registrations.set(name, registration);
+	return () => {
+		if (registrations.get(name) === registration) {
+			registrations.delete(name);
+			r.Rxml_unregister_tag(name);
+		}
+	};
+}