@octanejs/opentui 0.0.1

package/src/index.ts

@@ -0,0 +1,9 @@
+export { createPortal } from 'octane/universal';
+export { baseComponents, componentCatalogue, extend, getComponentCatalogue } from './components.js';
+export { AppContext, useAppContext, type AppContextValue } from './context.js';
+export * from './hooks.js';
+export { act, flushSync, type Act } from './scheduling.js';
+export { createRoot, type Root } from './root.js';
+export * from './slot.js';
+export { TimeToFirstDraw } from './time-to-first-draw.js';
+export type * from './types.js';

package/src/intrinsics.ts

@@ -0,0 +1,16 @@
+import type { OpenTUIIntrinsicElements } from './types.js';
+import type { UniversalKey, UniversalRenderable } from 'octane/universal';
+
+export type * from './types.js';
+
+/** TypeScript resolves this namespace through the renderer-local intrinsic entry point. */
+export namespace JSX {
+	export type Element = UniversalRenderable;
+	export interface ElementChildrenAttribute {
+		children: {};
+	}
+	export interface IntrinsicAttributes {
+		key?: UniversalKey;
+	}
+	export interface IntrinsicElements extends OpenTUIIntrinsicElements {}
+}

package/src/props.ts

@@ -0,0 +1,198 @@
+import {
+	InputRenderable,
+	InputRenderableEvents,
+	isRenderable,
+	SelectRenderable,
+	SelectRenderableEvents,
+	TabSelectRenderable,
+	TabSelectRenderableEvents,
+	TextareaRenderable,
+	type BaseRenderable,
+} from '@opentui/core';
+import type { UniversalEventPriority } from 'octane/universal';
+
+export interface CallbackEnvironment {
+	eventScope<T>(priority: UniversalEventPriority, run: () => T): T;
+}
+
+type Props = Readonly<Record<string, unknown>>;
+
+const callbackCaches = new WeakMap<
+	CallbackEnvironment,
+	WeakMap<(...args: any[]) => unknown, Map<string, (...args: any[]) => unknown>>
+>();
+
+function callbackPriority(name: string): UniversalEventPriority {
+	if (
+		name === 'onMouseMove' ||
+		name === 'onMouseDrag' ||
+		name === 'onMouseOver' ||
+		name === 'onMouseOut' ||
+		name === 'onMouseScroll'
+	) {
+		return 'continuous';
+	}
+	if (name === 'renderBefore' || name === 'renderAfter' || name === 'onSizeChange') {
+		return 'default';
+	}
+	return 'discrete';
+}
+
+function wrapCallback(
+	environment: CallbackEnvironment,
+	name: string,
+	handler: (...args: any[]) => unknown,
+): (...args: any[]) => unknown {
+	let environmentCache = callbackCaches.get(environment);
+	if (environmentCache === undefined) {
+		environmentCache = new WeakMap();
+		callbackCaches.set(environment, environmentCache);
+	}
+	let handlerCache = environmentCache.get(handler);
+	if (handlerCache === undefined) {
+		handlerCache = new Map();
+		environmentCache.set(handler, handlerCache);
+	}
+	const cached = handlerCache.get(name);
+	if (cached !== undefined) return cached;
+	const priority = callbackPriority(name);
+	const wrapped = function openTUIHostCallback(this: unknown, ...args: unknown[]): unknown {
+		return environment.eventScope(priority, () => handler.apply(this, args));
+	};
+	handlerCache.set(name, wrapped);
+	return wrapped;
+}
+
+/** Preserve OpenTUI's multi-argument callback API while entering Octane's scheduler scope. */
+export function materializeOpenTUIProps(environment: CallbackEnvironment, props: Props): Props {
+	const output: Record<string, unknown> = {};
+	for (const [name, value] of Object.entries(props)) {
+		output[name] =
+			typeof value === 'function'
+				? wrapCallback(environment, name, value as (...args: any[]) => unknown)
+				: value;
+	}
+	return output;
+}
+
+function updateEmitterListener(
+	instance: BaseRenderable,
+	eventName: string,
+	listener: unknown,
+	previousListener: unknown,
+): void {
+	if (typeof previousListener === 'function') {
+		instance.off(eventName, previousListener as (...args: any[]) => void);
+	}
+	if (typeof listener === 'function') {
+		instance.on(eventName, listener as (...args: any[]) => void);
+	}
+}
+
+function setStyle(instance: BaseRenderable, styles: unknown, oldStyles: unknown): void {
+	if (oldStyles !== null && typeof oldStyles === 'object') {
+		for (const styleName of Object.keys(oldStyles)) {
+			if (styles === null || typeof styles !== 'object' || !(styleName in styles)) {
+				Reflect.set(instance, styleName, null);
+			}
+		}
+	}
+	if (styles !== null && typeof styles === 'object') {
+		for (const [styleName, value] of Object.entries(styles)) {
+			if (!Object.is(value, (oldStyles as Record<string, unknown> | null)?.[styleName])) {
+				Reflect.set(instance, styleName, value);
+			}
+		}
+	}
+}
+
+function setProperty(
+	instance: BaseRenderable,
+	propKey: string,
+	propValue: unknown,
+	oldPropValue?: unknown,
+): void {
+	switch (propKey) {
+		case 'onChange':
+			if (instance instanceof InputRenderable) {
+				updateEmitterListener(instance, InputRenderableEvents.CHANGE, propValue, oldPropValue);
+			} else if (instance instanceof SelectRenderable) {
+				updateEmitterListener(
+					instance,
+					SelectRenderableEvents.SELECTION_CHANGED,
+					propValue,
+					oldPropValue,
+				);
+			} else if (instance instanceof TabSelectRenderable) {
+				updateEmitterListener(
+					instance,
+					TabSelectRenderableEvents.SELECTION_CHANGED,
+					propValue,
+					oldPropValue,
+				);
+			}
+			break;
+		case 'onInput':
+			if (instance instanceof InputRenderable) {
+				updateEmitterListener(instance, InputRenderableEvents.INPUT, propValue, oldPropValue);
+			}
+			break;
+		case 'onSubmit':
+			if (instance instanceof InputRenderable) {
+				updateEmitterListener(instance, InputRenderableEvents.ENTER, propValue, oldPropValue);
+			} else if (instance instanceof TextareaRenderable) {
+				instance.onSubmit = propValue as (() => void) | undefined;
+			}
+			break;
+		case 'onSelect':
+			if (instance instanceof SelectRenderable) {
+				updateEmitterListener(
+					instance,
+					SelectRenderableEvents.ITEM_SELECTED,
+					propValue,
+					oldPropValue,
+				);
+			} else if (instance instanceof TabSelectRenderable) {
+				updateEmitterListener(
+					instance,
+					TabSelectRenderableEvents.ITEM_SELECTED,
+					propValue,
+					oldPropValue,
+				);
+			}
+			break;
+		case 'focused':
+			if (isRenderable(instance)) {
+				if (propValue) instance.focus();
+				else instance.blur();
+			}
+			break;
+		case 'style':
+			setStyle(instance, propValue, oldPropValue);
+			break;
+		case 'children':
+			break;
+		default:
+			Reflect.set(instance, propKey, propValue);
+	}
+}
+
+export function setInitialProperties(instance: BaseRenderable, props: Props): void {
+	for (const [name, value] of Object.entries(props)) {
+		if (value != null) setProperty(instance, name, value);
+	}
+}
+
+export function updateProperties(instance: BaseRenderable, previous: Props, next: Props): void {
+	for (const [name, value] of Object.entries(previous)) {
+		if (value != null && !Object.prototype.hasOwnProperty.call(next, name)) {
+			setProperty(instance, name, null, value);
+		}
+	}
+	for (const [name, value] of Object.entries(next)) {
+		const previousValue = previous[name];
+		if (!Object.is(value, previousValue) && (value != null || previousValue != null)) {
+			setProperty(instance, name, value, previousValue);
+		}
+	}
+}

