@prometheus-ai/tui 0.5.4 → 0.5.8

package/src/components/spacer.ts

@@ -5,24 +5,28 @@ import type { Component } from "../tui";
  */
 export class Spacer implements Component {
 	#lines: number;
+	#cached: string[] | undefined;
 
 	constructor(lines: number = 1) {
 		this.#lines = lines;
 	}
 
 	setLines(lines: number): void {
+		if (lines === this.#lines) return;
 		this.#lines = lines;
+		this.#cached = undefined;
 	}
 
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
 
-	render(_width: number): string[] {
-		const result: string[] = [];
-		for (let i = 0; i < this.#lines; i++) {
-			result.push("");
+	render(_width: number): readonly string[] {
+		let cached = this.#cached;
+		if (cached === undefined) {
+			cached = new Array(this.#lines).fill("");
+			this.#cached = cached;
 		}
-		return result;
+		return cached;
 	}
 }

package/src/components/tab-bar.ts

@@ -18,6 +18,10 @@ export interface Tab {
 	id: string;
 	/** Display label shown in the tab bar */
 	label: string;
+	/** Compact form (e.g. just the icon) used when the bar must shrink to fit one line. */
+	short?: string;
+	/** Render with the muted style and skip during keyboard navigation. */
+	muted?: boolean;
 }
 
 /** Theme for styling the tab bar */
@@ -30,6 +34,10 @@ export interface TabBarTheme {
 	inactiveTab: (text: string) => string;
 	/** Style for the hint text (e.g., "(tab to cycle)") */
 	hint: (text: string) => string;
+	/** Style for muted tabs. Falls back to `inactiveTab` when omitted. */
+	mutedTab?: (text: string) => string;
+	/** Style for the tab under the mouse pointer. Falls back to `inactiveTab` when omitted. */
+	hoverTab?: (text: string) => string;
 }
 
 /**
@@ -50,10 +58,16 @@ export class TabBar implements Component {
 	#activeIndex: number = 0;
 	#theme: TabBarTheme;
 	#label: string;
+	#hoverTabId: string | null = null;
+	/** Per-render tab hit zones: 0-based line + [start, end) columns. */
+	#hitZones: { line: number; start: number; end: number; index: number }[] = [];
 
 	/** Callback fired when the active tab changes */
 	onTabChange?: (tab: Tab, index: number) => void;
 
+	/** Render the trailing "(tab to cycle)" hint. Disable when the host folds the hint into its own footer. */
+	showHint = true;
+
 	constructor(label: string, tabs: Tab[], theme: TabBarTheme, initialIndex: number = 0) {
 		this.#label = label;
 		this.#tabs = tabs;
@@ -80,14 +94,55 @@ export class TabBar implements Component {
 		}
 	}
 
-	/** Move to the next tab (wraps to first tab after last) */
+	/**
+	 * Replace the tab set without firing onTabChange. The active tab is
+	 * preserved by id when it survives the swap (or forced via `activeId`);
+	 * otherwise the index is clamped.
+	 */
+	setTabs(tabs: Tab[], activeId?: string): void {
+		const targetId = activeId ?? this.#tabs[this.#activeIndex]?.id;
+		this.#tabs = tabs;
+		const index = tabs.findIndex(tab => tab.id === targetId);
+		this.#activeIndex = index >= 0 ? index : Math.max(0, Math.min(this.#activeIndex, tabs.length - 1));
+	}
+
+	/** Set the active tab by id without firing onTabChange. Returns false when the id is unknown. */
+	setActiveById(id: string): boolean {
+		const index = this.#tabs.findIndex(tab => tab.id === id);
+		if (index === -1) return false;
+		this.#activeIndex = index;
+		return true;
+	}
+
+	/** Activate the tab with `id`, firing onTabChange when it changes. Muted tabs are ignored. */
+	selectTab(id: string): boolean {
+		const index = this.#tabs.findIndex(tab => tab.id === id);
+		if (index === -1 || this.#tabs[index]?.muted) return false;
+		this.setActiveIndex(index);
+		return true;
+	}
+
+	/** Move to the next non-muted tab (wraps to first tab after last) */
 	nextTab(): void {
-		this.setActiveIndex((this.#activeIndex + 1) % this.#tabs.length);
+		this.#stepTab(1);
 	}
 
-	/** Move to the previous tab (wraps to last tab before first) */
+	/** Move to the previous non-muted tab (wraps to last tab before first) */
 	prevTab(): void {
-		this.setActiveIndex((this.#activeIndex - 1 + this.#tabs.length) % this.#tabs.length);
+		this.#stepTab(-1);
+	}
+
+	/** Step to the nearest non-muted tab in `delta` direction; no-op when none exists. */
+	#stepTab(delta: -1 | 1): void {
+		const len = this.#tabs.length;
+		if (len === 0) return;
+		for (let step = 1; step <= len; step++) {
+			const index = (((this.#activeIndex + delta * step) % len) + len) % len;
+			if (!this.#tabs[index]?.muted) {
+				this.setActiveIndex(index);
+				return;
+			}
+		}
 	}
 
 	invalidate(): void {
@@ -110,38 +165,78 @@ export class TabBar implements Component {
 		return false;
 	}
 
-	/** Render the tab bar, wrapping to multiple lines if needed */
-	render(width: number): string[] {
+	/**
+	 * Render the tab bar. When the full labels overflow the width, tabs are
+	 * collapsed to their `short` form one by one — starting with the tabs
+	 * farthest from the active one — until the bar fits on a single line.
+	 * Wrapping to multiple lines is the last resort.
+	 */
+	render(width: number): readonly string[] {
 		const maxWidth = Math.max(1, width);
-		const chunks: string[] = [];
-
-		// Label prefix
-		chunks.push(this.#theme.label(`${this.#label}:`));
-		chunks.push("  ");
-
-		// Tab buttons
-		for (let i = 0; i < this.#tabs.length; i++) {
-			const tab = this.#tabs[i];
-			if (i === this.#activeIndex) {
-				chunks.push(this.#theme.activeTab(` ${tab.label} `));
-			} else {
-				chunks.push(this.#theme.inactiveTab(` ${tab.label} `));
+
+		interface TabChunk {
+			text: string;
+			/** Index into #tabs when this chunk is a clickable tab button. */
+			tabIndex?: number;
+		}
+
+		const buildChunks = (labels: readonly string[]): TabChunk[] => {
+			const chunks: TabChunk[] = [];
+			// Label prefix (omitted when the label is empty)
+			if (this.#label) {
+				chunks.push({ text: this.#theme.label(`${this.#label}:`) });
+				chunks.push({ text: "  " });
 			}
-			if (i < this.#tabs.length - 1) {
-				chunks.push("  ");
+			for (let i = 0; i < this.#tabs.length; i++) {
+				const tab = this.#tabs[i];
+				// Muted tabs never take the active highlight: they are skipped by
+				// navigation and only become "active" transiently via setTabs swaps.
+				// A hovered (non-active) tab lights up so mouse users see the target.
+				const hovered = tab.id === this.#hoverTabId && !tab.muted && i !== this.#activeIndex;
+				const style = tab.muted
+					? (this.#theme.mutedTab ?? this.#theme.inactiveTab)
+					: i === this.#activeIndex
+						? this.#theme.activeTab
+						: hovered
+							? (this.#theme.hoverTab ?? this.#theme.inactiveTab)
+							: this.#theme.inactiveTab;
+				chunks.push({ text: style(` ${labels[i]} `), tabIndex: i });
+				if (i < this.#tabs.length - 1) {
+					chunks.push({ text: "  " });
+				}
 			}
-		}
+			// Navigation hint
+			if (this.showHint) {
+				chunks.push({ text: "  " });
+				chunks.push({ text: this.#theme.hint("(tab to cycle)") });
+			}
+			return chunks;
+		};
+		const totalWidth = (chunks: TabChunk[]): number =>
+			chunks.reduce((sum, chunk) => sum + visibleWidth(chunk.text), 0);
 
-		// Navigation hint
-		chunks.push("  ");
-		chunks.push(this.#theme.hint("(tab to cycle)"));
+		const labels = this.#tabs.map(tab => tab.label);
+		let chunks = buildChunks(labels);
 
+		if (totalWidth(chunks) > maxWidth) {
+			const collapseOrder = this.#tabs
+				.map((_, index) => index)
+				.filter(index => index !== this.#activeIndex && this.#tabs[index].short !== undefined)
+				.sort((a, b) => Math.abs(b - this.#activeIndex) - Math.abs(a - this.#activeIndex));
+			for (const index of collapseOrder) {
+				labels[index] = this.#tabs[index].short ?? this.#tabs[index].label;
+				chunks = buildChunks(labels);
+				if (totalWidth(chunks) <= maxWidth) break;
+			}
+		}
+
+		this.#hitZones = [];
 		const lines: string[] = [];
 		let currentLine = "";
 		let currentWidth = 0;
 
 		for (const chunk of chunks) {
-			const chunkWidth = visibleWidth(chunk);
+			const chunkWidth = visibleWidth(chunk.text);
 			if (chunkWidth <= 0) {
 				continue;
 			}
@@ -152,7 +247,10 @@ export class TabBar implements Component {
 					currentLine = "";
 					currentWidth = 0;
 				}
-				lines.push(truncateToWidth(chunk, maxWidth));
+				if (chunk.tabIndex !== undefined) {
+					this.#hitZones.push({ line: lines.length, start: 0, end: maxWidth, index: chunk.tabIndex });
+				}
+				lines.push(truncateToWidth(chunk.text, maxWidth));
 				continue;
 			}
 
@@ -162,7 +260,15 @@ export class TabBar implements Component {
 				currentWidth = 0;
 			}
 
-			currentLine += chunk;
+			if (chunk.tabIndex !== undefined) {
+				this.#hitZones.push({
+					line: lines.length,
+					start: currentWidth,
+					end: currentWidth + chunkWidth,
+					index: chunk.tabIndex,
+				});
+			}
+			currentLine += chunk.text;
 			currentWidth += chunkWidth;
 		}
 
@@ -172,4 +278,23 @@ export class TabBar implements Component {
 
 		return lines.length > 0 ? lines : [""];
 	}
+
+	/**
+	 * Resolve a pointer position against the last rendered frame. `line` is the
+	 * 0-based line index within this component's render output, `col` the
+	 * 0-based column.
+	 */
+	tabAt(line: number, col: number): Tab | undefined {
+		for (const zone of this.#hitZones) {
+			if (zone.line === line && col >= zone.start && col < zone.end) {
+				return this.#tabs[zone.index];
+			}
+		}
+		return undefined;
+	}
+
+	/** Highlight the tab under the pointer (null clears). */
+	setHoverTab(id: string | null): void {
+		this.#hoverTabId = id;
+	}
 }

package/src/components/text.ts

@@ -26,11 +26,15 @@ export class Text implements Component {
 		return this.#text;
 	}
 
-	setText(text: string): void {
+	setText(text: string): boolean {
+		if (text === this.#text) {
+			return false;
+		}
 		this.#text = text;
 		this.#cachedText = undefined;
 		this.#cachedWidth = undefined;
 		this.#cachedLines = undefined;
+		return true;
 	}
 
 	setCustomBgFn(customBgFn?: (text: string) => string): void {
@@ -46,7 +50,7 @@ export class Text implements Component {
 		this.#cachedLines = undefined;
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		// Check cache
 		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
 			return this.#cachedLines;

package/src/components/truncated-text.ts

@@ -8,6 +8,8 @@ export class TruncatedText implements Component {
 	#text: string;
 	#paddingX: number;
 	#paddingY: number;
+	#cachedWidth = -1;
+	#cachedLines: string[] | undefined;
 
 	constructor(text: string, paddingX: number = 0, paddingY: number = 0) {
 		this.#text = text;
@@ -16,10 +18,14 @@ export class TruncatedText implements Component {
 	}
 
 	invalidate(): void {
-		// No cached state to invalidate currently
+		this.#cachedWidth = -1;
+		this.#cachedLines = undefined;
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
+		if (this.#cachedLines && this.#cachedWidth === width) {
+			return this.#cachedLines;
+		}
 		const result: string[] = [];
 
 		// Empty line padded to width
@@ -56,6 +62,8 @@ export class TruncatedText implements Component {
 			result.push(emptyLine);
 		}
 
+		this.#cachedWidth = width;
+		this.#cachedLines = result;
 		return result;
 	}
 }

package/src/fuzzy.ts

@@ -1,6 +1,10 @@
 /**
  * Fuzzy matching utilities.
- * Matches if all query characters appear in order (not necessarily consecutive).
+ *
+ * Matching is deliberately word-local for normal words. This keeps a query like
+ * "image provider" from matching a long setting description only because the
+ * letters i-m-a-g-e appear somewhere in order across unrelated words.
+ *
  * Lower score = better match.
  */
 
@@ -9,56 +13,107 @@ export interface FuzzyMatch {
 	score: number;
 }
 
+export interface FuzzyFilterResult<T> {
+	item: T;
+	score: number;
+}
+
+interface CharacterMatch {
+	matches: boolean;
+	score: number;
+	span: number;
+}
+
+interface SearchWord {
+	text: string;
+	index: number;
+	ordinal: number;
+}
+
+interface SearchIndex {
+	normalized: string;
+	compact: string;
+	/** Start offsets of each word within `compact` (cumulative word lengths). */
+	compactWordStarts: Set<number>;
+	words: SearchWord[];
+}
+
 const ALPHANUMERIC_SWAP_PENALTY = 5;
+const COMPACT_PHRASE_BONUS = 1200;
+const PHRASE_BONUS = 1000;
 
-function scoreMatch(queryLower: string, textLower: string): FuzzyMatch {
+function normalizeForSearch(value: string): string {
+	return value
+		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.replace(/\s+/g, " ");
+}
+
+function buildSearchIndex(text: string): SearchIndex {
+	const normalized = normalizeForSearch(text);
+	if (normalized.length === 0) {
+		return { normalized, compact: "", compactWordStarts: new Set(), words: [] };
+	}
+
+	const words: SearchWord[] = [];
+	const compactWordStarts = new Set<number>();
+	let index = 0;
+	let compactIndex = 0;
+	let ordinal = 0;
+	for (const word of normalized.split(" ")) {
+		words.push({ text: word, index, ordinal });
+		compactWordStarts.add(compactIndex);
+		index += word.length + 1;
+		compactIndex += word.length;
+		ordinal++;
+	}
+
+	return { normalized, compact: normalized.replaceAll(" ", ""), compactWordStarts, words };
+}
+
+function scoreCharacters(queryLower: string, textLower: string): CharacterMatch {
 	if (queryLower.length === 0) {
-		return { matches: true, score: 0 };
+		return { matches: true, score: 0, span: 0 };
 	}
 
 	if (queryLower.length > textLower.length) {
-		return { matches: false, score: 0 };
+		return { matches: false, score: 0, span: 0 };
 	}
 
 	let queryIndex = 0;
 	let score = 0;
+	let firstMatchIndex = -1;
 	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]!);
+			if (firstMatchIndex < 0) firstMatchIndex = i;
 
-			// 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: false, score: 0, span: 0 };
 	}
 
-	return { matches: true, score };
+	return { matches: true, score, span: lastMatchIndex - firstMatchIndex + 1 };
 }
 
 function buildAlphanumericSwapQueries(queryLower: string): string[] {
@@ -76,68 +131,168 @@ function buildAlphanumericSwapQueries(queryLower: string): string[] {
 	return [...variants];
 }
 
-export function fuzzyMatch(query: string, text: string): FuzzyMatch {
-	const queryLower = query.toLowerCase();
-	const textLower = text.toLowerCase();
+function withPosition(score: number, index: number): number {
+	return score + index * 0.01;
+}
+
+function isWordBoundaryPhrase(normalized: string, index: number, length: number): boolean {
+	const before = index === 0 || normalized[index - 1] === " ";
+	const afterIndex = index + length;
+	const after = afterIndex === normalized.length || normalized[afterIndex] === " ";
+	return before && after;
+}
+
+function scoreTokenAgainstWord(token: string, word: SearchWord): FuzzyMatch | null {
+	if (word.text === token) {
+		return { matches: true, score: withPosition(-200, word.index) };
+	}
+
+	if (word.text.startsWith(token)) {
+		return { matches: true, score: withPosition(-170 + (word.text.length - token.length) * 0.5, word.index) };
+	}
+
+	if (token.startsWith(word.text) && token.length - word.text.length <= 2) {
+		return { matches: true, score: withPosition(-150 + token.length - word.text.length, word.index) };
+	}
+
+	const substringIndex = word.text.indexOf(token);
+	if (substringIndex >= 0) {
+		return { matches: true, score: withPosition(-20 + substringIndex, word.index) };
+	}
+
+	const characterMatch = scoreCharacters(token, word.text);
+	if (!characterMatch.matches) return null;
+
+	const maxSpan = Math.max(token.length + 2, Math.ceil(token.length * 1.8));
+	if (characterMatch.span > maxSpan) return null;
+
+	return { matches: true, score: withPosition(-40 + characterMatch.score, word.index) };
+}
+
+function scoreAcronym(token: string, index: SearchIndex): FuzzyMatch | null {
+	if (token.length < 2 || token.length > 4 || index.words.length === 0) return null;
+
+	let queryIndex = 0;
+	let firstOrdinal = -1;
+	let lastOrdinal = -1;
+	let firstTextIndex = 0;
 
-	const direct = scoreMatch(queryLower, textLower);
-	if (direct.matches) {
-		return direct;
+	for (const word of index.words) {
+		if (word.text[0] !== token[queryIndex]) continue;
+		if (firstOrdinal < 0) {
+			firstOrdinal = word.ordinal;
+			firstTextIndex = word.index;
+		}
+		lastOrdinal = word.ordinal;
+		queryIndex++;
+		if (queryIndex === token.length) break;
+	}
+
+	if (queryIndex < token.length || firstOrdinal < 0 || lastOrdinal < 0) return null;
+
+	const wordSpan = lastOrdinal - firstOrdinal + 1;
+	if (wordSpan > token.length + 2) return null;
+
+	return { matches: true, score: withPosition(-30 + wordSpan * 4 - token.length * 2, firstTextIndex) };
+}
+
+function scoreTokenDirect(token: string, index: SearchIndex): FuzzyMatch {
+	if (token.length === 0) return { matches: true, score: 0 };
+
+	let best: FuzzyMatch | null = null;
+	const compactIndex = index.compact.indexOf(token);
+	if (compactIndex >= 0 && index.compactWordStarts.has(compactIndex)) {
+		best = { matches: true, score: withPosition(-140, compactIndex) };
+	}
+
+	for (const word of index.words) {
+		const match = scoreTokenAgainstWord(token, word);
+		if (match && (!best || match.score < best.score)) {
+			best = match;
+		}
 	}
 
-	let bestSwap: FuzzyMatch | null = null;
-	for (const variant of buildAlphanumericSwapQueries(queryLower)) {
-		const match = scoreMatch(variant, textLower);
+	const acronym = scoreAcronym(token, index);
+	if (acronym && (!best || acronym.score < best.score)) {
+		best = acronym;
+	}
+
+	return best ?? { matches: false, score: 0 };
+}
+
+function scoreToken(token: string, index: SearchIndex): FuzzyMatch {
+	let best = scoreTokenDirect(token, index);
+	if (best.matches) return best;
+
+	for (const variant of buildAlphanumericSwapQueries(token)) {
+		const match = scoreTokenDirect(variant, index);
 		if (!match.matches) continue;
 		const score = match.score + ALPHANUMERIC_SWAP_PENALTY;
-		if (!bestSwap || score < bestSwap.score) {
-			bestSwap = { matches: true, score };
+		if (!best.matches || score < best.score) {
+			best = { matches: true, score };
 		}
 	}
 
-	return bestSwap ?? direct;
+	return best;
 }
 
-/**
- * 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;
+export function fuzzyMatch(query: string, text: string): FuzzyMatch {
+	const normalizedQuery = normalizeForSearch(query);
+	if (normalizedQuery.length === 0) {
+		return { matches: true, score: 0 };
 	}
 
-	const tokens = query
-		.trim()
-		.split(/\s+/)
-		.filter(t => t.length > 0);
+	const index = buildSearchIndex(text);
+	if (index.words.length === 0) {
+		return { matches: false, score: 0 };
+	}
 
-	if (tokens.length === 0) {
-		return items;
+	let totalScore = 0;
+	const phraseIndex = index.normalized.indexOf(normalizedQuery);
+	if (phraseIndex >= 0 && isWordBoundaryPhrase(index.normalized, phraseIndex, normalizedQuery.length)) {
+		totalScore -= PHRASE_BONUS;
+		totalScore += phraseIndex * 0.01;
 	}
 
-	const results: { item: T; totalScore: number }[] = [];
+	const compactQuery = normalizedQuery.replaceAll(" ", "");
+	const compactPhraseIndex = index.compact.indexOf(compactQuery);
+	if (compactPhraseIndex >= 0 && index.compactWordStarts.has(compactPhraseIndex)) {
+		totalScore -= COMPACT_PHRASE_BONUS;
+		totalScore += compactPhraseIndex * 0.01;
+	}
 
-	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;
-			}
+	for (const token of normalizedQuery.split(" ")) {
+		const match = scoreToken(token, index);
+		if (!match.matches) {
+			return { matches: false, score: 0 };
 		}
+		totalScore += match.score;
+	}
+
+	return { matches: true, score: totalScore };
+}
 
-		if (allMatch) {
-			results.push({ item, totalScore });
+/**
+ * Filter and sort items by fuzzy match quality (best matches first).
+ * Supports space-separated tokens: all tokens must match.
+ */
+export function fuzzyRank<T>(items: T[], query: string, getText: (item: T) => string): FuzzyFilterResult<T>[] {
+	if (!query.trim()) {
+		return items.map(item => ({ item, score: 0 }));
+	}
+
+	const results: FuzzyFilterResult<T>[] = [];
+	for (const item of items) {
+		const match = fuzzyMatch(query, getText(item));
+		if (match.matches) {
+			results.push({ item, score: match.score });
 		}
 	}
 
-	results.sort((a, b) => a.totalScore - b.totalScore);
-	return results.map(r => r.item);
+	results.sort((a, b) => a.score - b.score);
+	return results;
+}
+
+export function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[] {
+	return fuzzyRank(items, query, getText).map(result => result.item);
 }