@wayofmono/wo-tui 1.0.0

package/src/components/image.ts

@@ -0,0 +1,121 @@
+import {
+	allocateImageId,
+	getCapabilities,
+	getImageDimensions,
+	type ImageDimensions,
+	imageFallback,
+	renderImage,
+} from "../terminal-image.js";
+import type { Component } from "../tui.js";
+
+export interface ImageTheme {
+	fallbackColor: (str: string) => string;
+}
+
+export interface ImageOptions {
+	maxWidthCells?: number;
+	maxHeightCells?: number;
+	filename?: string;
+	/** Kitty image ID. If provided, reuses this ID (for animations/updates). */
+	imageId?: number;
+}
+
+export class Image implements Component {
+	private base64Data: string;
+	private mimeType: string;
+	private dimensions: ImageDimensions;
+	private theme: ImageTheme;
+	private options: ImageOptions;
+	private imageId?: number;
+
+	private cachedLines?: string[];
+	private cachedWidth?: number;
+
+	constructor(
+		base64Data: string,
+		mimeType: string,
+		theme: ImageTheme,
+		options: ImageOptions = {},
+		dimensions?: ImageDimensions,
+	) {
+		this.base64Data = base64Data;
+		this.mimeType = mimeType;
+		this.theme = theme;
+		this.options = options;
+		this.dimensions = dimensions || getImageDimensions(base64Data, mimeType) || { widthPx: 800, heightPx: 600 };
+		this.imageId = options.imageId;
+	}
+
+	/** Get the Kitty image ID used by this image (if any). */
+	getImageId(): number | undefined {
+		return this.imageId;
+	}
+
+	invalidate(): void {
+		this.cachedLines = undefined;
+		this.cachedWidth = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) {
+			return this.cachedLines;
+		}
+
+		const maxWidth = Math.min(width - 2, this.options.maxWidthCells ?? 60);
+
+		const caps = getCapabilities();
+		let lines: string[];
+
+		if (caps.images) {
+			if (caps.images === "kitty" && this.imageId === undefined) {
+				this.imageId = allocateImageId();
+			}
+			const result = renderImage(this.base64Data, this.dimensions, {
+				maxWidthCells: maxWidth,
+				imageId: this.imageId,
+				moveCursor: false,
+			});
+
+			if (result) {
+				// Store the image ID for later cleanup
+				if (result.imageId) {
+					this.imageId = result.imageId;
+				}
+
+				if (caps.images === "kitty") {
+					// For Kitty: C=1 prevents cursor movement.
+					// Don't need the cursor movement.
+					lines = [result.sequence];
+
+					// Return `rows` lines so TUI accounts for image height.
+					for (let i = 0; i < result.rows - 1; i++) {
+						lines.push("");
+					}
+				} else {
+					// Return `rows` lines so TUI accounts for image height.
+					// First (rows-1) lines are empty and cleared before the image is drawn.
+					// Last line: move cursor back up, draw the image, then move back down
+					// so TUI cursor accounting stays inside the scroll area.
+					lines = [];
+					for (let i = 0; i < result.rows - 1; i++) {
+						lines.push("");
+					}
+					const rowOffset = result.rows - 1;
+					const moveUp = rowOffset > 0 ? `\x1b[${rowOffset}A` : "";
+					lines.push(moveUp + result.sequence);
+				}
+			} else {
+				const fallback = imageFallback(this.mimeType, this.dimensions, this.options.filename);
+				lines = [this.theme.fallbackColor(fallback)];
+			}
+		} else {
+			const fallback = imageFallback(this.mimeType, this.dimensions, this.options.filename);
+			lines = [this.theme.fallbackColor(fallback)];
+		}
+
+		this.cachedLines = lines;
+		this.cachedWidth = width;
+
+		return lines;
+	}
+}

package/src/components/input.ts

