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

package/src/components/layout/geometry.ts

@@ -0,0 +1,202 @@
+import type { MouseRoutable } from "../../mouse";
+import type { Component } from "../../tui";
+import { padding, truncateToWidth, visibleWidth } from "../../utils";
+
+/** Alignment within space allocated by a layout component. */
+export type LayoutAlignment = "start" | "center" | "end";
+
+/** Insets reserved inside a layout child's allocated rectangle. */
+export interface LayoutInsets {
+	top?: number;
+	right?: number;
+	bottom?: number;
+	left?: number;
+}
+
+/** Insets normalized to finite, non-negative terminal-cell counts. */
+export interface NormalizedLayoutInsets {
+	top: number;
+	right: number;
+	bottom: number;
+	left: number;
+}
+
+/** Rectangle in coordinates local to a layout component. */
+export interface LayoutRect {
+	row: number;
+	col: number;
+	width: number;
+	height: number;
+}
+
+/** Lazy layout child, evaluated only when the child is visible. */
+export type LayoutRenderer = (width: number, height: number | undefined) => readonly string[];
+
+/** A concrete component or a lazy renderer used as a layout child. */
+export type LayoutContent = Component | LayoutRenderer;
+
+/** Static text or a late-bound layout decoration, useful for theme-colored rules. */
+export type LayoutDecoration = string | (() => string);
+
+/** A component whose parent may assign a local row budget before rendering. */
+export interface HeightConstrainedComponent extends Component {
+	setHeight(height: number | undefined): void;
+}
+
+/** One fixed or growing constraint consumed by {@link allocateLayoutSpace}. */
+export interface LayoutAllocation {
+	fixed?: number;
+	grow?: number;
+	min?: number;
+	max?: number;
+}
+
+/** Clamp an external size to a finite, non-negative integer cell count. */
+export function layoutSize(value: number | undefined, fallback = 0): number {
+	const resolved = value === undefined || !Number.isFinite(value) ? fallback : value;
+	return Number.isFinite(resolved) ? Math.max(0, Math.floor(resolved)) : 0;
+}
+
+/** Normalize an optional external size while preserving `undefined`. */
+export function optionalLayoutSize(value: number | undefined): number | undefined {
+	return value === undefined ? undefined : layoutSize(value);
+}
+
+/** Clamp a proportional layout input to a finite, non-negative number. */
+export function layoutRatio(value: number | undefined, fallback: number): number {
+	const resolved = value === undefined || !Number.isFinite(value) ? fallback : value;
+	return Number.isFinite(resolved) ? Math.max(0, resolved) : 0;
+}
+
+/** Resolve static or late-bound layout decoration text. */
+export function layoutDecorationText(decoration: LayoutDecoration | undefined): string {
+	return typeof decoration === "function" ? decoration() : (decoration ?? "");
+}
+
+function allocationMaximum(item: LayoutAllocation): number {
+	return item.max === undefined ? Number.MAX_SAFE_INTEGER : Math.max(layoutSize(item.min), layoutSize(item.max));
+}
+
+/**
+ * Allocate bounded integer cells across fixed and growing children. When the
+ * minimums cannot fit, later children collapse first so output stays bounded.
+ */
+export function allocateLayoutSpace(items: readonly LayoutAllocation[], available: number): number[] {
+	available = layoutSize(available);
+	const sizes = items.map(item => {
+		const minimum = layoutSize(item.min);
+		const maximum = allocationMaximum(item);
+		return item.fixed === undefined ? minimum : Math.max(minimum, Math.min(maximum, layoutSize(item.fixed)));
+	});
+	const used = sizes.reduce((sum, size) => sum + size, 0);
+	if (used > available) {
+		let overflow = used - available;
+		for (let index = sizes.length - 1; index >= 0 && overflow > 0; index--) {
+			const reduction = Math.min(sizes[index] ?? 0, overflow);
+			sizes[index] = (sizes[index] ?? 0) - reduction;
+			overflow -= reduction;
+		}
+		return sizes;
+	}
+
+	let remaining = available - used;
+	let flexible = items
+		.map((item, index) => ({ item, index }))
+		.filter(({ item }) => item.fixed === undefined && layoutSize(item.grow) > 0);
+	while (remaining > 0 && flexible.length > 0) {
+		const totalWeight = flexible.reduce((sum, { item }) => sum + layoutSize(item.grow), 0);
+		let granted = 0;
+		for (const { item, index } of flexible) {
+			const maximum = allocationMaximum(item);
+			const capacity = maximum - (sizes[index] ?? 0);
+			if (capacity <= 0) continue;
+			const proportional = Math.floor((remaining * layoutSize(item.grow)) / totalWeight);
+			const share = Math.min(capacity, Math.max(1, proportional), remaining - granted);
+			if (share <= 0) continue;
+			sizes[index] = (sizes[index] ?? 0) + share;
+			granted += share;
+			if (granted === remaining) break;
+		}
+		if (granted === 0) break;
+		remaining -= granted;
+		flexible = flexible.filter(({ item, index }) => {
+			const maximum = allocationMaximum(item);
+			return (sizes[index] ?? 0) < maximum;
+		});
+	}
+	return sizes;
+}
+
+/** Normalize every inset to a finite, non-negative integer cell count. */
+export function layoutInsets(insets: LayoutInsets | undefined): NormalizedLayoutInsets {
+	return {
+		top: layoutSize(insets?.top),
+		right: layoutSize(insets?.right),
+		bottom: layoutSize(insets?.bottom),
+		left: layoutSize(insets?.left),
+	};
+}
+
+/** Compare optional inset objects by their normalized terminal geometry. */
+export function equalLayoutInsets(left: LayoutInsets | undefined, right: LayoutInsets | undefined): boolean {
+	return (
+		layoutSize(left?.top) === layoutSize(right?.top) &&
+		layoutSize(left?.right) === layoutSize(right?.right) &&
+		layoutSize(left?.bottom) === layoutSize(right?.bottom) &&
+		layoutSize(left?.left) === layoutSize(right?.left)
+	);
+}
+
+/** Offset content within spare cells according to an alignment. */
+export function layoutAlignmentOffset(space: number, alignment: LayoutAlignment): number {
+	if (space <= 0 || alignment === "start") return 0;
+	return alignment === "end" ? space : Math.floor(space / 2);
+}
+
+/** Narrow a concrete-or-lazy child to a concrete component. */
+export function isLayoutComponent(content: LayoutContent): content is Component {
+	return typeof content !== "function";
+}
+
+/** Narrow a layout child to a component accepting a row budget. */
+export function isHeightConstrainedComponent(content: LayoutContent): content is HeightConstrainedComponent {
+	return isLayoutComponent(content) && "setHeight" in content && typeof content.setHeight === "function";
+}
+
+/** Narrow a layout child to a mouse-routable component. */
+export function isLayoutMouseRoutable(content: LayoutContent): content is Component & MouseRoutable {
+	return isLayoutComponent(content) && "routeMouse" in content && typeof content.routeMouse === "function";
+}
+
+/** Return concrete children once each, preserving their first layout order. */
+export function uniqueLayoutComponents(contents: readonly LayoutContent[]): readonly Component[] {
+	const seen = new Set<Component>();
+	const components: Component[] = [];
+	for (const content of contents) {
+		if (!isLayoutComponent(content) || seen.has(content)) continue;
+		seen.add(content);
+		components.push(content);
+	}
+	return components;
+}
+
+/** Fit one ANSI-styled row to an exact terminal-cell width. */
+export function fitLayoutLine(line: string, width: number): string {
+	width = layoutSize(width);
+	if (width === 0) return "";
+	const lineWidth = visibleWidth(line);
+	const clipped = lineWidth > width ? truncateToWidth(line, width) : line;
+	const clippedWidth = lineWidth > width ? visibleWidth(clipped) : lineWidth;
+	return clipped + padding(Math.max(0, width - clippedWidth));
+}
+
+/** Render a concrete or lazy child with an optional local height budget. */
+export function renderLayoutContent(
+	content: LayoutContent,
+	width: number,
+	height: number | undefined,
+): readonly string[] {
+	if (typeof content === "function") return content(layoutSize(width), optionalLayoutSize(height));
+	if (isHeightConstrainedComponent(content)) content.setHeight(optionalLayoutSize(height));
+	return content.render(layoutSize(width));
+}

