@f5-sales-demo/pi-tui 19.51.2

package/src/bracketed-paste.ts

@@ -0,0 +1,47 @@
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+
+export type PasteResult = { handled: false } | { handled: true; pasteContent?: string; remaining: string };
+
+/**
+ * Handles bracketed paste mode buffering for terminal input components.
+ *
+ * Bracketed paste mode wraps pasted content between start (\x1b[200~) and
+ * end (\x1b[201~) markers, which may arrive split across multiple chunks.
+ * This class buffers incoming data and assembles complete paste payloads.
+ */
+export class BracketedPasteHandler {
+	#buffer = "";
+	#active = false;
+
+	/**
+	 * Process incoming terminal data for bracketed paste sequences.
+	 *
+	 * @returns `{ handled: false }` if the data contains no paste sequence and
+	 *          should be processed normally. `{ handled: true }` if the data was
+	 *          consumed by paste buffering — `pasteContent` is set when a complete
+	 *          paste has been assembled; omitted when still buffering.
+	 */
+	process(data: string): PasteResult {
+		if (data.includes(PASTE_START)) {
+			this.#active = true;
+			this.#buffer = "";
+			data = data.replace(PASTE_START, "");
+		}
+
+		if (!this.#active) return { handled: false };
+
+		this.#buffer += data;
+
+		const endIndex = this.#buffer.indexOf(PASTE_END);
+		if (endIndex === -1) return { handled: true, remaining: "" };
+
+		const pasteContent = this.#buffer.substring(0, endIndex);
+		const remaining = this.#buffer.substring(endIndex + PASTE_END.length);
+
+		this.#buffer = "";
+		this.#active = false;
+
+		return { handled: true, pasteContent, remaining };
+	}
+}

package/src/chord-dispatcher.ts

@@ -0,0 +1,90 @@
+import type { ChordBinding } from "./chord-parser";
+import type { KeyId } from "./keys";
+
+export type ChordResult =
+	| { kind: "dispatched"; action: string }
+	| { kind: "pending"; leader: KeyId }
+	| { kind: "passthrough" }
+	| { kind: "abandoned" };
+
+export interface ChordDispatcherCallbacks {
+	onPending?: (leader: KeyId) => void;
+	onCleared?: () => void;
+}
+
+interface PendingState {
+	leader: KeyId;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Two-key chord state machine. Stateless across keystrokes except for one
+ * optional "pending leader" slot + its timeout timer. Consumers feed KeyIds
+ * via feedKey() and act on the returned ChordResult.
+ */
+export class ChordDispatcher {
+	readonly #bindings: ChordBinding[];
+	readonly #timeoutMs: number;
+	readonly #callbacks: ChordDispatcherCallbacks;
+	#pending: PendingState | null = null;
+
+	constructor(bindings: ChordBinding[], timeoutMs: number, callbacks: ChordDispatcherCallbacks = {}) {
+		this.#bindings = bindings;
+		this.#timeoutMs = timeoutMs;
+		this.#callbacks = callbacks;
+	}
+
+	feedKey(key: KeyId): ChordResult {
+		// Phase 1: pending chord is active — interpret this key as the 2nd stroke.
+		if (this.#pending) {
+			const match = this.#bindings.find(
+				b => b.sequence.length === 2 && b.sequence[0] === this.#pending!.leader && b.sequence[1] === key,
+			);
+			this.#clearPending();
+			if (match) return { kind: "dispatched", action: match.action };
+			return { kind: "abandoned" };
+		}
+
+		// Phase 2: no pending chord.
+		// Single-stroke match wins first.
+		for (const b of this.#bindings) {
+			if (b.sequence.length === 1 && b.sequence[0] === key) {
+				return { kind: "dispatched", action: b.action };
+			}
+		}
+		// Chord leader?
+		const isLeader = this.#bindings.some(b => b.sequence.length === 2 && b.sequence[0] === key);
+		if (isLeader) {
+			this.#setPending(key);
+			return { kind: "pending", leader: key };
+		}
+		return { kind: "passthrough" };
+	}
+
+	#setPending(leader: KeyId): void {
+		const timer = setTimeout(() => this.#timeoutClear(), this.#timeoutMs);
+		this.#pending = { leader, timer };
+		this.#callbacks.onPending?.(leader);
+	}
+
+	#clearPending(): void {
+		if (!this.#pending) return;
+		clearTimeout(this.#pending.timer);
+		this.#pending = null;
+		this.#callbacks.onCleared?.();
+	}
+
+	#timeoutClear(): void {
+		// Timer fired; timer handle consumed by runtime.
+		if (!this.#pending) return;
+		this.#pending = null;
+		this.#callbacks.onCleared?.();
+	}
+
+	dispose(): void {
+		if (this.#pending) {
+			clearTimeout(this.#pending.timer);
+			this.#pending = null;
+		}
+	}
+}

package/src/chord-parser.ts

@@ -0,0 +1,66 @@
+import type { KeyId } from "./keys";
+
+export interface ParsedBinding {
+	sequence: KeyId[];
+}
+
+export interface BindingParseError {
+	readonly message: string;
+	readonly input: string;
+}
+
+export type ParseResult = { ok: true; sequence: KeyId[] } | { ok: false; error: BindingParseError };
+
+/**
+ * Parse a binding string into a keystroke sequence.
+ *
+ * - Whitespace separates keystrokes in a chord.
+ * - One keystroke = single-stroke binding; two keystrokes = chord.
+ * - v1 rejects 3+ keystrokes.
+ * - Individual keystroke validation (known key names + modifier combos) is
+ *   deferred to KeyId at type check time and at runtime via parseKey on input.
+ */
+export function parseBinding(input: string): ParseResult {
+	const trimmed = input.trim();
+	if (trimmed.length === 0) {
+		return { ok: false, error: { message: "empty binding", input } };
+	}
+	const tokens = trimmed.split(/\s+/);
+	if (tokens.length > 2) {
+		return {
+			ok: false,
+			error: {
+				message: `chord bindings support at most 2 keystrokes (got ${tokens.length})`,
+				input,
+			},
+		};
+	}
+	return { ok: true, sequence: tokens as KeyId[] };
+}
+
+export interface ChordBinding {
+	action: string;
+	sequence: KeyId[];
+}
+
+export type BindingsInput = Record<string, string | string[]>;
+
+export type ParseBindingsResult = { ok: true; bindings: ChordBinding[] } | { ok: false; error: BindingParseError };
+
+/**
+ * Parse a map of action → binding string(s) into a flat list of ChordBinding.
+ * Array values expand into multiple ChordBindings for the same action.
+ * Stops at the first parse error.
+ */
+export function parseBindings(input: BindingsInput): ParseBindingsResult {
+	const bindings: ChordBinding[] = [];
+	for (const [action, value] of Object.entries(input)) {
+		const list = Array.isArray(value) ? value : [value];
+		for (const str of list) {
+			const parsed = parseBinding(str);
+			if (!parsed.ok) return parsed;
+			bindings.push({ action, sequence: parsed.sequence });
+		}
+	}
+	return { ok: true, bindings };
+}

package/src/components/box.ts

@@ -0,0 +1,155 @@
+import type { Component } from "../tui";
+import { applyBackgroundToLine, padding, visibleWidth } from "../utils";
+
+type Cache = {
+	key: bigint | number;
+	result: string[];
+};
+
+/**
+ * Box component - a container that applies padding and background to all children
+ */
+export class Box implements Component {
+	children: Component[] = [];
+	#paddingX: number;
+	#paddingY: number;
+	#bgFn?: (text: string) => string;
+
+	// Cache for rendered output
+	#cached?: Cache;
+
+	constructor(paddingX = 1, paddingY = 1, bgFn?: (text: string) => string) {
+		this.#paddingX = paddingX;
+		this.#paddingY = paddingY;
+		this.#bgFn = bgFn;
+	}
+
+	addChild(component: Component): void {
+		this.children.push(component);
+		this.#invalidateCache();
+	}
+
+	removeChild(component: Component): void {
+		const index = this.children.indexOf(component);
+		if (index !== -1) {
+			this.children.splice(index, 1);
+			this.#invalidateCache();
+		}
+	}
+
+	clear(): void {
+		this.children = [];
+		this.#invalidateCache();
+	}
+
+	setBgFn(bgFn?: (text: string) => string): void {
+		this.#bgFn = bgFn;
+		// Don't invalidate here - we'll detect bgFn changes by sampling output
+	}
+
+	setPaddingX(paddingX: number): void {
+		if (this.#paddingX !== paddingX) {
+			this.#paddingX = paddingX;
+			this.#invalidateCache();
+		}
+	}
+
+	#invalidateCache(): void {
+		this.#cached = undefined;
+	}
+
+	static #tmp = new Uint32Array(2);
+	#computeCacheKey(width: number, childLines: string[], bgSample: string | undefined): bigint | number {
+		Box.#tmp[0] = width;
+		Box.#tmp[1] = childLines.length;
+		let h = Bun.hash(Box.#tmp);
+		for (const line of childLines) {
+			h = Bun.hash(line, h);
+		}
+		if (bgSample) {
+			h = Bun.hash(bgSample, h);
+		}
+		return h;
+	}
+
+	#matchCache(cacheKey: bigint | number): boolean {
+		return this.#cached?.key === cacheKey;
+	}
+
+	invalidate(): void {
+		this.#invalidateCache();
+		for (const child of this.children) {
+			child.invalidate?.();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.children.length === 0) {
+			return [];
+		}
+
+		const contentWidth = Math.max(1, width - this.#paddingX * 2);
+		const leftPad = padding(this.#paddingX);
+
+		// Render all children
+		const childLines: string[] = [];
+		for (const child of this.children) {
+			try {
+				const lines = child.render(contentWidth);
+				for (const line of lines) {
+					childLines.push(leftPad + line);
+				}
+			} catch {
+				// Swallow render errors from individual children to prevent process crash
+			}
+		}
+
+		if (childLines.length === 0) {
+			return [];
+		}
+
+		// Check if bgFn output changed by sampling
+		const bgSample = this.#bgFn ? this.#bgFn("test") : undefined;
+
+		const cacheKey = this.#computeCacheKey(width, childLines, bgSample);
+
+		// Check cache validity
+		if (this.#matchCache(cacheKey)) {
+			return this.#cached!.result;
+		}
+
+		// Apply background and padding
+		const result: string[] = [];
+
+		// Top padding
+		for (let i = 0; i < this.#paddingY; i++) {
+			result.push(this.#applyBg("", width));
+		}
+
+		// Content
+		for (const line of childLines) {
+			result.push(this.#applyBg(line, width));
+		}
+
+		// Bottom padding
+		for (let i = 0; i < this.#paddingY; i++) {
+			result.push(this.#applyBg("", width));
+		}
+
+		// Update cache
+		this.#cached = { key: cacheKey, result };
+
+		return result;
+	}
+
+	#applyBg(line: string, width: number): string {
+		const visLen = visibleWidth(line);
+		const padNeeded = Math.max(0, width - visLen);
+		const padded = line + padding(padNeeded);
+
+		if (this.#bgFn) {
+			return applyBackgroundToLine(padded, width, this.#bgFn);
+		}
+		return padded;
+	}
+}

package/src/components/cancellable-loader.ts

@@ -0,0 +1,40 @@
+import { getKeybindings } from "../keybindings";
+import { Loader } from "./loader";
+
+/**
+ * Loader that can be cancelled with Escape.
+ * Extends Loader with an AbortSignal for cancelling async operations.
+ *
+ * @example
+ * const loader = new CancellableLoader(tui, cyan, dim, "Working...");
+ * loader.onAbort = () => done(null);
+ * doWork(loader.signal).then(done);
+ */
+export class CancellableLoader extends Loader {
+	#abortController = new AbortController();
+
+	/** Called when user presses Escape */
+	onAbort?: () => void;
+
+	/** AbortSignal that is aborted when user presses Escape */
+	get signal(): AbortSignal {
+		return this.#abortController.signal;
+	}
+
+	/** Whether the loader was aborted */
+	get aborted(): boolean {
+		return this.#abortController.signal.aborted;
+	}
+
+	handleInput(data: string): void {
+		const kb = getKeybindings();
+		if (kb.matches(data, "tui.select.cancel")) {
+			this.#abortController.abort();
+			this.onAbort?.();
+		}
+	}
+
+	dispose(): void {
+		this.stop();
+	}
+}