package/src/renderer.ts

@@ -0,0 +1,11 @@
+/** Compiler-facing OpenTUI renderer ABI. */
+export * from 'octane/universal';
+export * from './components.js';
+export * from './context.js';
+export * from './driver.js';
+export * from './hooks.js';
+export * from './root.js';
+export * from './scheduling.js';
+export * from './slot.js';
+export * from './time-to-first-draw.js';
+export type * from './types.js';

package/src/root.ts

@@ -0,0 +1,120 @@
+import { CliRenderEvents, engine, type CliRenderer } from '@opentui/core';
+import {
+	createUniversalRoot,
+	defineUniversalComponent,
+	universalComponent,
+	universalContext,
+	universalPlan,
+	universalTry,
+	universalValue,
+	type UniversalComponent,
+	type UniversalRoot,
+} from 'octane/universal';
+import { AppContext } from './context.js';
+import { OPENTUI_RENDERER_ID } from './config.js';
+import {
+	createOpenTUIContainer,
+	createOpenTUIDriver,
+	type OpenTUIHostEnvironment,
+} from './driver.js';
+
+export interface Root {
+	render(component: UniversalComponent<void | undefined>): void;
+	render<P>(component: UniversalComponent<P>, props: P): void;
+	unmount(): void;
+}
+
+interface RootProviderProps {
+	readonly renderer: CliRenderer;
+	readonly component: UniversalComponent<any>;
+	readonly componentProps: any;
+}
+
+const ERROR_PLAN = universalPlan(OPENTUI_RENDERER_ID, {
+	kind: 'host',
+	type: 'box',
+	props: { style: { flexDirection: 'column', padding: 2 } },
+	children: [
+		{
+			kind: 'host',
+			type: 'text',
+			props: { fg: 'red' },
+			children: [{ kind: 'text', slot: 0 }],
+		},
+	],
+});
+
+function errorText(error: unknown): string {
+	if (error instanceof Error) return error.stack || error.message;
+	return String(error);
+}
+
+const RootProvider = defineUniversalComponent<RootProviderProps>(
+	OPENTUI_RENDERER_ID,
+	(props) =>
+		universalContext(
+			AppContext,
+			{ keyHandler: props.renderer.keyInput, renderer: props.renderer },
+			() =>
+				universalTry(
+					() => universalComponent(OPENTUI_RENDERER_ID, props.component, props.componentProps),
+					null,
+					(error) => universalValue(ERROR_PLAN, [errorText(error)]),
+				),
+		),
+	{ module: '@octanejs/opentui' },
+);
+
+const roots = new WeakMap<CliRenderer, Root>();
+
+export function createRoot(renderer: CliRenderer): Root {
+	const existing = roots.get(renderer);
+	if (existing !== undefined) {
+		console.warn('@octanejs/opentui: createRoot should only be called once for a renderer.');
+		return existing;
+	}
+
+	let hostRoot: UniversalRoot | null = null;
+	let unmounted = false;
+	const environment: OpenTUIHostEnvironment = {
+		eventScope(priority, run) {
+			if (hostRoot === null) {
+				throw new Error('@octanejs/opentui: A host callback ran before the root was created.');
+			}
+			return hostRoot.eventScope(priority, run);
+		},
+	};
+	const container = createOpenTUIContainer(renderer, environment);
+	hostRoot = createUniversalRoot(container, createOpenTUIDriver());
+
+	const cleanup = (): void => {
+		if (unmounted) return;
+		unmounted = true;
+		try {
+			hostRoot?.unmount();
+		} finally {
+			hostRoot = null;
+			renderer.off(CliRenderEvents.DESTROY, cleanup);
+			roots.delete(renderer);
+		}
+	};
+
+	const root: Root = {
+		render<P>(component: UniversalComponent<P>, props?: P): void {
+			if (unmounted || hostRoot === null) {
+				throw new Error('@octanejs/opentui: Cannot render into an unmounted root.');
+			}
+			engine.attach(renderer);
+			hostRoot.render(RootProvider, {
+				renderer,
+				component,
+				componentProps: props,
+			});
+		},
+		unmount: cleanup,
+	};
+
+	renderer.once(CliRenderEvents.DESTROY, cleanup);
+	roots.set(renderer, root);
+	return root;
+}

