@prometheus-ai/tui 0.5.0

package/src/components/scroll-view.ts

@@ -0,0 +1,166 @@
+import type { Component } from "../tui";
+import { Ellipsis, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+
+const DEFAULT_TRACK = "│";
+const DEFAULT_THUMB = "█";
+
+type ScrollbarMode = "auto" | "always" | "never";
+
+export interface ScrollViewTheme {
+	track?: (text: string) => string;
+	thumb?: (text: string) => string;
+}
+
+export interface ScrollViewOptions {
+	height: number;
+	/** Defaults to "auto". "auto" reserves a scrollbar column only when content overflows. */
+	scrollbar?: ScrollbarMode | boolean;
+	/** Logical row count for pre-windowed line slices. Defaults to lines.length. */
+	totalRows?: number;
+	theme?: ScrollViewTheme;
+	trackChar?: string;
+	thumbChar?: string;
+}
+
+function normalizeScrollbarMode(scrollbar: ScrollViewOptions["scrollbar"]): ScrollbarMode {
+	if (scrollbar === true) return "auto";
+	if (scrollbar === false) return "never";
+	return scrollbar ?? "auto";
+}
+
+function firstCellGlyph(value: string, fallback: string): string {
+	const glyph = Array.from(value)[0] ?? fallback;
+	return visibleWidth(glyph) === 1 ? glyph : fallback;
+}
+
+/**
+ * Fixed-height viewport over pre-rendered lines, with optional right-edge scrollbar.
+ *
+ * ScrollView owns only the row offset. Callers remain responsible for producing
+ * already-wrapped logical lines appropriate for the current render width.
+ */
+export class ScrollView implements Component {
+	#lines: string[];
+	#height: number;
+	#scrollOffset = 0;
+	#totalRows: number | undefined;
+	#scrollbar: ScrollbarMode;
+	#theme: Required<ScrollViewTheme>;
+	#trackChar: string;
+	#thumbChar: string;
+
+	constructor(lines: readonly string[], options: ScrollViewOptions) {
+		this.#lines = [...lines];
+		this.#height = Number.isFinite(options.height) ? Math.max(0, Math.trunc(options.height)) : 0;
+		this.#totalRows = options.totalRows === undefined ? undefined : Math.max(0, Math.trunc(options.totalRows));
+		this.#scrollbar = normalizeScrollbarMode(options.scrollbar);
+		this.#theme = {
+			track: options.theme?.track ?? (text => text),
+			thumb: options.theme?.thumb ?? (text => text),
+		};
+		this.#trackChar = firstCellGlyph(options.trackChar ?? DEFAULT_TRACK, DEFAULT_TRACK);
+		this.#thumbChar = firstCellGlyph(options.thumbChar ?? DEFAULT_THUMB, DEFAULT_THUMB);
+		this.#clampScrollOffset();
+	}
+
+	setLines(lines: readonly string[]): void {
+		this.#lines = [...lines];
+		this.#clampScrollOffset();
+	}
+
+	setTotalRows(totalRows: number | undefined): void {
+		this.#totalRows = totalRows === undefined ? undefined : Math.max(0, Math.trunc(totalRows));
+		this.#clampScrollOffset();
+	}
+
+	setHeight(height: number): void {
+		this.#height = Number.isFinite(height) ? Math.max(0, Math.trunc(height)) : 0;
+		this.#clampScrollOffset();
+	}
+
+	setScrollbar(scrollbar: ScrollViewOptions["scrollbar"]): void {
+		this.#scrollbar = normalizeScrollbarMode(scrollbar);
+	}
+
+	getScrollOffset(): number {
+		return this.#scrollOffset;
+	}
+
+	getMaxScrollOffset(): number {
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		return Math.max(0, rowCount - this.#height);
+	}
+
+	setScrollOffset(offset: number): void {
+		this.#scrollOffset = Number.isFinite(offset) ? Math.trunc(offset) : 0;
+		this.#clampScrollOffset();
+	}
+
+	scroll(delta: number): void {
+		this.setScrollOffset(this.#scrollOffset + (Number.isFinite(delta) ? Math.trunc(delta) : 0));
+	}
+
+	page(delta: number): void {
+		const step = Math.max(1, this.#height - 1);
+		this.scroll(step * (Number.isFinite(delta) ? Math.trunc(delta) : 0));
+	}
+
+	scrollToTop(): void {
+		this.#scrollOffset = 0;
+	}
+
+	scrollToBottom(): void {
+		this.#scrollOffset = this.getMaxScrollOffset();
+	}
+
+	invalidate(): void {
+		// No cached layout to invalidate.
+	}
+
+	render(width: number): string[] {
+		this.#clampScrollOffset();
+		const safeWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+		if (this.#height === 0) return [];
+		const showScrollbar = safeWidth > 0 && this.#shouldRenderScrollbar();
+		const contentWidth = Math.max(0, safeWidth - (showScrollbar ? 1 : 0));
+		const thumb = showScrollbar ? this.#thumbRange() : undefined;
+		const lines: string[] = [];
+		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);
+			if (!showScrollbar) {
+				lines.push(truncated);
+				continue;
+			}
+			const content = `${truncated}${" ".repeat(Math.max(0, contentWidth - visibleWidth(truncated)))}`;
+			const barGlyph = thumb && row >= thumb.start && row < thumb.end ? this.#thumbChar : this.#trackChar;
+			const styledBar =
+				thumb && row >= thumb.start && row < thumb.end ? this.#theme.thumb(barGlyph) : this.#theme.track(barGlyph);
+			lines.push(`${content}${styledBar}`);
+		}
+		return lines;
+	}
+
+	#clampScrollOffset(): void {
+		this.#scrollOffset = Math.max(0, Math.min(this.#scrollOffset, this.getMaxScrollOffset()));
+	}
+
+	#shouldRenderScrollbar(): boolean {
+		if (this.#height <= 0) return false;
+		if (this.#scrollbar === "never") return false;
+		if (this.#scrollbar === "always") return true;
+		return (this.#totalRows ?? this.#lines.length) > this.#height;
+	}
+
+	#thumbRange(): { start: number; end: number } {
+		if (this.#height <= 0) return { start: 0, end: 0 };
+		const rowCount = this.#totalRows ?? this.#lines.length;
+		if (rowCount <= this.#height) return { start: 0, end: this.#height };
+		const thumbSize = Math.max(1, Math.min(Math.floor((this.#height * this.#height) / rowCount), this.#height));
+		const travel = this.#height - thumbSize;
+		const maxOffset = this.getMaxScrollOffset();
+		const start = maxOffset === 0 ? 0 : Math.round((this.#scrollOffset / maxOffset) * travel);
+		return { start, end: start + thumbSize };
+	}
+}

package/src/components/select-list.ts

@@ -0,0 +1,331 @@
+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 { ScrollView } from "./scroll-view";
+
+const DEFAULT_PRIMARY_COLUMN_WIDTH = 32;
+const PRIMARY_COLUMN_GAP = 2;
+const MIN_DESCRIPTION_WIDTH = 10;
+
+function sanitizeSingleLine(text: string): string {
+	return replaceTabs(text)
+		.replace(/[\r\n]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+const clamp = (value: number, min: number, max: number): number => Math.max(min, Math.min(value, max));
+
+export interface SelectItem {
+	value: string;
+	label: string;
+	description?: string;
+	/** Dim hint text shown inline after cursor when this item is selected */
+	hint?: string;
+}
+
+export interface SelectListTheme {
+	selectedPrefix: (text: string) => string;
+	selectedText: (text: string) => string;
+	description: (text: string) => string;
+	scrollInfo: (text: string) => string;
+	noMatch: (text: string) => string;
+	symbols: SymbolTheme;
+}
+
+export interface SelectListTruncatePrimaryContext {
+	text: string;
+	maxWidth: number;
+	columnWidth: number;
+	item: SelectItem;
+	isSelected: boolean;
+}
+
+export interface SelectListLayoutOptions {
+	minPrimaryColumnWidth?: number;
+	maxPrimaryColumnWidth?: number;
+	truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
+	/** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
+	overflowSearch?: boolean;
+}
+
+export class SelectList implements Component {
+	#filteredItems: ReadonlyArray<SelectItem>;
+	#filterQuery = "";
+	#selectedIndex: number = 0;
+
+	onSelect?: (item: SelectItem) => void;
+	onCancel?: () => void;
+	onSelectionChange?: (item: SelectItem) => void;
+
+	constructor(
+		private readonly items: ReadonlyArray<SelectItem>,
+		private readonly maxVisible: number,
+		private readonly theme: SelectListTheme,
+		private readonly layout: SelectListLayoutOptions = {},
+	) {
+		this.#filteredItems = items;
+	}
+
+	setFilter(filter: string): void {
+		this.#setFilter(filter, true);
+	}
+
+	setSelectedIndex(index: number): void {
+		this.#selectedIndex = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate currently
+	}
+
+	render(width: number): string[] {
+		const lines: string[] = [];
+		const showSearchStatus = this.#shouldRenderSearchStatus();
+
+		// If no items match filter, show message
+		if (this.#filteredItems.length === 0) {
+			if (showSearchStatus) {
+				lines.push(this.#renderStatusLine(width));
+			}
+			lines.push(this.theme.noMatch("  No matching items"));
+			return lines;
+		}
+
+		const primaryColumnWidth = this.#getPrimaryColumnWidth();
+
+		// 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 rowWidth = Math.max(0, width - (overflow ? 1 : 0));
+		const rows: string[] = [];
+		for (let i = startIndex; i < endIndex; 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 sv = new ScrollView(rows, {
+			height: rows.length,
+			scrollbar: "auto",
+			totalRows: this.#filteredItems.length,
+			theme: { track: t => this.theme.scrollInfo(t), thumb: t => this.theme.selectedPrefix(t) },
+		});
+		sv.setScrollOffset(startIndex);
+		lines.push(...sv.render(width));
+
+		// Add search status when relevant (scrollbar now indicates overflow)
+		if (showSearchStatus) {
+			lines.push(this.#renderStatusLine(width));
+		}
+
+		return lines;
+	}
+
+	handleInput(keyData: string): void {
+		const kb = getKeybindings();
+		// Escape or Ctrl+C
+		if (kb.matches(keyData, "tui.select.cancel")) {
+			if (this.onCancel) {
+				this.onCancel();
+			}
+			return;
+		}
+
+		if (this.#handleSearchInput(keyData)) {
+			return;
+		}
+
+		if (this.#filteredItems.length === 0) return;
+		// Up arrow - wrap to bottom when at top
+		if (kb.matches(keyData, "tui.select.up")) {
+			this.#selectedIndex = this.#selectedIndex === 0 ? this.#filteredItems.length - 1 : this.#selectedIndex - 1;
+			this.#notifySelectionChange();
+		}
+		// Down arrow - wrap to top when at bottom
+		else if (kb.matches(keyData, "tui.select.down")) {
+			this.#selectedIndex = this.#selectedIndex === this.#filteredItems.length - 1 ? 0 : this.#selectedIndex + 1;
+			this.#notifySelectionChange();
+		}
+		// PageUp - jump up by one visible page
+		else if (kb.matches(keyData, "tui.select.pageUp")) {
+			this.#selectedIndex = Math.max(0, this.#selectedIndex - this.maxVisible);
+			this.#notifySelectionChange();
+		}
+		// PageDown - jump down by one visible page
+		else if (kb.matches(keyData, "tui.select.pageDown")) {
+			this.#selectedIndex = Math.min(this.#filteredItems.length - 1, this.#selectedIndex + this.maxVisible);
+			this.#notifySelectionChange();
+		}
+		// Enter
+		else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n") {
+			const selectedItem = this.#filteredItems[this.#selectedIndex];
+			if (selectedItem && this.onSelect) {
+				this.onSelect(selectedItem);
+			}
+		}
+	}
+
+	#renderItem(
+		item: SelectItem,
+		isSelected: boolean,
+		width: number,
+		descriptionSingleLine: string | undefined,
+		primaryColumnWidth: number,
+	): string {
+		const prefix = isSelected
+			? `${this.theme.symbols.cursor} `
+			: padding(visibleWidth(this.theme.symbols.cursor) + 1);
+		const prefixWidth = visibleWidth(prefix);
+
+		if (descriptionSingleLine && width > 40) {
+			const effectivePrimaryColumnWidth = Math.max(1, Math.min(primaryColumnWidth, width - prefixWidth - 4));
+			const maxPrimaryWidth = Math.max(1, effectivePrimaryColumnWidth - PRIMARY_COLUMN_GAP);
+			const truncatedValue = this.#truncatePrimary(item, isSelected, maxPrimaryWidth, effectivePrimaryColumnWidth);
+			const truncatedValueWidth = visibleWidth(truncatedValue);
+			const spacing = padding(Math.max(1, effectivePrimaryColumnWidth - truncatedValueWidth));
+			const descriptionStart = prefixWidth + truncatedValueWidth + spacing.length;
+			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;
+			}
+		}
+
+		const maxWidth = width - prefixWidth - 2;
+		const truncatedValue = this.#truncatePrimary(item, isSelected, maxWidth, maxWidth);
+		if (isSelected) {
+			return this.theme.selectedText(`${prefix}${truncatedValue}`);
+		}
+
+		return prefix + truncatedValue;
+	}
+
+	#getPrimaryColumnWidth(): number {
+		const { min, max } = this.#getPrimaryColumnBounds();
+		const widestPrimary = this.#filteredItems.reduce((widest, item) => {
+			return Math.max(widest, visibleWidth(this.#getDisplayValue(item)) + PRIMARY_COLUMN_GAP);
+		}, 0);
+
+		return clamp(widestPrimary, min, max);
+	}
+
+	#getPrimaryColumnBounds(): { min: number; max: number } {
+		const rawMin =
+			this.layout.minPrimaryColumnWidth ?? this.layout.maxPrimaryColumnWidth ?? DEFAULT_PRIMARY_COLUMN_WIDTH;
+		const rawMax =
+			this.layout.maxPrimaryColumnWidth ?? this.layout.minPrimaryColumnWidth ?? DEFAULT_PRIMARY_COLUMN_WIDTH;
+
+		return {
+			min: Math.max(1, Math.min(rawMin, rawMax)),
+			max: Math.max(1, Math.max(rawMin, rawMax)),
+		};
+	}
+
+	#truncatePrimary(item: SelectItem, isSelected: boolean, maxWidth: number, columnWidth: number): string {
+		const displayValue = this.#getDisplayValue(item);
+		const truncatedValue = this.layout.truncatePrimary
+			? this.layout.truncatePrimary({
+					text: displayValue,
+					maxWidth,
+					columnWidth,
+					item,
+					isSelected,
+				})
+			: truncateToWidth(displayValue, maxWidth, Ellipsis.Omit);
+
+		return truncateToWidth(truncatedValue, maxWidth, Ellipsis.Omit);
+	}
+
+	#getDisplayValue(item: SelectItem): string {
+		return sanitizeSingleLine(item.label || item.value);
+	}
+
+	#renderStatusLine(width: number): string {
+		const query = sanitizeSingleLine(this.#filterQuery);
+		const statusText = query ? `  Search: ${query}` : "  Type to search";
+		return this.theme.scrollInfo(truncateToWidth(statusText, Math.max(1, width - 2), Ellipsis.Omit));
+	}
+
+	#shouldRenderSearchStatus(): boolean {
+		return (
+			this.layout.overflowSearch !== false && (this.items.length > this.maxVisible || this.#filterQuery.length > 0)
+		);
+	}
+
+	#canEditSearch(): boolean {
+		return this.layout.overflowSearch !== false && this.items.length > this.maxVisible;
+	}
+
+	#handleSearchInput(keyData: string): boolean {
+		if (!this.#canEditSearch()) return false;
+
+		const kb = getKeybindings();
+		if (kb.matches(keyData, "tui.editor.deleteCharBackward")) {
+			if (this.#filterQuery.length === 0) return false;
+			const chars = [...this.#filterQuery];
+			chars.pop();
+			this.#setFilter(chars.join(""), true);
+			return true;
+		}
+
+		const printableText = extractPrintableText(keyData);
+		if (printableText === undefined) return false;
+		if (this.#filterQuery.length === 0 && printableText.trim().length === 0) return false;
+
+		this.#setFilter(this.#filterQuery + printableText, true);
+		return true;
+	}
+
+	#setFilter(filter: string, notify: boolean): void {
+		this.#filterQuery = filter;
+		this.#filteredItems = filter.trim()
+			? fuzzyFilter([...this.items], filter, item => this.#getFilterText(item))
+			: this.items;
+		this.#selectedIndex = 0;
+		if (notify) {
+			this.#notifySelectionChange();
+		}
+	}
+
+	#getFilterText(item: SelectItem): string {
+		let text = `${item.label} ${item.value}`;
+		if (item.description) {
+			text += ` ${item.description}`;
+		}
+		if (item.hint) {
+			text += ` ${item.hint}`;
+		}
+		return sanitizeSingleLine(text);
+	}
+
+	#notifySelectionChange(): void {
+		const selectedItem = this.#filteredItems[this.#selectedIndex];
+		if (selectedItem && this.onSelectionChange) {
+			this.onSelectionChange(selectedItem);
+		}
+	}
+
+	getSelectedItem(): SelectItem | null {
+		const item = this.#filteredItems[this.#selectedIndex];
+		return item || null;
+	}
+}

package/src/components/settings-list.ts

@@ -0,0 +1,212 @@
+import { getKeybindings } from "../keybindings";
+import type { Component } from "../tui";
+import { Ellipsis, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+import { ScrollView } from "./scroll-view";
+
+export interface SettingItem {
+	/** Unique identifier for this setting */
+	id: string;
+	/** Display label (left side) */
+	label: string;
+	/** Optional description shown when selected */
+	description?: string;
+	/** Current value to display (right side) */
+	currentValue: string;
+	/** If provided, Enter/Space cycles through these values */
+	values?: string[];
+	/** If provided, Enter opens this submenu. Receives current value and done callback. */
+	submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
+	/** True when the displayed setting differs from its default value. */
+	changed?: boolean;
+}
+
+export interface SettingsListTheme {
+	label: (text: string, selected: boolean, changed: boolean) => string;
+	value: (text: string, selected: boolean, changed: boolean) => string;
+	description: (text: string) => string;
+	cursor: string;
+	hint: (text: string) => string;
+}
+
+export class SettingsList implements Component {
+	#items: SettingItem[];
+	#theme: SettingsListTheme;
+	#selectedIndex = 0;
+	#maxVisible: number;
+	#onChange: (id: string, newValue: string) => void;
+	#onCancel: () => void;
+
+	// Submenu state
+	#submenuComponent: Component | null = null;
+	#submenuItemIndex: number | null = null;
+
+	constructor(
+		items: SettingItem[],
+		maxVisible: number,
+		theme: SettingsListTheme,
+		onChange: (id: string, newValue: string) => void,
+		onCancel: () => void,
+	) {
+		this.#items = items;
+		this.#maxVisible = maxVisible;
+		this.#theme = theme;
+		this.#onChange = onChange;
+		this.#onCancel = onCancel;
+	}
+
+	/** Update an item's currentValue */
+	updateValue(id: string, newValue: string): void {
+		const item = this.#items.find(i => i.id === id);
+		if (item) {
+			item.currentValue = newValue;
+		}
+	}
+
+	/**
+	 * Replace the entire items array. Selection is preserved when the prior
+	 * index is still valid, otherwise clamped to the last item (or 0 if the
+	 * list is now empty). An open submenu is left untouched — its lifetime
+	 * is bounded by its own done callback, and `#closeSubmenu` re-clamps the
+	 * restored index against the new list on the way out.
+	 */
+	setItems(items: SettingItem[]): void {
+		this.#items = items;
+		if (this.#items.length === 0) {
+			this.#selectedIndex = 0;
+		} else if (this.#selectedIndex >= this.#items.length) {
+			this.#selectedIndex = this.#items.length - 1;
+		}
+	}
+
+	invalidate(): void {
+		this.#submenuComponent?.invalidate?.();
+	}
+
+	render(width: number): string[] {
+		// If submenu is active, render it instead
+		if (this.#submenuComponent) {
+			return this.#submenuComponent.render(width);
+		}
+
+		return this.#renderMainList(width);
+	}
+
+	#renderItemRow(item: SettingItem, index: number, maxLabelWidth: number, rowWidth: number): string {
+		const isSelected = index === this.#selectedIndex;
+		const prefix = isSelected ? this.#theme.cursor : "  ";
+		const prefixWidth = visibleWidth(prefix);
+		const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+		const labelText = this.#theme.label(labelPadded, isSelected, item.changed === true);
+		const separator = "  ";
+		const valueMaxWidth = rowWidth - prefixWidth - maxLabelWidth - visibleWidth(separator) - 2;
+		const valueText = this.#theme.value(
+			truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),
+			isSelected,
+			item.changed === true,
+		);
+		return truncateToWidth(prefix + labelText + separator + valueText, Math.max(0, rowWidth));
+	}
+
+	#renderMainList(width: number): string[] {
+		const lines: string[] = [];
+
+		if (this.#items.length === 0) {
+			lines.push(this.#theme.hint("  No settings available"));
+			return lines;
+		}
+
+		const viewportHeight = Math.min(this.#maxVisible, this.#items.length);
+		const startIndex = Math.max(
+			0,
+			Math.min(this.#selectedIndex - Math.floor(viewportHeight / 2), this.#items.length - viewportHeight),
+		);
+		const maxLabelWidth = Math.min(30, Math.max(...this.#items.map(item => visibleWidth(item.label))));
+		const itemRowsOverflow = this.#items.length > viewportHeight;
+		const itemRowWidth = Math.max(0, width - (itemRowsOverflow ? 1 : 0));
+		const visibleItems = this.#items.slice(startIndex, startIndex + viewportHeight);
+		const itemRows = visibleItems.map((item, index) =>
+			this.#renderItemRow(item, startIndex + index, maxLabelWidth, itemRowWidth),
+		);
+		const scrollView = new ScrollView(itemRows, {
+			height: viewportHeight,
+			scrollbar: "auto",
+			totalRows: this.#items.length,
+			theme: {
+				track: text => this.#theme.hint(text),
+				thumb: text => this.#theme.label(text, true, false),
+			},
+		});
+		scrollView.setScrollOffset(startIndex);
+		lines.push(...scrollView.render(width));
+
+		// Add description for selected item
+		const selectedItem = this.#items[this.#selectedIndex];
+		if (selectedItem?.description) {
+			lines.push("");
+			const wrappedDesc = wrapTextWithAnsi(selectedItem.description, width - 4);
+			for (const line of wrappedDesc) {
+				lines.push(this.#theme.description(`  ${line}`));
+			}
+		}
+
+		// Add hint
+		lines.push("");
+		lines.push(truncateToWidth(this.#theme.hint("  Enter/Space to change · Esc to cancel"), width));
+
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		// If submenu is active, delegate all input to it
+		// The submenu's onCancel (triggered by escape) will call done() which closes it
+		if (this.#submenuComponent) {
+			this.#submenuComponent.handleInput?.(data);
+			return;
+		}
+
+		// Main list input handling
+		const kb = getKeybindings();
+		if (kb.matches(data, "tui.select.up")) {
+			this.#selectedIndex = this.#selectedIndex === 0 ? this.#items.length - 1 : this.#selectedIndex - 1;
+		} else if (kb.matches(data, "tui.select.down")) {
+			this.#selectedIndex = this.#selectedIndex === this.#items.length - 1 ? 0 : this.#selectedIndex + 1;
+		} else if (kb.matches(data, "tui.select.confirm") || data === " " || data === "\n") {
+			this.#activateItem();
+		} else if (kb.matches(data, "tui.select.cancel")) {
+			this.#onCancel();
+		}
+	}
+
+	#activateItem(): void {
+		const item = this.#items[this.#selectedIndex];
+		if (!item) return;
+
+		if (item.submenu) {
+			// Open submenu, passing current value so it can pre-select correctly
+			this.#submenuItemIndex = this.#selectedIndex;
+			this.#submenuComponent = item.submenu(item.currentValue, (selectedValue?: string) => {
+				if (selectedValue !== undefined) {
+					item.currentValue = selectedValue;
+					this.#onChange(item.id, selectedValue);
+				}
+				this.#closeSubmenu();
+			});
+		} else if (item.values && item.values.length > 0) {
+			// Cycle through values
+			const currentIndex = item.values.indexOf(item.currentValue);
+			const nextIndex = (currentIndex + 1) % item.values.length;
+			const newValue = item.values[nextIndex];
+			item.currentValue = newValue;
+			this.#onChange(item.id, newValue);
+		}
+	}
+
+	#closeSubmenu(): void {
+		this.#submenuComponent = null;
+		// Restore selection to the item that opened the submenu
+		if (this.#submenuItemIndex !== null) {
+			this.#selectedIndex = this.#submenuItemIndex;
+			this.#submenuItemIndex = null;
+		}
+	}
+}