@yaebal/morda 0.0.1

package/src/jsx/index.ts

@@ -0,0 +1,325 @@
+import type { Context, Plugin, User } from "@yaebal/core";
+import {
+	type DialogContext,
+	type DialogControl,
+	type DialogDef,
+	type DialogsOptions,
+	type Button as MordaButton,
+	type WindowView,
+	dialogs,
+} from "../index.js";
+import { Fragment, VNODE, type VNode } from "./jsx-runtime.js";
+
+export type { VNode } from "./jsx-runtime.js";
+
+/** a screen is a component: a zero-arg function returning a `<Screen>` tree. */
+export type ScreenComponent = () => VNode;
+
+export interface ButtonProps {
+	id: string;
+	onClick?: () => unknown;
+	children?: unknown;
+}
+
+// component markers. never invoked by the runtime — matched by identity below.
+export function Screen(props: { children?: unknown }): VNode {
+	return { [VNODE]: true, type: Screen, props: { ...props } };
+}
+
+export function ButtonRow(props: { children?: unknown }): VNode {
+	return { [VNODE]: true, type: ButtonRow, props: { ...props } };
+}
+
+export function Button(props: ButtonProps): VNode {
+	return { [VNODE]: true, type: Button, props: { ...props } };
+}
+
+const MARKERS = new Set<unknown>([Screen, ButtonRow, Button, Fragment]);
+
+interface Frame {
+	slots: unknown[];
+	cursor: number;
+	effects: Array<() => unknown>;
+	ctx: DialogContext;
+	idByComponent: Map<ScreenComponent, string>;
+}
+
+let current: Frame | undefined;
+
+function need(): Frame {
+	if (!current) throw new Error("morda/jsx: hooks may only be called during a screen render");
+	return current;
+}
+
+/** per-frame state. `setState` re-renders the screen in place and resolves when the edit lands. */
+export function useState<T>(
+	initial: T | (() => T),
+): [T, (next: T | ((prev: T) => T)) => Promise<void>] {
+	const frame = need();
+	const i = frame.cursor++;
+
+	if (!(i in frame.slots)) {
+		frame.slots[i] = typeof initial === "function" ? (initial as () => T)() : initial;
+	}
+
+	const set = (next: T | ((prev: T) => T)): Promise<void> => {
+		const prev = frame.slots[i] as T;
+		frame.slots[i] = typeof next === "function" ? (next as (p: T) => T)(prev) : next;
+
+		// ponytail: one editMessageText per setState — no batching. Combine writes
+		// yourself if a handler calls setState many times in a row.
+		return frame.ctx.dialog.rerender();
+	};
+
+	return [frame.slots[i] as T, set];
+}
+
+/**
+ * run an effect after the screen renders. `deps` gate re-runs.
+ * prefer passing `deps` — the no-deps form fires on every *internal* render
+ * (a button press renders once to route and again to commit), not once per tap.
+ */
+export function useEffect(fn: () => unknown, deps?: unknown[]): void {
+	const frame = need();
+	const i = frame.cursor++;
+	const prev = frame.slots[i] as { deps?: unknown[] } | undefined;
+
+	frame.slots[i] = { deps };
+
+	// ponytail: no cleanup support — effects are fire-and-forget (enough for bots).
+	if (!prev || !depsEqual(prev.deps, deps)) frame.effects.push(fn);
+}
+
+function depsEqual(a: unknown[] | undefined, b: unknown[] | undefined): boolean {
+	if (!a || !b || a.length !== b.length) return false;
+	return a.every((v, i) => Object.is(v, b[i]));
+}
+
+export interface Navigation {
+	push(target: ScreenComponent | string): Promise<void>;
+	replace(target: ScreenComponent | string): Promise<void>;
+	back(): Promise<void>;
+}
+
+/** navigate by screen component (or window id). */
+export function useNavigation(): Navigation {
+	const frame = need();
+	const dialog = frame.ctx.dialog;
+
+	const idOf = (t: ScreenComponent | string): string => {
+		if (typeof t === "string") return t;
+
+		const id = frame.idByComponent.get(t);
+		if (id === undefined) throw new Error("morda/jsx: navigating to a screen not in jsxDialogs()");
+
+		return id;
+	};
+
+	return {
+		push: (t) => dialog.push(idOf(t)),
+		replace: (t) => dialog.replace(idOf(t)),
+		back: () => dialog.back(),
+	};
+}
+
+/** the telegram user behind the current update. */
+export function useUser(): User | undefined {
+	return need().ctx.from;
+}
+
+/** the session session (requires `@yaebal/session` installed before the dialog). */
+export function useSession<S>(): S {
+	return (need().ctx as unknown as { session: S }).session;
+}
+
+export interface Translation {
+	t(key: string, ...args: unknown[]): string;
+	changeLanguage(language: string): unknown;
+}
+
+/** i18n helpers (requires `@yaebal/i18n` installed before the dialog). */
+export function useTranslation(): Translation {
+	const ctx = need().ctx as unknown as Partial<Translation>;
+
+	if (!ctx.t || !ctx.changeLanguage) {
+		throw new Error("morda/jsx: useTranslation() requires @yaebal/i18n installed");
+	}
+
+	return { t: ctx.t, changeLanguage: ctx.changeLanguage };
+}
+
+// flattening
+
+function isVNode(x: unknown): x is VNode {
+	return typeof x === "object" && x !== null && VNODE in x;
+}
+
+function resolve(node: unknown): unknown {
+	let cur = node;
+
+	for (
+		let guard = 0;
+		isVNode(cur) && typeof cur.type === "function" && !MARKERS.has(cur.type);
+		guard++
+	) {
+		if (guard >= 50) throw new Error("morda/jsx: component nesting too deep (cyclic render?)");
+		cur = (cur.type as (p: unknown) => unknown)(cur.props);
+	}
+
+	return cur;
+}
+
+function toArray(x: unknown): unknown[] {
+	if (Array.isArray(x)) return x;
+	return x === undefined ? [] : [x];
+}
+
+function textOf(children: unknown): string {
+	const parts: string[] = [];
+
+	for (const c of toArray(children)) {
+		const n = resolve(c);
+
+		if (typeof n === "string" || typeof n === "number") parts.push(String(n));
+	}
+
+	return parts.join("");
+}
+
+function toButton(node: VNode): MordaButton {
+	const props = node.props as unknown as ButtonProps;
+	const onClick = props.onClick;
+
+	return {
+		id: props.id,
+		label: textOf(props.children),
+		onClick: onClick ? () => onClick() : undefined,
+	};
+}
+
+function collectRow(children: unknown): MordaButton[] {
+	const out: MordaButton[] = [];
+
+	for (const c of toArray(children)) {
+		const n = resolve(c);
+
+		if (isVNode(n) && n.type === Button) out.push(toButton(n));
+	}
+
+	return out;
+}
+
+function collect(node: unknown, texts: string[], rows: MordaButton[][]): void {
+	const n = resolve(node);
+	if (n === null || n === undefined || typeof n === "boolean") return;
+
+	if (typeof n === "string" || typeof n === "number") {
+		texts.push(String(n));
+		return;
+	}
+
+	if (Array.isArray(n)) {
+		for (const c of n) collect(c, texts, rows);
+		return;
+	}
+
+	if (isVNode(n)) {
+		if (n.type === Fragment) {
+			for (const c of toArray(n.props.children)) collect(c, texts, rows);
+		} else if (n.type === ButtonRow) {
+			rows.push(collectRow(n.props.children));
+		} else if (n.type === Button) {
+			rows.push([toButton(n)]);
+		}
+	}
+}
+
+function renderView(el: unknown): WindowView {
+	const screen = resolve(el);
+
+	if (!isVNode(screen) || screen.type !== Screen) {
+		throw new Error("morda/jsx: a screen component must render <Screen>…</Screen>");
+	}
+
+	const texts: string[] = [];
+	const rows: MordaButton[][] = [];
+
+	for (const c of toArray(screen.props.children)) collect(c, texts, rows);
+
+	const keyboard = rows.filter((r) => r.length > 0);
+	return keyboard.length > 0 ? { text: texts.join(""), keyboard } : { text: texts.join("") };
+}
+
+// hook state per chat+window. evicted when a window leaves the stack (via morda's
+// onLeave) so a reopened screen re-mounts fresh. bounded by chats × windows.
+const slotStore = new Map<string, unknown[]>();
+const hookCounts = new Map<string, number>();
+
+function makeRender(
+	windowId: string,
+	Component: ScreenComponent,
+	idByComponent: Map<ScreenComponent, string>,
+): (ctx: DialogContext) => Promise<WindowView> {
+	return async (ctx) => {
+		const storeKey = `${ctx.chat?.id ?? "_"}:${windowId}`;
+
+		let slots = slotStore.get(storeKey);
+		if (!slots) {
+			slots = [];
+			slotStore.set(storeKey, slots);
+		}
+
+		const frame: Frame = { slots, cursor: 0, effects: [], ctx, idByComponent };
+		const prev = current;
+
+		current = frame;
+
+		let tree: VNode;
+		try {
+			tree = Component();
+		} finally {
+			current = prev;
+		}
+
+		// rules of hooks: a changed hook count means a conditional hook — fail loud
+		// instead of silently reinterpreting slots.
+		const expected = hookCounts.get(storeKey);
+
+		if (expected !== undefined && expected !== frame.cursor) {
+			throw new Error(
+				"morda/jsx: hooks must be called unconditionally (hook count changed between renders)",
+			);
+		}
+
+		hookCounts.set(storeKey, frame.cursor);
+
+		const view = renderView(tree);
+		for (const effect of frame.effects) await effect();
+
+		return view;
+	};
+}
+
+/** install a set of JSX screens as a dialog. `bot.install(jsxDialogs({ main, settings }))`. */
+export function jsxDialogs(
+	screens: Record<string, ScreenComponent>,
+	options?: DialogsOptions,
+): Plugin<Context, { dialog: DialogControl }> {
+	const idByComponent = new Map<ScreenComponent, string>();
+	for (const [id, Component] of Object.entries(screens)) idByComponent.set(Component, id);
+
+	const def: DialogDef = {};
+	for (const [id, Component] of Object.entries(screens)) {
+		def[id] = makeRender(id, Component, idByComponent);
+	}
+	
+	return dialogs(def, {
+		...options,
+		onLeave: (chatId, windowId) => {
+			const key = `${chatId}:${windowId}`;
+			slotStore.delete(key);
+			hookCounts.delete(key);
+			options?.onLeave?.(chatId, windowId);
+		},
+	});
+}

