@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/src/components/select-list.ts

@@ -1,7 +1,7 @@
 import { popLoopPhase, pushLoopPhase } from "@oh-my-pi/pi-utils";
-import { fuzzyFilter } from "../fuzzy";
+import { getMenuWindow, MenuSelection } from "./menu-selection";
 import { getKeybindings } from "../keybindings";
-import { extractPrintableText } from "../keys";
+import { extractPrintableText, matchesKey } from "../keys";
 import { type MouseRoutable, routeSelectListMouse, type SgrMouseEvent } from "../mouse";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
@@ -31,6 +31,12 @@ export interface SelectItem {
 	icon?: string;
 	/** Dim hint text shown inline after cursor when this item is selected */
 	hint?: string;
+	/** Disabled rows stay visible but are skipped by navigation and cannot activate. */
+	disabled?: boolean;
+	/** When set, activation requires a second Enter/click and this text becomes the status line. */
+	confirmation?: string;
+	/** Additional text included by the default fuzzy filter without being rendered. */
+	searchText?: string;
 }
 
 export interface SelectListTheme {
@@ -54,12 +60,48 @@ export interface SelectListTruncatePrimaryContext {
 	isSelected: boolean;
 }
 
+/** State supplied to a rich SelectList row renderer or measurer. */
+export interface SelectListRenderItemContext {
+	item: SelectItem;
+	index: number;
+	width: number;
+	selected: boolean;
+	hovered: boolean;
+	pendingConfirmation: boolean;
+	theme: SelectListTheme;
+}
+
+/** Current controlled menu state supplied to a custom status renderer. */
+export interface SelectListStatusContext {
+	query: string;
+	selectedIndex: number;
+	visibleCount: number;
+	totalCount: number;
+	pendingItem: SelectItem | undefined;
+}
+
 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;
+	/** Search activation policy. `overflowSearch` remains authoritative when this is omitted. */
+	search?: "overflow" | "always" | "never";
+	/** Domain-specific filtering/ranking. Selection is retained by item value when possible. */
+	filterItems?: (items: readonly SelectItem[], query: string) => readonly SelectItem[];
+	/** Custom rich-row renderer. Every returned line is mouse-hit-tested as the same item. */
+	renderItem?: (context: SelectListRenderItemContext) => readonly string[];
+	/** Cheap row measurement for custom renderers; defaults to calling renderItem and reading its length. */
+	measureItem?: (context: SelectListRenderItemContext) => number;
+	/** Empty-list message (before a query is entered). */
+	emptyText?: string;
+	/** No-match message (after filtering). */
+	noMatchText?: string;
+	/** Optional status renderer. Return undefined to omit the status row. */
+	statusText?: (context: SelectListStatusContext) => string | undefined;
+	/** Whether single-step keyboard navigation wraps at the edges. Defaults to true. */
+	wrapNavigation?: boolean;
 	/**
 	 * Wrap long descriptions onto continuation rows indented under the
 	 * description column instead of truncating. Defaults to false so existing
@@ -95,10 +137,19 @@ type SelectItemLayout =
 	  };
 
 export class SelectList implements Component, MouseRoutable {
+	/**
+	 * Sanitized `{label, description}` per item object. `sanitizeSingleLine`
+	 * is 3 passes + 2 regex execs per call and render() used to run it up to
+	 * 3x per item per frame (column widths, row counts, item render). Items
+	 * are host-owned and stable across frames; the map is cleared when the
+	 * visible item list identity changes.
+	 */
+	#sanitized = new WeakMap<
+		SelectItem,
+		{ sourceLabel: string; sourceDescription: string | undefined; label: string; description: string | undefined }
+	>();
 	#maxVisible: number;
-	#filteredItems: ReadonlyArray<SelectItem>;
-	#filterQuery = "";
-	#selectedIndex: number = 0;
+	#selection: MenuSelection<SelectItem>;
 	#hoveredIndex: number | null = null;
 	/** Per-render map of 0-based output line → filtered-item index. */
 	#hitRows: (number | undefined)[] = [];
@@ -108,24 +159,31 @@ export class SelectList implements Component, MouseRoutable {
 	onSelectionChange?: (item: SelectItem) => void;
 
 	constructor(
-		private readonly items: ReadonlyArray<SelectItem>,
+		items: ReadonlyArray<SelectItem>,
 		maxVisible: number,
 		private readonly theme: SelectListTheme,
 		private readonly layout: SelectListLayoutOptions = {},
 	) {
 		this.#maxVisible = Math.max(1, Math.trunc(maxVisible));
-		this.#filteredItems = items;
+		this.#selection = new MenuSelection(items, {
+			getKey: item => item.value,
+			getSearchText: item => this.#getFilterText(item),
+			isDisabled: item => item.disabled === true,
+			requiresConfirmation: item => item.confirmation !== undefined,
+			filter: layout.filterItems,
+		});
 	}
 	/** Return item, selection, and filter state for debug inspection. */
 	debugState(): Record<string, unknown> {
-		const selected = this.#filteredItems[this.#selectedIndex];
+		const selected = this.#selection.selectedItem;
 		return {
-			itemCount: this.items.length,
-			filteredItemCount: this.#filteredItems.length,
-			selectedIndex: this.#filteredItems.length > 0 ? this.#selectedIndex : -1,
+			itemCount: this.#selection.items.length,
+			filteredItemCount: this.#selection.visibleItems.length,
+			selectedIndex: this.#selection.selectedIndex,
 			selectedItemId: selected?.value ?? null,
 			selectedItemLabel: selected?.label ?? null,
-			filterText: this.#filterQuery,
+			filterText: this.#selection.query,
+			pendingItemId: this.#selection.pendingKey ?? null,
 			maxVisible: this.#maxVisible,
 		};
 	}
