@oh-my-pi/pi-tui 3.14.0 → 3.15.1

package/README.md

@@ -154,9 +154,52 @@ input.getValue();
 Multi-line text editor with autocomplete, file completion, and paste handling.
 
 ```typescript
+interface SymbolTheme {
+	cursor: string;
+	ellipsis: string;
+	boxRound: {
+		topLeft: string;
+		topRight: string;
+		bottomLeft: string;
+		bottomRight: string;
+		horizontal: string;
+		vertical: string;
+	};
+	boxSharp: {
+		topLeft: string;
+		topRight: string;
+		bottomLeft: string;
+		bottomRight: string;
+		horizontal: string;
+		vertical: string;
+		teeDown: string;
+		teeUp: string;
+		teeLeft: string;
+		teeRight: string;
+		cross: string;
+	};
+	table: {
+		topLeft: string;
+		topRight: string;
+		bottomLeft: string;
+		bottomRight: string;
+		horizontal: string;
+		vertical: string;
+		teeDown: string;
+		teeUp: string;
+		teeLeft: string;
+		teeRight: string;
+		cross: string;
+	};
+	quoteBorder: string;
+	hrChar: string;
+	spinnerFrames: string[];
+}
+
 interface EditorTheme {
 	borderColor: (str: string) => string;
 	selectList: SelectListTheme;
+	symbols: SymbolTheme;
 }
 
 const editor = new Editor(theme);
@@ -206,6 +249,7 @@ interface MarkdownTheme {
 	strikethrough: (text: string) => string;
 	underline: (text: string) => string;
 	highlightCode?: (code: string, lang?: string) => string[];
+	symbols: SymbolTheme;
 }
 
 interface DefaultTextStyle {
@@ -289,6 +333,7 @@ interface SelectListTheme {
 	description: (text: string) => string;
 	scrollInfo: (text: string) => string;
 	noMatch: (text: string) => string;
+	symbols: SymbolTheme;
 }
 
 const list = new SelectList(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-tui",
-	"version": "3.14.0",
+	"version": "3.15.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "src/index.ts",

package/src/components/editor.ts

@@ -25,6 +25,7 @@ import {
 	isShiftEnter,
 	isTab,
 } from "../keys";
+import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { getSegmenter, isPunctuationChar, isWhitespaceChar, truncateToWidth, visibleWidth } from "../utils";
 import { SelectList, type SelectListTheme } from "./select-list";
@@ -46,6 +47,7 @@ interface LayoutLine {
 export interface EditorTheme {
 	borderColor: (str: string) => string;
 	selectList: SelectListTheme;
+	symbols: SymbolTheme;
 }
 
 export interface EditorTopBorder {
@@ -63,6 +65,7 @@ export class Editor implements Component {
 	};
 
 	private theme: EditorTheme;
+	private useTerminalCursor = false;
 
 	// Store last render width for cursor navigation
 	private lastWidth: number = 80;
@@ -112,6 +115,13 @@ export class Editor implements Component {
 		this.topBorderContent = content;
 	}
 
+	/**
+	 * Use the real terminal cursor instead of rendering a cursor glyph.
+	 */
+	setUseTerminalCursor(useTerminalCursor: boolean): void {
+		this.useTerminalCursor = useTerminalCursor;
+	}
+
 	/**
 	 * Add a prompt to history for up/down arrow navigation.
 	 * Called after successful submission.
@@ -181,11 +191,12 @@ export class Editor implements Component {
 		this.lastWidth = width;
 
 		// Box-drawing characters for rounded corners
-		const topLeft = this.borderColor("╭─");
-		const topRight = this.borderColor("─╮");
-		const bottomLeft = this.borderColor("╰─");
-		const bottomRight = this.borderColor("─╯");
-		const horizontal = this.borderColor("─");
+		const box = this.theme.symbols.boxRound;
+		const topLeft = this.borderColor(`${box.topLeft}${box.horizontal}`);
+		const topRight = this.borderColor(`${box.horizontal}${box.topRight}`);
+		const bottomLeft = this.borderColor(`${box.bottomLeft}${box.horizontal}`);
+		const bottomRight = this.borderColor(`${box.horizontal}${box.bottomRight}`);
+		const horizontal = this.borderColor(box.horizontal);
 
 		// Layout the text - content area is width minus 6 for borders (3 left + 3 right)
 		const contentAreaWidth = width - 6;
@@ -201,13 +212,13 @@ export class Editor implements Component {
 			if (statusWidth <= topFillWidth) {
 				// Status fits - add fill after it
 				const fillWidth = topFillWidth - statusWidth;
-				result.push(topLeft + content + this.borderColor("─".repeat(fillWidth)) + topRight);
+				result.push(topLeft + content + this.borderColor(box.horizontal.repeat(fillWidth)) + topRight);
 			} else {
 				// Status too long - truncate it
-				const truncated = truncateToWidth(content, topFillWidth - 1, this.borderColor("…"));
+				const truncated = truncateToWidth(content, topFillWidth - 1, this.borderColor(this.theme.symbols.ellipsis));
 				const truncatedWidth = visibleWidth(truncated);
 				const fillWidth = Math.max(0, topFillWidth - truncatedWidth);
-				result.push(topLeft + truncated + this.borderColor("─".repeat(fillWidth)) + topRight);
+				result.push(topLeft + truncated + this.borderColor(box.horizontal.repeat(fillWidth)) + topRight);
 			}
 		} else {
 			result.push(topLeft + horizontal.repeat(topFillWidth) + topRight);
@@ -221,7 +232,7 @@ export class Editor implements Component {
 			let displayWidth = visibleWidth(layoutLine.text);
 
 			// Add cursor if this line has it
-			if (layoutLine.hasCursor && layoutLine.cursorPos !== undefined) {
+			if (!this.useTerminalCursor && layoutLine.hasCursor && layoutLine.cursorPos !== undefined) {
 				const before = displayText.slice(0, layoutLine.cursorPos);
 				const after = displayText.slice(layoutLine.cursorPos);
 
@@ -236,10 +247,10 @@ export class Editor implements Component {
 					// displayWidth stays the same - we're replacing, not adding
 				} else {
 					// Cursor is at the end - add thin blinking bar cursor
-					// The ▏ character has width 1
-					const cursor = "\x1b[5m▏\x1b[0m";
+					const cursorChar = this.theme.symbols.inputCursor;
+					const cursor = `\x1b[5m${cursorChar}\x1b[0m`;
 					displayText = before + cursor;
-					displayWidth += 1; // Account for cursor width
+					displayWidth += visibleWidth(cursorChar);
 					if (displayWidth > lineContentWidth) {
 						// Line is at full width - use reverse video on last grapheme if possible
 						// or just show cursor at the end without adding space
@@ -267,8 +278,8 @@ export class Editor implements Component {
 				// Last line: "╰─ " (3) + content + padding + " ─╯" (3) = 6 chars border
 				result.push(`${bottomLeft} ${displayText}${padding} ${bottomRight}`);
 			} else {
-				const leftBorder = this.borderColor("│  ");
-				const rightBorder = this.borderColor("  │");
+				const leftBorder = this.borderColor(`${box.vertical}  `);
+				const rightBorder = this.borderColor(`  ${box.vertical}`);
 				result.push(leftBorder + displayText + padding + rightBorder);
 			}
 		}
@@ -282,6 +293,36 @@ export class Editor implements Component {
 		return result;
 	}
 
+	getCursorPosition(width: number): { row: number; col: number } | null {
+		if (!this.useTerminalCursor) return null;
+
+		const contentWidth = width - 6;
+		if (contentWidth <= 0) return null;
+
+		const layoutLines = this.layoutText(contentWidth);
+		for (let i = 0; i < layoutLines.length; i++) {
+			const layoutLine = layoutLines[i];
+			if (!layoutLine || !layoutLine.hasCursor || layoutLine.cursorPos === undefined) continue;
+
+			const lineWidth = visibleWidth(layoutLine.text);
+			const isCursorAtLineEnd = layoutLine.cursorPos === layoutLine.text.length;
+
+			if (isCursorAtLineEnd && lineWidth >= contentWidth && layoutLine.text.length > 0) {
+				const graphemes = [...segmenter.segment(layoutLine.text)];
+				const lastGrapheme = graphemes[graphemes.length - 1]?.segment || "";
+				const lastWidth = visibleWidth(lastGrapheme) || 1;
+				const colOffset = 3 + Math.max(0, lineWidth - lastWidth);
+				return { row: 1 + i, col: colOffset };
+			}
+
+			const before = layoutLine.text.slice(0, layoutLine.cursorPos);
+			const colOffset = 3 + visibleWidth(before);
+			return { row: 1 + i, col: colOffset };
+		}
+
+		return null;
+	}
+
 	handleInput(data: string): void {
 		// Handle bracketed paste mode
 		// Start of paste: \x1b[200~

package/src/components/loader.ts

@@ -15,9 +15,13 @@ export class Loader extends Text {
 		private spinnerColorFn: (str: string) => string,
 		private messageColorFn: (str: string) => string,
 		private message: string = "Loading...",
+		spinnerFrames?: string[],
 	) {
 		super("", 1, 0);
 		this.ui = ui;
+		if (spinnerFrames && spinnerFrames.length > 0) {
+			this.frames = spinnerFrames;
+		}
 		this.start();
 	}
 

package/src/components/markdown.ts

@@ -1,4 +1,5 @@
 import { marked, type Token } from "marked";
+import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { applyBackgroundToLine, visibleWidth, wrapTextWithAnsi } from "../utils";
 
@@ -41,6 +42,7 @@ export interface MarkdownTheme {
 	strikethrough: (text: string) => string;
 	underline: (text: string) => string;
 	highlightCode?: (code: string, lang?: string) => string[];
+	symbols: SymbolTheme;
 }
 
 export class Markdown implements Component {
@@ -301,7 +303,10 @@ export class Markdown implements Component {
 				const quoteText = this.renderInlineTokens(token.tokens || []);
 				const quoteLines = quoteText.split("\n");
 				for (const quoteLine of quoteLines) {
-					lines.push(this.theme.quoteBorder("│ ") + this.theme.quote(this.theme.italic(quoteLine)));
+					lines.push(
+						this.theme.quoteBorder(`${this.theme.symbols.quoteBorder} `) +
+							this.theme.quote(this.theme.italic(quoteLine)),
+					);
 				}
 				if (nextTokenType !== "space") {
 					lines.push(""); // Add spacing after blockquotes (unless space token follows)
@@ -310,7 +315,7 @@ export class Markdown implements Component {
 			}
 
 			case "hr":
-				lines.push(this.theme.hr("─".repeat(Math.min(width, 80))));
+				lines.push(this.theme.hr(this.theme.symbols.hrChar.repeat(Math.min(width, 80))));
 				if (nextTokenType !== "space") {
 					lines.push(""); // Add spacing after horizontal rules (unless space token follows)
 				}
@@ -595,9 +600,13 @@ export class Markdown implements Component {
 			}
 		}
 
+		const t = this.theme.symbols.table;
+		const h = t.horizontal;
+		const v = t.vertical;
+
 		// Render top border
-		const topBorderCells = columnWidths.map((w) => "─".repeat(w));
-		lines.push(`┌─${topBorderCells.join("─┬─")}─┐`);
+		const topBorderCells = columnWidths.map((w) => h.repeat(w));
+		lines.push(`${t.topLeft}${h}${topBorderCells.join(`${h}${t.teeDown}${h}`)}${h}${t.topRight}`);
 
 		// Render header with wrapping
 		const headerCellLines: string[][] = token.header.map((cell, i) => {
@@ -612,12 +621,12 @@ export class Markdown implements Component {
 				const padded = text + " ".repeat(Math.max(0, columnWidths[colIdx] - visibleWidth(text)));
 				return this.theme.bold(padded);
 			});
-			lines.push(`│ ${rowParts.join(" │ ")} │`);
+			lines.push(`${v} ${rowParts.join(` ${v} `)} ${v}`);
 		}
 
 		// Render separator
-		const separatorCells = columnWidths.map((w) => "─".repeat(w));
-		lines.push(`├─${separatorCells.join("─┼─")}─┤`);
+		const separatorCells = columnWidths.map((w) => h.repeat(w));
+		lines.push(`${t.teeRight}${h}${separatorCells.join(`${h}${t.cross}${h}`)}${h}${t.teeLeft}`);
 
 		// Render rows with wrapping
 		for (const row of token.rows) {
@@ -632,13 +641,13 @@ export class Markdown implements Component {
 					const text = cellLines[lineIdx] || "";
 					return text + " ".repeat(Math.max(0, columnWidths[colIdx] - visibleWidth(text)));
 				});
-				lines.push(`│ ${rowParts.join(" │ ")} │`);
+				lines.push(`${v} ${rowParts.join(` ${v} `)} ${v}`);
 			}
 		}
 
 		// Render bottom border
-		const bottomBorderCells = columnWidths.map((w) => "─".repeat(w));
-		lines.push(`└─${bottomBorderCells.join("─┴─")}─┘`);
+		const bottomBorderCells = columnWidths.map((w) => h.repeat(w));
+		lines.push(`${t.bottomLeft}${h}${bottomBorderCells.join(`${h}${t.teeUp}${h}`)}${h}${t.bottomRight}`);
 
 		lines.push(""); // Add spacing after table
 		return lines;

package/src/components/select-list.ts

@@ -1,6 +1,7 @@
 import { isArrowDown, isArrowUp, isCtrlC, isEnter, isEscape } from "../keys";
+import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
-import { truncateToWidth } from "../utils";
+import { truncateToWidth, visibleWidth } from "../utils";
 
 export interface SelectItem {
 	value: string;
@@ -14,6 +15,7 @@ export interface SelectListTheme {
 	description: (text: string) => string;
 	scrollInfo: (text: string) => string;
 	noMatch: (text: string) => string;
+	symbols: SymbolTheme;
 }
 
 export class SelectList implements Component {
@@ -74,7 +76,8 @@ export class SelectList implements Component {
 			let line = "";
 			if (isSelected) {
 				// Use arrow indicator for selection - entire line uses selectedText color
-				const prefixWidth = 2; // "→ " is 2 characters visually
+				const prefix = `${this.theme.symbols.cursor} `;
+				const prefixWidth = visibleWidth(prefix);
 				const displayValue = item.label || item.value;
 
 				if (item.description && width > 40) {
@@ -90,20 +93,20 @@ export class SelectList implements Component {
 					if (remainingWidth > 10) {
 						const truncatedDesc = truncateToWidth(item.description, remainingWidth, "");
 						// Apply selectedText to entire line content
-						line = this.theme.selectedText(`→ ${truncatedValue}${spacing}${truncatedDesc}`);
+						line = this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`);
 					} else {
 						// Not enough space for description
 						const maxWidth = width - prefixWidth - 2;
-						line = this.theme.selectedText(`→ ${truncateToWidth(displayValue, maxWidth, "")}`);
+						line = this.theme.selectedText(`${prefix}${truncateToWidth(displayValue, maxWidth, "")}`);
 					}
 				} else {
 					// No description or not enough width
 					const maxWidth = width - prefixWidth - 2;
-					line = this.theme.selectedText(`→ ${truncateToWidth(displayValue, maxWidth, "")}`);
+					line = this.theme.selectedText(`${prefix}${truncateToWidth(displayValue, maxWidth, "")}`);
 				}
 			} else {
 				const displayValue = item.label || item.value;
-				const prefix = "  ";
+				const prefix = " ".repeat(visibleWidth(`${this.theme.symbols.cursor} `));
 
 				if (item.description && width > 40) {
 					// Calculate how much space we have for value + description

package/src/index.ts

@@ -61,6 +61,7 @@ export {
 	isTab,
 	Keys,
 } from "./keys";
+export type { BoxSymbols, SymbolTheme } from "./symbols";
 // Terminal interface and implementations
 export { emergencyTerminalRestore, ProcessTerminal, type Terminal } from "./terminal";
 // Terminal image support

package/src/symbols.ts

@@ -0,0 +1,25 @@
+export interface BoxSymbols {
+	topLeft: string;
+	topRight: string;
+	bottomLeft: string;
+	bottomRight: string;
+	horizontal: string;
+	vertical: string;
+	teeDown: string;
+	teeUp: string;
+	teeLeft: string;
+	teeRight: string;
+	cross: string;
+}
+
+export interface SymbolTheme {
+	cursor: string;
+	inputCursor: string;
+	ellipsis: string;
+	boxRound: Omit<BoxSymbols, "teeDown" | "teeUp" | "teeLeft" | "teeRight" | "cross">;
+	boxSharp: BoxSymbols;
+	table: BoxSymbols;
+	quoteBorder: string;
+	hrChar: string;
+	spinnerFrames: string[];
+}

package/src/tui.ts

@@ -26,6 +26,11 @@ export interface Component {
 	 */
 	handleInput?(data: string): void;
 
+	/**
+	 * Optional cursor position within the rendered output (0-based row/col).
+	 */
+	getCursorPosition?(width: number): { row: number; col: number } | null;
+
 	/**
 	 * Invalidate any cached rendering state.
 	 * Called when theme changes or when component needs to re-render from scratch.
@@ -62,6 +67,19 @@ export class Container implements Component {
 		}
 	}
 
+	getCursorPosition(width: number): { row: number; col: number } | null {
+		let rowOffset = 0;
+		for (const child of this.children) {
+			const lines = child.render(width);
+			const childCursor = child.getCursorPosition?.(width) ?? null;
+			if (childCursor) {
+				return { row: rowOffset + childCursor.row, col: childCursor.col };
+			}
+			rowOffset += lines.length;
+		}
+		return null;
+	}
+
 	render(width: number): string[] {
 		const lines: string[] = [];
 		for (const child of this.children) {
@@ -84,6 +102,7 @@ export class TUI extends Container {
 	public onDebug?: () => void;
 	private renderRequested = false;
 	private cursorRow = 0; // Track where cursor is (0-indexed, relative to our first line)
+	private previousCursor: { row: number; col: number } | null = null;
 	private inputBuffer = ""; // Buffer for parsing terminal responses
 	private cellSizeQueryPending = false;
 	private inputQueue: string[] = []; // Queue input during cell size query to avoid interleaving
@@ -132,6 +151,7 @@ export class TUI extends Container {
 			this.previousLines = [];
 			this.previousWidth = 0;
 			this.cursorRow = 0;
+			this.previousCursor = null;
 		}
 		if (this.renderRequested) return;
 		this.renderRequested = true;
@@ -141,6 +161,42 @@ export class TUI extends Container {
 		});
 	}
 
+	private areCursorsEqual(
+		left: { row: number; col: number } | null,
+		right: { row: number; col: number } | null,
+	): boolean {
+		if (!left && !right) return true;
+		if (!left || !right) return false;
+		return left.row === right.row && left.col === right.col;
+	}
+
+	private updateHardwareCursor(
+		width: number,
+		totalLines: number,
+		cursor: { row: number; col: number } | null,
+		currentCursorRow: number,
+	): void {
+		if (!cursor || totalLines <= 0) {
+			this.terminal.hideCursor();
+			return;
+		}
+
+		const targetRow = Math.max(0, Math.min(cursor.row, totalLines - 1));
+		const targetCol = Math.max(0, Math.min(cursor.col, width - 1));
+		const rowDelta = targetRow - currentCursorRow;
+
+		let buffer = "";
+		if (rowDelta > 0) {
+			buffer += `\x1b[${rowDelta}B`;
+		} else if (rowDelta < 0) {
+			buffer += `\x1b[${-rowDelta}A`;
+		}
+		buffer += `\r\x1b[${targetCol + 1}G`;
+		this.terminal.write(buffer);
+		this.cursorRow = targetRow;
+		this.terminal.showCursor();
+	}
+
 	private handleInput(data: string): void {
 		// If we're waiting for cell size response, buffer input and parse
 		if (this.cellSizeQueryPending) {
@@ -235,6 +291,7 @@ export class TUI extends Container {
 
 		// Render all components to get new lines
 		const newLines = this.render(width);
+		const cursorInfo = this.getCursorPosition(width);
 
 		// Width changed - need full re-render
 		const widthChanged = this.previousWidth !== 0 && this.previousWidth !== width;
@@ -250,6 +307,8 @@ export class TUI extends Container {
 			this.terminal.write(buffer);
 			// After rendering N lines, cursor is at end of last line (line N-1)
 			this.cursorRow = newLines.length - 1;
+			this.updateHardwareCursor(width, newLines.length, cursorInfo, this.cursorRow);
+			this.previousCursor = cursorInfo;
 			this.previousLines = newLines;
 			this.previousWidth = width;
 			return;
@@ -266,6 +325,8 @@ export class TUI extends Container {
 			buffer += "\x1b[?2026l"; // End synchronized output
 			this.terminal.write(buffer);
 			this.cursorRow = newLines.length - 1;
+			this.updateHardwareCursor(width, newLines.length, cursorInfo, this.cursorRow);
+			this.previousCursor = cursorInfo;
 			this.previousLines = newLines;
 			this.previousWidth = width;
 			return;
@@ -287,6 +348,10 @@ export class TUI extends Container {
 
 		// No changes
 		if (firstChanged === -1) {
+			if (!this.areCursorsEqual(cursorInfo, this.previousCursor)) {
+				this.updateHardwareCursor(width, newLines.length, cursorInfo, currentCursorRow);
+				this.previousCursor = cursorInfo;
+			}
 			return;
 		}
 
@@ -306,6 +371,8 @@ export class TUI extends Container {
 			buffer += "\x1b[?2026l"; // End synchronized output
 			this.terminal.write(buffer);
 			this.cursorRow = newLines.length - 1;
+			this.updateHardwareCursor(width, newLines.length, cursorInfo, this.cursorRow);
+			this.previousCursor = cursorInfo;
 			this.previousLines = newLines;
 			this.previousWidth = width;
 			return;
@@ -372,6 +439,8 @@ export class TUI extends Container {
 
 		// Cursor is now at end of last line
 		this.cursorRow = newLines.length - 1;
+		this.updateHardwareCursor(width, newLines.length, cursorInfo, this.cursorRow);
+		this.previousCursor = cursorInfo;
 
 		this.previousLines = newLines;
 		this.previousWidth = width;