@lenylvt/pi-tui 0.64.0

package/src/editor-component.ts

@@ -0,0 +1,74 @@
+import type { AutocompleteProvider } from "./autocomplete.js";
+import type { Component } from "./tui.js";
+
+/**
+ * Interface for custom editor components.
+ *
+ * This allows extensions to provide their own editor implementation
+ * (e.g., vim mode, emacs mode, custom keybindings) while maintaining
+ * compatibility with the core application.
+ */
+export interface EditorComponent extends Component {
+	// =========================================================================
+	// Core text access (required)
+	// =========================================================================
+
+	/** Get the current text content */
+	getText(): string;
+
+	/** Set the text content */
+	setText(text: string): void;
+
+	/** Handle raw terminal input (key presses, paste sequences, etc.) */
+	handleInput(data: string): void;
+
+	// =========================================================================
+	// Callbacks (required)
+	// =========================================================================
+
+	/** Called when user submits (e.g., Enter key) */
+	onSubmit?: (text: string) => void;
+
+	/** Called when text changes */
+	onChange?: (text: string) => void;
+
+	// =========================================================================
+	// History support (optional)
+	// =========================================================================
+
+	/** Add text to history for up/down navigation */
+	addToHistory?(text: string): void;
+
+	// =========================================================================
+	// Advanced text manipulation (optional)
+	// =========================================================================
+
+	/** Insert text at current cursor position */
+	insertTextAtCursor?(text: string): void;
+
+	/**
+	 * Get text with any markers expanded (e.g., paste markers).
+	 * Falls back to getText() if not implemented.
+	 */
+	getExpandedText?(): string;
+
+	// =========================================================================
+	// Autocomplete support (optional)
+	// =========================================================================
+
+	/** Set the autocomplete provider */
+	setAutocompleteProvider?(provider: AutocompleteProvider): void;
+
+	// =========================================================================
+	// Appearance (optional)
+	// =========================================================================
+
+	/** Border color function */
+	borderColor?: (str: string) => string;
+
+	/** Set horizontal padding */
+	setPaddingX?(padding: number): void;
+
+	/** Set max visible items in autocomplete dropdown */
+	setAutocompleteMaxVisible?(maxVisible: number): void;
+}

package/src/fuzzy.ts