@@ -0,0 +1,503 @@
+import { getKeybindings } from "../keybindings.js";
+import { decodeKittyPrintable } from "../keys.js";
+import { KillRing } from "../kill-ring.js";
+import { type Component, CURSOR_MARKER, type Focusable } from "../tui.js";
+import { UndoStack } from "../undo-stack.js";
+import { getSegmenter, isPunctuationChar, isWhitespaceChar, sliceByColumn, visibleWidth } from "../utils.js";
+
+const segmenter = getSegmenter();
+
+interface InputState {
+	value: string;
+	cursor: number;
+}
+
+/**
+ * Input component - single-line text input with horizontal scrolling
+ */
+export class Input implements Component, Focusable {
+	private value: string = "";
+	private cursor: number = 0; // Cursor position in the value
+	public onSubmit?: (value: string) => void;
+	public onEscape?: () => void;
+
+	/** Focusable interface - set by TUI when focus changes */
+	focused: boolean = false;
+
+	// Bracketed paste mode buffering
+	private pasteBuffer: string = "";
+	private isInPaste: boolean = false;
+
+	// Kill ring for Emacs-style kill/yank operations
+	private killRing = new KillRing();
+	private lastAction: "kill" | "yank" | "type-word" | null = null;
+
+	// Undo support
+	private undoStack = new UndoStack<InputState>();
+
+	getValue(): string {
+		return this.value;
+	}
+
+	setValue(value: string): void {
+		this.value = value;
+		this.cursor = Math.min(this.cursor, value.length);
+	}
+
+	handleInput(data: string): void {
+		// Handle bracketed paste mode
+		// Start of paste: \x1b[200~
+		// End of paste: \x1b[201~
+
+		// Check if we're starting a bracketed paste
+		if (data.includes("\x1b[200~")) {
+			this.isInPaste = true;
+			this.pasteBuffer = "";
+			data = data.replace("\x1b[200~", "");
+		}
+
+		// If we're in a paste, buffer the data
+		if (this.isInPaste) {
+			// Check if this chunk contains the end marker
+			this.pasteBuffer += data;
+
+			const endIndex = this.pasteBuffer.indexOf("\x1b[201~");
+			if (endIndex !== -1) {
+				// Extract the pasted content
+				const pasteContent = this.pasteBuffer.substring(0, endIndex);
+
+				// Process the complete paste
+				this.handlePaste(pasteContent);
+
+				// Reset paste state
+				this.isInPaste = false;
+
+				// Handle any remaining input after the paste marker
+				const remaining = this.pasteBuffer.substring(endIndex + 6); // 6 = length of \x1b[201~
+				this.pasteBuffer = "";
+				if (remaining) {
+					this.handleInput(remaining);
+				}
+			}
+			return;
+		}
+
+		const kb = getKeybindings();
+
+		// Escape/Cancel
+		if (kb.matches(data, "tui.select.cancel")) {
+			if (this.onEscape) this.onEscape();
+			return;
+		}
+
+		// Undo
+		if (kb.matches(data, "tui.editor.undo")) {
+			this.undo();
+			return;
+		}
+
+		// Submit
+		if (kb.matches(data, "tui.input.submit") || data === "\n") {
+			if (this.onSubmit) this.onSubmit(this.value);
+			return;
+		}
+
+		// Deletion
+		if (kb.matches(data, "tui.editor.deleteCharBackward")) {
+			this.handleBackspace();
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.deleteCharForward")) {
+			this.handleForwardDelete();
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.deleteWordBackward")) {
+			this.deleteWordBackwards();
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.deleteWordForward")) {
+			this.deleteWordForward();
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.deleteToLineStart")) {
+			this.deleteToLineStart();
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.deleteToLineEnd")) {
+			this.deleteToLineEnd();
+			return;
+		}
+
+		// Kill ring actions
+		if (kb.matches(data, "tui.editor.yank")) {
+			this.yank();
+			return;
+		}
+		if (kb.matches(data, "tui.editor.yankPop")) {
+			this.yankPop();
+			return;
+		}
+
+		// Cursor movement
+		if (kb.matches(data, "tui.editor.cursorLeft")) {
+			this.lastAction = null;
+			if (this.cursor > 0) {
+				const beforeCursor = this.value.slice(0, this.cursor);
+				const graphemes = [...segmenter.segment(beforeCursor)];
+				const lastGrapheme = graphemes[graphemes.length - 1];
+				this.cursor -= lastGrapheme ? lastGrapheme.segment.length : 1;
+			}
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.cursorRight")) {
+			this.lastAction = null;
+			if (this.cursor < this.value.length) {
+				const afterCursor = this.value.slice(this.cursor);
+				const graphemes = [...segmenter.segment(afterCursor)];
+				const firstGrapheme = graphemes[0];
+				this.cursor += firstGrapheme ? firstGrapheme.segment.length : 1;
+			}
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.cursorLineStart")) {
+			this.lastAction = null;
+			this.cursor = 0;
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.cursorLineEnd")) {
+			this.lastAction = null;
+			this.cursor = this.value.length;
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.cursorWordLeft")) {
+			this.moveWordBackwards();
+			return;
+		}
+
+		if (kb.matches(data, "tui.editor.cursorWordRight")) {
+			this.moveWordForwards();
+			return;
+		}
+
+		// Kitty CSI-u printable character (e.g. \x1b[97u for 'a').
+		// Terminals with Kitty protocol flag 1 (disambiguate) send CSI-u for all keys,
+		// including plain printable characters. Decode before the control-char check
+		// since CSI-u sequences contain \x1b which would be rejected.
+		const kittyPrintable = decodeKittyPrintable(data);
+		if (kittyPrintable !== undefined) {
+			this.insertCharacter(kittyPrintable);
+			return;
+		}
+
+		// Regular character input - accept printable characters including Unicode,
+		// but reject control characters (C0: 0x00-0x1F, DEL: 0x7F, C1: 0x80-0x9F)
+		const hasControlChars = [...data].some((ch) => {
+			const code = ch.charCodeAt(0);
+			return code < 32 || code === 0x7f || (code >= 0x80 && code <= 0x9f);
+		});
+		if (!hasControlChars) {
+			this.insertCharacter(data);
+		}
+	}
+
+	private insertCharacter(char: string): void {
+		// Undo coalescing: consecutive word chars coalesce into one undo unit
+		if (isWhitespaceChar(char) || this.lastAction !== "type-word") {
+			this.pushUndo();
+		}
+		this.lastAction = "type-word";
+
+		this.value = this.value.slice(0, this.cursor) + char + this.value.slice(this.cursor);
+		this.cursor += char.length;
+	}
+
+	private handleBackspace(): void {
+		this.lastAction = null;
+		if (this.cursor > 0) {
+			this.pushUndo();
+			const beforeCursor = this.value.slice(0, this.cursor);
+			const graphemes = [...segmenter.segment(beforeCursor)];
+			const lastGrapheme = graphemes[graphemes.length - 1];
+			const graphemeLength = lastGrapheme ? lastGrapheme.segment.length : 1;
+			this.value = this.value.slice(0, this.cursor - graphemeLength) + this.value.slice(this.cursor);
+			this.cursor -= graphemeLength;
+		}
+	}
+
+	private handleForwardDelete(): void {
+		this.lastAction = null;
+		if (this.cursor < this.value.length) {
+			this.pushUndo();
+			const afterCursor = this.value.slice(this.cursor);
+			const graphemes = [...segmenter.segment(afterCursor)];
+			const firstGrapheme = graphemes[0];
+			const graphemeLength = firstGrapheme ? firstGrapheme.segment.length : 1;
+			this.value = this.value.slice(0, this.cursor) + this.value.slice(this.cursor + graphemeLength);
+		}
+	}
+
+	private deleteToLineStart(): void {
+		if (this.cursor === 0) return;
+		this.pushUndo();
+		const deletedText = this.value.slice(0, this.cursor);
+		this.killRing.push(deletedText, { prepend: true, accumulate: this.lastAction === "kill" });
+		this.lastAction = "kill";
+		this.value = this.value.slice(this.cursor);
+		this.cursor = 0;
+	}
+
+	private deleteToLineEnd(): void {
+		if (this.cursor >= this.value.length) return;
+		this.pushUndo();
+		const deletedText = this.value.slice(this.cursor);
+		this.killRing.push(deletedText, { prepend: false, accumulate: this.lastAction === "kill" });
+		this.lastAction = "kill";
+		this.value = this.value.slice(0, this.cursor);
+	}
+
+	private deleteWordBackwards(): void {
+		if (this.cursor === 0) return;
+
+		// Save lastAction before cursor movement (moveWordBackwards resets it)
+		const wasKill = this.lastAction === "kill";
+
+		this.pushUndo();
+
+		const oldCursor = this.cursor;
+		this.moveWordBackwards();
+		const deleteFrom = this.cursor;
+		this.cursor = oldCursor;
+
+		const deletedText = this.value.slice(deleteFrom, this.cursor);
+		this.killRing.push(deletedText, { prepend: true, accumulate: wasKill });
+		this.lastAction = "kill";
+
+		this.value = this.value.slice(0, deleteFrom) + this.value.slice(this.cursor);
+		this.cursor = deleteFrom;
+	}
+
+	private deleteWordForward(): void {
+		if (this.cursor >= this.value.length) return;
+
+		// Save lastAction before cursor movement (moveWordForwards resets it)
+		const wasKill = this.lastAction === "kill";
+
+		this.pushUndo();
+
+		const oldCursor = this.cursor;
+		this.moveWordForwards();
+		const deleteTo = this.cursor;
+		this.cursor = oldCursor;
+
+		const deletedText = this.value.slice(this.cursor, deleteTo);
+		this.killRing.push(deletedText, { prepend: false, accumulate: wasKill });
+		this.lastAction = "kill";
+
+		this.value = this.value.slice(0, this.cursor) + this.value.slice(deleteTo);
+	}
+
+	private yank(): void {
+		const text = this.killRing.peek();
+		if (!text) return;
+
+		this.pushUndo();
+
+		this.value = this.value.slice(0, this.cursor) + text + this.value.slice(this.cursor);
+		this.cursor += text.length;
+		this.lastAction = "yank";
+	}
+
+	private yankPop(): void {
+		if (this.lastAction !== "yank" || this.killRing.length <= 1) return;
+
+		this.pushUndo();
+
+		// Delete the previously yanked text (still at end of ring before rotation)
+		const prevText = this.killRing.peek() || "";
+		this.value = this.value.slice(0, this.cursor - prevText.length) + this.value.slice(this.cursor);
+		this.cursor -= prevText.length;
+
+		// Rotate and insert new entry
+		this.killRing.rotate();
+		const text = this.killRing.peek() || "";
+		this.value = this.value.slice(0, this.cursor) + text + this.value.slice(this.cursor);
+		this.cursor += text.length;
+		this.lastAction = "yank";
+	}
+
+	private pushUndo(): void {
+		this.undoStack.push({ value: this.value, cursor: this.cursor });
+	}
+
+	private undo(): void {
+		const snapshot = this.undoStack.pop();
+		if (!snapshot) return;
+		this.value = snapshot.value;
+		this.cursor = snapshot.cursor;
+		this.lastAction = null;
+	}
+
+	private moveWordBackwards(): void {
+		if (this.cursor === 0) {
+			return;
+		}
+
+		this.lastAction = null;
+		const textBeforeCursor = this.value.slice(0, this.cursor);
+		const graphemes = [...segmenter.segment(textBeforeCursor)];
+
+		// Skip trailing whitespace
+		while (graphemes.length > 0 && isWhitespaceChar(graphemes[graphemes.length - 1]?.segment || "")) {
+			this.cursor -= graphemes.pop()?.segment.length || 0;
+		}
+
+		if (graphemes.length > 0) {
+			const lastGrapheme = graphemes[graphemes.length - 1]?.segment || "";
+			if (isPunctuationChar(lastGrapheme)) {
+				// Skip punctuation run
+				while (graphemes.length > 0 && isPunctuationChar(graphemes[graphemes.length - 1]?.segment || "")) {
+					this.cursor -= graphemes.pop()?.segment.length || 0;
+				}
+			} else {
+				// Skip word run
+				while (
+					graphemes.length > 0 &&
+					!isWhitespaceChar(graphemes[graphemes.length - 1]?.segment || "") &&
+					!isPunctuationChar(graphemes[graphemes.length - 1]?.segment || "")
+				) {
+					this.cursor -= graphemes.pop()?.segment.length || 0;
+				}
+			}
+		}
+	}
+
+	private moveWordForwards(): void {
+		if (this.cursor >= this.value.length) {
+			return;
+		}
+
+		this.lastAction = null;
+		const textAfterCursor = this.value.slice(this.cursor);
+		const segments = segmenter.segment(textAfterCursor);
+		const iterator = segments[Symbol.iterator]();
+		let next = iterator.next();
+
+		// Skip leading whitespace
+		while (!next.done && isWhitespaceChar(next.value.segment)) {
+			this.cursor += next.value.segment.length;
+			next = iterator.next();
+		}
+
+		if (!next.done) {
+			const firstGrapheme = next.value.segment;
+			if (isPunctuationChar(firstGrapheme)) {
+				// Skip punctuation run
+				while (!next.done && isPunctuationChar(next.value.segment)) {
+					this.cursor += next.value.segment.length;
+					next = iterator.next();
+				}
+			} else {
+				// Skip word run
+				while (!next.done && !isWhitespaceChar(next.value.segment) && !isPunctuationChar(next.value.segment)) {
+					this.cursor += next.value.segment.length;
+					next = iterator.next();
+				}
+			}
+		}
+	}
+
+	private handlePaste(pastedText: string): void {
+		this.lastAction = null;
+		this.pushUndo();
+
+		// Clean the pasted text - remove newlines and carriage returns
+		const cleanText = pastedText.replace(/\r\n/g, "").replace(/\r/g, "").replace(/\n/g, "").replace(/\t/g, "    ");
+
+		// Insert at cursor position
+		this.value = this.value.slice(0, this.cursor) + cleanText + this.value.slice(this.cursor);
+		this.cursor += cleanText.length;
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate currently
+	}
+
+	render(width: number): string[] {
+		// Calculate visible window
+		const prompt = "> ";
+		const availableWidth = width - prompt.length;
+
+		if (availableWidth <= 0) {
+			return [prompt];
+		}
+
+		let visibleText = "";
+		let cursorDisplay = this.cursor;
+		const totalWidth = visibleWidth(this.value);
+
+		if (totalWidth < availableWidth) {
+			// Everything fits (leave room for cursor at end)
+			visibleText = this.value;
+		} else {
+			// Need horizontal scrolling
+			// Reserve one column for cursor if it's at the end
+			const scrollWidth = this.cursor === this.value.length ? availableWidth - 1 : availableWidth;
+			const cursorCol = visibleWidth(this.value.slice(0, this.cursor));
+
+			if (scrollWidth > 0) {
+				const halfWidth = Math.floor(scrollWidth / 2);
+				let startCol = 0;
+
+				if (cursorCol < halfWidth) {
+					// Cursor near start
+					startCol = 0;
+				} else if (cursorCol > totalWidth - halfWidth) {
+					// Cursor near end
+					startCol = Math.max(0, totalWidth - scrollWidth);
+				} else {
+					// Cursor in middle
+					startCol = Math.max(0, cursorCol - halfWidth);
+				}
+
+				visibleText = sliceByColumn(this.value, startCol, scrollWidth, true);
+				const beforeCursor = sliceByColumn(this.value, startCol, Math.max(0, cursorCol - startCol), true);
+				cursorDisplay = beforeCursor.length;
+			} else {
+				visibleText = "";
+				cursorDisplay = 0;
+			}
+		}
+
+		// Build line with fake cursor
+		// Insert cursor character at cursor position
+		const graphemes = [...segmenter.segment(visibleText.slice(cursorDisplay))];
+		const cursorGrapheme = graphemes[0];
+
+		const beforeCursor = visibleText.slice(0, cursorDisplay);
+		const atCursor = cursorGrapheme?.segment ?? " "; // Character at cursor, or space if at end
+		const afterCursor = visibleText.slice(cursorDisplay + atCursor.length);
+
+		// Hardware cursor marker (zero-width, emitted before fake cursor for IME positioning)
+		const marker = this.focused ? CURSOR_MARKER : "";
+
+		// Use inverse video to show cursor
+		const cursorChar = `\x1b[7m${atCursor}\x1b[27m`; // ESC[7m = reverse video, ESC[27m = normal
+		const textWithCursor = beforeCursor + marker + cursorChar + afterCursor;
+
+		// Calculate visual width
+		const visualLength = visibleWidth(textWithCursor);
+		const padding = " ".repeat(Math.max(0, availableWidth - visualLength));
+		const line = prompt + textWithCursor + padding;
+
+		return [line];
+	}
+}

