@prometheus-ai/tui 0.5.0

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 : [""];
+	}
+}

package/src/components/text.ts

@@ -0,0 +1,110 @@
+import type { Component } from "../tui";
+import { applyBackgroundToLine, padding, replaceTabs, visibleWidth, wrapTextWithAnsi } from "../utils";
+
+/**
+ * Text component - displays multi-line text with word wrapping
+ */
+export class Text implements Component {
+	#text: string;
+	#paddingX: number; // Left/right padding
+	#paddingY: number; // Top/bottom padding
+	#customBgFn?: (text: string) => string;
+
+	// Cache for rendered output
+	#cachedText?: string;
+	#cachedWidth?: number;
+	#cachedLines?: string[];
+
+	constructor(text: string = "", paddingX: number = 1, paddingY: number = 1, customBgFn?: (text: string) => string) {
+		this.#text = text;
+		this.#paddingX = paddingX;
+		this.#paddingY = paddingY;
+		this.#customBgFn = customBgFn;
+	}
+
+	getText(): string {
+		return this.#text;
+	}
+
+	setText(text: string): void {
+		this.#text = text;
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedLines = undefined;
+	}
+
+	setCustomBgFn(customBgFn?: (text: string) => string): void {
+		this.#customBgFn = customBgFn;
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedLines = undefined;
+	}
+
+	invalidate(): void {
+		this.#cachedText = undefined;
+		this.#cachedWidth = undefined;
+		this.#cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		// Check cache
+		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
+			return this.#cachedLines;
+		}
+
+		// Don't render anything if there's no actual text
+		if (!this.#text || this.#text.trim() === "") {
+			const result: string[] = [];
+			this.#cachedText = this.#text;
+			this.#cachedWidth = width;
+			this.#cachedLines = result;
+			return result;
+		}
+
+		// Replace tabs with 3 spaces
+		const normalizedText = replaceTabs(this.#text);
+
+		// Calculate content width (subtract left/right margins)
+		const contentWidth = Math.max(1, width - this.#paddingX * 2);
+
+		// Wrap text (this preserves ANSI codes but does NOT pad)
+		const wrappedLines = wrapTextWithAnsi(normalizedText, contentWidth);
+
+		// Add margins and background to each line
+		const leftMargin = padding(this.#paddingX);
+		const rightMargin = padding(this.#paddingX);
+		const contentLines: string[] = [];
+
+		for (const line of wrappedLines) {
+			// Add margins
+			const lineWithMargins = leftMargin + line + rightMargin;
+
+			// Apply background if specified (this also pads to full width)
+			if (this.#customBgFn) {
+				contentLines.push(applyBackgroundToLine(lineWithMargins, width, this.#customBgFn));
+			} else {
+				// No background - just pad to width with spaces
+				const visibleLen = visibleWidth(lineWithMargins);
+				const paddingNeeded = Math.max(0, width - visibleLen);
+				contentLines.push(lineWithMargins + padding(paddingNeeded));
+			}
+		}
+
+		// Add top/bottom padding (empty lines)
+		const emptyLine = padding(width);
+		const emptyLines: string[] = [];
+		for (let i = 0; i < this.#paddingY; i++) {
+			const line = this.#customBgFn ? applyBackgroundToLine(emptyLine, width, this.#customBgFn) : emptyLine;
+			emptyLines.push(line);
+		}
+
+		const result = [...emptyLines, ...contentLines, ...emptyLines];
+
+		// Update cache
+		this.#cachedText = this.#text;
+		this.#cachedWidth = width;
+		this.#cachedLines = result;
+
+		return result.length > 0 ? result : [""];
+	}
+}

package/src/components/truncated-text.ts

@@ -0,0 +1,61 @@
+import type { Component } from "../tui";
+import { padding, truncateToWidth } from "../utils";
+
+/**
+ * Text component that truncates to fit viewport width
+ */
+export class TruncatedText implements Component {
+	#text: string;
+	#paddingX: number;
+	#paddingY: number;
+
+	constructor(text: string, paddingX: number = 0, paddingY: number = 0) {
+		this.#text = text;
+		this.#paddingX = paddingX;
+		this.#paddingY = paddingY;
+	}
+
+	invalidate(): void {
+		// No cached state to invalidate currently
+	}
+
+	render(width: number): string[] {
+		const result: string[] = [];
+
+		// Empty line padded to width
+		const emptyLine = padding(width);
+
+		// Add vertical padding above
+		for (let i = 0; i < this.#paddingY; i++) {
+			result.push(emptyLine);
+		}
+
+		// Calculate available width after horizontal padding
+		const availableWidth = Math.max(1, width - this.#paddingX * 2);
+
+		// Take only the first line (stop at newline)
+		let singleLineText = this.#text;
+		const newlineIndex = this.#text.indexOf("\n");
+		if (newlineIndex !== -1) {
+			singleLineText = this.#text.substring(0, newlineIndex);
+		}
+
+		// Truncate text if needed (accounting for ANSI codes)
+		const displayText = truncateToWidth(singleLineText, availableWidth);
+
+		// Add horizontal padding
+		const leftPadding = padding(this.#paddingX);
+		const rightPadding = padding(this.#paddingX);
+		const lineWithPadding = leftPadding + displayText + rightPadding;
+
+		// Don't pad to full width - avoids trailing spaces when copying
+		result.push(lineWithPadding);
+
+		// Add vertical padding below
+		for (let i = 0; i < this.#paddingY; i++) {
+			result.push(emptyLine);
+		}
+
+		return result;
+	}
+}

package/src/deccara.ts

@@ -0,0 +1,314 @@
+/**
+ * DECCARA rectangular-SGR background-fill optimizer.
+ *
+ * Kitty extends VT510 DECCARA ("Change Attributes in Rectangular Area") to all
+ * SGR attributes, including background color, so a solid background panel can be
+ * painted as a single rectangle escape instead of a full-width run of
+ * background-styled spaces on every row (see kitty `docs/deccara.rst`):
+ *
+ *   <ESC>[2*x                 DECSACE: select rectangle change extent
+ *   <ESC>[Pt;Pl;Pb;Pr;<sgr>$r DECCARA: apply <sgr> to rows Pt..Pb, cols Pl..Pr
+ *   <ESC>[*x                  DECSACE: restore default extent
+ *
+ * Coordinates are 1-based and inclusive. This module is a pure, renderer-level
+ * planner: it consumes the *final* ANSI strings the renderer would otherwise
+ * write, strips the trailing background-padded spaces it can prove are safe to
+ * drop, and returns the rectangles to emit in their place. It never mutates
+ * component output and never decides which rows are scrollback-bound — those
+ * concerns belong to the caller in `tui.ts`.
+ */
+import { visibleWidth } from "./utils";
+
+/** Reset every attribute (SGR 0). Mirrors `tui.ts`'s per-line terminator. */
+const SEGMENT_RESET = "\x1b[0m";
+
+/** DECSACE — select the rectangle change extent so DECCARA fills a rectangle. */
+export const DECSACE_RECT = "\x1b[2*x";
+/** DECSACE — restore the default (stream) change extent. */
+export const DECSACE_DEFAULT = "\x1b[*x";
+
+/**
+ * Byte cost of the per-frame DECSACE wrapper ({@link DECSACE_RECT} +
+ * {@link DECSACE_DEFAULT}) that brackets every rectangle batch. Charged once per
+ * frame: a plan is emitted only when the trailing-space bytes it removes exceed
+ * the rectangles' own bytes by more than this, so the optimizer never inflates.
+ */
+const DECSACE_WRAPPER_BYTES = DECSACE_RECT.length + DECSACE_DEFAULT.length;
+
+/**
+ * Encode a single DECCARA rectangle. `top`/`bottom` are 1-based inclusive screen
+ * rows, `left`/`right` 1-based inclusive columns, `sgr` the raw SGR parameter
+ * list to apply (e.g. `48;2;10;20;30`, `48;5;4`, `41`).
+ */
+export function encodeDeccara(top: number, left: number, bottom: number, right: number, sgr: string): string {
+	return `\x1b[${top};${left};${bottom};${right};${sgr}$r`;
+}
+
+/** Sentinel for a background form this optimizer refuses to reason about. */
+const BAIL = Symbol("deccara-bail");
+type BgState = string | null;
+
+/**
+ * Fold one SGR parameter list into the active background-color parameter string.
+ * Returns the new background (`null` = default/no background) or {@link BAIL}
+ * when the sequence contains a background form this optimizer will not reason
+ * about (colon-form extended color, malformed params). Foreground and style
+ * parameters are skipped; only background state is tracked.
+ */
+function nextBackground(bg: BgState, params: string): BgState | typeof BAIL {
+	// CSI m with no parameters is SGR 0 (reset everything).
+	if (params.length === 0) return null;
+	const tokens = params.split(";");
+	let result: BgState = bg;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		// An empty parameter defaults to 0 (reset), matching terminal behavior.
+		const n = token.length === 0 ? 0 : Number(token);
+		if (!Number.isInteger(n)) return BAIL;
+		if (n === 0 || n === 49) {
+			result = null;
+			continue;
+		}
+		if ((n >= 40 && n <= 47) || (n >= 100 && n <= 107)) {
+			result = token;
+			continue;
+		}
+		if (n === 48) {
+			const mode = tokens[i + 1];
+			if (mode === "5") {
+				const idx = tokens[i + 2];
+				if (idx === undefined) return BAIL;
+				result = `48;5;${idx}`;
+				i += 2;
+				continue;
+			}
+			if (mode === "2") {
+				const r = tokens[i + 2];
+				const g = tokens[i + 3];
+				const b = tokens[i + 4];
+				if (r === undefined || g === undefined || b === undefined) return BAIL;
+				result = `48;2;${r};${g};${b}`;
+				i += 4;
+				continue;
+			}
+			// Colon-form (`48:2:...`) collapses to a single non-integer token and is
+			// rejected above; anything else following 48 is unexpected — bail.
+			return BAIL;
+		}
+		if (n === 38) {
+			// Foreground extended color: skip its sub-parameters, leave bg alone.
+			const mode = tokens[i + 1];
+			if (mode === "5") {
+				i += 2;
+				continue;
+			}
+			if (mode === "2") {
+				i += 4;
+				continue;
+			}
+			return BAIL;
+		}
+		// Every other parameter (foreground 30-39/90-97, styles) leaves bg alone.
+	}
+	return result;
+}
+
+/** Where to cut a fillable line and the background to paint over the remainder. */
+export interface BgFillAnalysis {
+	/** Byte index where droppable trailing background padding begins (0 = whole line). */
+	cut: number;
+	/** 0-based column where the trailing padding begins (DECCARA left = leftCol + 1). */
+	leftCol: number;
+	/** SGR parameter list of the background covering the trailing region. */
+	bg: string;
+}
+
+/**
+ * Decide whether `line` (a final, width-fit, reset-terminated ANSI string) is a
+ * full-width background fill whose trailing padding can be replaced by a DECCARA
+ * rectangle. Returns `null` unless it can *prove* the dropped bytes are literal
+ * trailing spaces under a single, constant, non-default background span (or the
+ * entire row is background-styled spaces).
+ *
+ * Conservative by construction: any OSC sequence (hyperlinks/images), any
+ * non-SGR CSI, a partial row, an inconsistent or default trailing background, or
+ * a malformed escape all yield `null` so the caller keeps the exact original.
+ */
+export function analyzeBgFillLine(line: string, width: number): BgFillAnalysis | null {
+	if (width <= 0 || line.length === 0) return null;
+	let i = 0;
+	let col = 0;
+	let bg: BgState = null;
+	// Byte index / column immediately after the last non-space printable glyph.
+	let nonSpaceEndByte = 0;
+	let nonSpaceEndCol = 0;
+	// Background covering the current trailing run of spaces, and whether that
+	// trailing run has started. `null` is a real "default background" value, so
+	// it cannot double as the uninitialized sentinel.
+	let trailBg: BgState = null;
+	let trailStarted = false;
+	let trailConsistent = true;
+
+	while (i < line.length) {
+		if (line.charCodeAt(i) === 0x1b) {
+			// Only CSI SGR (`\x1b[ ... m`) is tolerated. OSC, APC, and any other
+			// CSI mean styled hyperlinks/images/cursor markers — refuse to touch.
+			if (line.charCodeAt(i + 1) !== 0x5b) return null;
+			let j = i + 2;
+			while (j < line.length) {
+				const c = line.charCodeAt(j);
+				if (c >= 0x40 && c <= 0x7e) break;
+				j++;
+			}
+			if (j >= line.length) return null; // unterminated CSI
+			if (line.charCodeAt(j) !== 0x6d) return null; // non-SGR CSI (final byte != 'm')
+			const next = nextBackground(bg, line.slice(i + 2, j));
+			if (next === BAIL) return null;
+			bg = next;
+			i = j + 1;
+			continue;
+		}
+
+		// Printable run up to the next escape.
+		let j = i;
+		while (j < line.length && line.charCodeAt(j) !== 0x1b) j++;
+		const text = line.slice(i, j);
+		let nonSpaceLen = text.length;
+		while (nonSpaceLen > 0 && text.charCodeAt(nonSpaceLen - 1) === 0x20) nonSpaceLen--;
+
+		if (nonSpaceLen > 0) {
+			// Run carries a non-space glyph: the trailing region restarts after it.
+			const nonSpaceWidth = visibleWidth(text.slice(0, nonSpaceLen));
+			nonSpaceEndByte = i + nonSpaceLen;
+			nonSpaceEndCol = col + nonSpaceWidth;
+			// Spaces after the last non-space glyph in this same printable run sit
+			// under the current bg. If there are none, the trailing region has not
+			// started yet; a later SGR can still begin a uniform fill safely.
+			if (nonSpaceLen < text.length) {
+				trailBg = bg;
+				trailStarted = true;
+			} else {
+				trailBg = null;
+				trailStarted = false;
+			}
+			trailConsistent = true;
+		} else if (text.length > 0) {
+			// Whole run is spaces: it extends the trailing region. Track bg drift.
+			if (!trailStarted) {
+				trailBg = bg;
+				trailStarted = true;
+			} else if (bg !== trailBg) {
+				trailConsistent = false;
+			}
+		}
+		col += visibleWidth(text);
+		i = j;
+	}
+
+	if (col !== width) return null; // not a full-width fill
+	if (nonSpaceEndCol >= width) return null; // no trailing padding to drop
+	if (!trailStarted || trailBg === null || !trailConsistent) return null; // default/mixed bg — nothing safe to paint
+	return { cut: nonSpaceEndByte, leftCol: nonSpaceEndCol, bg: trailBg };
+}
+
+interface FillCandidate {
+	left: number;
+	right: number;
+	bg: string;
+	short: string;
+	origLen: number;
+}
+
+/** Per-frame plan: the (possibly shortened) row strings and the DECCARA batch. */
+export interface DeccaraPlan {
+	/** Row strings to write, parallel to the input. Optimized rows are shortened. */
+	texts: string[];
+	/** DECSACE-wrapped rectangle batch to emit after the rows, or `""` if none. */
+	sequence: string;
+}
+
+/**
+ * Plan DECCARA rectangles for a contiguous block of visible rows.
+ *
+ * `lines[k]` is the final ANSI string for screen row `firstScreenRow + k`
+ * (0-based). For each fillable row the trailing background padding is removed
+ * (the row's cells are cleared/erased by the caller, then repainted by the
+ * rectangle), and vertically adjacent rows with an identical left/right/bg span
+ * coalesce into one rectangle. Rectangles are emitted only when they save more
+ * bytes than they cost, so the result never exceeds the original byte count.
+ */
+export function planDeccaraFills(lines: string[], width: number, firstScreenRow = 0): DeccaraPlan {
+	const n = lines.length;
+	const texts: string[] = new Array(n);
+	const candidates: (FillCandidate | null)[] = new Array(n);
+
+	for (let k = 0; k < n; k++) {
+		const line = lines[k];
+		texts[k] = line;
+		const analysis = analyzeBgFillLine(line, width);
+		if (!analysis) {
+			candidates[k] = null;
+			continue;
+		}
+		// Cut at the last non-space glyph and re-close attributes. An all-space row
+		// (cut 0) needs no styled text at all — the caller's erase plus the
+		// rectangle paint it. A content row keeps its prefix and a fresh reset so
+		// the inline background never bleeds past the row.
+		const short = analysis.cut === 0 ? "" : line.slice(0, analysis.cut) + SEGMENT_RESET;
+		candidates[k] = { left: analysis.leftCol + 1, right: width, bg: analysis.bg, short, origLen: line.length };
+	}
+
+	// Collect coalesced groups whose rectangle at least pays for its own bytes.
+	// The DECSACE wrapper is a single per-frame cost, so it is charged once below
+	// rather than amortized into each group (which would over-reject lone rows).
+	interface Group {
+		start: number;
+		end: number;
+		rect: string;
+	}
+	const groups: Group[] = [];
+	let removedTotal = 0;
+	let rectBytesTotal = 0;
+	let k = 0;
+	while (k < n) {
+		const head = candidates[k];
+		if (!head) {
+			k++;
+			continue;
+		}
+		// Extend the group over adjacent rows sharing the same fill span.
+		let end = k;
+		while (end + 1 < n) {
+			const next = candidates[end + 1];
+			if (!next || next.left !== head.left || next.right !== head.right || next.bg !== head.bg) break;
+			end++;
+		}
+		const rect = encodeDeccara(firstScreenRow + k + 1, head.left, firstScreenRow + end + 1, head.right, head.bg);
+		let removed = 0;
+		for (let r = k; r <= end; r++) {
+			const c = candidates[r];
+			if (c) removed += c.origLen - c.short.length;
+		}
+		if (removed > rect.length) {
+			groups.push({ start: k, end, rect });
+			removedTotal += removed;
+			rectBytesTotal += rect.length;
+		}
+		k = end + 1;
+	}
+
+	// Emit nothing unless the batch beats the original by more than the wrapper.
+	if (groups.length === 0 || removedTotal - rectBytesTotal <= DECSACE_WRAPPER_BYTES) {
+		return { texts, sequence: "" };
+	}
+	let sequence = DECSACE_RECT;
+	for (const group of groups) {
+		for (let r = group.start; r <= group.end; r++) {
+			const c = candidates[r];
+			if (c) texts[r] = c.short;
+		}
+		sequence += group.rect;
+	}
+	sequence += DECSACE_DEFAULT;
+	return { texts, sequence };
+}