package/src/jsx/jsx-runtime.ts

@@ -0,0 +1,34 @@
+// automatic JSX runtime. `jsx(type, props)` just builds a vnode; the morda/jsx
+// renderer flattens it to a WindowView. components are never invoked by the
+// runtime itself — they are resolved during flattening.
+
+/** brand so `isVNode` can't mistake a plain user object for an element. */
+export const VNODE: unique symbol = Symbol.for("yaebal.morda.vnode");
+
+export interface VNode {
+	[VNODE]: true;
+	type: unknown;
+	props: { children?: unknown; [key: string]: unknown };
+}
+
+export function jsx(type: unknown, props: { children?: unknown; [key: string]: unknown }): VNode {
+	return { [VNODE]: true, type, props };
+}
+
+export const jsxs = jsx;
+
+export function Fragment(props: { children?: unknown }): VNode {
+	return { [VNODE]: true, type: Fragment, props };
+}
+
+export namespace JSX {
+	export type Element = VNode;
+	
+	export interface ElementChildrenAttribute {
+		children: Record<never, never>;
+	}
+
+	export interface IntrinsicElements {
+		[elem: string]: never;
+	}
+}

package/src/jsx.test.tsx

@@ -0,0 +1,266 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import {
+	Button,
+	ButtonRow,
+	Screen,
+	jsxDialogs,
+	useEffect,
+	useNavigation,
+	useState,
+} from "./jsx/index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+interface Call {
+	method: string;
+	// biome-ignore lint/suspicious/noExplicitAny: test recorder captures arbitrary params
+	params: any;
+}
+
+function fakeApi() {
+	const calls: Call[] = [];
+	let nextId = 100;
+
+	const api = {
+		sendMessage(params: Record<string, unknown>) {
+			calls.push({ method: "sendMessage", params });
+			return Promise.resolve({ message_id: nextId++ });
+		},
+		answerCallbackQuery(params: Record<string, unknown>) {
+			calls.push({ method: "answerCallbackQuery", params });
+			return Promise.resolve(true);
+		},
+		call(method: string, params: Record<string, unknown>) {
+			calls.push({ method, params });
+			return Promise.resolve(true);
+		},
+	} as never;
+
+	return { api, calls };
+}
+
+const msgCtx = (api: never, text: string, chatId: number) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: chatId, type: "private" },
+				from: { id: chatId, is_bot: false, first_name: "u" },
+				text,
+			},
+		} as never,
+		updateType: "message",
+	});
+
+const cbCtx = (api: never, data: string, chatId: number, messageId: number) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			callback_query: {
+				id: "cb",
+				from: { id: chatId, is_bot: false, first_name: "u" },
+				message: { message_id: messageId, date: 0, chat: { id: chatId, type: "private" } },
+				data,
+			},
+		} as never,
+		updateType: "callback_query",
+	});
+
+// biome-ignore lint/suspicious/noExplicitAny: reaching into recorded params
+const dataAt = (params: any, row: number, col: number): string =>
+	params.reply_markup.inline_keyboard[row][col].callback_data;
+
+test("useState re-renders the screen in place on setState", async () => {
+	function Counter() {
+		const [n, setN] = useState(0);
+		return (
+			<Screen>
+				{`n=${n}`}
+				<ButtonRow>
+					<Button id="inc" onClick={() => setN((v) => v + 1)}>
+						+
+					</Button>
+				</ButtonRow>
+			</Screen>
+		);
+	}
+
+	const { api, calls } = fakeApi();
+	const mw = entry(
+		new Composer<Context>()
+			.install(jsxDialogs({ counter: Counter }))
+			.command("go", (ctx) => ctx.dialog.start("counter")),
+	);
+
+	await mw(msgCtx(api, "/go", 1), noop);
+
+	const sent = calls.find((c) => c.method === "sendMessage");
+	assert.equal(sent?.params.text, "n=0");
+
+	const incData = dataAt(sent?.params, 0, 0);
+	calls.length = 0;
+
+	await mw(cbCtx(api, incData, 1, 100), noop);
+	assert.equal(calls.find((c) => c.method === "editMessageText")?.params.text, "n=1");
+
+	calls.length = 0;
+
+	await mw(cbCtx(api, incData, 1, 100), noop);
+	assert.equal(calls.find((c) => c.method === "editMessageText")?.params.text, "n=2");
+});
+
+test("useEffect with [] runs once on mount, not on re-render", async () => {
+	let runs = 0;
+	function Screen1() {
+		const [n, setN] = useState(0);
+
+		useEffect(() => {
+			runs++;
+		}, []);
+
+		return (
+			<Screen>
+				{`n=${n}`}
+				<ButtonRow>
+					<Button id="inc" onClick={() => setN((v) => v + 1)}>
+						+
+					</Button>
+				</ButtonRow>
+			</Screen>
+		);
+	}
+
+	const { api, calls } = fakeApi();
+	const mw = entry(
+		new Composer<Context>()
+			.install(jsxDialogs({ s: Screen1 }))
+			.command("go", (ctx) => ctx.dialog.start("s")),
+	);
+
+	await mw(msgCtx(api, "/go", 1), noop);
+	assert.equal(runs, 1);
+
+	const incData = dataAt(calls.find((c) => c.method === "sendMessage")?.params, 0, 0);
+
+	await mw(cbCtx(api, incData, 1, 100), noop); // re-renders twice (find + after setState)
+	assert.equal(runs, 1);
+});
+
+test("reopening a closed screen resets hook state", async () => {
+	let runs = 0;
+	function Counter() {
+		const [n, setN] = useState(0);
+		const { back } = useNavigation();
+
+		useEffect(() => {
+			runs++;
+		}, []);
+
+		return (
+			<Screen>
+				{`n=${n}`}
+				<ButtonRow>
+					<Button id="inc" onClick={() => setN((v) => v + 1)}>
+						+
+					</Button>
+				</ButtonRow>
+				<ButtonRow>
+					<Button id="close" onClick={() => back()}>
+						x
+					</Button>
+				</ButtonRow>
+			</Screen>
+		);
+	}
+
+	const { api, calls } = fakeApi();
+
+	// distinct window id ("rc") so this test's hook slots don't collide with the
+	// other counter test (module-level slot store is keyed by chat:window).
+	const mw = entry(
+		new Composer<Context>()
+			.install(jsxDialogs({ rc: Counter }))
+			.command("go", (ctx) => ctx.dialog.start("rc")),
+	);
+
+	await mw(msgCtx(api, "/go", 1), noop);
+
+	let sent = calls.find((c) => c.method === "sendMessage");
+	assert.equal(sent?.params.text, "n=0");
+	assert.equal(runs, 1);
+
+	const incData = dataAt(sent?.params, 0, 0);
+	const closeData = dataAt(sent?.params, 1, 0);
+
+	await mw(cbCtx(api, incData, 1, 100), noop); // n=1
+	calls.length = 0;
+
+	await mw(cbCtx(api, closeData, 1, 100), noop); // back() at root → close + evict slots
+	assert.ok(calls.some((c) => c.method === "deleteMessage"));
+
+	calls.length = 0;
+	await mw(msgCtx(api, "/go", 1), noop); // reopen
+
+	sent = calls.find((c) => c.method === "sendMessage");
+	assert.equal(sent?.params.text, "n=0"); // counter reset, not "n=1"
+	assert.equal(runs, 2); // mount effect re-fired
+});
+
+test("useNavigation pushes and pops across screens", async () => {
+	function Detail() {
+		const { back } = useNavigation();
+		return (
+			<Screen>
+				{"detail"}
+				<ButtonRow>
+					<Button id="back" onClick={() => back()}>
+						back
+					</Button>
+				</ButtonRow>
+			</Screen>
+		);
+	}
+
+	function Home() {
+		const { push } = useNavigation();
+		return (
+			<Screen>
+				{"home"}
+				<ButtonRow>
+					<Button id="go" onClick={() => push(Detail)}>
+						detail
+					</Button>
+				</ButtonRow>
+			</Screen>
+		);
+	}
+
+	const { api, calls } = fakeApi();
+	const mw = entry(
+		new Composer<Context>()
+			.install(jsxDialogs({ home: Home, detail: Detail }))
+			.command("go", (ctx) => ctx.dialog.start("home")),
+	);
+
+	await mw(msgCtx(api, "/go", 1), noop);
+	const goData = dataAt(calls.find((c) => c.method === "sendMessage")?.params, 0, 0);
+
+	calls.length = 0;
+	await mw(cbCtx(api, goData, 1, 100), noop);
+
+	const edit1 = calls.find((c) => c.method === "editMessageText");
+	assert.equal(edit1?.params.text, "detail");
+
+	calls.length = 0;
+	await mw(cbCtx(api, dataAt(edit1?.params, 0, 0), 1, 100), noop);
+	
+	assert.equal(calls.find((c) => c.method === "editMessageText")?.params.text, "home");
+});