package/src/components/loader.ts

@@ -0,0 +1,86 @@
+import type { TUI } from "../tui.js";
+import { Text } from "./text.js";
+
+export interface LoaderIndicatorOptions {
+	/** Animation frames. Use an empty array to hide the indicator. */
+	frames?: string[];
+	/** Frame interval in milliseconds for animated indicators. */
+	intervalMs?: number;
+}
+
+const DEFAULT_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const DEFAULT_INTERVAL_MS = 80;
+
+/**
+ * Loader component that updates with an optional spinning animation.
+ */
+export class Loader extends Text {
+	private frames = [...DEFAULT_FRAMES];
+	private intervalMs = DEFAULT_INTERVAL_MS;
+	private currentFrame = 0;
+	private intervalId: NodeJS.Timeout | null = null;
+	private ui: TUI | null = null;
+	private renderIndicatorVerbatim = false;
+
+	constructor(
+		ui: TUI,
+		private spinnerColorFn: (str: string) => string,
+		private messageColorFn: (str: string) => string,
+		private message: string = "Loading...",
+		indicator?: LoaderIndicatorOptions,
+	) {
+		super("", 1, 0);
+		this.ui = ui;
+		this.setIndicator(indicator);
+	}
+
+	render(width: number): string[] {
+		return ["", ...super.render(width)];
+	}
+
+	start(): void {
+		this.updateDisplay();
+		this.restartAnimation();
+	}
+
+	stop(): void {
+		if (this.intervalId) {
+			clearInterval(this.intervalId);
+			this.intervalId = null;
+		}
+	}
+
+	setMessage(message: string): void {
+		this.message = message;
+		this.updateDisplay();
+	}
+
+	setIndicator(indicator?: LoaderIndicatorOptions): void {
+		this.renderIndicatorVerbatim = indicator !== undefined;
+		this.frames = indicator?.frames !== undefined ? [...indicator.frames] : [...DEFAULT_FRAMES];
+		this.intervalMs = indicator?.intervalMs && indicator.intervalMs > 0 ? indicator.intervalMs : DEFAULT_INTERVAL_MS;
+		this.currentFrame = 0;
+		this.start();
+	}
+
+	private restartAnimation(): void {
+		this.stop();
+		if (this.frames.length <= 1) {
+			return;
+		}
+		this.intervalId = setInterval(() => {
+			this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+			this.updateDisplay();
+		}, this.intervalMs);
+	}
+
+	private updateDisplay(): void {
+		const frame = this.frames[this.currentFrame] ?? "";
+		const renderedFrame = this.renderIndicatorVerbatim ? frame : this.spinnerColorFn(frame);
+		const indicator = frame.length > 0 ? `${renderedFrame} ` : "";
+		this.setText(`${indicator}${this.messageColorFn(this.message)}`);
+		if (this.ui) {
+			this.ui.requestRender();
+		}
+	}
+}