@@ -139,8 +197,22 @@ export class SelectList implements Component, MouseRoutable {
 		this.#setFilter(filter, true);
 	}
 
+	/** Replace controlled items while retaining the selected value when possible. */
+	setItems(items: readonly SelectItem[]): void {
+		if (this.#selection.setItems(items)) this.#notifySelectionChange();
+	}
+
 	setSelectedIndex(index: number): void {
-		this.#selectedIndex = Math.max(0, Math.min(index, this.#filteredItems.length - 1));
+		this.#selection.setSelectedIndex(index);
+	}
+
+	/** Select a visible item by its stable value. */
+	setSelectedValue(value: string): void {
+		this.#selection.setSelectedKey(value);
+	}
+
+	getFilter(): string {
+		return this.#selection.query;
 	}
 
 	/** Resolve a 0-based rendered-line index to a filtered-item index. */
@@ -155,22 +227,15 @@ export class SelectList implements Component, MouseRoutable {
 
 	/** 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();
+		if (this.#selection.move(delta)) this.#notifySelectionChange();
 	}
 
-	/** Mouse click: select the item under the pointer and confirm it. */
+	/** Mouse click: select the item under the pointer and request activation. */
 	clickItem(index: number): void {
-		const item = this.#filteredItems[index];
-		if (!item) return;
-		if (index !== this.#selectedIndex) {
-			this.#selectedIndex = index;
-			this.#notifySelectionChange();
-		}
-		this.onSelect?.(item);
+		const item = this.#selection.visibleItems[index];
+		if (!item || item.disabled) return;
+		if (this.#selection.setSelectedIndex(index)) this.#notifySelectionChange();
+		this.#activateSelected();
 	}
 
 	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
@@ -184,14 +249,18 @@ export class SelectList implements Component, MouseRoutable {
 	render(width: number): readonly string[] {
 		const lines: string[] = [];
 		this.#hitRows = [];
-		const showSearchStatus = this.#shouldRenderSearchStatus();
+		let showSearchStatus = this.#shouldRenderSearchStatus();
 
-		// If no items match filter, show message
-		if (this.#filteredItems.length === 0) {
+		// If no items match filter, distinguish an empty data set from no search matches.
+		if (this.#selection.visibleItems.length === 0) {
 			if (showSearchStatus) {
 				lines.push(this.#renderStatusLine(width));
 			}
-			lines.push(this.theme.noMatch("  No matching items"));
+			const message =
+				this.#selection.query.trim().length > 0
+					? (this.layout.noMatchText ?? "No matching items")
+					: (this.layout.emptyText ?? "No items");
+			lines.push(this.theme.noMatch(`  ${message}`));
 			return lines;
 		}
 
@@ -204,31 +273,35 @@ export class SelectList implements Component, MouseRoutable {
 
 		// 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.
+		// every count is 1, so total visual rows equal the visible item count.
 		const conservativeRowWidth = Math.max(0, width - 1);
 		// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
-		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];
+		const rowCounts = new Array<number>(this.#selection.visibleItems.length);
+		for (let i = 0; i < this.#selection.visibleItems.length; i++) {
+			const item = this.#selection.visibleItems[i];
 			if (!item) {
 				rowCounts[i] = 0;
 				continue;
 			}
-			rowCounts[i] = wrapEnabled
-				? this.#computeItemRowCount(item, conservativeRowWidth, primaryColumnWidth, iconColumnWidth)
-				: 1;
-			visualTotal += rowCounts[i];
+			const context = this.#renderContext(item, i, conservativeRowWidth);
+			rowCounts[i] = this.layout.measureItem
+				? Math.max(1, Math.trunc(this.layout.measureItem(context)))
+				: this.layout.renderItem
+					? Math.max(1, this.layout.renderItem(context).length)
+					: wrapEnabled
+						? this.#computeItemRowCount(item, conservativeRowWidth, primaryColumnWidth, iconColumnWidth)
+						: 1;
 		}
 
-		const overflow = visualTotal > visualBudget;
+		const window = getMenuWindow(rowCounts, this.#selection.selectedIndex, visualBudget);
+		const overflow = window.totalRows > visualBudget;
+		showSearchStatus = this.#shouldRenderSearchStatus();
 		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);
+		const { startIndex, endIndex, rowOffset } = window;
 
 		// 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
@@ -236,30 +309,36 @@ export class SelectList implements Component, MouseRoutable {
 		// scrollbar carries the offscreen rows.
 		const rows: string[] = [];
 		for (let i = startIndex; i < endIndex && rows.length < visualBudget; i++) {
-			const item = this.#filteredItems[i];
+			const item = this.#selection.visibleItems[i];
 			if (!item) continue;
-			const hovered = this.theme.hovered !== undefined && i === this.#hoveredIndex && i !== this.#selectedIndex;
-			const itemRows = this.#renderItem(
-				item,
-				i === this.#selectedIndex,
-				rowWidth,
-				primaryColumnWidth,
-				iconColumnWidth,
-			);
+			const isSelected = i === this.#selection.selectedIndex;
+			const hovered = i === this.#hoveredIndex && !isSelected;
+			const context = this.#renderContext(item, i, rowWidth);
+			const itemRows = this.layout.renderItem
+				? [...this.layout.renderItem(context)]
+				: this.#renderItem(item, isSelected, rowWidth, primaryColumnWidth, iconColumnWidth);
 			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 styled =
+					this.layout.renderItem !== undefined
+						? row
+						: item.disabled
+							? this.theme.description(row)
+							: hovered && this.theme.hovered
+								? this.theme.hovered(row)
+								: row;
+				rows.push(styled);
 			}
 		}
 
 		const sv = new ScrollView(rows, {
 			height: rows.length,
 			scrollbar: "auto",
-			totalRows: visualTotal,
+			totalRows: window.totalRows,
 			theme: { track: t => this.theme.scrollInfo(t), thumb: t => this.theme.selectedPrefix(t) },
 		});
-		sv.setScrollOffset(visualOffset);
+		sv.setScrollOffset(rowOffset);
 		lines.push(...sv.render(width));
 
 		// Add search status when relevant (scrollbar now indicates overflow)
@@ -272,46 +351,31 @@ export class SelectList implements Component, MouseRoutable {
 
 	handleInput(keyData: string): void {
 		const kb = getKeybindings();
-		// Escape or Ctrl+C
 		if (kb.matches(keyData, "tui.select.cancel")) {
-			if (this.onCancel) {
-				this.onCancel();
-			}
+			if (!this.#selection.cancelConfirmation()) this.onCancel?.();
 			return;
 		}
 
-		if (this.#handleSearchInput(keyData)) {
-			return;
-		}
+		if (this.#handleSearchInput(keyData)) return;
+		if (this.#selection.visibleItems.length === 0) return;
 
-		if (this.#filteredItems.length === 0) return;
-		// Up arrow - wrap to bottom when at top
+		let selectionChanged = false;
 		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);
-			}
+			selectionChanged = this.#selection.move(-1, this.layout.wrapNavigation !== false);
+		} else if (kb.matches(keyData, "tui.select.down")) {
+			selectionChanged = this.#selection.move(1, this.layout.wrapNavigation !== false);
+		} else if (kb.matches(keyData, "tui.select.pageUp")) {
+			selectionChanged = this.#selection.move(-this.#maxVisible);
+		} else if (kb.matches(keyData, "tui.select.pageDown")) {
+			selectionChanged = this.#selection.move(this.#maxVisible);
+		} else if (matchesKey(keyData, "home")) {
+			selectionChanged = this.#selection.moveToBoundary("first");
+		} else if (matchesKey(keyData, "end")) {
+			selectionChanged = this.#selection.moveToBoundary("last");
+		} else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n") {
+			this.#activateSelected();
 		}
+		if (selectionChanged) this.#notifySelectionChange();
 	}
 
 	#renderItem(
@@ -378,54 +442,6 @@ export class SelectList implements Component, MouseRoutable {
 		return kept;
 	}
 
-	/**
-	 * 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,
@@ -440,7 +456,7 @@ export class SelectList implements Component, MouseRoutable {
 		const iconWidth = item.icon ? visibleWidth(item.icon) : 0;
 		const iconCell = iconColumnWidth > 0 ? (item.icon ?? "") + padding(iconColumnWidth - iconWidth + 1) : "";
 		const prefixWidth = visibleWidth(prefix) + (iconColumnWidth > 0 ? iconColumnWidth + 1 : 0);
-		const descriptionSingleLine = item.description ? sanitizeSingleLine(item.description) : undefined;
+		const descriptionSingleLine = this.#sanitizedDescription(item);
 
 		if (descriptionSingleLine && width > 40) {
 			const effectivePrimaryColumnWidth = Math.max(1, Math.min(primaryColumnWidth, width - prefixWidth - 4));
@@ -478,7 +494,7 @@ export class SelectList implements Component, MouseRoutable {
 
 	#getIconColumnWidth(): number {
 		let widest = 0;
-		for (const item of this.#filteredItems) {
+		for (const item of this.#selection.visibleItems) {
 			if (item.icon) widest = Math.max(widest, visibleWidth(item.icon));
 		}
 		return widest;
@@ -486,7 +502,7 @@ export class SelectList implements Component, MouseRoutable {
 
 	#getPrimaryColumnWidth(): number {
 		const { min, max } = this.#getPrimaryColumnBounds();
-		const widestPrimary = this.#filteredItems.reduce((widest, item) => {
+		const widestPrimary = this.#selection.visibleItems.reduce((widest, item) => {
 			return Math.max(widest, visibleWidth(this.#getDisplayValue(item)) + PRIMARY_COLUMN_GAP);
 		}, 0);
 
@@ -521,23 +537,72 @@ export class SelectList implements Component, MouseRoutable {
 	}
 
 	#getDisplayValue(item: SelectItem): string {
-		return sanitizeSingleLine(item.label || item.value);
+		return this.#sanitizedLabel(item);
+	}
+
+	#sanitizedLabel(item: SelectItem): string {
+		return this.#sanitizedEntry(item).label;
+	}
+
+	#sanitizedDescription(item: SelectItem): string | undefined {
+		return this.#sanitizedEntry(item).description;
+	}
+
+	#sanitizedEntry(item: SelectItem): { label: string; description: string | undefined } {
+		const sourceLabel = item.label || item.value;
+		const sourceDescription = item.description;
+		const cached = this.#sanitized.get(item);
+		if (
+			cached !== undefined &&
+			cached.sourceLabel === sourceLabel &&
+			cached.sourceDescription === sourceDescription
+		) {
+			return cached;
+		}
+		const entry = {
+			sourceLabel,
+			sourceDescription,
+			label: sanitizeSingleLine(sourceLabel),
+			description: sourceDescription ? sanitizeSingleLine(sourceDescription) : undefined,
+		};
+		this.#sanitized.set(item, entry);
+		return entry;
 	}
 
 	#renderStatusLine(width: number): string {
-		const query = sanitizeSingleLine(this.#filterQuery);
-		const statusText = query ? `  Search: ${query}` : "  Type to search";
+		const pendingItem =
+			this.#selection.pendingKey === undefined
+				? undefined
+				: this.#selection.visibleItems.find(item => item.value === this.#selection.pendingKey);
+		const query = sanitizeSingleLine(this.#selection.query);
+		const custom = this.layout.statusText?.({
+			query,
+			selectedIndex: this.#selection.selectedIndex,
+			visibleCount: this.#selection.visibleItems.length,
+			totalCount: this.#selection.items.length,
+			pendingItem,
+		});
+		const statusText =
+			this.layout.statusText !== undefined
+				? (custom ?? "")
+				: (pendingItem?.confirmation ??
+					(query ? `  Search: ${query}` : this.#canEditSearch() ? "  Type to search" : ""));
 		return this.theme.scrollInfo(truncateToWidth(statusText, Math.max(1, width - 2), Ellipsis.Omit));
 	}
 
 	#shouldRenderSearchStatus(): boolean {
+		const policy = this.layout.search ?? (this.layout.overflowSearch === false ? "never" : "overflow");
 		return (
-			this.layout.overflowSearch !== false && (this.items.length > this.#maxVisible || this.#filterQuery.length > 0)
+			this.#selection.pendingKey !== undefined ||
+			this.layout.statusText !== undefined ||
+			(policy !== "never" && this.#selection.query.length > 0) ||
+			(this.#canEditSearch() && this.#selection.items.length > this.#maxVisible)
 		);
 	}
 
 	#canEditSearch(): boolean {
-		return this.layout.overflowSearch !== false && this.items.length > this.#maxVisible;
+		const policy = this.layout.search ?? (this.layout.overflowSearch === false ? "never" : "overflow");
+		return policy === "always" || (policy === "overflow" && this.#selection.items.length > this.#maxVisible);
 	}
 
 	#handleSearchInput(keyData: string): boolean {
@@ -545,8 +610,8 @@ export class SelectList implements Component, MouseRoutable {
 
 		const kb = getKeybindings();
 		if (kb.matches(keyData, "tui.editor.deleteCharBackward")) {
-			if (this.#filterQuery.length === 0) return false;
-			const chars = [...this.#filterQuery];
+			if (this.#selection.query.length === 0) return false;
+			const chars = [...this.#selection.query];
 			chars.pop();
 			this.#setFilter(chars.join(""), true);
 			return true;
@@ -554,30 +619,25 @@ export class SelectList implements Component, MouseRoutable {
 
 		const printableText = extractPrintableText(keyData);
 		if (printableText === undefined) return false;
-		if (this.#filterQuery.length === 0 && printableText.trim().length === 0) return false;
+		if (this.#selection.query.length === 0 && printableText.trim().length === 0) return false;
 
-		this.#setFilter(this.#filterQuery + printableText, true);
+		this.#setFilter(this.#selection.query + printableText, true);
 		return true;
 	}
 
 	#setFilter(filter: string, notify: boolean): void {
-		this.#filterQuery = filter;
+		let changed: boolean;
 		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));
+				changed = this.#selection.setQuery(filter);
 			} finally {
 				popLoopPhase();
 			}
 		} else {
-			this.#filteredItems = this.items;
-		}
-		this.#selectedIndex = 0;
-		if (notify) {
-			this.#notifySelectionChange();
+			changed = this.#selection.setQuery(filter);
 		}
+		if (notify && changed) this.#notifySelectionChange();
 	}
 
 	#getFilterText(item: SelectItem): string {
@@ -588,18 +648,37 @@ export class SelectList implements Component, MouseRoutable {
 		if (item.hint) {
 			text += ` ${item.hint}`;
 		}
+		if (item.searchText) {
+			text += ` ${item.searchText}`;
+		}
 		return sanitizeSingleLine(text);
 	}
 
+	#renderContext(item: SelectItem, index: number, width: number): SelectListRenderItemContext {
+		return {
+			item,
+			index,
+			width,
+			selected: index === this.#selection.selectedIndex,
+			hovered: index === this.#hoveredIndex,
+			pendingConfirmation: this.#selection.isPending(item),
+			theme: this.theme,
+		};
+	}
+
+	#activateSelected(): void {
+		const activation = this.#selection.requestActivation();
+		if (activation.kind === "confirmed") this.onSelect?.(activation.item);
+	}
+
 	#notifySelectionChange(): void {
-		const selectedItem = this.#filteredItems[this.#selectedIndex];
+		const selectedItem = this.#selection.selectedItem;
 		if (selectedItem && this.onSelectionChange) {
 			this.onSelectionChange(selectedItem);
 		}
 	}
 
 	getSelectedItem(): SelectItem | null {
-		const item = this.#filteredItems[this.#selectedIndex];
-		return item || null;
+		return this.#selection.selectedItem ?? null;
 	}
 }