@oh-my-pi/pi-tui 3.15.0 → 3.20.0

package/package.json

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

package/src/components/editor.ts

@@ -22,7 +22,10 @@ import {
 	isEnter,
 	isEscape,
 	isHome,
+	isShiftBackspace,
+	isShiftDelete,
 	isShiftEnter,
+	isShiftSpace,
 	isTab,
 } from "../keys";
 import type { SymbolTheme } from "../symbols";
@@ -32,6 +35,186 @@ import { SelectList, type SelectListTheme } from "./select-list";
 
 const segmenter = getSegmenter();
 
+/**
+ * Represents a chunk of text for word-wrap layout.
+ * Tracks both the text content and its position in the original line.
+ */
+interface TextChunk {
+	text: string;
+	startIndex: number;
+	endIndex: number;
+}
+
+/**
+ * Split a line into word-wrapped chunks.
+ * Wraps at word boundaries when possible, falling back to character-level
+ * wrapping for words longer than the available width.
+ *
+ * @param line - The text line to wrap
+ * @param maxWidth - Maximum visible width per chunk
+ * @returns Array of chunks with text and position information
+ */
+function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
+	if (!line || maxWidth <= 0) {
+		return [{ text: "", startIndex: 0, endIndex: 0 }];
+	}
+
+	const lineWidth = visibleWidth(line);
+	if (lineWidth <= maxWidth) {
+		return [{ text: line, startIndex: 0, endIndex: line.length }];
+	}
+
+	const chunks: TextChunk[] = [];
+
+	// Split into tokens (words and whitespace runs)
+	const tokens: { text: string; startIndex: number; endIndex: number; isWhitespace: boolean }[] = [];
+	let currentToken = "";
+	let tokenStart = 0;
+	let inWhitespace = false;
+	let charIndex = 0;
+
+	for (const seg of segmenter.segment(line)) {
+		const grapheme = seg.segment;
+		const graphemeIsWhitespace = isWhitespaceChar(grapheme);
+
+		if (currentToken === "") {
+			inWhitespace = graphemeIsWhitespace;
+			tokenStart = charIndex;
+		} else if (graphemeIsWhitespace !== inWhitespace) {
+			// Token type changed - save current token
+			tokens.push({
+				text: currentToken,
+				startIndex: tokenStart,
+				endIndex: charIndex,
+				isWhitespace: inWhitespace,
+			});
+			currentToken = "";
+			tokenStart = charIndex;
+			inWhitespace = graphemeIsWhitespace;
+		}
+
+		currentToken += grapheme;
+		charIndex += grapheme.length;
+	}
+
+	// Push final token
+	if (currentToken) {
+		tokens.push({
+			text: currentToken,
+			startIndex: tokenStart,
+			endIndex: charIndex,
+			isWhitespace: inWhitespace,
+		});
+	}
+
+	// Build chunks using word wrapping
+	let currentChunk = "";
+	let currentWidth = 0;
+	let chunkStartIndex = 0;
+	let atLineStart = true; // Track if we're at the start of a line (for skipping whitespace)
+
+	for (const token of tokens) {
+		const tokenWidth = visibleWidth(token.text);
+
+		// Skip leading whitespace at line start
+		if (atLineStart && token.isWhitespace) {
+			chunkStartIndex = token.endIndex;
+			continue;
+		}
+		atLineStart = false;
+
+		// If this single token is wider than maxWidth, we need to break it
+		if (tokenWidth > maxWidth) {
+			// First, push any accumulated chunk
+			if (currentChunk) {
+				chunks.push({
+					text: currentChunk,
+					startIndex: chunkStartIndex,
+					endIndex: token.startIndex,
+				});
+				currentChunk = "";
+				currentWidth = 0;
+				chunkStartIndex = token.startIndex;
+			}
+
+			// Break the long token by grapheme
+			let tokenChunk = "";
+			let tokenChunkWidth = 0;
+			let tokenChunkStart = token.startIndex;
+			let tokenCharIndex = token.startIndex;
+
+			for (const seg of segmenter.segment(token.text)) {
+				const grapheme = seg.segment;
+				const graphemeWidth = visibleWidth(grapheme);
+
+				if (tokenChunkWidth + graphemeWidth > maxWidth && tokenChunk) {
+					chunks.push({
+						text: tokenChunk,
+						startIndex: tokenChunkStart,
+						endIndex: tokenCharIndex,
+					});
+					tokenChunk = grapheme;
+					tokenChunkWidth = graphemeWidth;
+					tokenChunkStart = tokenCharIndex;
+				} else {
+					tokenChunk += grapheme;
+					tokenChunkWidth += graphemeWidth;
+				}
+				tokenCharIndex += grapheme.length;
+			}
+
+			// Keep remainder as start of next chunk
+			if (tokenChunk) {
+				currentChunk = tokenChunk;
+				currentWidth = tokenChunkWidth;
+				chunkStartIndex = tokenChunkStart;
+			}
+			continue;
+		}
+
+		// Check if adding this token would exceed width
+		if (currentWidth + tokenWidth > maxWidth) {
+			// Push current chunk (trimming trailing whitespace for display)
+			const trimmedChunk = currentChunk.trimEnd();
+			if (trimmedChunk || chunks.length === 0) {
+				chunks.push({
+					text: trimmedChunk,
+					startIndex: chunkStartIndex,
+					endIndex: chunkStartIndex + currentChunk.length,
+				});
+			}
+
+			// Start new line - skip leading whitespace
+			atLineStart = true;
+			if (token.isWhitespace) {
+				currentChunk = "";
+				currentWidth = 0;
+				chunkStartIndex = token.endIndex;
+			} else {
+				currentChunk = token.text;
+				currentWidth = tokenWidth;
+				chunkStartIndex = token.startIndex;
+				atLineStart = false;
+			}
+		} else {
+			// Add token to current chunk
+			currentChunk += token.text;
+			currentWidth += tokenWidth;
+		}
+	}
+
+	// Push final chunk
+	if (currentChunk) {
+		chunks.push({
+			text: currentChunk,
+			startIndex: chunkStartIndex,
+			endIndex: line.length,
+		});
+	}
+
+	return chunks.length > 0 ? chunks : [{ text: "", startIndex: 0, endIndex: 0 }];
+}
+
 interface EditorState {
 	lines: string[];
 	cursorLine: number;
@@ -65,6 +248,7 @@ export class Editor implements Component {
 	};
 
 	private theme: EditorTheme;
+	private useTerminalCursor = false;
 
 	// Store last render width for cursor navigation
 	private lastWidth: number = 80;
@@ -91,6 +275,7 @@ export class Editor implements Component {
 	private historyIndex: number = -1; // -1 = not browsing, 0 = most recent, 1 = older, etc.
 
 	public onSubmit?: (text: string) => void;
+	public onAltEnter?: (text: string) => void;
 	public onChange?: (text: string) => void;
 	public disableSubmit: boolean = false;
 
@@ -114,6 +299,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.
@@ -224,7 +416,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);
 
@@ -285,6 +477,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~
@@ -455,13 +677,20 @@ export class Editor implements Component {
 		else if (isCtrlE(data)) {
 			this.moveToLineEnd();
 		}
+		// Alt+Enter - special handler if callback exists, otherwise new line
+		else if (isAltEnter(data)) {
+			if (this.onAltEnter) {
+				this.onAltEnter(this.getText());
+			} else {
+				this.addNewLine();
+			}
+		}
 		// New line shortcuts (but not plain LF/CR which should be submit)
 		else if (
 			(data.charCodeAt(0) === 10 && data.length > 1) || // Ctrl+Enter with modifiers
 			data === "\x1b\r" || // Option+Enter in some terminals (legacy)
 			data === "\x1b[13;2~" || // Shift+Enter in some terminals (legacy format)
 			isShiftEnter(data) || // Shift+Enter (Kitty protocol, handles lock bits)
-			isAltEnter(data) || // Alt+Enter (Kitty protocol, handles lock bits)
 			(data.length > 1 && data.includes("\x1b") && data.includes("\r")) ||
 			(data === "\n" && data.length === 1) || // Shift+Enter from iTerm2 mapping
 			data === "\\\r" // Shift+Enter in VS Code terminal
@@ -505,8 +734,8 @@ export class Editor implements Component {
 				this.onSubmit(result);
 			}
 		}
-		// Backspace
-		else if (isBackspace(data)) {
+		// Backspace (including Shift+Backspace)
+		else if (isBackspace(data) || isShiftBackspace(data)) {
 			this.handleBackspace();
 		}
 		// Line navigation shortcuts (Home/End keys)
@@ -515,8 +744,8 @@ export class Editor implements Component {
 		} else if (isEnd(data)) {
 			this.moveToLineEnd();
 		}
-		// Forward delete (Fn+Backspace or Delete key)
-		else if (isDelete(data)) {
+		// Forward delete (Fn+Backspace or Delete key, including Shift+Delete)
+		else if (isDelete(data) || isShiftDelete(data)) {
 			this.handleForwardDelete();
 		}
 		// Word navigation (Option/Alt + Arrow or Ctrl + Arrow)
@@ -551,8 +780,8 @@ export class Editor implements Component {
 			// Left
 			this.moveCursor(0, -1);
 		}
-		// Shift+Space via Kitty protocol (sends \x1b[32;2u instead of plain space)
-		else if (data === "\x1b[32;2u" || data.match(/^\x1b\[32;\d+u$/)) {
+		// Shift+Space - insert regular space (Kitty protocol sends escape sequence)
+		else if (isShiftSpace(data)) {
 			this.insertCharacter(" ");
 		}
 		// Regular characters (printable characters and unicode, but not control characters)
@@ -595,42 +824,8 @@ export class Editor implements Component {
 					});
 				}
 			} else {
-				// Line needs wrapping - use grapheme-aware chunking
-				const chunks: { text: string; startIndex: number; endIndex: number }[] = [];
-				let currentChunk = "";
-				let currentWidth = 0;
-				let chunkStartIndex = 0;
-				let currentIndex = 0;
-
-				for (const seg of segmenter.segment(line)) {
-					const grapheme = seg.segment;
-					const graphemeWidth = visibleWidth(grapheme);
-
-					if (currentWidth + graphemeWidth > contentWidth && currentChunk !== "") {
-						// Start a new chunk
-						chunks.push({
-							text: currentChunk,
-							startIndex: chunkStartIndex,
-							endIndex: currentIndex,
-						});
-						currentChunk = grapheme;
-						currentWidth = graphemeWidth;
-						chunkStartIndex = currentIndex;
-					} else {
-						currentChunk += grapheme;
-						currentWidth += graphemeWidth;
-					}
-					currentIndex += grapheme.length;
-				}
-
-				// Push the last chunk
-				if (currentChunk !== "") {
-					chunks.push({
-						text: currentChunk,
-						startIndex: chunkStartIndex,
-						endIndex: currentIndex,
-					});
-				}
+				// Line needs wrapping - use word-aware wrapping
+				const chunks = wordWrapLine(line, contentWidth);
 
 				for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
 					const chunk = chunks[chunkIndex];
@@ -638,17 +833,37 @@ export class Editor implements Component {
 
 					const cursorPos = this.state.cursorCol;
 					const isLastChunk = chunkIndex === chunks.length - 1;
-					// For non-last chunks, cursor at endIndex belongs to the next chunk
-					const hasCursorInChunk =
-						isCurrentLine &&
-						cursorPos >= chunk.startIndex &&
-						(isLastChunk ? cursorPos <= chunk.endIndex : cursorPos < chunk.endIndex);
+
+					// Determine if cursor is in this chunk
+					// For word-wrapped chunks, we need to handle the case where
+					// cursor might be in trimmed whitespace at end of chunk
+					let hasCursorInChunk = false;
+					let adjustedCursorPos = 0;
+
+					if (isCurrentLine) {
+						if (isLastChunk) {
+							// Last chunk: cursor belongs here if >= startIndex
+							hasCursorInChunk = cursorPos >= chunk.startIndex;
+							adjustedCursorPos = cursorPos - chunk.startIndex;
+						} else {
+							// Non-last chunk: cursor belongs here if in range [startIndex, endIndex)
+							// But we need to handle the visual position in the trimmed text
+							hasCursorInChunk = cursorPos >= chunk.startIndex && cursorPos < chunk.endIndex;
+							if (hasCursorInChunk) {
+								adjustedCursorPos = cursorPos - chunk.startIndex;
+								// Clamp to text length (in case cursor was in trimmed whitespace)
+								if (adjustedCursorPos > chunk.text.length) {
+									adjustedCursorPos = chunk.text.length;
+								}
+							}
+						}
+					}
 
 					if (hasCursorInChunk) {
 						layoutLines.push({
 							text: chunk.text,
 							hasCursor: true,
-							cursorPos: cursorPos - chunk.startIndex,
+							cursorPos: adjustedCursorPos,
 						});
 					} else {
 						layoutLines.push({
@@ -729,7 +944,7 @@ export class Editor implements Component {
 				}
 			}
 			// Also auto-trigger when typing letters in a slash command context
-			else if (/[a-zA-Z0-9]/.test(char)) {
+			else if (/[a-zA-Z0-9.\-_]/.test(char)) {
 				const currentLine = this.state.lines[this.state.cursorLine] || "";
 				const textBeforeCursor = currentLine.slice(0, this.state.cursorCol);
 				// Check if we're in a slash command (with or without space for arguments)
@@ -1065,36 +1280,13 @@ export class Editor implements Component {
 			} else if (lineVisWidth <= width) {
 				visualLines.push({ logicalLine: i, startCol: 0, length: line.length });
 			} else {
-				// Line needs wrapping - use grapheme-aware chunking
-				let currentWidth = 0;
-				let chunkStartIndex = 0;
-				let currentIndex = 0;
-
-				for (const seg of segmenter.segment(line)) {
-					const grapheme = seg.segment;
-					const graphemeWidth = visibleWidth(grapheme);
-
-					if (currentWidth + graphemeWidth > width && currentIndex > chunkStartIndex) {
-						// Start a new chunk
-						visualLines.push({
-							logicalLine: i,
-							startCol: chunkStartIndex,
-							length: currentIndex - chunkStartIndex,
-						});
-						chunkStartIndex = currentIndex;
-						currentWidth = graphemeWidth;
-					} else {
-						currentWidth += graphemeWidth;
-					}
-					currentIndex += grapheme.length;
-				}
-
-				// Push the last chunk
-				if (currentIndex > chunkStartIndex) {
+				// Line needs wrapping - use word-aware wrapping
+				const chunks = wordWrapLine(line, width);
+				for (const chunk of chunks) {
 					visualLines.push({
 						logicalLine: i,
-						startCol: chunkStartIndex,
-						length: currentIndex - chunkStartIndex,
+						startCol: chunk.startIndex,
+						length: chunk.endIndex - chunk.startIndex,
 					});
 				}
 			}

package/src/components/settings-list.ts

@@ -1,6 +1,6 @@
 import { isArrowDown, isArrowUp, isCtrlC, isEnter, isEscape } from "../keys";
 import type { Component } from "../tui";
-import { truncateToWidth, visibleWidth } from "../utils";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 
 export interface SettingItem {
 	/** Unique identifier for this setting */
@@ -123,7 +123,10 @@ export class SettingsList implements Component {
 		const selectedItem = this.items[this.selectedIndex];
 		if (selectedItem?.description) {
 			lines.push("");
-			lines.push(this.theme.description(`  ${truncateToWidth(selectedItem.description, width - 4, "")}`));
+			const wrappedDesc = wrapTextWithAnsi(selectedItem.description, width - 4);
+			for (const line of wrappedDesc) {
+				lines.push(this.theme.description(`  ${line}`));
+			}
 		}
 
 		// Add hint

package/src/index.ts

@@ -21,6 +21,15 @@ export { Spacer } from "./components/spacer";
 export { type Tab, TabBar, type TabBarTheme } from "./components/tab-bar";
 export { Text } from "./components/text";
 export { TruncatedText } from "./components/truncated-text";
+// Keybindings
+export {
+	DEFAULT_EDITOR_KEYBINDINGS,
+	type EditorAction,
+	type EditorKeybindingsConfig,
+	EditorKeybindingsManager,
+	getEditorKeybindings,
+	setEditorKeybindings,
+} from "./keybindings";
 // Kitty keyboard protocol helpers
 export {
 	isAltBackspace,
@@ -32,6 +41,7 @@ export {
 	isArrowRight,
 	isArrowUp,
 	isBackspace,
+	isCapsLock,
 	isCtrlA,
 	isCtrlC,
 	isCtrlD,
@@ -47,19 +57,26 @@ export {
 	isCtrlU,
 	isCtrlV,
 	isCtrlW,
+	isCtrlY,
 	isCtrlZ,
 	isDelete,
 	isEnd,
 	isEnter,
 	isEscape,
 	isHome,
+	isShiftBackspace,
 	isShiftCtrlD,
 	isShiftCtrlO,
 	isShiftCtrlP,
+	isShiftDelete,
 	isShiftEnter,
+	isShiftSpace,
 	isShiftTab,
 	isTab,
-	Keys,
+	Key,
+	type KeyId,
+	matchesKey,
+	parseKey,
 } from "./keys";
 export type { BoxSymbols, SymbolTheme } from "./symbols";
 // Terminal interface and implementations

package/src/keybindings.ts

@@ -0,0 +1,143 @@
+import { type KeyId, matchesKey } from "./keys";
+
+/**
+ * Editor actions that can be bound to keys.
+ */
+export type EditorAction =
+	// Cursor movement
+	| "cursorUp"
+	| "cursorDown"
+	| "cursorLeft"
+	| "cursorRight"
+	| "cursorWordLeft"
+	| "cursorWordRight"
+	| "cursorLineStart"
+	| "cursorLineEnd"
+	// Deletion
+	| "deleteCharBackward"
+	| "deleteCharForward"
+	| "deleteWordBackward"
+	| "deleteToLineStart"
+	| "deleteToLineEnd"
+	// Text input
+	| "newLine"
+	| "submit"
+	| "tab"
+	// Selection/autocomplete
+	| "selectUp"
+	| "selectDown"
+	| "selectConfirm"
+	| "selectCancel"
+	// Clipboard
+	| "copy";
+
+// Re-export KeyId from keys.ts
+export type { KeyId };
+
+/**
+ * Editor keybindings configuration.
+ */
+export type EditorKeybindingsConfig = {
+	[K in EditorAction]?: KeyId | KeyId[];
+};
+
+/**
+ * Default editor keybindings.
+ */
+export const DEFAULT_EDITOR_KEYBINDINGS: Required<EditorKeybindingsConfig> = {
+	// Cursor movement
+	cursorUp: "up",
+	cursorDown: "down",
+	cursorLeft: "left",
+	cursorRight: "right",
+	cursorWordLeft: ["alt+left", "ctrl+left"],
+	cursorWordRight: ["alt+right", "ctrl+right"],
+	cursorLineStart: ["home", "ctrl+a"],
+	cursorLineEnd: ["end", "ctrl+e"],
+	// Deletion
+	deleteCharBackward: "backspace",
+	deleteCharForward: "delete",
+	deleteWordBackward: ["ctrl+w", "alt+backspace"],
+	deleteToLineStart: "ctrl+u",
+	deleteToLineEnd: "ctrl+k",
+	// Text input
+	newLine: ["shift+enter", "alt+enter"],
+	submit: "enter",
+	tab: "tab",
+	// Selection/autocomplete
+	selectUp: "up",
+	selectDown: "down",
+	selectConfirm: "enter",
+	selectCancel: ["escape", "ctrl+c"],
+	// Clipboard
+	copy: "ctrl+c",
+};
+
+/**
+ * Manages keybindings for the editor.
+ */
+export class EditorKeybindingsManager {
+	private actionToKeys: Map<EditorAction, KeyId[]>;
+
+	constructor(config: EditorKeybindingsConfig = {}) {
+		this.actionToKeys = new Map();
+		this.buildMaps(config);
+	}
+
+	private buildMaps(config: EditorKeybindingsConfig): void {
+		this.actionToKeys.clear();
+
+		// Start with defaults
+		for (const [action, keys] of Object.entries(DEFAULT_EDITOR_KEYBINDINGS)) {
+			const keyArray = Array.isArray(keys) ? keys : [keys];
+			this.actionToKeys.set(action as EditorAction, [...keyArray]);
+		}
+
+		// Override with user config
+		for (const [action, keys] of Object.entries(config)) {
+			if (keys === undefined) continue;
+			const keyArray = Array.isArray(keys) ? keys : [keys];
+			this.actionToKeys.set(action as EditorAction, keyArray);
+		}
+	}
+
+	/**
+	 * Check if input matches a specific action.
+	 */
+	matches(data: string, action: EditorAction): boolean {
+		const keys = this.actionToKeys.get(action);
+		if (!keys) return false;
+		for (const key of keys) {
+			if (matchesKey(data, key)) return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Get keys bound to an action.
+	 */
+	getKeys(action: EditorAction): KeyId[] {
+		return this.actionToKeys.get(action) ?? [];
+	}
+
+	/**
+	 * Update configuration.
+	 */
+	setConfig(config: EditorKeybindingsConfig): void {
+		this.buildMaps(config);
+	}
+}
+
+// Global instance
+let globalEditorKeybindings: EditorKeybindingsManager | null = null;
+
+export function getEditorKeybindings(): EditorKeybindingsManager {
+	if (!globalEditorKeybindings) {
+		globalEditorKeybindings = new EditorKeybindingsManager();
+	}
+	return globalEditorKeybindings;
+}
+
+export function setEditorKeybindings(manager: EditorKeybindingsManager): void {
+	globalEditorKeybindings = manager;
+}