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

package/src/components/settings-list.ts

@@ -5,6 +5,8 @@ import type { MouseRoutable, SgrMouseEvent } from "../mouse";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 import { ScrollView } from "./scroll-view";
+import { FormField, type FormFieldOptions, type FormFieldTheme } from "./form";
+import { MenuSelection } from "./menu-selection";
 
 function sanitizeSingleLine(text: string): string {
 	return replaceTabs(text)
@@ -13,6 +15,10 @@ function sanitizeSingleLine(text: string): string {
 		.trim();
 }
 
+function hasMouseRouter(component: Component): component is Component & MouseRoutable {
+	return "routeMouse" in component && typeof component.routeMouse === "function";
+}
+
 export interface SettingItem {
 	/** Unique identifier for this setting */
 	id: string;
@@ -100,8 +106,9 @@ export function getSettingItemFilterText(item: SettingItem): string {
 }
 
 export class SettingsList implements Component {
-	#items: SettingItem[];
-	#filteredItems: SettingItem[];
+	#items: readonly SettingItem[] = [];
+	#filteredItems: readonly SettingItem[] = [];
+	#selection: MenuSelection<SettingItem>;
 	#theme: SettingsListTheme;
 	#selectedIndex = 0;
 	#maxVisible: number;
@@ -132,14 +139,23 @@ export class SettingsList implements Component {
 		onCancel: () => void,
 		options: SettingsListOptions = {},
 	) {
-		this.#items = items;
-		this.#filteredItems = items;
+		this.#selection = new MenuSelection(items, {
+			getKey: item => item.id,
+			getSearchText: getSettingItemFilterText,
+			isDisabled: item => item.heading === true,
+			filter: (candidates, query) =>
+				fuzzyFilter(
+					candidates.filter(item => !item.heading),
+					query,
+					getSettingItemFilterText,
+				),
+		});
+		this.#syncSelectionState();
 		this.#maxVisible = maxVisible;
 		this.#theme = theme;
 		this.#onChange = onChange;
 		this.#onCancel = onCancel;
 		this.#options = options;
-		this.#selectedIndex = this.#firstSelectableIndex();
 		this.#lastNotifiedSelectionId = this.getSelectedItem()?.id;
 	}
 	/** Return item, selection, filter, and submenu state for debug inspection. */
@@ -170,10 +186,11 @@ export class SettingsList implements Component {
 
 	/** Move selection to the item with `id`. Returns false when it is not visible. */
 	selectItem(id: string): boolean {
-		const index = this.#filteredItems.findIndex(item => !item.heading && item.id === id);
-		if (index === -1) return false;
+		const item = this.#filteredItems.find(candidate => !candidate.heading && candidate.id === id);
+		if (!item) return false;
+		this.#selection.setSelectedKey(id);
 		this.#sectionFocus = false;
-		this.#selectedIndex = index;
+		this.#syncSelectionState();
 		this.#notifySelection();
 		return true;
 	}
@@ -272,7 +289,9 @@ export class SettingsList implements Component {
 	 */
 	routeSubmenuMouse(event: SgrMouseEvent, line: number, col: number): boolean {
 		if (!this.#submenuComponent) return false;
-		(this.#submenuComponent as Component & Partial<MouseRoutable>).routeMouse?.(event, line, col);
+		if (hasMouseRouter(this.#submenuComponent)) {
+			this.#submenuComponent.routeMouse(event, line, col);
+		}
 		return true;
 	}
 
@@ -296,8 +315,8 @@ export class SettingsList implements Component {
 
 		item.currentValue = newValue;
 		if (this.#filterQuery.trim()) {
-			this.#applyFilter();
-			this.#clampSelectedIndex();
+			this.#selection.setItems(this.#items, this.#selection.selectedKey);
+			this.#syncSelectionState();
 		}
 	}
 
@@ -309,65 +328,41 @@ export class SettingsList implements Component {
 	 * done callback, and `#closeSubmenu` re-resolves the restored item on exit.
 	 */
 	setItems(items: SettingItem[]): void {
-		const selectedId = this.#filteredItems[this.#selectedIndex]?.id;
-		this.#items = items;
-		this.#applyFilter();
-		if (this.#sectionFocus && !this.hasSectionFocusTargets()) this.#sectionFocus = false;
-
-		const nextIndex = selectedId ? this.#filteredItems.findIndex(item => item.id === selectedId) : -1;
-		if (nextIndex >= 0) {
-			this.#selectedIndex = nextIndex;
-		} else {
-			this.#clampSelectedIndex();
+		const selectedId = this.#selection.selectedKey;
+		const previousIndex = this.#selection.selectedIndex;
+		this.#selection.setItems(items, selectedId);
+		if (selectedId !== undefined && !this.#selection.visibleItems.some(item => item.id === selectedId)) {
+			this.#selection.setSelectedIndex(Math.min(previousIndex, this.#selection.visibleItems.length - 1));
 		}
+		this.#syncSelectionState();
+		if (this.#sectionFocus && !this.hasSectionFocusTargets()) this.#sectionFocus = false;
 		this.#notifySelection();
 	}
 
 	#setFilter(filter: string): void {
-		this.#filterQuery = filter;
 		if (filter.trim()) this.#sectionFocus = false;
-		this.#applyFilter();
-		this.#selectedIndex = this.#firstSelectableIndex();
+		this.#selection.setQuery(filter, false);
+		this.#syncSelectionState();
 		this.#notifySelection();
 	}
 
-	#applyFilter(): void {
-		this.#filteredItems = this.#filterQuery.trim()
-			? fuzzyFilter(
-					this.#items.filter(item => !item.heading),
-					this.#filterQuery,
-					getSettingItemFilterText,
-				)
-			: this.#items;
+	/** Move selection by one selectable item, wrapping or clamping, and skipping headings. */
+	#moveSelection(delta: -1 | 1, wrap = true): void {
+		if (!this.#selection.move(delta, wrap)) return;
+		this.#syncSelectionState();
+		this.#notifySelection();
 	}
 
-	#firstSelectableIndex(): number {
-		const index = this.#filteredItems.findIndex(item => !item.heading);
-		return index >= 0 ? index : 0;
+	#syncSelectionState(): void {
+		this.#items = this.#selection.items;
+		this.#filteredItems = this.#selection.visibleItems;
+		this.#filterQuery = this.#selection.query;
+		this.#selectedIndex = Math.max(0, this.#selection.selectedIndex);
 	}
 
-	/** Move selection by one selectable item, wrapping or clamping, and skipping headings. */
-	#moveSelection(delta: -1 | 1, wrap = true): void {
-		const len = this.#filteredItems.length;
-		if (len === 0) return;
-		let index = this.#selectedIndex;
-		for (let step = 0; step < len * 2; step++) {
-			const next = index + delta;
-			if (next < 0 || next >= len) {
-				if (wrap) {
-					index = (next + len) % len;
-				} else {
-					return;
-				}
-			} else {
-				index = next;
-			}
-			if (!this.#filteredItems[index]?.heading) {
-				this.#selectedIndex = index;
-				this.#notifySelection();
-				return;
-			}
-		}
+	#setSelectedIndex(index: number): void {
+		this.#selection.setSelectedIndex(index);
+		this.#syncSelectionState();
 	}
 
 	/** Sections derived from heading rows in the filtered list. */
@@ -404,35 +399,17 @@ export class SettingsList implements Component {
 		if (sections.length < 2) {
 			const len = this.#filteredItems.length;
 			if (len === 0) return;
-			this.#selectedIndex = Math.max(0, Math.min(this.#selectedIndex + delta * this.#maxVisible, len - 1));
-			this.#clampSelectedIndex();
+			const index = Math.max(0, Math.min(this.#selectedIndex + delta * this.#maxVisible, len - 1));
+			this.#setSelectedIndex(index);
 		} else {
 			const next = (this.#activeSectionIndex(sections) + delta + sections.length) % sections.length;
-			this.#selectedIndex = sections[next].firstItemIndex;
+			this.#setSelectedIndex(sections[next].firstItemIndex);
 		}
 		this.#notifySelection();
 	}
 
 	#clampSelectedIndex(): void {
-		if (this.#filteredItems.length === 0) {
-			this.#selectedIndex = 0;
-			return;
-		}
-		this.#selectedIndex = Math.max(0, Math.min(this.#selectedIndex, this.#filteredItems.length - 1));
-		if (!this.#filteredItems[this.#selectedIndex]?.heading) return;
-		// Landed on a heading: prefer the next selectable item, else the previous one.
-		for (let i = this.#selectedIndex + 1; i < this.#filteredItems.length; i++) {
-			if (!this.#filteredItems[i].heading) {
-				this.#selectedIndex = i;
-				return;
-			}
-		}
-		for (let i = this.#selectedIndex - 1; i >= 0; i--) {
-			if (!this.#filteredItems[i].heading) {
-				this.#selectedIndex = i;
-				return;
-			}
-		}
+		this.#setSelectedIndex(this.#selectedIndex);
 	}
 
 	#renderSearchStatus(width: number): string {
@@ -834,7 +811,7 @@ export class SettingsList implements Component {
 			const index = this.#filteredItems.findIndex(item => !item.heading && item.id === this.#submenuItemId);
 			this.#submenuItemId = null;
 			if (index >= 0) {
-				this.#selectedIndex = index;
+				this.#setSelectedIndex(index);
 			} else {
 				this.#clampSelectedIndex();
 			}
@@ -842,3 +819,49 @@ export class SettingsList implements Component {
 		}
 	}
 }
+
+/** Construction options for a SettingsList composed as a form field. */
+export interface SettingsFormFieldOptions extends Omit<FormFieldOptions, "theme"> {
+	items: SettingItem[];
+	maxVisible: number;
+	settingsTheme: SettingsListTheme;
+	fieldTheme: FormFieldTheme;
+	onChange(id: string, newValue: string): void;
+	onCancel(): void;
+	listOptions?: SettingsListOptions;
+}
+
+/**
+ * SettingsList adapter for detail forms. It retains the canonical list
+ * implementation while sharing FormField label, description, hint, focus, and
+ * input dispatch with text and selection fields.
+ */
+export class SettingsFormField extends FormField {
+	readonly settingsList: SettingsList;
+
+	constructor(options: SettingsFormFieldOptions) {
+		const settingsList = new SettingsList(
+			options.items,
+			options.maxVisible,
+			options.settingsTheme,
+			options.onChange,
+			options.onCancel,
+			options.listOptions,
+		);
+		super(settingsList, {
+			theme: options.fieldTheme,
+			label: options.label,
+			description: options.description,
+			details: options.details,
+			previewLabel: options.previewLabel,
+			preview: options.preview,
+			hint: options.hint,
+			summary: options.summary,
+			footer: options.footer,
+			leadingSpace: options.leadingSpace,
+			spaceBeforeControl: options.spaceBeforeControl,
+			spaceAfterControl: options.spaceAfterControl,
+		});
+		this.settingsList = settingsList;
+	}
+}

package/src/components/table.ts

@@ -0,0 +1,127 @@
+import type { Component } from "../tui";
+import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+
+/** One table cell. Styling is applied after alignment so padding shares the cell style. */
+export interface TableCell {
+	readonly text: string;
+	readonly style?: (text: string) => string;
+}
+
+/** Explicit sizing and overflow policy for a table column. */
+export interface TableColumn {
+	readonly width: number;
+	readonly minWidth?: number;
+	readonly align: "left" | "right";
+	readonly overflow: "allow" | "truncate";
+	/** Lower-priority columns shrink before higher-priority columns. */
+	readonly priority?: number;
+	readonly style?: (text: string) => string;
+}
+
+/** Row-layout options shared by table functions and the component. */
+export interface TableOptions {
+	readonly gap?: string;
+	readonly indent?: string;
+	readonly fit?: boolean;
+}
+
+function finiteWidth(width: number, fallback = 0): number {
+	return Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : fallback;
+}
+
+function singleLine(text: string): string {
+	return replaceTabs(text).replace(/[\r\n]+/g, " ");
+}
+
+function fitWidths(columns: readonly TableColumn[], maxWidth: number, gapWidth: number): number[] {
+	const widths = columns.map(column => finiteWidth(column.width));
+	let overflow = widths.reduce((sum, width) => sum + width, 0) + Math.max(0, columns.length - 1) * gapWidth - maxWidth;
+	if (overflow <= 0) return widths;
+
+	const order = columns
+		.map((column, index) => ({ index, priority: column.priority ?? 0 }))
+		.sort((a, b) => a.priority - b.priority || b.index - a.index);
+	for (const { index } of order) {
+		if (overflow <= 0) break;
+		const column = columns[index]!;
+		if (column.overflow !== "truncate") continue;
+		const minimum = Math.min(widths[index]!, finiteWidth(column.minWidth ?? 1));
+		const shrink = Math.min(overflow, widths[index]! - minimum);
+		widths[index] = widths[index]! - shrink;
+		overflow -= shrink;
+	}
+	return widths;
+}
+
+function alignCell(cell: TableCell, column: TableColumn, width: number): string {
+	const text = singleLine(cell.text);
+	const visible = visibleWidth(text);
+	const fitted = visible > width && column.overflow === "truncate" ? truncateToWidth(text, width) : text;
+	const fittedWidth = visibleWidth(fitted);
+	const padding = " ".repeat(Math.max(0, width - fittedWidth));
+	const aligned = column.align === "right" ? `${padding}${fitted}` : `${fitted}${padding}`;
+	const style = cell.style ?? column.style;
+	return style ? style(aligned) : aligned;
+}
+
+/** Render one ANSI-aware fixed-column row. */
+export function renderTableRow(
+	cells: readonly TableCell[],
+	columns: readonly TableColumn[],
+	maxWidth?: number,
+	options: TableOptions = {},
+): string {
+	const count = Math.min(cells.length, columns.length);
+	const indent = singleLine(options.indent ?? "");
+	if (count === 0) return indent;
+	const activeColumns = columns.slice(0, count);
+	const gap = singleLine(options.gap ?? " ");
+	const widthBudget = maxWidth === undefined ? Number.MAX_SAFE_INTEGER : finiteWidth(maxWidth);
+	const contentBudget = Math.max(0, widthBudget - visibleWidth(indent));
+	const widths =
+		options.fit === false
+			? activeColumns.map(column => finiteWidth(column.width))
+			: fitWidths(activeColumns, contentBudget, visibleWidth(gap));
+	const rendered = cells.slice(0, count).map((cell, index) => alignCell(cell, activeColumns[index]!, widths[index]!));
+	return `${indent}${rendered.join(gap)}`;
+}
+
+/** Bounded table component for structured rows with replaceable data and stable unchanged-render arrays. */
+export class Table implements Component {
+	#rows: readonly (readonly TableCell[])[];
+	readonly #columns: readonly TableColumn[];
+	readonly #options: TableOptions;
+	#cache: { width: number; epoch: number; lines: readonly string[] } | undefined;
+
+	constructor(rows: readonly (readonly TableCell[])[], columns: readonly TableColumn[], options: TableOptions = {}) {
+		this.#rows = rows;
+		this.#columns = columns;
+		this.#options = options;
+	}
+
+	setRows(rows: readonly (readonly TableCell[])[]): boolean {
+		if (this.#rows === rows) return false;
+		this.#rows = rows;
+		this.#cache = undefined;
+		return true;
+	}
+
+	invalidate(): void {
+		this.#cache = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		const renderWidth = finiteWidth(width);
+		const epoch = getWidthConfigEpoch();
+		if (this.#cache?.width === renderWidth && this.#cache.epoch === epoch) return this.#cache.lines;
+		const lines = this.#rows.map(row =>
+			truncateToWidth(
+				singleLine(renderTableRow(row, this.#columns, renderWidth, this.#options)),
+				renderWidth,
+				Ellipsis.Omit,
+			),
+		);
+		this.#cache = { width: renderWidth, epoch, lines };
+		return lines;
+	}
+}