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

package/src/components/menu-selection.ts

@@ -0,0 +1,248 @@
+import { fuzzyFilter } from "../fuzzy";
+
+/** Describes how a menu identifies, searches, disables, and confirms its items. */
+export interface MenuSelectionAdapter<T> {
+	/** Stable identity used to retain selection while data or filtering changes. */
+	getKey: (item: T) => string;
+	/** Searchable text used by the default fuzzy filter. */
+	getSearchText: (item: T) => string;
+	/** Disabled items remain visible but are skipped by navigation and cannot activate. */
+	isDisabled?: (item: T) => boolean;
+	/** Items returning true require two activation requests without an intervening state change. */
+	requiresConfirmation?: (item: T) => boolean;
+	/** Optional domain-specific filtering/ranking. */
+	filter?: (items: readonly T[], query: string) => readonly T[];
+}
+
+/** Result of requesting activation of the current menu item. */
+export type MenuActivation<T> =
+	| { kind: "empty" }
+	| { kind: "disabled"; item: T }
+	| { kind: "pending"; item: T }
+	| { kind: "confirmed"; item: T };
+
+/** A viewport over variable-height items. */
+export interface MenuWindow {
+	startIndex: number;
+	endIndex: number;
+	/** Number of visual rows before startIndex, for scrollbar positioning. */
+	rowOffset: number;
+	/** Total visual rows across every item. */
+	totalRows: number;
+}
+
+/**
+ * Pick a selection-centered, contiguous window whose visual rows fit `rowBudget`.
+ * A selected item taller than the budget is retained and clipped by the renderer.
+ */
+export function getMenuWindow(rowCounts: readonly number[], selectedIndex: number, rowBudget: number): MenuWindow {
+	let totalRows = 0;
+	for (const count of rowCounts) totalRows += Math.max(0, count);
+	if (rowCounts.length === 0) return { startIndex: 0, endIndex: 0, rowOffset: 0, totalRows };
+
+	const budget = Math.max(1, Math.trunc(rowBudget));
+	const selected = Math.max(0, Math.min(Math.trunc(selectedIndex), rowCounts.length - 1));
+	const selectedRows = Math.max(0, rowCounts[selected] ?? 0);
+	const targetRowsBeforeSelection = Math.floor(Math.max(0, budget - Math.min(selectedRows, budget)) / 2);
+	let startIndex = selected;
+	let rowsBeforeSelection = 0;
+	while (startIndex > 0) {
+		const cost = Math.max(0, rowCounts[startIndex - 1] ?? 0);
+		if (rowsBeforeSelection + cost > targetRowsBeforeSelection) break;
+		startIndex--;
+		rowsBeforeSelection += cost;
+	}
+
+	let endIndex = selected + 1;
+	let used = rowsBeforeSelection + selectedRows;
+	while (endIndex < rowCounts.length) {
+		const cost = Math.max(0, rowCounts[endIndex] ?? 0);
+		if (used + cost > budget) break;
+		used += cost;
+		endIndex++;
+	}
+	while (startIndex > 0) {
+		const cost = Math.max(0, rowCounts[startIndex - 1] ?? 0);
+		if (used + cost > budget) break;
+		startIndex--;
+		used += cost;
+	}
+
+	let rowOffset = 0;
+	for (let index = 0; index < startIndex; index++) rowOffset += Math.max(0, rowCounts[index] ?? 0);
+	return { startIndex, endIndex, rowOffset, totalRows };
+}
+
+/**
+ * Controlled menu data, filtering, selection, disabled-row navigation, and
+ * confirmation state. Renderers remain domain-owned and consume `visibleItems`.
+ */
+export class MenuSelection<T> {
+	#items: readonly T[];
+	#visibleItems: readonly T[];
+	#query = "";
+	#selectedIndex = -1;
+	#pendingKey: string | undefined;
+
+	constructor(
+		items: readonly T[],
+		readonly adapter: MenuSelectionAdapter<T>,
+		initialKey?: string,
+	) {
+		this.#items = items;
+		this.#visibleItems = items;
+		this.#selectedIndex = this.#findInitialIndex(initialKey);
+	}
+
+	get items(): readonly T[] {
+		return this.#items;
+	}
+
+	get visibleItems(): readonly T[] {
+		return this.#visibleItems;
+	}
+
+	get query(): string {
+		return this.#query;
+	}
+
+	get selectedIndex(): number {
+		return this.#selectedIndex;
+	}
+
+	get selectedItem(): T | undefined {
+		return this.#visibleItems[this.#selectedIndex];
+	}
+
+	get selectedKey(): string | undefined {
+		const item = this.selectedItem;
+		return item === undefined ? undefined : this.adapter.getKey(item);
+	}
+
+	get pendingKey(): string | undefined {
+		return this.#pendingKey;
+	}
+
+	isDisabled(item: T): boolean {
+		return this.adapter.isDisabled?.(item) ?? false;
+	}
+
+	isPending(item: T): boolean {
+		return this.#pendingKey === this.adapter.getKey(item);
+	}
+
+	/** Replace controlled data, retaining the selected key when it remains visible. */
+	setItems(items: readonly T[], selectedKey = this.selectedKey): boolean {
+		const previousKey = this.selectedKey;
+		this.#items = items;
+		this.#applyFilter(selectedKey);
+		this.#pendingKey = undefined;
+		return previousKey !== this.selectedKey;
+	}
+
+	/** Set the query and retain the selected key when it survives filtering. */
+	setQuery(query: string, retainSelection = true): boolean {
+		if (query === this.#query) return false;
+		const previousKey = this.selectedKey;
+		this.#query = query;
+		this.#pendingKey = undefined;
+		this.#applyFilter(retainSelection ? previousKey : undefined);
+		return previousKey !== this.selectedKey;
+	}
+
+	/** Select a visible row, coercing disabled rows to the nearest enabled row. */
+	setSelectedIndex(index: number, direction: -1 | 1 = 1): boolean {
+		const next = this.#coerceIndex(index, direction);
+		if (next === this.#selectedIndex) return false;
+		this.#selectedIndex = next;
+		this.#pendingKey = undefined;
+		return true;
+	}
+
+	setSelectedKey(key: string): boolean {
+		const index = this.#visibleItems.findIndex(item => this.adapter.getKey(item) === key);
+		return index >= 0 ? this.setSelectedIndex(index) : false;
+	}
+
+	/** Move by item count, optionally wrapping at list edges. */
+	move(delta: number, wrap = false): boolean {
+		const total = this.#visibleItems.length;
+		if (total === 0 || delta === 0) return false;
+		const direction: -1 | 1 = delta < 0 ? -1 : 1;
+		let remaining = Math.max(1, Math.abs(Math.trunc(delta)));
+		let index = this.#selectedIndex;
+		for (let attempts = 0; attempts < total && remaining > 0; attempts++) {
+			let next = index + direction;
+			if (next < 0 || next >= total) {
+				if (!wrap) break;
+				next = direction > 0 ? 0 : total - 1;
+			}
+			if (next === index) break;
+			index = next;
+			const item = this.#visibleItems[index];
+			if (item !== undefined && !this.isDisabled(item)) remaining--;
+		}
+		return index !== this.#selectedIndex && this.setSelectedIndex(index, direction);
+	}
+
+	moveToBoundary(boundary: "first" | "last"): boolean {
+		return this.setSelectedIndex(
+			boundary === "first" ? 0 : this.#visibleItems.length - 1,
+			boundary === "first" ? 1 : -1,
+		);
+	}
+
+	/** Clear a pending confirmation. Returns true only when one was cleared. */
+	cancelConfirmation(): boolean {
+		if (this.#pendingKey === undefined) return false;
+		this.#pendingKey = undefined;
+		return true;
+	}
+
+	requestActivation(index = this.#selectedIndex): MenuActivation<T> {
+		const item = this.#visibleItems[index];
+		if (item === undefined) return { kind: "empty" };
+		if (this.isDisabled(item)) return { kind: "disabled", item };
+		const key = this.adapter.getKey(item);
+		if (this.adapter.requiresConfirmation?.(item) === true && this.#pendingKey !== key) {
+			this.#pendingKey = key;
+			return { kind: "pending", item };
+		}
+		this.#pendingKey = undefined;
+		return { kind: "confirmed", item };
+	}
+
+	#applyFilter(preferredKey: string | undefined): void {
+		const query = this.#query.trim();
+		this.#visibleItems = query
+			? (this.adapter.filter?.(this.#items, query) ??
+				fuzzyFilter([...this.#items], query, item => this.adapter.getSearchText(item)))
+			: this.#items;
+		this.#selectedIndex = this.#findInitialIndex(preferredKey);
+	}
+
+	#findInitialIndex(preferredKey: string | undefined): number {
+		if (this.#visibleItems.length === 0) return -1;
+		if (preferredKey !== undefined) {
+			const preferred = this.#visibleItems.findIndex(item => this.adapter.getKey(item) === preferredKey);
+			if (preferred >= 0 && !this.isDisabled(this.#visibleItems[preferred]!)) return preferred;
+		}
+		return this.#coerceIndex(0, 1);
+	}
+
+	#coerceIndex(index: number, direction: -1 | 1): number {
+		if (this.#visibleItems.length === 0) return -1;
+		const clamped = Math.max(0, Math.min(Math.trunc(index), this.#visibleItems.length - 1));
+		const candidate = this.#visibleItems[clamped];
+		if (candidate !== undefined && !this.isDisabled(candidate)) return clamped;
+		for (let next = clamped + direction; next >= 0 && next < this.#visibleItems.length; next += direction) {
+			const item = this.#visibleItems[next];
+			if (item !== undefined && !this.isDisabled(item)) return next;
+		}
+		for (let next = clamped - direction; next >= 0 && next < this.#visibleItems.length; next -= direction) {
+			const item = this.#visibleItems[next];
+			if (item !== undefined && !this.isDisabled(item)) return next;
+		}
+		return clamped;
+	}
+}

package/src/components/metric.ts

@@ -0,0 +1,132 @@
+import type { Component } from "../tui";
+import { Ellipsis, getWidthConfigEpoch, truncateToWidth, visibleWidth } from "../utils";
+import { Text } from "./text";
+
+/** One preformatted metric. Domain-specific number, cost, and quota policy stays with the caller. */
+export interface MetricSpec {
+	/** Undefined omits the metric; an empty string and zero-like strings remain observable values. */
+	readonly value: string | undefined;
+	/** Optional icon or label placed before the value. */
+	readonly leading?: string;
+	/** Separator between `leading` and `value`. */
+	readonly separator?: string;
+	/** Higher-priority metrics survive first when a row uses `drop` overflow. */
+	readonly priority?: number;
+	/** Render-time styling for the complete metric. */
+	readonly style?: (text: string) => string;
+}
+
+/** Width behavior for an inline metric row. */
+export type MetricOverflow = "allow" | "drop" | "truncate" | "wrap";
+
+/** Presentation options shared by {@link formatMetricRow} and {@link MetricRow}. */
+export interface MetricRowOptions {
+	readonly separator?: string;
+	readonly overflow?: MetricOverflow;
+	readonly maxWidth?: number;
+	readonly paddingX?: number;
+	readonly paddingY?: number;
+	readonly style?: (text: string) => string;
+}
+
+/** Format one metric without imposing domain-specific value policy. */
+export function formatMetric(metric: MetricSpec): string | undefined {
+	if (metric.value === undefined) return undefined;
+	const text =
+		metric.leading !== undefined ? `${metric.leading}${metric.separator ?? " "}${metric.value}` : metric.value;
+	return metric.style ? metric.style(text) : text;
+}
+
+/**
+ * Join metrics in declaration order. `drop` removes the lowest-priority metric
+ * first (rightmost on ties); `truncate` clips the complete row. `wrap` is
+ * applied by {@link MetricRow}, where the component owns the available width.
+ */
+export function formatMetricRow(metrics: readonly MetricSpec[], options: MetricRowOptions = {}): string {
+	const separator = options.separator ?? " ";
+	const entries = metrics.flatMap((metric, index) => {
+		const text = formatMetric(metric);
+		return text === undefined ? [] : [{ text, index, priority: metric.priority ?? 0 }];
+	});
+	if (entries.length === 0) return "";
+
+	const maxWidth = options.maxWidth;
+	const overflow = options.overflow ?? "allow";
+	const join = (): string => entries.map(entry => entry.text).join(separator);
+	if (maxWidth === undefined || overflow === "allow" || overflow === "wrap") return join();
+
+	if (overflow === "truncate") {
+		return truncateToWidth(join(), Math.max(0, maxWidth));
+	}
+
+	while (entries.length > 1 && visibleWidth(join()) > maxWidth) {
+		let dropIndex = 0;
+		for (let i = 1; i < entries.length; i += 1) {
+			const candidate = entries[i]!;
+			const current = entries[dropIndex]!;
+			if (
+				candidate.priority < current.priority ||
+				(candidate.priority === current.priority && candidate.index > current.index)
+			) {
+				dropIndex = i;
+			}
+		}
+		entries.splice(dropIndex, 1);
+	}
+	return join();
+}
+
+/**
+ * Component form of an inline metric row. It delegates ANSI-aware wrapping,
+ * padding, theme invalidation, and stable unchanged-render arrays to {@link Text}.
+ */
+export class MetricRow implements Component {
+	#metrics: readonly MetricSpec[];
+	readonly #options: MetricRowOptions;
+	readonly #text: Text;
+	#cache: { width: number; epoch: number; source: readonly string[]; lines: readonly string[] } | undefined;
+
+	constructor(metrics: readonly MetricSpec[], options: MetricRowOptions = {}) {
+		this.#metrics = metrics;
+		this.#options = options;
+		this.#text = new Text("", options.paddingX ?? 0, options.paddingY ?? 0).setStyleFn(options.style);
+	}
+
+	setMetrics(metrics: readonly MetricSpec[]): boolean {
+		if (this.#metrics === metrics) return false;
+		this.#metrics = metrics;
+		this.#cache = undefined;
+		return true;
+	}
+
+	invalidate(): void {
+		this.#text.invalidate();
+		this.#cache = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		const renderWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+		const paddingX =
+			this.#options.paddingX !== undefined && Number.isFinite(this.#options.paddingX)
+				? Math.max(0, Math.trunc(this.#options.paddingX))
+				: 0;
+		const maxWidth = Math.max(0, renderWidth - paddingX * 2);
+		this.#text.setText(
+			formatMetricRow(this.#metrics, {
+				...this.#options,
+				maxWidth,
+				overflow: this.#options.overflow === "wrap" ? "allow" : this.#options.overflow,
+			}),
+		);
+		const source = this.#text.render(renderWidth);
+		const epoch = getWidthConfigEpoch();
+		if (this.#cache?.width === renderWidth && this.#cache.epoch === epoch && this.#cache.source === source) {
+			return this.#cache.lines;
+		}
+		const lines = source.every(line => visibleWidth(line) <= renderWidth)
+			? source
+			: source.map(line => truncateToWidth(line, renderWidth, Ellipsis.Omit));
+		this.#cache = { width: renderWidth, epoch, source, lines };
+		return lines;
+	}
+}

package/src/components/progress-bar.ts

@@ -0,0 +1,140 @@
+import type { Component } from "../tui";
+import { Ellipsis, getWidthConfigEpoch, truncateToWidth, visibleWidth } from "../utils";
+
+/** Explicit glyph and styling policy for a progress bar. */
+export interface ProgressBarStyle {
+	readonly filled: string;
+	readonly empty: string;
+	readonly indeterminate?: string;
+	readonly styleFilled?: (text: string) => string;
+	readonly styleEmpty?: (text: string) => string;
+	readonly styleIndeterminate?: (text: string) => string;
+	readonly styleBar?: (text: string) => string;
+}
+
+/** Layout and labeling policy for a progress bar. */
+export interface ProgressBarOptions {
+	readonly min?: number;
+	readonly max?: number;
+	readonly minWidth?: number;
+	readonly maxWidth?: number;
+	readonly prefix?: string;
+	readonly suffix?: string;
+	readonly showPercentage?: boolean;
+	readonly percentageSeparator?: string;
+	readonly formatPercentage?: (fraction: number) => string;
+	readonly style: ProgressBarStyle;
+}
+
+function finiteWidth(width: number, fallback: number): number {
+	return Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : fallback;
+}
+
+function boundedWidth(width: number, options: ProgressBarOptions): number {
+	const minWidth = finiteWidth(options.minWidth ?? 0, 0);
+	const maxWidth = Math.max(
+		minWidth,
+		finiteWidth(options.maxWidth ?? Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER),
+	);
+	return Math.max(minWidth, Math.min(maxWidth, finiteWidth(width, 0)));
+}
+
+function fillCells(glyph: string, width: number): string {
+	const cleanGlyph = glyph.replace(/[\t\r\n]/g, " ");
+	const glyphWidth = visibleWidth(cleanGlyph);
+	if (glyphWidth <= 0) return " ".repeat(width);
+	const count = Math.floor(width / glyphWidth);
+	return `${cleanGlyph.repeat(count)}${" ".repeat(width - count * glyphWidth)}`;
+}
+
+function singleLine(text: string): string {
+	return text.replace(/[\t\r\n]/g, " ");
+}
+
+/** Normalize a progress value to a clamped fraction, preserving undefined as indeterminate. */
+export function progressFraction(value: number | undefined, min = 0, max = 1): number | undefined {
+	if (value === undefined) return undefined;
+	if (max <= min) return value >= max ? 1 : 0;
+	return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+
+/** Render a single progress bar line; `width` is the inner bar width before frame and percentage chrome. */
+export function renderProgressBar(value: number | undefined, width: number, options: ProgressBarOptions): string {
+	const barWidth = boundedWidth(width, options);
+	const fraction = progressFraction(value, options.min, options.max);
+	let bar: string;
+	if (fraction === undefined) {
+		const glyph = options.style.indeterminate ?? options.style.empty;
+		const raw = fillCells(glyph, barWidth);
+		bar = options.style.styleIndeterminate?.(raw) ?? options.style.styleEmpty?.(raw) ?? raw;
+	} else {
+		const filledWidth = Math.round(fraction * barWidth);
+		const filledRaw = fillCells(options.style.filled, filledWidth);
+		const emptyRaw = fillCells(options.style.empty, Math.max(0, barWidth - filledWidth));
+		const filled = options.style.styleFilled?.(filledRaw) ?? filledRaw;
+		const empty = options.style.styleEmpty?.(emptyRaw) ?? emptyRaw;
+		bar = `${filled}${empty}`;
+	}
+	bar = options.style.styleBar?.(bar) ?? bar;
+	const framed = `${singleLine(options.prefix ?? "")}${bar}${singleLine(options.suffix ?? "")}`;
+	if (fraction === undefined || options.showPercentage !== true) return framed;
+	const percentage = singleLine(options.formatPercentage?.(fraction) ?? `${Math.round(fraction * 100)}%`);
+	return `${framed}${singleLine(options.percentageSeparator ?? " ")}${percentage}`;
+}
+
+/** Mutable progress component whose `render(width)` bounds the complete framed and labeled line to `width`. */
+export class ProgressBar implements Component {
+	#value: number | undefined;
+	readonly #options: ProgressBarOptions;
+	#cache: { width: number; epoch: number; value: number | undefined; lines: readonly string[] } | undefined;
+
+	constructor(value: number | undefined, options: ProgressBarOptions) {
+		this.#value = value;
+		this.#options = options;
+	}
+
+	setValue(value: number | undefined): boolean {
+		if (Object.is(this.#value, value)) return false;
+		this.#value = value;
+		this.#cache = undefined;
+		return true;
+	}
+
+	invalidate(): void {
+		this.#cache = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		const renderWidth = finiteWidth(width, 0);
+		const epoch = getWidthConfigEpoch();
+		if (
+			this.#cache &&
+			this.#cache.width === renderWidth &&
+			this.#cache.epoch === epoch &&
+			Object.is(this.#cache.value, this.#value)
+		) {
+			return this.#cache.lines;
+		}
+
+		const fraction = progressFraction(this.#value, this.#options.min, this.#options.max);
+		const prefix = singleLine(this.#options.prefix ?? "");
+		const suffix = singleLine(this.#options.suffix ?? "");
+		const percentage =
+			fraction !== undefined && this.#options.showPercentage === true
+				? singleLine(this.#options.formatPercentage?.(fraction) ?? `${Math.round(fraction * 100)}%`)
+				: "";
+		const percentageSeparator = percentage ? singleLine(this.#options.percentageSeparator ?? " ") : "";
+		const chromeWidth =
+			visibleWidth(prefix) + visibleWidth(suffix) + visibleWidth(percentageSeparator) + visibleWidth(percentage);
+		const barWidth = Math.max(0, renderWidth - chromeWidth);
+		const line = renderProgressBar(this.#value, barWidth, {
+			...this.#options,
+			minWidth: 0,
+			maxWidth: Math.min(barWidth, finiteWidth(this.#options.maxWidth ?? barWidth, barWidth)),
+			formatPercentage: percentage ? () => percentage : this.#options.formatPercentage,
+		});
+		const lines = [truncateToWidth(singleLine(line), renderWidth, Ellipsis.Omit)];
+		this.#cache = { width: renderWidth, epoch, value: this.#value, lines };
+		return lines;
+	}
+}