package/src/scheduling.ts

@@ -0,0 +1,78 @@
+import * as Octane from 'octane';
+import { flushUniversalAct, flushUniversalSync, type UniversalSyncFlusher } from 'octane/universal';
+
+export type Act = typeof import('octane').act;
+type FlushSync = typeof import('octane').flushSync;
+const NO_ACT_ERROR = Symbol('octane.opentui.no-act-error');
+
+function isThenable<T>(value: T | Promise<T>): value is Promise<T> {
+	return (
+		value !== null &&
+		(typeof value === 'object' || typeof value === 'function') &&
+		typeof (value as PromiseLike<T>).then === 'function'
+	);
+}
+
+function runActCallback<T>(
+	callback: () => T | Promise<T>,
+	flushOwner?: UniversalSyncFlusher,
+): T | Promise<T> {
+	const result = flushUniversalAct(callback, flushOwner);
+	if (!isThenable(result)) return result;
+	return Promise.resolve(result).then((value) => flushUniversalAct(() => value, flushOwner));
+}
+
+function runClientAct<T>(callback: () => T | Promise<T>, clientAct: Act): Promise<T> {
+	const completions: Promise<unknown>[] = [];
+	const flushOwner: UniversalSyncFlusher = <Value>(run: () => Value): Value => {
+		let value!: Value;
+		let error: unknown = NO_ACT_ERROR;
+		const completion = clientAct(() => {
+			try {
+				value = run();
+			} catch (caught) {
+				error = caught;
+			}
+		});
+		completions.push(completion);
+		if (error !== NO_ACT_ERROR) throw error;
+		return value;
+	};
+
+	let result: T | Promise<T>;
+	try {
+		result = flushUniversalAct(callback, flushOwner);
+	} catch (error) {
+		return Promise.allSettled(completions.splice(0)).then(() => {
+			throw error;
+		});
+	}
+	return (async () => {
+		try {
+			const value = await result;
+			await Promise.all(completions.splice(0));
+			const settled = flushUniversalAct(() => value, flushOwner);
+			await Promise.all(completions.splice(0));
+			return settled;
+		} catch (error) {
+			await Promise.allSettled(completions.splice(0));
+			throw error;
+		}
+	})();
+}
+
+export const flushSync: FlushSync = (callback) => {
+	const clientFlushSync = Reflect.get(Octane, 'flushSync') as FlushSync | undefined;
+	return flushUniversalSync(callback, clientFlushSync);
+};
+
+export const act: Act = (callback) => {
+	const clientAct = Reflect.get(Octane, 'act') as Act | undefined;
+	const clientFlushSync = Reflect.get(Octane, 'flushSync') as FlushSync | undefined;
+	if (typeof clientAct === 'function') return runClientAct(callback, clientAct);
+	try {
+		return Promise.resolve(runActCallback(callback, clientFlushSync));
+	} catch (error) {
+		return Promise.reject(error);
+	}
+};