@f5-sales-demo/pi-tui 19.51.2

package/src/components/text.ts

@@ -0,0 +1,110 @@
+import type { Component } from "../tui";
+import { applyBackgroundToLine, padding, replaceTabs, visibleWidth, wrapTextWithAnsi } from "../utils";
+
+/**
+ * Text component - displays multi-line text with word wrapping
+ */
+export class Text implements Component {
+	#text: string;
+	#paddingX: number; // Left/right padding
+	#paddingY: number; // Top/bottom padding
+	#customBgFn?: (text: string) => string;
+
+	// Cache for rendered output
+	#cachedText?: string;
+	#cachedWidth?: number;
+	#cachedLines?: string[];
+
+	constructor(text: string = "", paddingX: number = 1, paddingY: number = 1, customBgFn?: (text: string) => string) {
+		this.#text = text;
+		this.#paddingX = paddingX;
+		this.#paddingY = paddingY;
+		this.#customBgFn = customBgFn;
+	}
+
+	getText(): string {
+		return this.#text;
+	}
+
+	setText(text: string): void {
+		this.#text = text;
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedLines = undefined;
+	}
+
+	setCustomBgFn(customBgFn?: (text: string) => string): void {
+		this.#customBgFn = customBgFn;
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedLines = undefined;
+	}
+
+	invalidate(): void {
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		// Check cache
+		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
+			return this.#cachedLines;
+		}
+
+		// Don't render anything if there's no actual text
+		if (!this.#text || this.#text.trim() === "") {
+			const result: string[] = [];
+			this.#cachedText = this.#text;
+			this.#cachedWidth = width;
+			this.#cachedLines = result;
+			return result;
+		}
+
+		// Replace tabs with 3 spaces
+		const normalizedText = replaceTabs(this.#text);
+
+		// Calculate content width (subtract left/right margins)
+		const contentWidth = Math.max(1, width - this.#paddingX * 2);
+
+		// Wrap text (this preserves ANSI codes but does NOT pad)
+		const wrappedLines = wrapTextWithAnsi(normalizedText, contentWidth);
+
+		// Add margins and background to each line
+		const leftMargin = padding(this.#paddingX);
+		const rightMargin = padding(this.#paddingX);
+		const contentLines: string[] = [];
+
+		for (const line of wrappedLines) {
+			// Add margins
+			const lineWithMargins = leftMargin + line + rightMargin;
+
+			// Apply background if specified (this also pads to full width)
+			if (this.#customBgFn) {
+				contentLines.push(applyBackgroundToLine(lineWithMargins, width, this.#customBgFn));
+			} else {
+				// No background - just pad to width with spaces
+				const visibleLen = visibleWidth(lineWithMargins);
+				const paddingNeeded = Math.max(0, width - visibleLen);
+				contentLines.push(lineWithMargins + padding(paddingNeeded));
+			}
+		}
+
+		// Add top/bottom padding (empty lines)
+		const emptyLine = padding(width);
+		const emptyLines: string[] = [];
+		for (let i = 0; i < this.#paddingY; i++) {
+			const line = this.#customBgFn ? applyBackgroundToLine(emptyLine, width, this.#customBgFn) : emptyLine;
+			emptyLines.push(line);
+		}
+
+		const result = [...emptyLines, ...contentLines, ...emptyLines];
+
+		// Update cache
+		this.#cachedText = this.#text;
+		this.#cachedWidth = width;
+		this.#cachedLines = result;
+
+		return result.length > 0 ? result : [""];
+	}
+}

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/events.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed publish-subscribe emitter.
+ *
+ * - Keys of `T` are event names; values are payload shapes.
+ * - `on()` returns an unsubscribe closure — the ONLY unsubscribe path.
+ *   No public `off()` method; this avoids divergence between two
+ *   unsubscribe mechanisms and keeps bookkeeping on the emitter.
+ * - `emit()` with zero subscribers is a documented no-op (it does not
+ *   throw and invokes no callback).
+ */
+export class TypedEventEmitter<T extends Record<string, unknown>> {
+	readonly #handlers = new Map<keyof T, Set<(payload: unknown) => void>>();
+
+	on<K extends keyof T>(event: K, handler: (payload: T[K]) => void): () => void {
+		let set = this.#handlers.get(event);
+		if (!set) {
+			set = new Set();
+			this.#handlers.set(event, set);
+		}
+		const wrapped = (p: unknown) => handler(p as T[K]);
+		set.add(wrapped);
+		return () => {
+			set?.delete(wrapped);
+		};
+	}
+
+	emit<K extends keyof T>(event: K, payload: T[K]): void {
+		const set = this.#handlers.get(event);
+		if (!set) return;
+		for (const handler of set) handler(payload);
+	}
+}

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/horizontal-split.ts

@@ -0,0 +1,186 @@
+import type { Component } from "./tui";
+import { padding, sliceByColumn, visibleWidth } from "./utils";
+
+const RESET_SGR = "\x1b[0m";
+
+/** Width configuration for a single HorizontalSplit child. */
+export type SplitChildWidth = { kind: "fixed"; value: number } | { kind: "flex"; value: number; minWidth?: number };
+
+/** One child placed in a HorizontalSplit, with width + priority metadata. */
+export interface SplitChild {
+	component: Component;
+	width: SplitChildWidth;
+	/** Lower priority collapses first when the terminal is too narrow to satisfy all flex minimums. */
+	priority: number;
+}
+
+/**
+ * Side-by-side layout primitive.
+ *
+ * Implements `Component` directly (not a Container subclass) because each
+ * child carries width/priority metadata that doesn't fit the plain
+ * `Component[]` model of `Container`. API surface matches spec §6.1:
+ * `render(width)` returns the composed rows.
+ *
+ * Width allocation (spec §6.1):
+ * 1. Subtract separator cost (N-1 columns for N children).
+ * 2. Allocate fixed-width children first.
+ * 3. Distribute remaining columns across flex children proportionally
+ *    by `flex.value`.
+ * 4. If any flex child falls below its `minWidth`: drop the lowest-priority
+ *    child (binary collapse — not fractional shrink) and retry.
+ * 5. If all minimums still unsatisfiable: expand the highest-priority flex
+ *    child to consume everything; no separators rendered.
+ *
+ * Line composition (spec §6.1):
+ * - row count = max(child.render(w).length)
+ * - each row: per-child slice-or-pad to its allocated width, joined by
+ *   the separator character, terminated with `\x1b[0m`.
+ */
+export class HorizontalSplit implements Component {
+	readonly #children: SplitChild[];
+	readonly #separator: string;
+
+	constructor(children: SplitChild[], separator: string = " ") {
+		this.#children = children;
+		this.#separator = separator;
+	}
+
+	invalidate(): void {
+		for (const c of this.#children) c.component.invalidate?.();
+	}
+
+	render(totalWidth: number): string[] {
+		const widths = this.#allocate(Math.max(1, totalWidth));
+		return this.#compose(widths);
+	}
+
+	/**
+	 * Allocate per-child widths. Fixed children get their configured value;
+	 * flex children split the remainder proportionally. Collapsed children
+	 * receive 0. Separator columns (widths.separatorCount) are accounted for.
+	 *
+	 * Task 5 adds binary collapse: when a flex child's minWidth is unmet, the
+	 * lowest-priority active child is dropped to zero and allocation is retried.
+	 * Task 6 adds the final fallback when nothing can be dropped.
+	 */
+	#allocate(totalWidth: number): number[] {
+		return this.#allocateWithActive(
+			totalWidth,
+			this.#children.map((_, i) => i),
+		);
+	}
+
+	#allocateWithActive(totalWidth: number, activeIndices: number[]): number[] {
+		const n = this.#children.length;
+		const widths = new Array<number>(n).fill(0);
+		if (activeIndices.length === 0) return widths;
+
+		const separatorCost = Math.max(0, activeIndices.length - 1);
+		let remaining = totalWidth - separatorCost;
+
+		// Fixed pass for active children only
+		for (const i of activeIndices) {
+			const child = this.#children[i]!;
+			if (child.width.kind === "fixed") {
+				widths[i] = Math.min(child.width.value, Math.max(0, remaining));
+				remaining -= widths[i]!;
+			}
+		}
+
+		// Flex pass
+		const flexIndices = activeIndices.filter(i => this.#children[i]!.width.kind === "flex");
+		let totalFlex = 0;
+		for (const i of flexIndices) {
+			totalFlex += (this.#children[i]!.width as { value: number }).value;
+		}
+		if (flexIndices.length > 0 && totalFlex > 0) {
+			let distributed = 0;
+			for (let k = 0; k < flexIndices.length - 1; k++) {
+				const i = flexIndices[k]!;
+				const flex = (this.#children[i]!.width as { value: number }).value;
+				widths[i] = Math.floor((remaining * flex) / totalFlex);
+				distributed += widths[i]!;
+			}
+			const last = flexIndices[flexIndices.length - 1]!;
+			widths[last] = Math.max(0, remaining - distributed);
+		} else if (flexIndices.length > 0) {
+			// All flex values sum to 0 — distribute evenly or give to first.
+			// Spec doesn't hit this normally; give all remaining to first flex child.
+			widths[flexIndices[0]!] = Math.max(0, remaining);
+		}
+
+		// minWidth validation — if violations, drop lowest-priority violator and retry.
+		const violators: number[] = [];
+		for (const i of flexIndices) {
+			const spec = this.#children[i]!.width as { kind: "flex"; value: number; minWidth?: number };
+			if (spec.minWidth !== undefined && widths[i]! < spec.minWidth) {
+				violators.push(i);
+			}
+		}
+		if (violators.length === 0) return widths;
+
+		// Find lowest-priority active child.
+		const activeByPriority = [...activeIndices].sort(
+			(a, b) => this.#children[a]!.priority - this.#children[b]!.priority,
+		);
+		const drop = activeByPriority[0]!;
+		const nextActive = activeIndices.filter(i => i !== drop);
+		if (nextActive.length === 0) {
+			// Terminal fallback: expand the highest-priority child of the ORIGINAL
+			// child set to consume everything. No separators (only one active child).
+			const byPriority = [...this.#children.keys()].sort(
+				(a, b) => this.#children[b]!.priority - this.#children[a]!.priority,
+			);
+			const winner = byPriority[0]!;
+			const fallback = new Array<number>(n).fill(0);
+			fallback[winner] = Math.max(1, totalWidth);
+			return fallback;
+		}
+		return this.#allocateWithActive(totalWidth, nextActive);
+	}
+
+	#compose(widths: number[]): string[] {
+		const visibleIdx = widths.map((w, i) => (w > 0 ? i : -1)).filter(i => i >= 0);
+		if (visibleIdx.length === 0) return [];
+
+		const perChildLines = visibleIdx.map(i => this.#children[i]!.component.render(widths[i]!));
+		const rowCount = perChildLines.reduce((m, l) => Math.max(m, l.length), 0);
+
+		const rows: string[] = [];
+		for (let r = 0; r < rowCount; r++) {
+			const parts: string[] = [];
+			for (let v = 0; v < visibleIdx.length; v++) {
+				const childWidth = widths[visibleIdx[v]!]!;
+				const raw = perChildLines[v]![r] ?? "";
+				parts.push(padOrSliceToWidth(raw, childWidth));
+			}
+			// Insert RESET_SGR between cells so unclosed SGR in one cell does
+			// not bleed through the separator into the next cell. Row end still
+			// gets RESET_SGR.
+			rows.push(parts.join(RESET_SGR + this.#separator) + RESET_SGR);
+		}
+		return rows;
+	}
+}
+
+/**
+ * Pad `line` to exactly `width` visible columns, slicing if longer.
+ * Uses the existing ANSI-aware helpers from `utils.ts` so SGR state is
+ * preserved (and any open SGR is closed) at the slice boundary.
+ */
+function padOrSliceToWidth(line: string, width: number): string {
+	if (width <= 0) return "";
+	const visible = visibleWidth(line);
+	if (visible === width) return line;
+	if (visible > width) {
+		// strict=true: exclude any wide char that would extend past the right edge.
+		// The resulting slice has visibleWidth <= width; pad the remainder with
+		// unstyled spaces so the next child still starts at its own col 0.
+		const sliced = sliceByColumn(line, 0, width, true);
+		const slicedWidth = visibleWidth(sliced);
+		if (slicedWidth < width) return sliced + padding(width - slicedWidth);
+		return sliced;
+	}
+	return line + padding(width - visible);
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+// Core TUI interfaces and classes
+
+// Autocomplete support
+export * from "./autocomplete";
+// Chord dispatcher
+export {
+	ChordDispatcher,
+	type ChordDispatcherCallbacks,
+	type ChordResult,
+} from "./chord-dispatcher";
+// Chord parser
+export {
+	type BindingParseError,
+	type BindingsInput,
+	type ChordBinding,
+	type ParseBindingsResult,
+	type ParsedBinding,
+	type ParseResult,
+	parseBinding,
+	parseBindings,
+} from "./chord-parser";
+// Components
+export * from "./components/box";
+export * from "./components/cancellable-loader";
+export * from "./components/editor";
+export * from "./components/image";
+export * from "./components/input";
+export * from "./components/loader";
+export * from "./components/markdown";
+export * from "./components/select-list";
+export * from "./components/settings-list";
+export * from "./components/spacer";
+export * from "./components/tab-bar";
+export * from "./components/text";
+export * from "./components/truncated-text";
+// Editor component interface (for custom editors)
+export type * from "./editor-component";
+// Events
+export { TypedEventEmitter } from "./events";
+// Fuzzy matching
+export * from "./fuzzy";
+// Horizontal split layout primitive
+export {
+	HorizontalSplit,
+	type SplitChild,
+	type SplitChildWidth,
+} from "./horizontal-split";
+// Keybindings
+export * from "./keybindings";
+// Kitty keyboard protocol helpers
+export * from "./keys";
+// Mermaid diagram support
+// Input buffering for batch splitting
+export * from "./stdin-buffer";
+export type * from "./symbols";
+// Terminal interface and implementations
+export * from "./terminal";
+// Terminal image support
+export * from "./terminal-capabilities";
+// TTY ID
+export * from "./ttyid";
+export * from "./tui";
+// Utilities
+export * from "./utils";