pi-libtui 0.3.2

package/src/overlay/dialog.ts

@@ -0,0 +1,266 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type Focusable,
+	isFocusable,
+	type OverlayHandle,
+	type OverlayOptions,
+	type SizeValue,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { tuiTheme } from "../color/theme.ts";
+import { resolveTuiTitle, type TuiTitleSource } from "../decoration/status.ts";
+import { fitLine } from "../line-layout.ts";
+import type { TuiMouseEvent } from "../mouse.ts";
+import { placeAnchoredOverlay } from "./anchored.ts";
+
+type PointerComponent = Component & { onMouse?: (event: TuiMouseEvent) => boolean };
+type HeightAwareComponent = Component & { setMaxHeight?: (maxHeight: number) => void };
+
+/** Zero-based cell used to anchor a dialog relative to its parent host. */
+export interface DialogOverlayAnchor {
+	/** Row in the parent host's coordinate space. */
+	row: number;
+	/** Column in the parent host's coordinate space. */
+	col: number;
+}
+
+/** Native overlay options plus pi-libtui title and parent-anchor semantics. */
+export interface DialogOverlayOptions extends Omit<OverlayOptions, "anchor" | "row" | "col"> {
+	/** Optional title rendered into the top border. */
+	title?: TuiTitleSource;
+	/** Zero-based parent cell in the host's coordinate space. */
+	parent?: DialogOverlayAnchor;
+}
+
+/** Owner that opens components as focus-owning dialogs. */
+export interface DialogHost {
+	/**
+	 * Open a component in the host's dialog layer.
+	 * @param component Child component rendered inside the dialog frame.
+	 * @param options Optional sizing, visibility, title, and parent-anchor policy.
+	 * @returns An idempotent function that closes this dialog.
+	 */
+	open(component: Component, options?: DialogOverlayOptions): () => void;
+}
+
+/**
+ * Wrap a dialog host so parent-relative anchors are translated by an outer layout offset.
+ * @param host Underlying host that owns the native overlay lifecycle.
+ * @param offset Static offset or callback evaluated each time an anchored dialog opens.
+ * @returns A host that preserves unanchored options and offsets only `parent` coordinates.
+ */
+export function offsetDialogHost(
+	host: DialogHost,
+	offset: DialogOverlayAnchor | (() => DialogOverlayAnchor),
+): DialogHost {
+	return {
+		open(component, options = {}) {
+			if (!options.parent) return host.open(component, options);
+			const resolved = typeof offset === "function" ? offset() : offset;
+			return host.open(component, {
+				...options,
+				parent: {
+					row: resolved.row + options.parent.row,
+					col: resolved.col + options.parent.col,
+				},
+			});
+		},
+	};
+}
+
+function border(theme: Theme, title: string, width: number): string {
+	const colors = tuiTheme(theme);
+	if (width <= 2) return colors.fg("border", "╭╮".slice(0, width));
+	const visibleTitle = truncateToWidth(title, Math.max(0, width - 5), "");
+	const label = visibleTitle ? ` ${colors.fg("accent", visibleTitle)} ` : "";
+	const used = 2 + visibleWidth(label) + 1;
+	return colors.fg("border", "╭─") + label + colors.fg("border", `${"─".repeat(Math.max(0, width - used))}╮`);
+}
+
+/** A bordered component suitable for Pi's native overlay stack. */
+export class DialogOverlay implements Component, Focusable {
+	private childWidth = 0;
+	private childHeight = 0;
+	private _focused = false;
+
+	/**
+	 * Create a border around an arbitrary child component.
+	 * @param theme Active Pi theme used for semantic frame colors.
+	 * @param child Component rendered within the one-cell frame inset.
+	 * @param title Static or dynamic title resolved on each render.
+	 */
+	constructor(
+		private readonly theme: Theme,
+		private readonly child: Component,
+		private readonly title: TuiTitleSource = "",
+	) {}
+
+	/** Give height-aware children the rows remaining inside this dialog's frame. */
+	setMaxHeight(maxHeight: number): void {
+		(this.child as HeightAwareComponent).setMaxHeight?.(Math.max(0, maxHeight - 2));
+	}
+
+	/** Whether the dialog currently owns focus. */
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	/**
+	 * Transfer focus to the dialog and to its child when the child is focusable.
+	 * @param value Whether the dialog should own focus.
+	 */
+	set focused(value: boolean) {
+		this._focused = value;
+		if (isFocusable(this.child)) this.child.focused = value;
+	}
+
+	/**
+	 * Forward raw terminal input to the child when it implements input handling.
+	 * @param data Raw terminal input received by the focused dialog.
+	 */
+	handleInput(data: string): void {
+		this.child.handleInput?.(data);
+	}
+
+	/** Invalidate the child component's cached presentation state. */
+	invalidate(): void {
+		this.child.invalidate();
+	}
+
+	/**
+	 * Translate dialog-local pointer input through the one-cell frame to the child.
+	 * @param event Pointer event whose row and column are relative to this dialog.
+	 * @returns The child's handled result, or `false` when the child has no pointer
+	 * handler, the event is outside its last rendered bounds, or the handler throws.
+	 */
+	onMouse(event: TuiMouseEvent): boolean {
+		const child = this.child as PointerComponent;
+		if (typeof child.onMouse !== "function") return false;
+		const translated = { ...event, row: event.row - 1, col: event.col - 1 };
+		if (
+			event.type !== "leave" &&
+			(translated.row < 0 ||
+				translated.row >= this.childHeight ||
+				translated.col < 0 ||
+				translated.col >= this.childWidth)
+		)
+			return false;
+		try {
+			return child.onMouse(translated) === true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Render the dynamic title, child content, and one-cell border.
+	 * @param width Total available columns including both border columns.
+	 * @returns ANSI-styled dialog rows; widths below two columns produce one blank fitted row.
+	 */
+	render(width: number): string[] {
+		const colors = tuiTheme(this.theme);
+		if (width < 2) {
+			this.childWidth = 0;
+			this.childHeight = 0;
+			return [fitLine("", width)];
+		}
+		this.childWidth = width - 2;
+		const content = this.child.render(this.childWidth);
+		this.childHeight = content.length;
+		return [
+			border(this.theme, resolveTuiTitle(this.title), width),
+			...content.map(
+				(line) => `${colors.fg("border", "│")}${fitLine(line, this.childWidth)}${colors.fg("border", "│")}`,
+			),
+			colors.fg("border", `╰${"─".repeat(this.childWidth)}╯`),
+		];
+	}
+}
+
+/** Opens reusable components on Pi's native, focus-owning overlay stack. */
+export class DialogOverlayHost implements DialogHost {
+	private readonly handles = new Set<OverlayHandle>();
+
+	/**
+	 * Create a dialog host for one TUI and semantic theme.
+	 * @param tui TUI whose native overlay stack owns opened dialogs.
+	 * @param theme Active Pi theme used for every dialog frame.
+	 */
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+	) {}
+
+	/**
+	 * Open a centered or parent-anchored native overlay around a component.
+	 * @param component Child component to frame and show.
+	 * @param options Dialog title and native sizing/visibility options. Supplying
+	 * `parent` selects bounded anchored placement; omitting it uses centered defaults.
+	 * @returns An idempotent close function that hides only this overlay and requests a render.
+	 */
+	open(component: Component, { title, parent, ...options }: DialogOverlayOptions = {}): () => void {
+		const dialog = new DialogOverlay(this.theme, component, title);
+		const requestedMaxHeight = options.maxHeight ?? (parent ? undefined : "90%");
+		dialog.setMaxHeight(resolveSize(requestedMaxHeight, this.tui.terminal.rows, this.tui.terminal.rows));
+		const overlayOptions = parent
+			? this.anchoredOptions(dialog, parent, options)
+			: {
+					anchor: "center" as const,
+					width: 56,
+					maxHeight: "90%" as const,
+					margin: 1,
+					...options,
+				};
+		const handle = this.tui.showOverlay(dialog, overlayOptions);
+		this.handles.add(handle);
+		this.tui.requestRender();
+		let closed = false;
+		return () => {
+			if (closed) return;
+			closed = true;
+			this.handles.delete(handle);
+			handle.hide();
+			this.tui.requestRender();
+		};
+	}
+
+	/** Hide all dialogs still owned by this host, clear their handles, and request a render. */
+	dispose(): void {
+		for (const handle of this.handles) handle.hide();
+		this.handles.clear();
+		this.tui.requestRender();
+	}
+
+	private anchoredOptions(
+		dialog: DialogOverlay,
+		parent: DialogOverlayAnchor,
+		options: Omit<DialogOverlayOptions, "title" | "parent">,
+	): OverlayOptions {
+		const width = Math.min(this.tui.terminal.columns, resolveSize(options.width, this.tui.terminal.columns, 56));
+		const measuredHeight = dialog.render(width).length;
+		const maxHeight = resolveSize(options.maxHeight, this.tui.terminal.rows, measuredHeight);
+		const placement = placeAnchoredOverlay({
+			terminalCols: this.tui.terminal.columns,
+			terminalRows: this.tui.terminal.rows,
+			anchorRow: parent.row,
+			anchorCol: parent.col,
+			desiredWidth: width,
+			height: Math.min(measuredHeight, maxHeight),
+		});
+		return {
+			...placement.options,
+			minWidth: options.minWidth,
+			visible: options.visible,
+			nonCapturing: options.nonCapturing,
+		};
+	}
+}
+
+function resolveSize(value: SizeValue | undefined, total: number, fallback: number): number {
+	if (typeof value === "number") return Math.max(1, Math.floor(value));
+	if (typeof value === "string") return Math.max(1, Math.floor((total * Number.parseFloat(value)) / 100));
+	return Math.max(1, Math.floor(fallback));
+}

package/src/overlay/floating.ts

@@ -0,0 +1,106 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, compositeTuiLine, type Focusable, isFocusable } from "@earendil-works/pi-tui";
+import { BackgroundSurface } from "../background-surface.ts";
+import type { TuiBackgroundToken } from "../color/theme.ts";
+import type { TuiMouseEvent } from "../mouse.ts";
+
+type PointerComponent = Component & { onMouse?(event: TuiMouseEvent): boolean; dispose?(): void };
+type HeightAwareComponent = Component & { setMaxHeight?(height: number): void };
+
+export interface FloatingOverlayOptions {
+	readonly base: Component;
+	readonly overlay: Component;
+	readonly overlayWidth: (availableWidth: number) => number;
+	readonly align?: "start" | "end";
+	/** Top row in the base component. Values are clamped to keep the overlay visible. */
+	readonly top?: number | (() => number);
+	readonly maxHeight?: () => number;
+	readonly surface?: { readonly theme: Theme; readonly background: TuiBackgroundToken };
+	/** Consume a primary press outside the overlay and notify its owner. */
+	readonly onOutsidePress?: () => void;
+}
+
+/** Composites a focus-owning child over ordinary content and owns its pointer geometry. */
+export class FloatingOverlay implements Component, Focusable {
+	private readonly renderedOverlay: Component;
+	private overlayX = 0;
+	private overlayY = 0;
+	private overlayWidth = 0;
+	private overlayHeight = 0;
+
+	constructor(private readonly options: FloatingOverlayOptions) {
+		this.renderedOverlay = options.surface
+			? new BackgroundSurface({
+					theme: options.surface.theme,
+					component: options.overlay,
+					background: options.surface.background,
+				})
+			: options.overlay;
+	}
+
+	get focused(): boolean {
+		return isFocusable(this.options.overlay) && this.options.overlay.focused;
+	}
+
+	set focused(value: boolean) {
+		if (isFocusable(this.options.overlay)) this.options.overlay.focused = value;
+		if (isFocusable(this.options.base)) this.options.base.focused = false;
+	}
+
+	handleInput(data: string): void {
+		this.options.overlay.handleInput?.(data);
+	}
+
+	onMouse(event: TuiMouseEvent): boolean {
+		const overlay = this.options.overlay as PointerComponent;
+		const base = this.options.base as PointerComponent;
+		if (event.type === "leave") {
+			overlay.onMouse?.(event);
+			return base.onMouse?.(event) === true;
+		}
+		if (
+			event.col >= this.overlayX &&
+			event.col < this.overlayX + this.overlayWidth &&
+			event.row >= this.overlayY &&
+			event.row < this.overlayY + this.overlayHeight
+		)
+			return overlay.onMouse?.({ ...event, row: event.row - this.overlayY, col: event.col - this.overlayX }) === true;
+		if (event.type === "press" && event.button === 0 && this.options.onOutsidePress) {
+			this.options.onOutsidePress();
+			return true;
+		}
+		return base.onMouse?.(event) === true;
+	}
+
+	render(width: number): string[] {
+		const boundedWidth = Math.max(0, Math.floor(width));
+		const base = this.options.base.render(boundedWidth);
+		if (boundedWidth === 0) return base;
+		this.overlayWidth = Math.max(1, Math.min(boundedWidth, Math.floor(this.options.overlayWidth(boundedWidth))));
+		this.overlayX = this.options.align === "start" ? 0 : boundedWidth - this.overlayWidth;
+		const maxHeight = this.options.maxHeight?.();
+		if (maxHeight !== undefined)
+			(this.options.overlay as HeightAwareComponent).setMaxHeight?.(Math.max(0, Math.floor(maxHeight)));
+		const overlay = this.renderedOverlay.render(this.overlayWidth);
+		this.overlayHeight = overlay.length;
+		const requestedTop = typeof this.options.top === "function" ? this.options.top() : (this.options.top ?? 0);
+		this.overlayY = Math.max(0, Math.min(Math.floor(requestedTop), Math.max(0, base.length - overlay.length)));
+		return Array.from({ length: Math.max(base.length, this.overlayY + overlay.length) }, (_, row) => {
+			const line = base[row] ?? "";
+			const floating = overlay[row - this.overlayY];
+			return floating === undefined
+				? line
+				: compositeTuiLine(line, floating, this.overlayX, this.overlayWidth, boundedWidth);
+		});
+	}
+
+	invalidate(): void {
+		this.options.base.invalidate();
+		this.renderedOverlay.invalidate();
+	}
+
+	dispose(): void {
+		(this.options.base as PointerComponent).dispose?.();
+		(this.options.overlay as PointerComponent).dispose?.();
+	}
+}

