@dungle-scrubs/tallow 0.8.21 → 0.8.23

package/packages/tallow-tui/src/border-styles.ts

@@ -0,0 +1,60 @@
+/**
+ * Border character sets for box-drawing.
+ *
+ * @module
+ */
+
+/** A set of box-drawing characters for rendering borders. */
+export interface BorderStyle {
+	topLeft: string;
+	topRight: string;
+	bottomLeft: string;
+	bottomRight: string;
+	horizontal: string;
+	vertical: string;
+}
+
+/** Sharp corners — standard box-drawing (┌┐└┘). */
+export const SHARP: BorderStyle = {
+	topLeft: "┌",
+	topRight: "┐",
+	bottomLeft: "└",
+	bottomRight: "┘",
+	horizontal: "─",
+	vertical: "│",
+};
+
+/** Rounded corners — Unicode arc box-drawing (╭╮╰╯). */
+export const ROUNDED: BorderStyle = {
+	topLeft: "╭",
+	topRight: "╮",
+	bottomLeft: "╰",
+	bottomRight: "╯",
+	horizontal: "─",
+	vertical: "│",
+};
+
+/** Flat — horizontal rules only, no corners or verticals. */
+export const FLAT: BorderStyle = {
+	topLeft: "─",
+	topRight: "─",
+	bottomLeft: "─",
+	bottomRight: "─",
+	horizontal: "─",
+	vertical: " ",
+};
+
+/**
+ * Global default border style — set once, applies to all new BorderedBox instances.
+ * Extensions can set this at session_start to override.
+ */
+export let defaultBorderStyle: BorderStyle = SHARP;
+
+/**
+ * Set the global default border style.
+ *
+ * @param style - Border style to use as default
+ */
+export function setDefaultBorderStyle(style: BorderStyle): void {
+	defaultBorderStyle = style;
+}

package/packages/tallow-tui/src/components/bordered-box.ts

@@ -0,0 +1,113 @@
+/**
+ * Box component with configurable border style (sharp, rounded, flat).
+ *
+ * Wraps child content lines in a full border with optional title,
+ * padding, and background fill.
+ *
+ * @module
+ */
+
+import { type BorderStyle, defaultBorderStyle } from "../border-styles.js";
+import { truncateToWidth, visibleWidth } from "../utils.js";
+import { Text } from "./text.js";
+
+/** Configuration for a BorderedBox. */
+export interface BorderedBoxOptions {
+	/** Border character set (defaults to global defaultBorderStyle). */
+	borderStyle?: BorderStyle;
+	/** Title rendered in the top border (optional). */
+	title?: string;
+	/** Horizontal padding inside the border (default: 1). */
+	paddingX?: number;
+	/** Color function applied to border characters. */
+	borderColorFn?: (str: string) => string;
+	/** Color function applied to the title. */
+	titleColorFn?: (str: string) => string;
+}
+
+/**
+ * Renders content inside a bordered box.
+ *
+ * Usage:
+ * ```typescript
+ * const box = new BorderedBox(["line 1", "line 2"], {
+ *   borderStyle: ROUNDED,
+ *   title: "Output",
+ * });
+ * const lines = box.render(80);
+ * ```
+ */
+export class BorderedBox extends Text {
+	private contentLines: string[];
+	private options: BorderedBoxOptions;
+
+	/**
+	 * @param contentLines - Pre-rendered content lines to wrap
+	 * @param options - Border style, title, padding, color functions
+	 */
+	constructor(contentLines: string[], options: BorderedBoxOptions = {}) {
+		super("", contentLines.length + 2, 0);
+		this.contentLines = contentLines;
+		this.options = options;
+	}
+
+	/**
+	 * Render the bordered box to an array of terminal lines.
+	 *
+	 * @param width - Available terminal width
+	 * @returns Array of rendered lines including top/bottom borders
+	 */
+	render(width: number): string[] {
+		const style = this.options.borderStyle ?? defaultBorderStyle;
+		const padX = this.options.paddingX ?? 1;
+		const colorBorder = this.options.borderColorFn ?? ((s: string) => s);
+		const colorTitle = this.options.titleColorFn ?? ((s: string) => s);
+
+		const innerWidth = width - 2 - padX * 2; // borders + padding
+		if (innerWidth < 1) return this.contentLines;
+
+		const pad = " ".repeat(padX);
+
+		// Top border with optional title
+		let topBar: string;
+		if (this.options.title) {
+			const titleStr = ` ${colorTitle(this.options.title)} `;
+			const titleVisLen = visibleWidth(titleStr);
+			// topLeft(1) + leftBar(1) + titleStr + rightBar(rightFill) + topRight(1)
+			const rightFill = Math.max(0, width - 3 - titleVisLen);
+			topBar =
+				colorBorder(style.topLeft) +
+				colorBorder(style.horizontal) +
+				titleStr +
+				colorBorder(style.horizontal.repeat(rightFill)) +
+				colorBorder(style.topRight);
+		} else {
+			topBar =
+				colorBorder(style.topLeft) +
+				colorBorder(style.horizontal.repeat(width - 2)) +
+				colorBorder(style.topRight);
+		}
+
+		// Content lines with side borders
+		const bodyLines = this.contentLines.map((line) => {
+			const clamped = visibleWidth(line) > innerWidth ? truncateToWidth(line, innerWidth) : line;
+			const fill = Math.max(0, innerWidth - visibleWidth(clamped));
+			return (
+				colorBorder(style.vertical) +
+				pad +
+				clamped +
+				" ".repeat(fill) +
+				pad +
+				colorBorder(style.vertical)
+			);
+		});
+
+		// Bottom border
+		const bottomBar =
+			colorBorder(style.bottomLeft) +
+			colorBorder(style.horizontal.repeat(width - 2)) +
+			colorBorder(style.bottomRight);
+
+		return [topBar, ...bodyLines, bottomBar];
+	}
+}

