@nghyane/arcane-tui 0.1.0

package/src/components/truncated-text.ts

@@ -0,0 +1,61 @@
+import type { Component } from "../tui";
+import { padding, truncateToWidth } from "../utils";
+
+/**
+ * Text component that truncates to fit viewport width
+ */
+export class TruncatedText implements Component {
+	#text: string;
+	#paddingX: number;
+	#paddingY: number;
+
+	constructor(text: string, paddingX: number = 0, paddingY: number = 0) {
+		this.#text = text;
+		this.#paddingX = paddingX;
+		this.#paddingY = paddingY;
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate currently
+	}
+
+	render(width: number): string[] {
+		const result: string[] = [];
+
+		// Empty line padded to width
+		const emptyLine = padding(width);
+
+		// Add vertical padding above
+		for (let i = 0; i < this.#paddingY; i++) {
+			result.push(emptyLine);
+		}
+
+		// Calculate available width after horizontal padding
+		const availableWidth = Math.max(1, width - this.#paddingX * 2);
+
+		// Take only the first line (stop at newline)
+		let singleLineText = this.#text;
+		const newlineIndex = this.#text.indexOf("\n");
+		if (newlineIndex !== -1) {
+			singleLineText = this.#text.substring(0, newlineIndex);
+		}
+
+		// Truncate text if needed (accounting for ANSI codes)
+		const displayText = truncateToWidth(singleLineText, availableWidth);
+
+		// Add horizontal padding
+		const leftPadding = padding(this.#paddingX);
+		const rightPadding = padding(this.#paddingX);
+		const lineWithPadding = leftPadding + displayText + rightPadding;
+
+		// Don't pad to full width - avoids trailing spaces when copying
+		result.push(lineWithPadding);
+
+		// Add vertical padding below
+		for (let i = 0; i < this.#paddingY; i++) {
+			result.push(emptyLine);
+		}
+
+		return result;
+	}
+}

package/src/editor-component.ts

@@ -0,0 +1,71 @@
+import type { AutocompleteProvider } from "./autocomplete";
+import type { Component } from "./tui";
+
+/**
+ * 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;
+}

package/src/fuzzy.ts

@@ -0,0 +1,143 @@
+/**
+ * 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;
+}
+
+const ALPHANUMERIC_SWAP_PENALTY = 5;
+
+function scoreMatch(queryLower: string, textLower: string): FuzzyMatch {
+	if (queryLower.length === 0) {
+		return { matches: true, score: 0 };
+	}
+
+	if (queryLower.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 < queryLower.length; i++) {
+		if (textLower[i] === queryLower[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 < queryLower.length) {
+		return { matches: false, score: 0 };
+	}
+
+	return { matches: true, score };
+}
+
+function buildAlphanumericSwapQueries(queryLower: string): string[] {
+	const variants = new Set<string>();
+	for (let i = 0; i < queryLower.length - 1; i++) {
+		const current = queryLower[i];
+		const next = queryLower[i + 1];
+		const isAlphaNumSwap =
+			(current && /[a-z]/.test(current) && next && /\d/.test(next)) ||
+			(current && /\d/.test(current) && next && /[a-z]/.test(next));
+		if (!isAlphaNumSwap) continue;
+		const swapped = queryLower.slice(0, i) + next + current + queryLower.slice(i + 2);
+		variants.add(swapped);
+	}
+	return [...variants];
+}
+
+export function fuzzyMatch(query: string, text: string): FuzzyMatch {
+	const queryLower = query.toLowerCase();
+	const textLower = text.toLowerCase();
+
+	const direct = scoreMatch(queryLower, textLower);
+	if (direct.matches) {
+		return direct;
+	}
+
+	let bestSwap: FuzzyMatch | null = null;
+	for (const variant of buildAlphanumericSwapQueries(queryLower)) {
+		const match = scoreMatch(variant, textLower);
+		if (!match.matches) continue;
+		const score = match.score + ALPHANUMERIC_SWAP_PENALTY;
+		if (!bestSwap || score < bestSwap.score) {
+			bestSwap = { matches: true, score };
+		}
+	}
+
+	return bestSwap ?? direct;
+}
+
+/**
+ * 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,69 @@
+// Core TUI interfaces and classes
+
+// Autocomplete support
+export {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	CombinedAutocompleteProvider,
+	type SlashCommand,
+} from "./autocomplete";
+// Cell-based buffer rendering
+export * from "./buffer/index";
+// Components
+export { Box } from "./components/box";
+export { CancellableLoader } from "./components/cancellable-loader";
+export { Editor, type EditorTheme, type EditorTopBorder } from "./components/editor";
+export { Image, type ImageOptions, type ImageTheme } from "./components/image";
+export { Input } from "./components/input";
+export { Loader } from "./components/loader";
+export { type DefaultTextStyle, Markdown, type MarkdownTheme } from "./components/markdown";
+export { type SelectItem, SelectList, type SelectListTheme } from "./components/select-list";
+export { type SettingItem, SettingsList, type SettingsListTheme } from "./components/settings-list";
+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";
+// Editor component interface (for custom editors)
+export type { EditorComponent } from "./editor-component";
+// Fuzzy matching
+export { type FuzzyMatch, fuzzyFilter, fuzzyMatch } from "./fuzzy";
+// Keybindings
+export {
+	DEFAULT_EDITOR_KEYBINDINGS,
+	type EditorAction,
+	type EditorKeybindingsConfig,
+	EditorKeybindingsManager,
+	getEditorKeybindings,
+	setEditorKeybindings,
+} from "./keybindings";
+// Kitty keyboard protocol helpers
+export {
+	isKeyRelease,
+	isKeyRepeat,
+	isKittyProtocolActive,
+	type KeyId,
+	matchesKey,
+	parseKey,
+	parseKittySequence,
+	setKittyProtocolActive,
+} from "./keys";
+// Mermaid diagram support
+export {
+	extractMermaidBlocks,
+	type MermaidImage,
+	type MermaidRenderOptions,
+	prerenderMermaidBlocks,
+	renderMermaidToPng,
+} from "./mermaid";
+// Input buffering for batch splitting
+export { StdinBuffer, type StdinBufferEventMap, type StdinBufferOptions } from "./stdin-buffer";
+export type { BoxSymbols, SymbolTheme } from "./symbols";
+// Terminal interface and implementations
+export { emergencyTerminalRestore, ProcessTerminal, type Terminal } from "./terminal";
+// Terminal image support
+export * from "./terminal-capabilities";
+// TTY ID
+export { getTerminalId, getTtyPath } from "./ttyid";
+export { type Component, Container, type OverlayHandle, type SizeValue, TUI } from "./tui";
+// Utilities
+export { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "./utils";

package/src/keybindings.ts

@@ -0,0 +1,197 @@
+import { type KeyId, matchesKey, parseKey } from "./keys";
+
+/**
+ * Editor actions that can be bound to keys.
+ */
+export type EditorAction =
+	// Cursor movement
+	| "cursorUp"
+	| "cursorDown"
+	| "cursorLeft"
+	| "cursorRight"
+	| "cursorWordLeft"
+	| "cursorWordRight"
+	| "cursorLineStart"
+	| "cursorLineEnd"
+	| "jumpForward"
+	| "jumpBackward"
+	// Deletion
+	| "deleteCharBackward"
+	| "deleteCharForward"
+	| "deleteWordBackward"
+	| "deleteWordForward"
+	| "deleteToLineStart"
+	| "deleteToLineEnd"
+	// Text input
+	| "newLine"
+	| "submit"
+	| "tab"
+	// Selection/autocomplete
+	| "selectUp"
+	| "selectDown"
+	| "selectPageUp"
+	| "selectPageDown"
+	| "selectConfirm"
+	| "selectCancel"
+	// Clipboard
+	| "copy"
+	// Kill ring / undo
+	| "undo"
+	| "yank"
+	| "yankPop";
+
+// 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", "ctrl+b"],
+	cursorRight: ["right", "ctrl+f"],
+	cursorWordLeft: ["alt+left", "ctrl+left", "alt+b"],
+	cursorWordRight: ["alt+right", "ctrl+right", "alt+f"],
+	cursorLineStart: ["home", "ctrl+a"],
+	cursorLineEnd: ["end", "ctrl+e"],
+	jumpForward: "ctrl+]",
+	jumpBackward: "ctrl+alt+]",
+	// Deletion
+	deleteCharBackward: "backspace",
+	deleteCharForward: ["delete", "ctrl+d"],
+	deleteWordBackward: ["ctrl+w", "alt+backspace", "ctrl+backspace"],
+	deleteWordForward: ["alt+delete", "alt+d"],
+	deleteToLineStart: "ctrl+u",
+	deleteToLineEnd: "ctrl+k",
+	// Text input
+	newLine: "shift+enter",
+	submit: "enter",
+	tab: "tab",
+	// Selection/autocomplete
+	selectUp: "up",
+	selectDown: "down",
+	selectPageUp: "pageUp",
+	selectPageDown: "pageDown",
+	selectConfirm: "enter",
+	selectCancel: ["escape", "ctrl+c"],
+	// Clipboard
+	copy: "ctrl+c",
+	// Kill ring / undo
+	undo: "ctrl+-",
+	yank: "ctrl+y",
+	yankPop: "alt+y",
+};
+
+const SHIFTED_SYMBOL_KEYS = new Set<string>([
+	"!",
+	"@",
+	"#",
+	"$",
+	"%",
+	"^",
+	"&",
+	"*",
+	"(",
+	")",
+	"_",
+	"+",
+	"{",
+	"}",
+	"|",
+	":",
+	"<",
+	">",
+	"?",
+	"~",
+]);
+
+const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
+
+/**
+ * Manages keybindings for the editor.
+ */
+export class EditorKeybindingsManager {
+	#actionToKeys: Map<EditorAction, KeyId[]>;
+
+	constructor(config: EditorKeybindingsConfig = {}) {
+		this.#actionToKeys = new Map();
+		this.#buildMaps(config);
+	}
+
+	#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.map(key => normalizeKeyId(key as KeyId)),
+			);
+		}
+
+		// 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.map(key => normalizeKeyId(key as KeyId)),
+			);
+		}
+	}
+
+	/**
+	 * 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;
+		}
+
+		const parsed = parseKey(data);
+		if (!parsed || !parsed.startsWith("shift+")) return false;
+		const keyName = parsed.slice("shift+".length);
+		if (!SHIFTED_SYMBOL_KEYS.has(keyName)) return false;
+		return keys.includes(keyName as KeyId);
+	}
+
+	/**
+	 * 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;
+}