package/src/components/layout/row.ts

@@ -0,0 +1,283 @@
+import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import type { Component } from "../../tui";
+import { padding, visibleWidth } from "../../utils";
+import {
+	allocateLayoutSpace,
+	equalLayoutInsets,
+	fitLayoutLine,
+	isLayoutMouseRoutable,
+	layoutAlignmentOffset,
+	type LayoutAlignment,
+	type LayoutContent,
+	layoutDecorationText,
+	type LayoutDecoration,
+	layoutInsets,
+	type LayoutInsets,
+	type LayoutRect,
+	layoutSize,
+	optionalLayoutSize,
+	renderLayoutContent,
+	uniqueLayoutComponents,
+} from "./geometry";
+
+/** One child and its horizontal sizing and alignment constraints. */
+export interface RowChild {
+	content: LayoutContent;
+	width?: number;
+	grow?: number;
+	minWidth?: number;
+	maxWidth?: number;
+	padding?: LayoutInsets;
+	align?: LayoutAlignment;
+}
+
+/** Construction options for {@link Row}. */
+export interface RowOptions {
+	children: readonly RowChild[];
+	height?: number;
+	gap?: LayoutDecoration;
+	prefix?: LayoutDecoration;
+	suffix?: LayoutDecoration;
+	align?: LayoutAlignment;
+}
+
+/** A child hit translated into that child's local coordinates. */
+export interface RowHit {
+	index: number;
+	content: LayoutContent;
+	line: number;
+	col: number;
+	rect: LayoutRect;
+}
+
+interface RowMemo {
+	width: number;
+	height: number | undefined;
+	prefix: string;
+	gap: string;
+	suffix: string;
+	widths: readonly number[];
+	lines: readonly (readonly string[])[];
+	result: readonly string[];
+}
+
+function sameChild(left: RowChild, right: RowChild): boolean {
+	return (
+		left.content === right.content &&
+		left.width === right.width &&
+		left.grow === right.grow &&
+		left.minWidth === right.minWidth &&
+		left.maxWidth === right.maxWidth &&
+		left.align === right.align &&
+		equalLayoutInsets(left.padding, right.padding)
+	);
+}
+
+/**
+ * Horizontal component layout with fixed/proportional slots, exact row budgets,
+ * ANSI-aware clipping, alignment, and local mouse-coordinate translation.
+ */
+export class Row implements Component, MouseRoutable {
+	#children: RowChild[];
+	#height: number | undefined;
+	#gap: LayoutDecoration | undefined;
+	#prefix: LayoutDecoration | undefined;
+	#suffix: LayoutDecoration | undefined;
+	#align: LayoutAlignment;
+	#frames: LayoutRect[] = [];
+	#memo: RowMemo | undefined;
+	#ignoreTight = false;
+
+	constructor(options: RowOptions) {
+		this.#children = options.children.map(child => ({ ...child, padding: { ...child.padding } }));
+		this.#height = optionalLayoutSize(options.height);
+		this.#gap = options.gap;
+		this.#prefix = options.prefix;
+		this.#suffix = options.suffix;
+		this.#align = options.align ?? "start";
+	}
+
+	/** Concrete component children exposed to the debug tree. */
+	get debugChildren(): readonly Component[] {
+		return uniqueLayoutComponents(this.#children.map(child => child.content));
+	}
+
+	/** Last-rendered content rectangle for `index`, excluding its padding. */
+	childRect(index: number): LayoutRect | undefined {
+		return this.#frames[index];
+	}
+
+	/** Replace the row's children without recreating the layout component. */
+	setChildren(children: readonly RowChild[]): void {
+		if (
+			children.length === this.#children.length &&
+			children.every((child, index) => sameChild(child, this.#children[index]!))
+		) {
+			return;
+		}
+		this.#children = children.map(child => ({ ...child, padding: { ...child.padding } }));
+		if (this.#ignoreTight) {
+			for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+				child.setIgnoreTight?.(true);
+			}
+		}
+		this.#memo = undefined;
+	}
+
+	/** Set the exact rendered row count, or clear it to use natural height. */
+	setHeight(height: number | undefined): void {
+		const next = optionalLayoutSize(height);
+		if (next === this.#height) return;
+		this.#height = next;
+		this.#memo = undefined;
+	}
+
+	/** Update outer and inter-child decorations. */
+	setDecorations(
+		prefix: LayoutDecoration | undefined,
+		gap: LayoutDecoration | undefined,
+		suffix: LayoutDecoration | undefined,
+	): void {
+		if (prefix === this.#prefix && gap === this.#gap && suffix === this.#suffix) return;
+		this.#prefix = prefix;
+		this.#gap = gap;
+		this.#suffix = suffix;
+		this.#memo = undefined;
+	}
+
+	setIgnoreTight(ignore: boolean): this {
+		if (ignore === this.#ignoreTight) return this;
+		this.#ignoreTight = ignore;
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.setIgnoreTight?.(ignore);
+		}
+		this.#memo = undefined;
+		return this;
+	}
+
+	invalidate(): void {
+		this.#memo = undefined;
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.invalidate?.();
+		}
+	}
+
+	dispose(): void {
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.dispose?.();
+		}
+	}
+
+	/** Translate a row-local point into a child's local coordinates. */
+	locate(line: number, col: number): RowHit | undefined {
+		for (let index = 0; index < this.#frames.length; index++) {
+			const rect = this.#frames[index];
+			if (!rect) continue;
+			if (line < rect.row || line >= rect.row + rect.height || col < rect.col || col >= rect.col + rect.width)
+				continue;
+			return {
+				index,
+				content: this.#children[index]!.content,
+				line: line - rect.row,
+				col: col - rect.col,
+				rect,
+			};
+		}
+		return undefined;
+	}
+
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		const hit = this.locate(line, col);
+		if (hit && isLayoutMouseRoutable(hit.content)) hit.content.routeMouse(event, hit.line, hit.col);
+	}
+
+	render(width: number): readonly string[] {
+		width = layoutSize(width);
+		const prefix = layoutDecorationText(this.#prefix);
+		const gap = layoutDecorationText(this.#gap);
+		const suffix = layoutDecorationText(this.#suffix);
+		const decorationWidth =
+			visibleWidth(prefix) + visibleWidth(suffix) + Math.max(0, this.#children.length - 1) * visibleWidth(gap);
+		const available = Math.max(0, width - decorationWidth);
+		const widths = allocateLayoutSpace(
+			this.#children.map(child => ({
+				fixed: child.width,
+				grow: child.width === undefined ? layoutSize(child.grow, 1) : 0,
+				min: child.minWidth,
+				max: child.maxWidth,
+			})),
+			available,
+		);
+		const childLines: (readonly string[])[] = [];
+		const insets = this.#children.map(child => layoutInsets(child.padding));
+		for (let index = 0; index < this.#children.length; index++) {
+			const slotWidth = widths[index] ?? 0;
+			const inset = insets[index]!;
+			const contentWidth = Math.max(0, slotWidth - inset.left - inset.right);
+			const contentHeight =
+				this.#height === undefined ? undefined : Math.max(0, this.#height - inset.top - inset.bottom);
+			childLines.push(
+				contentWidth > 0 ? renderLayoutContent(this.#children[index]!.content, contentWidth, contentHeight) : [],
+			);
+		}
+		const naturalHeight = childLines.reduce(
+			(maximum, lines, index) => Math.max(maximum, lines.length + insets[index]!.top + insets[index]!.bottom),
+			0,
+		);
+		const rowHeight = this.#height ?? naturalHeight;
+
+		let column = visibleWidth(prefix);
+		this.#frames = this.#children.map((_child, index) => {
+			const inset = insets[index]!;
+			const slotWidth = widths[index] ?? 0;
+			const rect: LayoutRect = {
+				row: inset.top,
+				col: column + inset.left,
+				width: Math.max(0, slotWidth - inset.left - inset.right),
+				height: Math.max(0, rowHeight - inset.top - inset.bottom),
+			};
+			column += slotWidth + (index + 1 < this.#children.length ? visibleWidth(gap) : 0);
+			return rect;
+		});
+
+		const memo = this.#memo;
+		if (
+			memo &&
+			memo.width === width &&
+			memo.height === this.#height &&
+			memo.prefix === prefix &&
+			memo.gap === gap &&
+			memo.suffix === suffix &&
+			memo.widths.length === widths.length &&
+			memo.widths.every((value, index) => value === widths[index]) &&
+			memo.lines.length === childLines.length &&
+			memo.lines.every((lines, index) => lines === childLines[index])
+		) {
+			return memo.result;
+		}
+
+		const result: string[] = [];
+		for (let line = 0; line < rowHeight; line++) {
+			let rendered = prefix;
+			for (let index = 0; index < this.#children.length; index++) {
+				const child = this.#children[index]!;
+				const inset = insets[index]!;
+				const slotWidth = widths[index] ?? 0;
+				const contentWidth = Math.max(0, slotWidth - inset.left - inset.right);
+				const lines = childLines[index]!;
+				const viewportHeight = Math.max(0, rowHeight - inset.top - inset.bottom);
+				const visibleHeight = Math.min(viewportHeight, lines.length);
+				const offset = layoutAlignmentOffset(viewportHeight - visibleHeight, child.align ?? this.#align);
+				const childLine = line - inset.top - offset;
+				const content = childLine >= 0 && childLine < visibleHeight ? (lines[childLine] ?? "") : "";
+				rendered += padding(inset.left) + fitLayoutLine(content, contentWidth) + padding(inset.right);
+				if (index + 1 < this.#children.length) rendered += gap;
+			}
+			const currentWidth = visibleWidth(rendered) + visibleWidth(suffix);
+			rendered += padding(Math.max(0, width - currentWidth)) + suffix;
+			result.push(fitLayoutLine(rendered, width));
+		}
+		this.#memo = { width, height: this.#height, prefix, gap, suffix, widths, lines: childLines, result };
+		return result;
+	}
+}