@@ -0,0 +1,133 @@
+/**
+ * Fuzzy matching utilities.
+ * Matches if all query characters appear in order (not necessarily consecutive).
+ * Lower score = better match.
+ */
+
+export interface FuzzyMatch {
+	matches: boolean;
+	score: number;
+}
+
+export function fuzzyMatch(query: string, text: string): FuzzyMatch {
+	const queryLower = query.toLowerCase();
+	const textLower = text.toLowerCase();
+
+	const matchQuery = (normalizedQuery: string): FuzzyMatch => {
+		if (normalizedQuery.length === 0) {
+			return { matches: true, score: 0 };
+		}
+
+		if (normalizedQuery.length > textLower.length) {
+			return { matches: false, score: 0 };
+		}
+
+		let queryIndex = 0;
+		let score = 0;
+		let lastMatchIndex = -1;
+		let consecutiveMatches = 0;
+
+		for (let i = 0; i < textLower.length && queryIndex < normalizedQuery.length; i++) {
+			if (textLower[i] === normalizedQuery[queryIndex]) {
+				const isWordBoundary = i === 0 || /[\s\-_./:]/.test(textLower[i - 1]!);
+
+				// Reward consecutive matches
+				if (lastMatchIndex === i - 1) {
+					consecutiveMatches++;
+					score -= consecutiveMatches * 5;
+				} else {
+					consecutiveMatches = 0;
+					// Penalize gaps
+					if (lastMatchIndex >= 0) {
+						score += (i - lastMatchIndex - 1) * 2;
+					}
+				}
+
+				// Reward word boundary matches
+				if (isWordBoundary) {
+					score -= 10;
+				}
+
+				// Slight penalty for later matches
+				score += i * 0.1;
+
+				lastMatchIndex = i;
+				queryIndex++;
+			}
+		}
+
+		if (queryIndex < normalizedQuery.length) {
+			return { matches: false, score: 0 };
+		}
+
+		return { matches: true, score };
+	};
+
+	const primaryMatch = matchQuery(queryLower);
+	if (primaryMatch.matches) {
+		return primaryMatch;
+	}
+
+	const alphaNumericMatch = queryLower.match(/^(?<letters>[a-z]+)(?<digits>[0-9]+)$/);
+	const numericAlphaMatch = queryLower.match(/^(?<digits>[0-9]+)(?<letters>[a-z]+)$/);
+	const swappedQuery = alphaNumericMatch
+		? `${alphaNumericMatch.groups?.digits ?? ""}${alphaNumericMatch.groups?.letters ?? ""}`
+		: numericAlphaMatch
+			? `${numericAlphaMatch.groups?.letters ?? ""}${numericAlphaMatch.groups?.digits ?? ""}`
+			: "";
+
+	if (!swappedQuery) {
+		return primaryMatch;
+	}
+
+	const swappedMatch = matchQuery(swappedQuery);
+	if (!swappedMatch.matches) {
+		return primaryMatch;
+	}
+
+	return { matches: true, score: swappedMatch.score + 5 };
+}
+
+/**
+ * Filter and sort items by fuzzy match quality (best matches first).
+ * Supports space-separated tokens: all tokens must match.
+ */
+export function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[] {
+	if (!query.trim()) {
+		return items;
+	}
+
+	const tokens = query
+		.trim()
+		.split(/\s+/)
+		.filter((t) => t.length > 0);
+
+	if (tokens.length === 0) {
+		return items;
+	}
+
+	const results: { item: T; totalScore: number }[] = [];
+
+	for (const item of items) {
+		const text = getText(item);
+		let totalScore = 0;
+		let allMatch = true;
+
+		for (const token of tokens) {
+			const match = fuzzyMatch(token, text);
+			if (match.matches) {
+				totalScore += match.score;
+			} else {
+				allMatch = false;
+				break;
+			}
+		}
+
+		if (allMatch) {
+			results.push({ item, totalScore });
+		}
+	}
+
+	results.sort((a, b) => a.totalScore - b.totalScore);
+	return results.map((r) => r.item);
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+// Core TUI interfaces and classes
+
+// Autocomplete support
+export {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	type AutocompleteSuggestions,
+	CombinedAutocompleteProvider,
+	type SlashCommand,
+} from "./autocomplete.js";
+// Components
+export { Box } from "./components/box.js";
+export { CancellableLoader } from "./components/cancellable-loader.js";
+export { Editor, type EditorOptions, type EditorTheme } from "./components/editor.js";
+export { Image, type ImageOptions, type ImageTheme } from "./components/image.js";
+export { Input } from "./components/input.js";
+export { Loader } from "./components/loader.js";
+export { type DefaultTextStyle, Markdown, type MarkdownTheme } from "./components/markdown.js";
+export {
+	type SelectItem,
+	SelectList,
+	type SelectListLayoutOptions,
+	type SelectListTheme,
+	type SelectListTruncatePrimaryContext,
+} from "./components/select-list.js";
+export { type SettingItem, SettingsList, type SettingsListTheme } from "./components/settings-list.js";
+export { Spacer } from "./components/spacer.js";
+export { Text } from "./components/text.js";
+export { TruncatedText } from "./components/truncated-text.js";
+// Editor component interface (for custom editors)
+export type { EditorComponent } from "./editor-component.js";
+// Fuzzy matching
+export { type FuzzyMatch, fuzzyFilter, fuzzyMatch } from "./fuzzy.js";
+// Keybindings
+export {
+	getKeybindings,
+	type Keybinding,
+	type KeybindingConflict,
+	type KeybindingDefinition,
+	type KeybindingDefinitions,
+	type Keybindings,
+	type KeybindingsConfig,
+	KeybindingsManager,
+	setKeybindings,
+	TUI_KEYBINDINGS,
+} from "./keybindings.js";
+// Keyboard input handling
+export {
+	decodeKittyPrintable,
+	isKeyRelease,
+	isKeyRepeat,
+	isKittyProtocolActive,
+	Key,
+	type KeyEventType,
+	type KeyId,
+	matchesKey,
+	parseKey,
+	setKittyProtocolActive,
+} from "./keys.js";
+// Input buffering for batch splitting
+export { StdinBuffer, type StdinBufferEventMap, type StdinBufferOptions } from "./stdin-buffer.js";
+// Terminal interface and implementations
+export { ProcessTerminal, type Terminal } from "./terminal.js";
+// Terminal image support
+export {
+	allocateImageId,
+	type CellDimensions,
+	calculateImageRows,
+	deleteAllKittyImages,
+	deleteKittyImage,
+	detectCapabilities,
+	encodeITerm2,
+	encodeKitty,
+	getCapabilities,
+	getCellDimensions,
+	getGifDimensions,
+	getImageDimensions,
+	getJpegDimensions,
+	getPngDimensions,
+	getWebpDimensions,
+	type ImageDimensions,
+	type ImageProtocol,
+	type ImageRenderOptions,
+	imageFallback,
+	renderImage,
+	resetCapabilitiesCache,
+	setCellDimensions,
+	type TerminalCapabilities,
+} from "./terminal-image.js";
+export {
+	type Component,
+	Container,
+	CURSOR_MARKER,
+	type Focusable,
+	isFocusable,
+	type OverlayAnchor,
+	type OverlayHandle,
+	type OverlayMargin,
+	type OverlayOptions,
+	type SizeValue,
+	TUI,
+} from "./tui.js";
+// Utilities
+export { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "./utils.js";

package/src/keybindings.ts

@@ -0,0 +1,244 @@
+import { type KeyId, matchesKey } from "./keys.js";
+
+/**
+ * Global keybinding registry.
+ * Downstream packages can add keybindings via declaration merging.
+ */
+export interface Keybindings {
+	// Editor navigation and editing
+	"tui.editor.cursorUp": true;
+	"tui.editor.cursorDown": true;
+	"tui.editor.cursorLeft": true;
+	"tui.editor.cursorRight": true;
+	"tui.editor.cursorWordLeft": true;
+	"tui.editor.cursorWordRight": true;
+	"tui.editor.cursorLineStart": true;
+	"tui.editor.cursorLineEnd": true;
+	"tui.editor.jumpForward": true;
+	"tui.editor.jumpBackward": true;
+	"tui.editor.pageUp": true;
+	"tui.editor.pageDown": true;
+	"tui.editor.deleteCharBackward": true;
+	"tui.editor.deleteCharForward": true;
+	"tui.editor.deleteWordBackward": true;
+	"tui.editor.deleteWordForward": true;
+	"tui.editor.deleteToLineStart": true;
+	"tui.editor.deleteToLineEnd": true;
+	"tui.editor.yank": true;
+	"tui.editor.yankPop": true;
+	"tui.editor.undo": true;
+	// Generic input actions
+	"tui.input.newLine": true;
+	"tui.input.submit": true;
+	"tui.input.tab": true;
+	"tui.input.copy": true;
+	// Generic selection actions
+	"tui.select.up": true;
+	"tui.select.down": true;
+	"tui.select.pageUp": true;
+	"tui.select.pageDown": true;
+	"tui.select.confirm": true;
+	"tui.select.cancel": true;
+}
+
+export type Keybinding = keyof Keybindings;
+
+export interface KeybindingDefinition {
+	defaultKeys: KeyId | KeyId[];
+	description?: string;
+}
+
+export type KeybindingDefinitions = Record<string, KeybindingDefinition>;
+export type KeybindingsConfig = Record<string, KeyId | KeyId[] | undefined>;
+
+export const TUI_KEYBINDINGS = {
+	"tui.editor.cursorUp": { defaultKeys: "up", description: "Move cursor up" },
+	"tui.editor.cursorDown": { defaultKeys: "down", description: "Move cursor down" },
+	"tui.editor.cursorLeft": {
+		defaultKeys: ["left", "ctrl+b"],
+		description: "Move cursor left",
+	},
+	"tui.editor.cursorRight": {
+		defaultKeys: ["right", "ctrl+f"],
+		description: "Move cursor right",
+	},
+	"tui.editor.cursorWordLeft": {
+		defaultKeys: ["alt+left", "ctrl+left", "alt+b"],
+		description: "Move cursor word left",
+	},
+	"tui.editor.cursorWordRight": {
+		defaultKeys: ["alt+right", "ctrl+right", "alt+f"],
+		description: "Move cursor word right",
+	},
+	"tui.editor.cursorLineStart": {
+		defaultKeys: ["home", "ctrl+a"],
+		description: "Move to line start",
+	},
+	"tui.editor.cursorLineEnd": {
+		defaultKeys: ["end", "ctrl+e"],
+		description: "Move to line end",
+	},
+	"tui.editor.jumpForward": {
+		defaultKeys: "ctrl+]",
+		description: "Jump forward to character",
+	},
+	"tui.editor.jumpBackward": {
+		defaultKeys: "ctrl+alt+]",
+		description: "Jump backward to character",
+	},
+	"tui.editor.pageUp": { defaultKeys: "pageUp", description: "Page up" },
+	"tui.editor.pageDown": { defaultKeys: "pageDown", description: "Page down" },
+	"tui.editor.deleteCharBackward": {
+		defaultKeys: "backspace",
+		description: "Delete character backward",
+	},
+	"tui.editor.deleteCharForward": {
+		defaultKeys: ["delete", "ctrl+d"],
+		description: "Delete character forward",
+	},
+	"tui.editor.deleteWordBackward": {
+		defaultKeys: ["ctrl+w", "alt+backspace"],
+		description: "Delete word backward",
+	},
+	"tui.editor.deleteWordForward": {
+		defaultKeys: ["alt+d", "alt+delete"],
+		description: "Delete word forward",
+	},
+	"tui.editor.deleteToLineStart": {
+		defaultKeys: "ctrl+u",
+		description: "Delete to line start",
+	},
+	"tui.editor.deleteToLineEnd": {
+		defaultKeys: "ctrl+k",
+		description: "Delete to line end",
+	},
+	"tui.editor.yank": { defaultKeys: "ctrl+y", description: "Yank" },
+	"tui.editor.yankPop": { defaultKeys: "alt+y", description: "Yank pop" },
+	"tui.editor.undo": { defaultKeys: "ctrl+-", description: "Undo" },
+	"tui.input.newLine": { defaultKeys: "shift+enter", description: "Insert newline" },
+	"tui.input.submit": { defaultKeys: "enter", description: "Submit input" },
+	"tui.input.tab": { defaultKeys: "tab", description: "Tab / autocomplete" },
+	"tui.input.copy": { defaultKeys: "ctrl+c", description: "Copy selection" },
+	"tui.select.up": { defaultKeys: "up", description: "Move selection up" },
+	"tui.select.down": { defaultKeys: "down", description: "Move selection down" },
+	"tui.select.pageUp": { defaultKeys: "pageUp", description: "Selection page up" },
+	"tui.select.pageDown": {
+		defaultKeys: "pageDown",
+		description: "Selection page down",
+	},
+	"tui.select.confirm": { defaultKeys: "enter", description: "Confirm selection" },
+	"tui.select.cancel": {
+		defaultKeys: ["escape", "ctrl+c"],
+		description: "Cancel selection",
+	},
+} as const satisfies KeybindingDefinitions;
+
+export interface KeybindingConflict {
+	key: KeyId;
+	keybindings: string[];
+}
+
+function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
+	if (keys === undefined) return [];
+	const keyList = Array.isArray(keys) ? keys : [keys];
+	const seen = new Set<KeyId>();
+	const result: KeyId[] = [];
+	for (const key of keyList) {
+		if (!seen.has(key)) {
+			seen.add(key);
+			result.push(key);
+		}
+	}
+	return result;
+}
+
+export class KeybindingsManager {
+	private definitions: KeybindingDefinitions;
+	private userBindings: KeybindingsConfig;
+	private keysById = new Map<Keybinding, KeyId[]>();
+	private conflicts: KeybindingConflict[] = [];
+
+	constructor(definitions: KeybindingDefinitions, userBindings: KeybindingsConfig = {}) {
+		this.definitions = definitions;
+		this.userBindings = userBindings;
+		this.rebuild();
+	}
+
+	private rebuild(): void {
+		this.keysById.clear();
+		this.conflicts = [];
+
+		const userClaims = new Map<KeyId, Set<Keybinding>>();
+		for (const [keybinding, keys] of Object.entries(this.userBindings)) {
+			if (!(keybinding in this.definitions)) continue;
+			for (const key of normalizeKeys(keys)) {
+				const claimants = userClaims.get(key) ?? new Set<Keybinding>();
+				claimants.add(keybinding as Keybinding);
+				userClaims.set(key, claimants);
+			}
+		}
+
+		for (const [key, keybindings] of userClaims) {
+			if (keybindings.size > 1) {
+				this.conflicts.push({ key, keybindings: [...keybindings] });
+			}
+		}
+
+		for (const [id, definition] of Object.entries(this.definitions)) {
+			const userKeys = this.userBindings[id];
+			const keys = userKeys === undefined ? normalizeKeys(definition.defaultKeys) : normalizeKeys(userKeys);
+			this.keysById.set(id as Keybinding, keys);
+		}
+	}
+
+	matches(data: string, keybinding: Keybinding): boolean {
+		const keys = this.keysById.get(keybinding) ?? [];
+		for (const key of keys) {
+			if (matchesKey(data, key)) return true;
+		}
+		return false;
+	}
+
+	getKeys(keybinding: Keybinding): KeyId[] {
+		return [...(this.keysById.get(keybinding) ?? [])];
+	}
+
+	getDefinition(keybinding: Keybinding): KeybindingDefinition {
+		return this.definitions[keybinding];
+	}
+
+	getConflicts(): KeybindingConflict[] {
+		return this.conflicts.map((conflict) => ({ ...conflict, keybindings: [...conflict.keybindings] }));
+	}
+
+	setUserBindings(userBindings: KeybindingsConfig): void {
+		this.userBindings = userBindings;
+		this.rebuild();
+	}
+
+	getUserBindings(): KeybindingsConfig {
+		return { ...this.userBindings };
+	}
+
+	getResolvedBindings(): KeybindingsConfig {
+		const resolved: KeybindingsConfig = {};
+		for (const id of Object.keys(this.definitions)) {
+			const keys = this.keysById.get(id as Keybinding) ?? [];
+			resolved[id] = keys.length === 1 ? keys[0]! : [...keys];
+		}
+		return resolved;
+	}
+}
+
+let globalKeybindings: KeybindingsManager | null = null;
+
+export function setKeybindings(keybindings: KeybindingsManager): void {
+	globalKeybindings = keybindings;
+}
+
+export function getKeybindings(): KeybindingsManager {
+	if (!globalKeybindings) {
+		globalKeybindings = new KeybindingsManager(TUI_KEYBINDINGS);
+	}
+	return globalKeybindings;
+}