package/src/overlay/framed-editor.ts

@@ -0,0 +1,236 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	CURSOR_MARKER,
+	Editor,
+	type EditorOptions,
+	type Focusable,
+	type KeybindingsManager,
+	stripTerminalSequences,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { tuiTheme } from "../color/theme.ts";
+import type { ActionPanelFooter, ActionPanelMouseEvent, ActionPanelRect } from "../controls/action-panel.ts";
+import { markEditorCursor } from "../cursor.ts";
+import { resolveTuiTitle, type TuiTitleValue } from "../decoration/status.ts";
+import { semanticEditorTheme } from "../editor.ts";
+import { fitLine } from "../line-layout.ts";
+
+function isEditorBorder(line: string): boolean {
+	const plain = stripTerminalSequences(line);
+	return /^[↑↓]?─+$/.test(plain);
+}
+
+/** Remove only Pi Editor's top and bottom rules, preserving autocomplete rows. */
+function withoutEditorBorders(lines: readonly string[]): string[] {
+	const result = [...lines];
+	if (result[0] !== undefined && isEditorBorder(result[0])) result.shift();
+	const bottom = result.findIndex((line, index) => index > 0 && isEditorBorder(line));
+	if (bottom >= 0) result.splice(bottom, 1);
+	return result;
+}
+
+/** Keep the cursor visible when a wrapper has fewer rows than Editor rendered. */
+function keepCursorVisible(lines: readonly string[], maxRows: number): string[] {
+	if (maxRows <= 0 || lines.length <= maxRows) return maxRows <= 0 ? [] : [...lines];
+	const cursor = lines.findIndex((line) => line.includes(CURSOR_MARKER));
+	const start = cursor < 0 ? 0 : Math.min(cursor, lines.length - maxRows);
+	return lines.slice(start, start + maxRows);
+}
+
+/** Last rendered bounds for a {@link FramedEditorOverlay}. */
+export interface FramedEditorOverlayGeometry extends ActionPanelRect {
+	/** Bounds of the optional footer row, relative to the overlay's top-left cell. */
+	footer?: ActionPanelRect;
+}
+
+/** Construction options for a bounded native Pi multiline editor. */
+export interface FramedEditorOverlayOptions {
+	/** TUI instance used by Pi's native editor for rendering and terminal measurements. */
+	tui: TUI;
+	/** Active Pi theme; pi-libtui maps it to semantic editor and frame colors. */
+	theme: Theme;
+	/** Active keybindings used to recognize semantic cancel input. */
+	keybindings: KeybindingsManager;
+	/** Static or semantic title rendered inside the top border. */
+	title: TuiTitleValue;
+	/** Initial editor text. Omit to start with Pi's default empty value. */
+	prefill?: string;
+	/** Maximum rendered width, including the two frame columns. */
+	maxWidth?: number;
+	/** Maximum rendered height, including frame, separator, and footer rows. */
+	maxHeight?: number;
+	/** Hide Pi Editor's horizontal rules when the outer frame is sufficient. */
+	editorBorders?: boolean;
+	/** A single component row rendered below an internal separator. */
+	footer?: ActionPanelFooter;
+	/** Options forwarded unchanged to Pi's native `Editor` constructor. */
+	editorOptions?: EditorOptions;
+	/** Called with the current editor text when Pi accepts submit input. */
+	onSubmit(text: string): void;
+	/** Called when input matches the semantic `tui.select.cancel` binding. */
+	onCancel(): void;
+}
+
+/** A small framed multiline overlay that delegates all text editing to Pi's Editor. */
+export class FramedEditorOverlay implements Component, Focusable {
+	private readonly editor: Editor;
+	private _focused = false;
+	private footerPointerInside = false;
+	private geometry: FramedEditorOverlayGeometry | undefined;
+
+	/**
+	 * Create a framed editor and initialize its native editor state.
+	 * @param config Theme, bounds, editor behavior, and completion callbacks.
+	 */
+	constructor(private readonly config: FramedEditorOverlayOptions) {
+		this.editor = new Editor(config.tui, semanticEditorTheme(config.theme), config.editorOptions);
+		this.editor.onSubmit = config.onSubmit;
+		if (config.prefill !== undefined) this.editor.setText(config.prefill);
+	}
+
+	/** Whether this overlay and its native editor currently own focus. */
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	/**
+	 * Transfer focus to or from both the frame and its native editor.
+	 * @param value Whether the editor should own focus.
+	 */
+	set focused(value: boolean) {
+		this._focused = value;
+		this.editor.focused = value;
+	}
+
+	/** @returns The native editor's current unrendered text. */
+	getText(): string {
+		return this.editor.getText();
+	}
+
+	/**
+	 * Replace all editor text and reset the native editor to that value.
+	 * @param text Complete unrendered value to install in the native editor.
+	 */
+	setText(text: string): void {
+		this.editor.setText(text);
+	}
+
+	/**
+	 * Route terminal input through cancel, footer shortcuts, then the native editor.
+	 * @param data Raw terminal input received by the focused component.
+	 */
+	handleInput(data: string): void {
+		if (this.config.keybindings.matches(data, "tui.select.cancel")) {
+			this.config.onCancel();
+			return;
+		}
+		if (this.config.footer?.handleInput?.(data) === true) return;
+		this.editor.handleInput(data);
+	}
+
+	/**
+	 * Route overlay-local pointer input to the optional footer.
+	 * @param event Pointer coordinates relative to the framed overlay.
+	 * @returns `true` when the event targets the footer; otherwise `false`.
+	 */
+	handleMouse(event: ActionPanelMouseEvent): boolean {
+		if (event.type === "leave") {
+			this.leaveFooter(event);
+			return false;
+		}
+		const footer = this.geometry?.footer;
+		if (
+			!footer ||
+			event.col < footer.x ||
+			event.col >= footer.x + footer.width ||
+			event.row < footer.y ||
+			event.row >= footer.y + footer.height
+		) {
+			this.leaveFooter(event);
+			return false;
+		}
+		const translated = { ...event, row: event.row - footer.y, col: event.col - footer.x };
+		if (!this.footerPointerInside) {
+			this.footerPointerInside = true;
+			this.config.footer?.handleMouse?.({ ...translated, type: "enter" });
+		}
+		if (event.type !== "enter") this.config.footer?.handleMouse?.(translated);
+		return true;
+	}
+
+	/**
+	 * @returns A defensive copy of the last rendered bounds, or `undefined`
+	 * before rendering, after invalidation, or when the available size is too small.
+	 */
+	getGeometry(): FramedEditorOverlayGeometry | undefined {
+		if (!this.geometry) return undefined;
+		return {
+			...this.geometry,
+			footer: this.geometry.footer ? { ...this.geometry.footer } : undefined,
+		};
+	}
+
+	/** Invalidate the native editor, footer, and cached render geometry. */
+	invalidate(): void {
+		this.editor.invalidate();
+		this.config.footer?.invalidate?.();
+		this.geometry = undefined;
+	}
+
+	/**
+	 * Render the frame, visible editor rows, and optional one-row footer.
+	 * @param availableWidth Maximum columns offered by the parent layout.
+	 * @returns ANSI-styled rows bounded by `availableWidth`, `maxWidth`, and
+	 * `maxHeight`; returns no rows when the bounds cannot fit editor chrome.
+	 */
+	render(availableWidth: number): string[] {
+		const colors = tuiTheme(this.config.theme);
+		const width = Math.max(0, Math.min(availableWidth, this.config.maxWidth ?? availableWidth));
+		const maxHeight = Math.max(0, Math.floor(this.config.maxHeight ?? Number.POSITIVE_INFINITY));
+		const chromeRows = this.config.footer ? 4 : 2;
+		if (width < 4 || maxHeight < chromeRows + 1) {
+			this.geometry = undefined;
+			return [];
+		}
+		const innerWidth = width - 2;
+		const visibleTitle = truncateToWidth(resolveTuiTitle(this.config.title), Math.max(0, innerWidth - 3), "");
+		const usedTitleWidth = visibleWidth(`─ ${visibleTitle} `);
+		const top =
+			colors.fg("border", "╭─ ") +
+			colors.fg("accent", this.config.theme.bold(visibleTitle)) +
+			colors.fg("border", ` ${"─".repeat(Math.max(0, innerWidth - usedTitleWidth))}╮`);
+		const bottom = colors.fg("border", `╰${"─".repeat(innerWidth)}╯`);
+		// Only the focused overlay can claim the screen's semantic cursor.
+		const editorLines = this.editor
+			.render(innerWidth)
+			.map((line) => markEditorCursor(line, { theme: this.config.theme, role: "insertion" }));
+		const content = this.config.editorBorders === false ? withoutEditorBorders(editorLines) : editorLines;
+		const maxContent = maxHeight - chromeRows;
+		const lines = [
+			top,
+			...keepCursorVisible(content, maxContent).map(
+				(line) => `${colors.fg("border", "│")}${fitLine(line, innerWidth)}${colors.fg("border", "│")}`,
+			),
+		];
+		let footer: ActionPanelRect | undefined;
+		if (this.config.footer) {
+			lines.push(colors.fg("border", `├${"─".repeat(innerWidth)}┤`));
+			const y = lines.length;
+			const content = this.config.footer.render(innerWidth)[0] ?? "";
+			lines.push(`${colors.fg("border", "│")}${fitLine(content, innerWidth)}${colors.fg("border", "│")}`);
+			footer = { x: 1, y, width: innerWidth, height: 1 };
+		}
+		lines.push(bottom);
+		this.geometry = { x: 0, y: 0, width, height: lines.length, footer };
+		return lines;
+	}
+
+	private leaveFooter(event: ActionPanelMouseEvent): void {
+		if (!this.footerPointerInside) return;
+		this.footerPointerInside = false;
+		this.config.footer?.handleMouse?.({ ...event, type: "leave", row: -1, col: -1 });
+	}
+}