package/packages/tallow-tui/src/components/box.ts

@@ -0,0 +1,137 @@
+import type { Component } from "../tui.js";
+import { applyBackgroundToLine, visibleWidth } from "../utils.js";
+
+type RenderCache = {
+	childLines: string[];
+	width: number;
+	bgSample: string | undefined;
+	lines: string[];
+};
+
+/**
+ * Box component - a container that applies padding and background to all children
+ */
+export class Box implements Component {
+	children: Component[] = [];
+	private paddingX: number;
+	private paddingY: number;
+	private bgFn?: (text: string) => string;
+
+	// Cache for rendered output
+	private cache?: RenderCache;
+
+	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
+	}
+
+	private invalidateCache(): void {
+		this.cache = undefined;
+	}
+
+	private matchCache(width: number, childLines: string[], bgSample: string | undefined): boolean {
+		const cache = this.cache;
+		return (
+			!!cache &&
+			cache.width === width &&
+			cache.bgSample === bgSample &&
+			cache.childLines.length === childLines.length &&
+			cache.childLines.every((line, i) => line === childLines[i])
+		);
+	}
+
+	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 = " ".repeat(this.paddingX);
+
+		// Render all children
+		const childLines: string[] = [];
+		for (const child of this.children) {
+			const lines = child.render(contentWidth);
+			for (const line of lines) {
+				childLines.push(leftPad + line);
+			}
+		}
+
+		if (childLines.length === 0) {
+			return [];
+		}
+
+		// Check if bgFn output changed by sampling
+		const bgSample = this.bgFn ? this.bgFn("test") : undefined;
+
+		// Check cache validity
+		if (this.matchCache(width, childLines, bgSample)) {
+			return this.cache!.lines;
+		}
+
+		// 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.cache = { childLines, width, bgSample, lines: result };
+
+		return result;
+	}
+
+	private applyBg(line: string, width: number): string {
+		const visLen = visibleWidth(line);
+		const padNeeded = Math.max(0, width - visLen);
+		const padded = line + " ".repeat(padNeeded);
+
+		if (this.bgFn) {
+			return applyBackgroundToLine(padded, width, this.bgFn);
+		}
+		return padded;
+	}
+}

package/packages/tallow-tui/src/components/cancellable-loader.ts

@@ -0,0 +1,40 @@
+import { getEditorKeybindings } from "../keybindings.js";
+import { Loader } from "./loader.js";
+
+/**
+ * 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 {
+	private 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 = getEditorKeybindings();
+		if (kb.matches(data, "selectCancel")) {
+			this.abortController.abort();
+			this.onAbort?.();
+		}
+	}
+
+	dispose(): void {
+		this.stop();
+	}
+}