@linxiraos/pi-tui 1.0.0

package/src/components/input.ts

@@ -0,0 +1,482 @@
+import { BracketedPasteHandler, decodeReencodedPasteControls } from "../bracketed-paste";
+import { getKeybindings } from "../keybindings";
+import { extractPrintableText } from "../keys";
+import { KillRing } from "../kill-ring";
+import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
+import {
+	getSegmenter,
+	getWordNavKind,
+	moveWordLeft,
+	moveWordRight,
+	padding,
+	replaceTabs,
+	sliceWithWidth,
+	visibleWidth,
+} from "../utils";
+
+const segmenter = getSegmenter();
+
+interface InputState {
+	value: string;
+	cursor: number;
+}
+
+/**
+ * Input component - single-line text input with horizontal scrolling
+ */
+export class Input implements Component, Focusable {
+	#value: string = "";
+	#cursor: number = 0; // Cursor position in the value
+	#useTerminalCursor = false;
+	/** Rendered before the editable area; set to "" for chrome-less embedding. */
+	prompt = "> ";
+	/** Render the editable value as bullets while retaining the real value internally. */
+	mask = false;
+	onSubmit?: (value: string) => void;
+	onEscape?: () => void;
+
+	/** Focusable interface - set by TUI when focus changes */
+	focused: boolean = false;
+
+	// Bracketed paste mode buffering
+	#pasteHandler = new BracketedPasteHandler();
+
+	// Kill ring for Emacs-style kill/yank operations
+	#killRing = new KillRing();
+	#lastAction: "kill" | "yank" | "type-word" | null = null;
+
+	// Undo support
+	#undoStack: InputState[] = [];
+
+	getValue(): string {
+		return this.#value;
+	}
+
+	setValue(value: string): void {
+		this.#value = value;
+		// Callers seed or replace the value wholesale; typing continues at the end.
+		this.#cursor = value.length;
+	}
+
+	setUseTerminalCursor(useTerminalCursor: boolean): void {
+		this.#useTerminalCursor = useTerminalCursor;
+	}
+
+	getUseTerminalCursor(): boolean {
+		return this.#useTerminalCursor;
+	}
+
+	handleInput(data: string): void {
+		// Handle bracketed paste mode
+		const paste = this.#pasteHandler.process(data);
+		if (paste.handled) {
+			if (paste.pasteContent !== undefined) {
+				this.#handlePaste(paste.pasteContent);
+				if (paste.remaining.length > 0) {
+					this.handleInput(paste.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;
+		}
+
+		// Regular character input, including Kitty CSI-u text-producing sequences.
+		const printableText = extractPrintableText(data);
+		if (printableText) {
+			this.#insertCharacter(printableText);
+		}
+	}
+
+	/** Apply terminal paste semantics to text from non-bracketed paste transports
+	 *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
+	pasteText(text: string): void {
+		this.#handlePaste(text);
+	}
+
+	#insertCharacter(text: string): void {
+		const isWordChunk = [...segmenter.segment(text)].every(seg => getWordNavKind(seg.segment) !== "whitespace");
+		// Undo coalescing: consecutive word typing coalesces into one undo unit.
+		if (!isWordChunk || this.#lastAction !== "type-word") {
+			this.#pushUndo();
+		}
+		this.#lastAction = "type-word";
+
+		this.#value = this.#value.slice(0, this.#cursor) + text + this.#value.slice(this.#cursor);
+		this.#cursor += text.length;
+	}
+
+	#handleBackspace(): void {
+		this.#lastAction = null;
+		if (this.#cursor <= 0) {
+			return;
+		}
+
+		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;
+	}
+
+	#handleForwardDelete(): void {
+		this.#lastAction = null;
+		if (this.#cursor >= this.#value.length) {
+			return;
+		}
+
+		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);
+	}
+
+	#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;
+	}
+
+	#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);
+	}
+
+	#deleteWordBackwards(): void {
+		if (this.#cursor === 0) {
+			return;
+		}
+
+		// Save state before cursor movement (moveWordBackwards resets lastAction).
+		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;
+	}
+
+	#deleteWordForward(): void {
+		if (this.#cursor >= this.#value.length) {
+			return;
+		}
+
+		// Save state before cursor movement (moveWordForwards resets lastAction).
+		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);
+	}
+
+	#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";
+	}
+
+	#yankPop(): void {
+		if (this.#lastAction !== "yank" || this.#killRing.length <= 1) {
+			return;
+		}
+
+		this.#pushUndo();
+
+		const prevText = this.#killRing.peek() ?? "";
+		this.#value = this.#value.slice(0, this.#cursor - prevText.length) + this.#value.slice(this.#cursor);
+		this.#cursor -= prevText.length;
+
+		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";
+	}
+
+	#pushUndo(): void {
+		this.#undoStack.push({ value: this.#value, cursor: this.#cursor });
+	}
+
+	#undo(): void {
+		const snapshot = this.#undoStack.pop();
+		if (!snapshot) {
+			return;
+		}
+		this.#value = snapshot.value;
+		this.#cursor = snapshot.cursor;
+		this.#lastAction = null;
+	}
+
+	#moveWordBackwards(): void {
+		if (this.#cursor === 0) {
+			return;
+		}
+		this.#lastAction = null;
+		this.#cursor = moveWordLeft(this.#value, this.#cursor);
+	}
+
+	#moveWordForwards(): void {
+		if (this.#cursor >= this.#value.length) {
+			return;
+		}
+		this.#lastAction = null;
+		this.#cursor = moveWordRight(this.#value, this.#cursor);
+	}
+
+	#handlePaste(pastedText: string): void {
+		this.#lastAction = null;
+		this.#pushUndo();
+
+		// Clean the pasted text — decode tmux's re-encoded control bytes (both
+		// extended-keys formats, e.g. Ctrl+J → "\n") back to literal bytes so the escape
+		// tail does not leak in, remove newlines/carriage returns, expand tabs, NFC-normalize,
+		// then strip any remaining control bytes. The decoder can synthesize Ctrl+A..Ctrl+Z
+		// (0x01..0x1A) from a paste, and a single-line value must hold none of them — newlines
+		// are already gone and tabs are already spaces by the time the C0/DEL strip runs.
+		//
+		// NFC normalization rationale: macOS Finder drag-drops file paths in NFD
+		// (Conjoining Jamo, U+1100..U+11FF). `Bun.stringWidth` counts each
+		// conjoining jamo as a separate cell — a Korean syllable like `화` is
+		// 1 char and 2 cells in NFC, but 2 chars and 3 cells in NFD (ᄒ=2 cells
+		// + ᅪ=1 cell). The terminal renders the NFD sequence as a single
+		// combined syllable (2 cells visible), so the width mismatch shows up
+		// as cursor drift past the visible filename — N×~1.5 cells for a path
+		// with N Korean syllables. NFC normalization at paste time stores the
+		// value in the same form everything else in the codebase assumes.
+		const cleanText = replaceTabs(
+			decodeReencodedPasteControls(pastedText).replace(/\r\n/g, "").replace(/\r/g, "").replace(/\n/g, ""),
+		)
+			.normalize("NFC")
+			.replace(/[\x00-\x1F\x7F]/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): readonly string[] {
+		// Calculate visible window
+		const prompt = this.prompt;
+		const availableWidth = width - visibleWidth(prompt);
+
+		if (availableWidth <= 0) {
+			return [prompt];
+		}
+
+		let cursorIndex = this.#cursor;
+		// Ensure we always have a grapheme to invert at the cursor (space at end).
+		let visibleValue = this.#value;
+		if (this.mask) {
+			const graphemes = [...segmenter.segment(this.#value)];
+			visibleValue = "•".repeat(graphemes.length);
+			cursorIndex = graphemes.filter(grapheme => grapheme.index < this.#cursor).length;
+		}
+		const displayValue = this.#cursor >= this.#value.length ? `${visibleValue} ` : visibleValue;
+
+		const totalCols = visibleWidth(displayValue);
+		const cursorCols = visibleWidth(displayValue.slice(0, cursorIndex));
+
+		// Width of the grapheme at the cursor, for ensuring it fits in the viewport.
+		const cursorIter = segmenter.segment(displayValue.slice(cursorIndex))[Symbol.iterator]();
+		const cursorG = cursorIter.next().value?.segment ?? " ";
+		const cursorGWidth = visibleWidth(cursorG);
+
+		const maxStart = Math.max(0, totalCols - availableWidth);
+		let startCol = 0;
+		if (totalCols > availableWidth) {
+			const half = Math.floor(availableWidth / 2);
+			startCol = Math.max(0, Math.min(maxStart, cursorCols - half));
+
+			// Ensure the cursor grapheme is inside the viewport (and fits fully if wide).
+			const maxCursorRel = Math.max(0, availableWidth - cursorGWidth);
+			const cursorRel = cursorCols - startCol;
+			if (cursorRel > maxCursorRel) {
+				startCol = Math.max(0, Math.min(maxStart, cursorCols - maxCursorRel));
+			}
+		}
+
+		const visibleText = sliceWithWidth(displayValue, startCol, availableWidth, true).text;
+		const prefixText = sliceWithWidth(displayValue, startCol, Math.max(0, cursorCols - startCol), true).text;
+		let cursorDisplay = prefixText.length;
+		cursorDisplay = Math.max(0, Math.min(cursorDisplay, visibleText.length));
+
+		// Build the visible line and insert the cursor marker at the buffer cursor.
+		const graphemes = [...segmenter.segment(visibleText.slice(cursorDisplay))];
+		const cursorGrapheme = graphemes[0];
+
+		const beforeCursor = visibleText.slice(0, cursorDisplay);
+		const atCursor = cursorGrapheme?.segment ?? "";
+		const afterCursor = visibleText.slice(cursorDisplay + atCursor.length);
+
+		// Hardware cursor marker (zero-width, emitted before the cursor cell for IME positioning)
+		const marker = this.focused ? CURSOR_MARKER : "";
+		const cursorChar = this.#useTerminalCursor ? atCursor : `\x1b[7m${atCursor || " "}\x1b[27m`;
+
+		// Clamp only the trailing text (measured in terminal cells), keeping the cursor marker intact.
+		const beforeWidth = visibleWidth(beforeCursor);
+		const cursorWidth = this.#useTerminalCursor ? visibleWidth(atCursor) : visibleWidth(atCursor || " ");
+		const remainingAfterWidth = Math.max(0, availableWidth - beforeWidth - cursorWidth);
+		const clampedAfterCursor = sliceWithWidth(afterCursor, 0, remainingAfterWidth, true).text;
+		const renderedNoMarker = beforeCursor + cursorChar + clampedAfterCursor;
+		const textWithCursor = beforeCursor + marker + cursorChar + clampedAfterCursor;
+
+		const visualLength = visibleWidth(renderedNoMarker);
+		const pad = padding(Math.max(0, availableWidth - visualLength));
+		const line = prompt + textWithCursor + pad;
+		return [line];
+	}
+}

package/src/components/loader.ts

@@ -0,0 +1,174 @@
+import type { TUI } from "../tui";
+import { getPaddingX, sliceByColumn, visibleWidth } from "../utils";
+import { Text } from "./text";
+
+const RENDER_INTERVAL_MS = 1000 / 30;
+const SPINNER_ADVANCE_MS = 80;
+const MAX_RENDER_BACKPRESSURE_MS = 200;
+const RENDER_BACKPRESSURE_MULTIPLIER = 9;
+
+type ColorFn = (str: string) => string;
+
+/**
+ * Styles Loader message fragments without changing their visible text or width.
+ * Set `animated` for colorizers whose ANSI output changes over time.
+ */
+export type LoaderMessageColorFn = ColorFn & {
+	readonly animated?: true;
+};
+
+/** Animates a spinner and colorized message while asynchronous work is pending. */
+export class Loader extends Text {
+	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+	#currentFrame = 0;
+	#intervalId?: NodeJS.Timeout;
+	#ui: TUI | null = null;
+	#lastSpinnerTick = 0;
+	#layoutSource?: readonly string[];
+	#layout?: readonly { leading: string; content: string; trailing: string }[];
+	#layoutFrames: readonly string[];
+	#layoutFrame: string;
+
+	constructor(
+		ui: TUI,
+		private spinnerColorFn: ColorFn,
+		private messageColorFn: LoaderMessageColorFn,
+		private message: string = "Loading...",
+		spinnerFrames?: string[],
+	) {
+		super("", 1, 0);
+		this.#ui = ui;
+		if (spinnerFrames && spinnerFrames.length > 0) {
+			this.#frames = spinnerFrames;
+		}
+		const representatives = new Map<number, string>();
+		this.#layoutFrames = this.#frames.map(frame => {
+			const width = visibleWidth(frame);
+			const representative = representatives.get(width);
+			if (representative !== undefined) {
+				return representative;
+			}
+			representatives.set(width, frame);
+			return frame;
+		});
+		this.#layoutFrame = this.#layoutFrames[0];
+		this.start();
+	}
+
+	override render(width: number): readonly string[] {
+		const source = super.render(width);
+		if (source !== this.#layoutSource) {
+			const paddingX = getPaddingX(1);
+			this.#layoutSource = source;
+			this.#layout = source.map(line => {
+				const clamped = visibleWidth(line) > width ? sliceByColumn(line, 0, width, true) : line;
+				const body = clamped.slice(paddingX);
+				const content = body.trimEnd();
+				return {
+					leading: clamped.slice(0, paddingX),
+					content,
+					trailing: body.slice(content.length),
+				};
+			});
+		}
+
+		const frame = this.#frames[this.#currentFrame];
+		// The wrapped text carries one stable representative per frame width.
+		// Same-width frames swap only the visible glyph here; crossing widths
+		// rewraps against the representative selected by #syncText.
+		const sentinel = this.#layoutFrame;
+		const lines = [""];
+		const layout = this.#layout ?? [];
+		for (let i = 0; i < layout.length; i++) {
+			const { leading, content, trailing } = layout[i];
+			if (i === 0 && content.startsWith(sentinel)) {
+				const remainder = content.slice(sentinel.length);
+				const separator = remainder.startsWith(" ") ? " " : "";
+				const message = remainder.slice(separator.length);
+				lines.push(
+					`${leading}${this.spinnerColorFn(frame)}${separator}${message ? this.messageColorFn(message) : ""}${trailing}`,
+				);
+			} else {
+				lines.push(`${leading}${content ? this.messageColorFn(content) : ""}${trailing}`);
+			}
+		}
+		return lines;
+	}
+
+	start() {
+		this.#lastSpinnerTick = performance.now();
+		this.#syncText();
+		this.#requestPaint();
+		const intervalMs = this.messageColorFn.animated === true ? RENDER_INTERVAL_MS : SPINNER_ADVANCE_MS;
+		this.#scheduleTick(intervalMs, intervalMs);
+	}
+
+	stop() {
+		if (this.#intervalId) {
+			clearTimeout(this.#intervalId);
+			this.#intervalId = undefined;
+		}
+	}
+
+	/** Lifecycle teardown: stop the animation timer. Idempotent. */
+	dispose() {
+		this.stop();
+	}
+
+	setMessage(message: string) {
+		if (message === this.message) {
+			return;
+		}
+		this.message = message;
+		this.#syncText();
+		this.#requestPaint();
+	}
+
+	#scheduleTick(intervalMs: number, delayMs: number): void {
+		const timer = setTimeout(() => {
+			if (this.#intervalId !== timer) return;
+			const startedAt = performance.now();
+			const elapsed = startedAt - this.#lastSpinnerTick;
+			const shouldAdvanceSpinner = elapsed >= SPINNER_ADVANCE_MS;
+			if (shouldAdvanceSpinner) {
+				const steps = Math.floor(elapsed / SPINNER_ADVANCE_MS);
+				this.#currentFrame = (this.#currentFrame + steps) % this.#frames.length;
+				this.#lastSpinnerTick += steps * SPINNER_ADVANCE_MS;
+				this.#syncText();
+			}
+			if (shouldAdvanceSpinner || this.#ui?.synchronizedOutput === true) {
+				this.#requestPaint();
+			}
+
+			const frameCostMs = performance.now() - startedAt;
+			if (this.#intervalId !== timer) return;
+			const cadenceDelayMs = Math.max(0, intervalMs - frameCostMs);
+			// Idle for nine times the paint cost to keep animation at or below
+			// 10% CPU, while cheap frames retain their original cadence.
+			const backpressureDelayMs = Math.min(MAX_RENDER_BACKPRESSURE_MS, frameCostMs * RENDER_BACKPRESSURE_MULTIPLIER);
+			this.#scheduleTick(intervalMs, Math.max(cadenceDelayMs, backpressureDelayMs));
+		}, delayMs);
+		this.#intervalId = timer;
+	}
+	/** Re-wrap the underlying Text only when its message or frame width changes. */
+	#syncText(): boolean {
+		const layoutFrame = this.#layoutFrames[this.#currentFrame];
+		this.#layoutFrame = layoutFrame;
+		return this.setText(`${layoutFrame} ${this.message}`);
+	}
+
+	#requestPaint() {
+		if (!this.#ui) {
+			return;
+		}
+		// Direct write: a loader tick changes only this component, so the TUI can
+		// update the already-positioned rows without driving the full
+		// compose/prepare/diff pipeline. Lightweight test stubs may not carry the
+		// newer API; keep their legacy component-scoped path working.
+		if (typeof this.#ui.requestDirectWrite === "function") {
+			this.#ui.requestDirectWrite(this);
+		} else {
+			this.#ui.requestComponentRender(this);
+		}
+	}
+}