@gajae-code/tui 0.1.1

package/src/components/select-list.ts

@@ -0,0 +1,249 @@
+import { getKeybindings } from "../keybindings";
+import type { SymbolTheme } from "../symbols";
+import type { Component } from "../tui";
+import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
+
+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;
+}
+
+export class SelectList implements Component {
+	#filteredItems: ReadonlyArray<SelectItem>;
+	#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.#filteredItems = this.items.filter(item => item.value.toLowerCase().startsWith(filter.toLowerCase()));
+		// Reset selection when filter changes
+		this.#selectedIndex = 0;
+	}
+
+	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[] = [];
+
+		// If no items match filter, show message
+		if (this.#filteredItems.length === 0) {
+			lines.push(this.theme.noMatch("  No matching commands"));
+			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
+		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;
+			lines.push(this.#renderItem(item, isSelected, width, descriptionText, primaryColumnWidth));
+		}
+
+		// Add scroll indicators if needed
+		if (startIndex > 0 || endIndex < this.#filteredItems.length) {
+			const scrollText = `  (${this.#selectedIndex + 1}/${this.#filteredItems.length})`;
+			// Truncate if too long for terminal
+			lines.push(this.theme.scrollInfo(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
+		}
+
+		return lines;
+	}
+
+	handleInput(keyData: string): void {
+		if (this.#filteredItems.length === 0) return;
+		const kb = getKeybindings();
+		// 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);
+			}
+		}
+		// Escape or Ctrl+C
+		else if (kb.matches(keyData, "tui.select.cancel")) {
+			if (this.onCancel) {
+				this.onCancel();
+			}
+		}
+	}
+
+	#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);
+	}
+
+	#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,211 @@
+import { getKeybindings } from "../keybindings";
+import type { Component } from "../tui";
+import { Ellipsis, padding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+
+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;
+}
+
+export interface SettingsListTheme {
+	label: (text: string, selected: boolean) => string;
+	value: (text: string, selected: 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);
+	}
+
+	#renderMainList(width: number): string[] {
+		const lines: string[] = [];
+
+		if (this.#items.length === 0) {
+			lines.push(this.#theme.hint("  No settings available"));
+			return lines;
+		}
+
+		// Calculate visible range with scrolling
+		const startIndex = Math.max(
+			0,
+			Math.min(this.#selectedIndex - Math.floor(this.#maxVisible / 2), this.#items.length - this.#maxVisible),
+		);
+		const endIndex = Math.min(startIndex + this.#maxVisible, this.#items.length);
+
+		// Calculate max label width for alignment
+		const maxLabelWidth = Math.min(30, Math.max(...this.#items.map(item => visibleWidth(item.label))));
+
+		// Render visible items
+		for (let i = startIndex; i < endIndex; i++) {
+			const item = this.#items[i];
+			if (!item) continue;
+
+			const isSelected = i === this.#selectedIndex;
+			const prefix = isSelected ? this.#theme.cursor : "  ";
+			const prefixWidth = visibleWidth(prefix);
+
+			// Pad label to align values
+			const labelPadded = item.label + padding(Math.max(0, maxLabelWidth - visibleWidth(item.label)));
+			const labelText = this.#theme.label(labelPadded, isSelected);
+
+			// Calculate space for value
+			const separator = "  ";
+			const usedWidth = prefixWidth + maxLabelWidth + visibleWidth(separator);
+			const valueMaxWidth = width - usedWidth - 2;
+
+			const valueText = this.#theme.value(
+				truncateToWidth(item.currentValue, valueMaxWidth, Ellipsis.Omit),
+				isSelected,
+			);
+
+			lines.push(truncateToWidth(prefix + labelText + separator + valueText, width));
+		}
+
+		// Add scroll indicator if needed
+		if (startIndex > 0 || endIndex < this.#items.length) {
+			const scrollText = `  (${this.#selectedIndex + 1}/${this.#items.length})`;
+			lines.push(this.#theme.hint(truncateToWidth(scrollText, width - 2, Ellipsis.Omit)));
+		}
+
+		// 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;
+		}
+	}
+}

package/src/components/spacer.ts

@@ -0,0 +1,28 @@
+import type { Component } from "../tui";
+
+/**
+ * Spacer component that renders empty lines
+ */
+export class Spacer implements Component {
+	#lines: number;
+
+	constructor(lines: number = 1) {
+		this.#lines = lines;
+	}
+
+	setLines(lines: number): void {
+		this.#lines = lines;
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate currently
+	}
+
+	render(_width: number): string[] {
+		const result: string[] = [];
+		for (let i = 0; i < this.#lines; i++) {
+			result.push("");
+		}
+		return result;
+	}
+}

package/src/components/tab-bar.ts

@@ -0,0 +1,175 @@
+/**
+ * Tab Bar Component
+ *
+ * A horizontal tab bar for switching between views/panels.
+ * Renders as: "Label:  Tab1   Tab2   Tab3  (tab to cycle)"
+ *
+ * Navigation:
+ * - Tab / Arrow Right: Next tab (wraps around)
+ * - Shift+Tab / Arrow Left: Previous tab (wraps around)
+ */
+import { matchesKey } from "../keys";
+import type { Component } from "../tui";
+import { truncateToWidth, visibleWidth } from "../utils";
+
+/** Tab definition */
+export interface Tab {
+	/** Unique identifier for the tab */
+	id: string;
+	/** Display label shown in the tab bar */
+	label: string;
+}
+
+/** Theme for styling the tab bar */
+export interface TabBarTheme {
+	/** Style for the label prefix (e.g., "Settings:") */
+	label: (text: string) => string;
+	/** Style for the currently active tab */
+	activeTab: (text: string) => string;
+	/** Style for inactive tabs */
+	inactiveTab: (text: string) => string;
+	/** Style for the hint text (e.g., "(tab to cycle)") */
+	hint: (text: string) => string;
+}
+
+/**
+ * Horizontal tab bar component.
+ *
+ * @example
+ * ```ts
+ * const tabs = [
+ *   { id: "config", label: "Config" },
+ *   { id: "tools", label: "Tools" },
+ * ];
+ * const tabBar = new TabBar("Settings", tabs, theme);
+ * tabBar.onTabChange = (tab) => console.log(`Switched to ${tab.id}`);
+ * ```
+ */
+export class TabBar implements Component {
+	#tabs: Tab[];
+	#activeIndex: number = 0;
+	#theme: TabBarTheme;
+	#label: string;
+
+	/** Callback fired when the active tab changes */
+	onTabChange?: (tab: Tab, index: number) => void;
+
+	constructor(label: string, tabs: Tab[], theme: TabBarTheme, initialIndex: number = 0) {
+		this.#label = label;
+		this.#tabs = tabs;
+		this.#theme = theme;
+		this.#activeIndex = initialIndex;
+	}
+
+	/** Get the currently active tab */
+	getActiveTab(): Tab {
+		return this.#tabs[this.#activeIndex];
+	}
+
+	/** Get the index of the currently active tab */
+	getActiveIndex(): number {
+		return this.#activeIndex;
+	}
+
+	/** Set the active tab by index (clamped to valid range) */
+	setActiveIndex(index: number): void {
+		const newIndex = Math.max(0, Math.min(index, this.#tabs.length - 1));
+		if (newIndex !== this.#activeIndex) {
+			this.#activeIndex = newIndex;
+			this.onTabChange?.(this.#tabs[this.#activeIndex], this.#activeIndex);
+		}
+	}
+
+	/** Move to the next tab (wraps to first tab after last) */
+	nextTab(): void {
+		this.setActiveIndex((this.#activeIndex + 1) % this.#tabs.length);
+	}
+
+	/** Move to the previous tab (wraps to last tab before first) */
+	prevTab(): void {
+		this.setActiveIndex((this.#activeIndex - 1 + this.#tabs.length) % this.#tabs.length);
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate
+	}
+
+	/**
+	 * Handle keyboard input for tab navigation.
+	 * @returns true if the input was handled, false otherwise
+	 */
+	handleInput(data: string): boolean {
+		if (matchesKey(data, "tab") || matchesKey(data, "right")) {
+			this.nextTab();
+			return true;
+		}
+		if (matchesKey(data, "shift+tab") || matchesKey(data, "left")) {
+			this.prevTab();
+			return true;
+		}
+		return false;
+	}
+
+	/** Render the tab bar, wrapping to multiple lines if needed */
+	render(width: number): string[] {
+		const maxWidth = Math.max(1, width);
+		const chunks: string[] = [];
+
+		// Label prefix
+		chunks.push(this.#theme.label(`${this.#label}:`));
+		chunks.push("  ");
+
+		// Tab buttons
+		for (let i = 0; i < this.#tabs.length; i++) {
+			const tab = this.#tabs[i];
+			if (i === this.#activeIndex) {
+				chunks.push(this.#theme.activeTab(` ${tab.label} `));
+			} else {
+				chunks.push(this.#theme.inactiveTab(` ${tab.label} `));
+			}
+			if (i < this.#tabs.length - 1) {
+				chunks.push("  ");
+			}
+		}
+
+		// Navigation hint
+		chunks.push("  ");
+		chunks.push(this.#theme.hint("(tab to cycle)"));
+
+		const lines: string[] = [];
+		let currentLine = "";
+		let currentWidth = 0;
+
+		for (const chunk of chunks) {
+			const chunkWidth = visibleWidth(chunk);
+			if (chunkWidth <= 0) {
+				continue;
+			}
+
+			if (chunkWidth > maxWidth) {
+				if (currentLine) {
+					lines.push(currentLine);
+					currentLine = "";
+					currentWidth = 0;
+				}
+				lines.push(truncateToWidth(chunk, maxWidth));
+				continue;
+			}
+
+			if (currentWidth > 0 && currentWidth + chunkWidth > maxWidth) {
+				lines.push(currentLine);
+				currentLine = "";
+				currentWidth = 0;
+			}
+
+			currentLine += chunk;
+			currentWidth += chunkWidth;
+		}
+
+		if (currentLine) {
+			lines.push(currentLine);
+		}
+
+		return lines.length > 0 ? lines : [""];
+	}
+}