@dungle-scrubs/tallow 0.8.21 → 0.8.23

package/packages/tallow-tui/src/editor-component.ts

@@ -0,0 +1,92 @@
+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;
+
+	// =========================================================================
+	// Ghost text / inline suggestions (optional)
+	// =========================================================================
+
+	/**
+	 * Register a change listener that fires alongside onChange.
+	 * Unlike onChange, listeners aren't overwritten by framework wiring.
+	 *
+	 * @param fn - Callback receiving the new text content
+	 */
+	addChangeListener?(fn: (text: string) => void): void;
+
+	/** Set ghost text (dim inline suggestion after cursor). Pass null to clear. */
+	setGhostText?(text: string | null): void;
+
+	/** Get current ghost text, or null if none. */
+	getGhostText?(): string | null;
+
+	// =========================================================================
+	// 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/packages/tallow-tui/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/packages/tallow-tui/src/index.ts

@@ -0,0 +1,118 @@
+// Core TUI interfaces and classes
+
+// Autocomplete support
+export {
+	type AutocompleteItem,
+	type AutocompleteProvider,
+	CombinedAutocompleteProvider,
+	type SlashCommand,
+} from "./autocomplete.js";
+// Border styles
+export {
+	type BorderStyle,
+	defaultBorderStyle,
+	FLAT,
+	ROUNDED,
+	SHARP,
+	setDefaultBorderStyle,
+} from "./border-styles.js";
+// Components
+export { BorderedBox, type BorderedBoxOptions } from "./components/bordered-box.js";
+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,
+	setNextImageFilePath,
+} from "./components/image.js";
+export { Input } from "./components/input.js";
+export { Loader, type LoaderOptions, type MessageTransformContext } from "./components/loader.js";
+export { type DefaultTextStyle, Markdown, type MarkdownTheme } from "./components/markdown.js";
+export { type SelectItem, SelectList, type SelectListTheme } 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 {
+	DEFAULT_EDITOR_KEYBINDINGS,
+	type EditorAction,
+	type EditorKeybindingsConfig,
+	EditorKeybindingsManager,
+	getEditorKeybindings,
+	setEditorKeybindings,
+} from "./keybindings.js";
+// Keyboard input handling
+export {
+	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,
+	calculateImageLayout,
+	createImageMetadata,
+	deleteAllKittyImages,
+	deleteKittyImage,
+	detectCapabilities,
+	detectImageFormat,
+	encodeITerm2,
+	encodeKitty,
+	formatImageDimensions,
+	getCapabilities,
+	getCellDimensions,
+	getGifDimensions,
+	getImageDimensions,
+	getJpegDimensions,
+	getPngDimensions,
+	getWebpDimensions,
+	type ImageDimensions,
+	type ImageFormat,
+	type ImageLayout,
+	type ImageMetadata,
+	type ImageProtocol,
+	type ImageRenderOptions,
+	imageFallback,
+	imageFormatToMime,
+	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 { fileLink, hyperlink, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "./utils.js";

package/packages/tallow-tui/src/keybindings.ts

@@ -0,0 +1,183 @@
+import { type KeyId, matchesKey } from "./keys.js";
+
+/**
+ * Editor actions that can be bound to keys.
+ */
+export type EditorAction =
+	// Cursor movement
+	| "cursorUp"
+	| "cursorDown"
+	| "cursorLeft"
+	| "cursorRight"
+	| "cursorWordLeft"
+	| "cursorWordRight"
+	| "cursorLineStart"
+	| "cursorLineEnd"
+	| "jumpForward"
+	| "jumpBackward"
+	| "pageUp"
+	| "pageDown"
+	// Deletion
+	| "deleteCharBackward"
+	| "deleteCharForward"
+	| "deleteWordBackward"
+	| "deleteWordForward"
+	| "deleteToLineStart"
+	| "deleteToLineEnd"
+	// Text input
+	| "newLine"
+	| "submit"
+	| "tab"
+	// Selection/autocomplete
+	| "selectUp"
+	| "selectDown"
+	| "selectPageUp"
+	| "selectPageDown"
+	| "selectConfirm"
+	| "selectCancel"
+	// Clipboard
+	| "copy"
+	// Kill ring
+	| "yank"
+	| "yankPop"
+	// Undo
+	| "undo"
+	// Tool output
+	| "expandTools"
+	// Session
+	| "toggleSessionPath"
+	| "toggleSessionSort"
+	| "renameSession"
+	| "deleteSession"
+	| "deleteSessionNoninvasive";
+
+// 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+]",
+	pageUp: "pageUp",
+	pageDown: "pageDown",
+	// Deletion
+	deleteCharBackward: "backspace",
+	deleteCharForward: ["delete", "ctrl+d"],
+	deleteWordBackward: ["ctrl+w", "alt+backspace"],
+	deleteWordForward: ["alt+d", "alt+delete"],
+	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 (ctrl+c in editor is handled as selectCancel/interrupt, not copy)
+	copy: "ctrl+shift+c",
+	// Kill ring
+	yank: "ctrl+y",
+	yankPop: "alt+y",
+	// Undo
+	undo: "ctrl+-",
+	// Tool output
+	expandTools: "ctrl+o",
+	// Session
+	toggleSessionPath: "ctrl+p",
+	toggleSessionSort: "ctrl+s",
+	renameSession: "ctrl+r",
+	deleteSession: "ctrl+d",
+	deleteSessionNoninvasive: "ctrl+backspace",
+};
+
+/**
+ * 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;
+}