@prometheus-ai/tui 0.5.3 → 0.5.8

package/src/components/scroll-view.ts

@@ -1,3 +1,4 @@
+import { matchesKey } from "../keys";
 import type { Component } from "../tui";
 import { Ellipsis, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
 
@@ -20,6 +21,18 @@ export interface ScrollViewOptions {
 	theme?: ScrollViewTheme;
 	trackChar?: string;
 	thumbChar?: string;
+	/**
+	 * Indicator appended when a row overflows `contentWidth`. Defaults to
+	 * {@link Ellipsis.Unicode}. Pass {@link Ellipsis.Omit} when callers wrap
+	 * lines to width themselves and only trailing padding can overflow (e.g.
+	 * the plan-review overlay), so no stray `…` lands on every padded row.
+	 */
+	ellipsis?: Ellipsis;
+	/**
+	 * Rows moved per keystroke when {@link ScrollView.handleScrollKey} sees a
+	 * Shift+Arrow (the "scroll faster" affordance). Defaults to 5.
+	 */
+	fastScrollLines?: number;
 }
 
 function normalizeScrollbarMode(scrollbar: ScrollViewOptions["scrollbar"]): ScrollbarMode {
@@ -48,6 +61,8 @@ export class ScrollView implements Component {
 	#theme: Required<ScrollViewTheme>;
 	#trackChar: string;
 	#thumbChar: string;
+	#ellipsis: Ellipsis;
+	#fastScrollLines: number;
 
 	constructor(lines: readonly string[], options: ScrollViewOptions) {
 		this.#lines = [...lines];
@@ -60,6 +75,8 @@ export class ScrollView implements Component {
 		};
 		this.#trackChar = firstCellGlyph(options.trackChar ?? DEFAULT_TRACK, DEFAULT_TRACK);
 		this.#thumbChar = firstCellGlyph(options.thumbChar ?? DEFAULT_THUMB, DEFAULT_THUMB);
+		this.#ellipsis = options.ellipsis ?? Ellipsis.Unicode;
+		this.#fastScrollLines = Math.max(1, Math.trunc(options.fastScrollLines ?? 5));
 		this.#clampScrollOffset();
 	}
 
@@ -113,11 +130,55 @@ export class ScrollView implements Component {
 		this.#scrollOffset = this.getMaxScrollOffset();
 	}
 
+	/**
+	 * Apply a standard navigation key to the viewport. Shift+Arrow scrolls by
+	 * {@link ScrollViewOptions.fastScrollLines} (the "scroll faster" affordance);
+	 * plain Arrow by one line; PageUp/PageDown by a page; Home/End to the ends.
+	 * Returns true when the key was consumed, so callers can fall through to
+	 * their own (e.g. vim-style) bindings. Generic on purpose: every ScrollView
+	 * consumer gets the same scroll keys, including Shift-to-go-faster.
+	 */
+	handleScrollKey(data: string): boolean {
+		if (matchesKey(data, "shift+up")) {
+			this.scroll(-this.#fastScrollLines);
+			return true;
+		}
+		if (matchesKey(data, "shift+down")) {
+			this.scroll(this.#fastScrollLines);
+			return true;
+		}
+		if (matchesKey(data, "up")) {
+			this.scroll(-1);
+			return true;
+		}
+		if (matchesKey(data, "down")) {
+			this.scroll(1);
+			return true;
+		}
+		if (matchesKey(data, "pageUp")) {
+			this.page(-1);
+			return true;
+		}
+		if (matchesKey(data, "pageDown")) {
+			this.page(1);
+			return true;
+		}
+		if (matchesKey(data, "home")) {
+			this.scrollToTop();
+			return true;
+		}
+		if (matchesKey(data, "end")) {
+			this.scrollToBottom();
+			return true;
+		}
+		return false;
+	}
+
 	invalidate(): void {
 		// No cached layout to invalidate.
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		this.#clampScrollOffset();
 		const safeWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
 		if (this.#height === 0) return [];
@@ -128,7 +189,7 @@ export class ScrollView implements Component {
 		for (let row = 0; row < this.#height; row++) {
 			const sourceIndex = this.#totalRows === undefined ? this.#scrollOffset + row : row;
 			const source = this.#lines[sourceIndex] ?? "";
-			const truncated = truncateToWidth(replaceTabs(source), contentWidth, Ellipsis.Unicode);
+			const truncated = truncateToWidth(replaceTabs(source), contentWidth, this.#ellipsis);
 			if (!showScrollbar) {
 				lines.push(truncated);
 				continue;

package/src/components/select-list.ts

@@ -1,9 +1,10 @@
+import { popLoopPhase, pushLoopPhase } from "@prometheus-ai/utils";
 import { fuzzyFilter } from "../fuzzy";
 import { getKeybindings } from "../keybindings";
 import { extractPrintableText } from "../keys";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
-import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 import { ScrollView } from "./scroll-view";
 
 const DEFAULT_PRIMARY_COLUMN_WIDTH = 32;
@@ -34,6 +35,8 @@ export interface SelectListTheme {
 	scrollInfo: (text: string) => string;
 	noMatch: (text: string) => string;
 	symbols: SymbolTheme;
+	/** Hover band applied to the full row under the mouse pointer. */
+	hovered?: (text: string) => string;
 }
 
 export interface SelectListTruncatePrimaryContext {
@@ -50,12 +53,40 @@ export interface SelectListLayoutOptions {
 	truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
 	/** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
 	overflowSearch?: boolean;
+	/**
+	 * Wrap long descriptions onto continuation rows indented under the
+	 * description column instead of truncating. Defaults to false so existing
+	 * single-line consumers are unaffected. Navigation remains item-to-item;
+	 * the scrollbar tracks visual rows so the thumb stays correct when items
+	 * wrap unevenly.
+	 */
+	wrapDescription?: boolean;
 }
 
+type SelectItemLayout =
+	| {
+			kind: "description";
+			prefix: string;
+			truncatedValue: string;
+			spacing: string;
+			descriptionSingleLine: string;
+			descriptionStart: number;
+			remainingWidth: number;
+	  }
+	| {
+			kind: "primary";
+			prefix: string;
+			truncatedValue: string;
+			spacing: "";
+	  };
+
 export class SelectList implements Component {
 	#filteredItems: ReadonlyArray<SelectItem>;
 	#filterQuery = "";
 	#selectedIndex: number = 0;
+	#hoveredIndex: number | null = null;
+	/** Per-render map of 0-based output line → filtered-item index. */
+	#hitRows: (number | undefined)[] = [];
 
 	onSelect?: (item: SelectItem) => void;
 	onCancel?: () => void;
@@ -78,12 +109,43 @@ export class SelectList implements Component {
 		this.#selectedIndex = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
 	}
 
+	/** Resolve a 0-based rendered-line index to a filtered-item index. */
+	hitTest(line: number): number | undefined {
+		return this.#hitRows[line];
+	}
+
+	/** Highlight the item under the pointer (null clears). */
+	setHoverIndex(index: number | null): void {
+		this.#hoveredIndex = index;
+	}
+
+	/** Move the selection one step for a wheel notch. */
+	handleWheel(delta: -1 | 1): void {
+		if (this.#filteredItems.length === 0) return;
+		const next = clamp(this.#selectedIndex + delta, 0, this.#filteredItems.length - 1);
+		if (next === this.#selectedIndex) return;
+		this.#selectedIndex = next;
+		this.#notifySelectionChange();
+	}
+
+	/** Mouse click: select the item under the pointer and confirm it. */
+	clickItem(index: number): void {
+		const item = this.#filteredItems[index];
+		if (!item) return;
+		if (index !== this.#selectedIndex) {
+			this.#selectedIndex = index;
+			this.#notifySelectionChange();
+		}
+		this.onSelect?.(item);
+	}
+
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const lines: string[] = [];
+		this.#hitRows = [];
 		const showSearchStatus = this.#shouldRenderSearchStatus();
 
 		// If no items match filter, show message
@@ -96,34 +158,60 @@ export class SelectList implements Component {
 		}
 
 		const primaryColumnWidth = this.#getPrimaryColumnWidth();
+		const wrapEnabled = this.layout.wrapDescription === true;
+		// `maxVisible` is the picker's visual row budget. For non-wrap layouts
+		// every item is one row, so the budget matches the original item count.
+		const visualBudget = this.maxVisible;
+
+		// Compute per-item visual row counts at the conservative width (i.e.
+		// assume the scrollbar column might be reserved). For non-wrap layouts
+		// every count is 1, so visualTotal == #filteredItems and overflow falls
+		// back to the original `N > maxVisible` predicate exactly.
+		const conservativeRowWidth = Math.max(0, width - 1);
+		const rowCounts = new Array<number>(this.#filteredItems.length);
+		let visualTotal = 0;
+		for (let i = 0; i < this.#filteredItems.length; i++) {
+			const item = this.#filteredItems[i];
+			if (!item) {
+				rowCounts[i] = 0;
+				continue;
+			}
+			rowCounts[i] = wrapEnabled ? this.#computeItemRowCount(item, conservativeRowWidth, primaryColumnWidth) : 1;
+			visualTotal += rowCounts[i];
+		}
 
-		// Calculate visible range with scrolling
-		const startIndex = Math.max(
-			0,
-			Math.min(this.#selectedIndex - Math.floor(this.maxVisible / 2), this.#filteredItems.length - this.maxVisible),
-		);
-		const endIndex = Math.min(startIndex + this.maxVisible, this.#filteredItems.length);
-
-		// Render visible items
-		const overflow = this.#filteredItems.length > this.maxVisible;
+		const overflow = visualTotal > visualBudget;
 		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+
+		// Pick a window centered on the selected item that fits in visualBudget
+		// rows. Falls through to the original item-count window when every row
+		// count is 1.
+		const { startIndex, endIndex, visualOffset } = this.#pickWindow(rowCounts, visualBudget);
+
+		// Render visible items. Cap rows at the budget so a single item that
+		// wraps to more than `visualBudget` rows (pathological — e.g. a 5-row
+		// description with maxVisible=3) still keeps the popup bounded; the
+		// scrollbar carries the offscreen rows.
 		const rows: string[] = [];
-		for (let i = startIndex; i < endIndex; i++) {
+		for (let i = startIndex; i < endIndex && rows.length < visualBudget; i++) {
 			const item = this.#filteredItems[i];
 			if (!item) continue;
-
-			const isSelected = i === this.#selectedIndex;
-			const descriptionText = item.description ? sanitizeSingleLine(item.description) : undefined;
-			rows.push(this.#renderItem(item, isSelected, rowWidth, descriptionText, primaryColumnWidth));
+			const hovered = this.theme.hovered !== undefined && i === this.#hoveredIndex && i !== this.#selectedIndex;
+			const itemRows = this.#renderItem(item, i === this.#selectedIndex, rowWidth, primaryColumnWidth);
+			for (const row of itemRows) {
+				if (rows.length >= visualBudget) break;
+				this.#hitRows[rows.length] = i;
+				rows.push(hovered && this.theme.hovered ? this.theme.hovered(row) : row);
+			}
 		}
 
 		const sv = new ScrollView(rows, {
 			height: rows.length,
 			scrollbar: "auto",
-			totalRows: this.#filteredItems.length,
+			totalRows: visualTotal,
 			theme: { track: t => this.theme.scrollInfo(t), thumb: t => this.theme.selectedPrefix(t) },
 		});
-		sv.setScrollOffset(startIndex);
+		sv.setScrollOffset(visualOffset);
 		lines.push(...sv.render(width));
 
 		// Add search status when relevant (scrollbar now indicates overflow)
@@ -178,17 +266,112 @@ export class SelectList implements Component {
 		}
 	}
 
-	#renderItem(
+	#renderItem(item: SelectItem, isSelected: boolean, width: number, primaryColumnWidth: number): string[] {
+		const layout = this.#computeItemLayout(item, isSelected, width, primaryColumnWidth);
+		const { prefix, truncatedValue, spacing } = layout;
+
+		if (layout.kind === "description") {
+			const { descriptionSingleLine, descriptionStart, remainingWidth } = layout;
+			if (this.layout.wrapDescription) {
+				const wrapped = wrapTextWithAnsi(descriptionSingleLine, remainingWidth);
+				if (wrapped.length === 0) wrapped.push("");
+				const indent = padding(descriptionStart);
+				const first = wrapped[0] ?? "";
+				if (isSelected) {
+					const rows = [this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${first}`)];
+					for (let i = 1; i < wrapped.length; i++) {
+						rows.push(this.theme.selectedText(`${indent}${wrapped[i]}`));
+					}
+					return rows;
+				}
+				const rows = [prefix + truncatedValue + this.theme.description(spacing + first)];
+				for (let i = 1; i < wrapped.length; i++) {
+					rows.push(this.theme.description(`${indent}${wrapped[i]}`));
+				}
+				return rows;
+			}
+
+			const truncatedDesc = truncateToWidth(descriptionSingleLine, remainingWidth, Ellipsis.Omit);
+			if (isSelected) {
+				return [this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`)];
+			}
+			return [prefix + truncatedValue + this.theme.description(spacing + truncatedDesc)];
+		}
+
+		if (isSelected) {
+			return [this.theme.selectedText(`${prefix}${truncatedValue}`)];
+		}
+		return [prefix + truncatedValue];
+	}
+
+	#computeItemRowCount(item: SelectItem, width: number, primaryColumnWidth: number): number {
+		// Selection style does not change row count; pass isSelected=false to
+		// keep the cheap path uniform for items outside the visible window.
+		const layout = this.#computeItemLayout(item, false, width, primaryColumnWidth);
+		if (layout.kind !== "description") return 1;
+		const wrapped = wrapTextWithAnsi(layout.descriptionSingleLine, layout.remainingWidth);
+		return Math.max(1, wrapped.length);
+	}
+
+	/**
+	 * Pick a contiguous window of items containing `selectedIndex` such that
+	 * their visual rows fit within `budget`. Centers the selection roughly
+	 * mid-window: first expands up by ⌊budget/2⌋ rows, then fills downward,
+	 * then back upward with any remaining budget. For non-wrap layouts (every
+	 * `rowCounts[i] === 1`) this resolves to the same `[start, start+maxVisible)`
+	 * window the prior arithmetic produced.
+	 */
+	#pickWindow(
+		rowCounts: ReadonlyArray<number>,
+		budget: number,
+	): { startIndex: number; endIndex: number; visualOffset: number } {
+		const n = rowCounts.length;
+		const selected = Math.max(0, Math.min(this.#selectedIndex, n - 1));
+		if (n === 0) return { startIndex: 0, endIndex: 0, visualOffset: 0 };
+
+		const half = Math.floor(budget / 2);
+		let lo = selected;
+		let rowsAboveSelected = 0;
+		// Step 1: expand upward up to `half` rows above the selection so it
+		// lands near the visual middle, matching the prior centering.
+		while (lo > 0 && rowsAboveSelected + (rowCounts[lo - 1] ?? 0) <= half) {
+			lo--;
+			rowsAboveSelected += rowCounts[lo] ?? 0;
+		}
+
+		// Step 2: expand downward until the budget is filled. The selected
+		// item's own rows are always counted; if it alone exceeds `budget`
+		// the surplus is clipped at render time and the scrollbar carries it.
+		let hi = selected + 1;
+		let used = rowsAboveSelected + (rowCounts[selected] ?? 0);
+		while (hi < n && used + (rowCounts[hi] ?? 0) <= budget) {
+			used += rowCounts[hi] ?? 0;
+			hi++;
+		}
+
+		// Step 3: if room remains (selection sat near the bottom), keep
+		// expanding upward.
+		while (lo > 0 && used + (rowCounts[lo - 1] ?? 0) <= budget) {
+			lo--;
+			used += rowCounts[lo] ?? 0;
+		}
+
+		let visualOffset = 0;
+		for (let i = 0; i < lo; i++) visualOffset += rowCounts[i] ?? 0;
+		return { startIndex: lo, endIndex: hi, visualOffset };
+	}
+
+	#computeItemLayout(
 		item: SelectItem,
 		isSelected: boolean,
 		width: number,
-		descriptionSingleLine: string | undefined,
 		primaryColumnWidth: number,
-	): string {
+	): SelectItemLayout {
 		const prefix = isSelected
 			? `${this.theme.symbols.cursor} `
 			: padding(visibleWidth(this.theme.symbols.cursor) + 1);
 		const prefixWidth = visibleWidth(prefix);
+		const descriptionSingleLine = item.description ? sanitizeSingleLine(item.description) : undefined;
 
 		if (descriptionSingleLine && width > 40) {
 			const effectivePrimaryColumnWidth = Math.max(1, Math.min(primaryColumnWidth, width - prefixWidth - 4));
@@ -200,23 +383,26 @@ export class SelectList implements Component {
 			const remainingWidth = width - descriptionStart - 2; // -2 for safety
 
 			if (remainingWidth > MIN_DESCRIPTION_WIDTH) {
-				const truncatedDesc = truncateToWidth(descriptionSingleLine, remainingWidth, Ellipsis.Omit);
-				if (isSelected) {
-					return this.theme.selectedText(`${prefix}${truncatedValue}${spacing}${truncatedDesc}`);
-				}
-
-				const descText = this.theme.description(spacing + truncatedDesc);
-				return prefix + truncatedValue + descText;
+				return {
+					kind: "description",
+					prefix,
+					truncatedValue,
+					spacing,
+					descriptionSingleLine,
+					descriptionStart,
+					remainingWidth,
+				};
 			}
 		}
 
-		const maxWidth = width - prefixWidth - 2;
-		const truncatedValue = this.#truncatePrimary(item, isSelected, maxWidth, maxWidth);
-		if (isSelected) {
-			return this.theme.selectedText(`${prefix}${truncatedValue}`);
-		}
-
-		return prefix + truncatedValue;
+		const fallbackMax = width - prefixWidth - 2;
+		const truncatedValue = this.#truncatePrimary(item, isSelected, fallbackMax, fallbackMax);
+		return {
+			kind: "primary",
+			prefix,
+			truncatedValue,
+			spacing: "",
+		};
 	}
 
 	#getPrimaryColumnWidth(): number {
@@ -297,9 +483,18 @@ export class SelectList implements Component {
 
 	#setFilter(filter: string, notify: boolean): void {
 		this.#filterQuery = filter;
-		this.#filteredItems = filter.trim()
-			? fuzzyFilter([...this.items], filter, item => this.#getFilterText(item))
-			: this.items;
+		if (filter.trim()) {
+			// Breadcrumb the fuzzy match so the loop watchdog can attribute a
+			// large-list filter stall instead of logging it as "unknown".
+			pushLoopPhase("ui.select-filter");
+			try {
+				this.#filteredItems = fuzzyFilter([...this.items], filter, item => this.#getFilterText(item));
+			} finally {
+				popLoopPhase();
+			}
+		} else {
+			this.#filteredItems = this.items;
+		}
 		this.#selectedIndex = 0;
 		if (notify) {
 			this.#notifySelectionChange();