pi-libtui 0.3.2

package/src/decoration/glyphs.ts

@@ -0,0 +1,326 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+import { getTuiAppearance, type TuiIconPack } from "../appearance.ts";
+import { type TuiBackgroundToken, type TuiColor, type TuiForegroundColor, tuiTheme } from "../color/theme.ts";
+
+/** Every semantic icon token supported by all pi-libtui icon packs. */
+export const TUI_ICON_NAMES = [
+	"settings",
+	"appearance",
+	"ux",
+	"animations",
+	"behavior",
+	"interaction",
+	"tools",
+	"toggle-on",
+	"toggle-off",
+	"checkbox-on",
+	"checkbox-off",
+	"comment",
+	"reaction",
+	"copy",
+	"paste",
+	"edit",
+	"delete",
+	"reset",
+	"close",
+	"cancel",
+	"confirm",
+	"search",
+	"selection",
+	"submit",
+	"warning",
+	"error",
+	"lightbulb",
+	"developer",
+	"user",
+	"code-mode",
+	"terminal",
+	"view-image",
+	"expand-closed",
+	"expand-open",
+	"fold-closed",
+	"fold-open",
+	"fold-unfold",
+	"fold-down",
+	"fold-up",
+	"fold",
+	"diff-hunk",
+] as const;
+
+/** A semantic icon role resolved through the active icon pack. */
+export type TuiIconName = (typeof TUI_ICON_NAMES)[number];
+
+/** Icon-bearing content accepted by every shared pill renderer. */
+export interface PillContent {
+	/** Semantic icon, a deliberate custom glyph, or an explicit iconless opt-out. */
+	icon: TuiIconName | { readonly glyph: string } | false;
+	/** Text shown after the icon. */
+	label: string;
+	/** Optional semantic icon tone; defaults to the pill foreground. */
+	iconTone?: TuiForegroundColor;
+}
+
+const ICONS: Record<TuiIconPack, Record<TuiIconName, string>> = {
+	"nerd-fonts": {
+		settings: "",
+		appearance: "󰃣",
+		ux: "󰮄",
+		animations: "",
+		behavior: "󰚩",
+		interaction: "󰌌",
+		tools: "",
+		"toggle-on": "",
+		"toggle-off": "",
+		"checkbox-on": "󰱒",
+		"checkbox-off": "󰄱",
+		comment: "",
+		reaction: "",
+		copy: "",
+		paste: "󰆒",
+		edit: "",
+		delete: "",
+		reset: "",
+		close: "󰅙",
+		cancel: "󰜺",
+		confirm: "",
+		search: "",
+		selection: "",
+		submit: "",
+		warning: "",
+		error: "",
+		lightbulb: "",
+		developer: "󱔘",
+		user: "󰷈",
+		"code-mode": "",
+		terminal: "",
+		"view-image": "",
+		"expand-closed": "",
+		"expand-open": "",
+		"fold-closed": "",
+		"fold-open": "",
+		"fold-unfold": "",
+		"fold-down": "",
+		"fold-up": "",
+		fold: "",
+		"diff-hunk": "",
+	},
+	unicode: {
+		settings: "⚙",
+		appearance: "✦",
+		ux: "●",
+		animations: "↺",
+		behavior: "⚗",
+		interaction: "⌨",
+		tools: "⚒",
+		"toggle-on": "●",
+		"toggle-off": "○",
+		"checkbox-on": "☑",
+		"checkbox-off": "☐",
+		comment: "✎",
+		reaction: "☺",
+		copy: "⧉",
+		paste: "⇲",
+		edit: "✎",
+		delete: "×",
+		reset: "↺",
+		close: "×",
+		cancel: "×",
+		confirm: "✓",
+		search: "⌕",
+		selection: "›",
+		submit: "➤",
+		warning: "⚠",
+		error: "×",
+		lightbulb: "💡",
+		developer: "◆",
+		user: "●",
+		"code-mode": "⌘",
+		terminal: ">_",
+		"view-image": "▣",
+		"expand-closed": "›",
+		"expand-open": "⌄",
+		"fold-closed": "›",
+		"fold-open": "⌄",
+		"fold-unfold": "↕",
+		"fold-down": "⌄",
+		"fold-up": "⌃",
+		fold: "•",
+		"diff-hunk": "≋",
+	},
+	emoji: {
+		settings: "⚙️",
+		appearance: "🎨",
+		ux: "👤",
+		animations: "🔄",
+		behavior: "🤖",
+		interaction: "⌨️",
+		tools: "🛠️",
+		"toggle-on": "✅",
+		"toggle-off": "⭕",
+		"checkbox-on": "☑️",
+		"checkbox-off": "⬜",
+		comment: "💬",
+		reaction: "🙂",
+		copy: "📋",
+		paste: "📥",
+		edit: "📝",
+		delete: "🗑️",
+		reset: "🔄",
+		close: "❌",
+		cancel: "❌",
+		confirm: "✅",
+		search: "🔍",
+		selection: "▶",
+		submit: "📤",
+		warning: "⚠️",
+		error: "❌",
+		lightbulb: "💡",
+		developer: "🛠️",
+		user: "👤",
+		"code-mode": "⌘",
+		terminal: "💻",
+		"view-image": "🖼️",
+		"expand-closed": "›",
+		"expand-open": "⌄",
+		"fold-closed": "›",
+		"fold-open": "⌄",
+		"fold-unfold": "↕",
+		"fold-down": "⌄",
+		"fold-up": "⌃",
+		fold: "•",
+		"diff-hunk": "≋",
+	},
+};
+
+/**
+ * Resolve a semantic icon through the active Unicode, Nerd Font, or emoji pack.
+ * @param name Semantic icon role.
+ * @returns The glyph owned by the active icon pack.
+ */
+export function icon(name: TuiIconName): string {
+	return ICONS[getTuiAppearance().iconPack][name];
+}
+
+/**
+ * Resolve the left and right pill caps for a requested shape.
+ * @param powerline Whether to use Powerline caps; defaults to the active appearance setting.
+ * @returns A readonly `[left, right]` separator pair.
+ */
+export function getTuiPillSeparators(powerline = getTuiAppearance().powerline): readonly [string, string] {
+	return powerline ? ["", ""] : ["▐", "▌"];
+}
+
+/**
+ * Render a label without terminal color state, using the configured pill shape.
+ * @param content Required icon decision and plain or already-styled label content.
+ * @returns The label surrounded by the active pill separators.
+ */
+export function renderPillText(content: PillContent): string {
+	const [left, right] = getTuiPillSeparators();
+	const glyph = pillIcon(content.icon);
+	return `${left}${glyph ? `${glyph} ` : ""}${content.label}${right}`;
+}
+
+/** Resolve a semantic or custom pill icon. */
+export function pillIcon(value: PillContent["icon"]): string {
+	if (value === false) return "";
+	return typeof value === "string" ? icon(value) : value.glyph;
+}
+
+/** Glyph family supported by reusable key hints. */
+export type TuiKeyIconPack = "nerd-fonts" | "unicode";
+
+const MODIFIER_ORDER = ["ctrl", "super", "alt", "shift"] as const;
+const MODIFIERS: Record<TuiKeyIconPack, Record<(typeof MODIFIER_ORDER)[number], string>> = {
+	"nerd-fonts": { ctrl: "󰘴", super: "󰘳", alt: "󰘵", shift: "󰘶" },
+	unicode: { ctrl: "⌃", super: "⌘", alt: "⌥", shift: "⇧" },
+};
+const NAMED_KEYS: Record<TuiKeyIconPack, Record<string, string>> = {
+	"nerd-fonts": {
+		space: "󱁐",
+		tab: "󰌒",
+		enter: "󰌑",
+		return: "󰌑",
+		backspace: "󰁮",
+		escape: "⎋",
+		esc: "⎋",
+	},
+	unicode: {
+		space: "␣",
+		tab: "⇥",
+		enter: "⏎",
+		return: "⏎",
+		backspace: "⌫",
+		escape: "⎋",
+		esc: "⎋",
+	},
+};
+const KEYCAP_BACKGROUND = "badge.neutral" as const;
+
+function activePack(): TuiKeyIconPack {
+	return getTuiAppearance().iconPack === "nerd-fonts" ? "nerd-fonts" : "unicode";
+}
+
+function letterIcon(letter: string, pack: TuiKeyIconPack): string {
+	const index = letter.codePointAt(0)! - "a".codePointAt(0)!;
+	return pack === "nerd-fonts" ? String.fromCodePoint(0xf0b08 + index) : String.fromCodePoint(0x1f170 + index);
+}
+
+/**
+ * Render a key identifier as compact reusable modifier and key glyphs.
+ * Unsupported bases remain literal instead of inventing a misleading icon.
+ * @param key Pi key identifier such as `ctrl+c`, `space`, or `escape`.
+ * @param pack Optional glyph family; defaults to Nerd Fonts only when the active appearance uses them.
+ * @returns An unstyled key-hint string.
+ */
+export function keyIcon(key: KeyId, pack: TuiKeyIconPack = activePack()): string {
+	const parts = key.split("+");
+	const base = parts.pop() ?? key;
+	const modifiers = MODIFIER_ORDER.filter((modifier) => parts.includes(modifier)).map(
+		(modifier) => MODIFIERS[pack][modifier],
+	);
+	const normalized = base.toLowerCase();
+	const baseIcon = /^[a-z]$/u.test(normalized) ? letterIcon(normalized, pack) : (NAMED_KEYS[pack][normalized] ?? base);
+	return [...modifiers, baseIcon].join(" ");
+}
+
+/** Render an unstyled key glyph with portable Unicode text presentation. */
+export function keyHintGlyph(key: KeyId, pack: TuiKeyIconPack = activePack()): string {
+	return textPresentation(keyIcon(key, pack), pack);
+}
+
+/**
+ * Render a key identifier as a subdued semantic keycap adapted to its destination background.
+ * @param theme Active Pi theme used for semantic coloring.
+ * @param key Pi key identifier to render.
+ * @param pack Optional explicit key glyph family.
+ * @param background Optional destination background restored after the keycap.
+ * @returns ANSI-styled key hint.
+ */
+export function renderKeyHint(
+	theme: Theme,
+	key: KeyId,
+	pack?: TuiKeyIconPack,
+	background?: TuiBackgroundToken | TuiColor,
+): string {
+	const colors = tuiTheme(theme);
+	const keycapBackground = colors.color(KEYCAP_BACKGROUND);
+	const keycapForeground = colors.contrastBackground(keycapBackground);
+	const glyph = keyHintGlyph(key, pack);
+	const keycap = colors.bg(keycapBackground, colors.fg(keycapForeground, glyph));
+	return `${keycap}${destinationBackgroundAnsi(colors, background)}`;
+}
+
+function destinationBackgroundAnsi(
+	colors: ReturnType<typeof tuiTheme>,
+	background: TuiBackgroundToken | TuiColor | undefined,
+): string {
+	if (background === undefined) return "\x1b[49m";
+	return colors.bgAnsi(background);
+}
+
+function textPresentation(glyph: string, pack: TuiKeyIconPack | undefined): string {
+	if (pack !== "unicode") return glyph;
+	return glyph.replace(/[🄰-🅉🅰-🆉]/gu, (letter) => `${letter}\uFE0E`);
+}

package/src/decoration/pointer-interaction.ts

@@ -0,0 +1,123 @@
+import type { MouseRect, TuiMouseEvent } from "../mouse/events.ts";
+
+/**
+ * Domain-owned screen target used by {@link PointerInteractionController}.
+ * Rendering and identity stay with the caller; this contract only supplies
+ * the stable key and hit rectangle needed for pointer state.
+ */
+export interface PointerInteractionOptions<Target> {
+	key(target: Target): string;
+	rect(target: Target): MouseRect;
+}
+
+/** Hover and click callbacks for a screen-positioned pointer controller. */
+export interface PointerInteractionHandlers<Target> {
+	onHoverChange?(target: Target | undefined): void;
+	onActivate?(target: Target): void;
+}
+
+/**
+ * Shared pointer lifecycle for screen decorations.
+ *
+ * Feature packages own target meaning, rendering, and activation. This class
+ * owns only hit testing, hover state, primary-button capture, and bounds.
+ * Keeping that state in one place prevents pills, markers, and other inline
+ * decorations from growing subtly different click/hover implementations.
+ */
+export class PointerInteractionController<Target> {
+	private targets: Target[] = [];
+	private hoveredKey: string | undefined;
+	private pressedTarget: Target | undefined;
+
+	constructor(private readonly options: PointerInteractionOptions<Target>) {}
+
+	/** Replace the current visible targets after a screen decoration render. */
+	setTargets(targets: readonly Target[]): void {
+		this.targets = [...targets];
+		if (this.hoveredKey !== undefined && !this.findByKey(this.hoveredKey)) this.hoveredKey = undefined;
+		if (this.pressedTarget !== undefined && !this.findByKey(this.options.key(this.pressedTarget))) {
+			this.pressedTarget = undefined;
+		}
+	}
+
+	/** Find the visible target containing an absolute terminal cell. */
+	targetAt(screenCol: number, screenRow: number): Target | undefined {
+		return this.targets.find((target) => contains(this.options.rect(target), screenCol, screenRow));
+	}
+
+	/** Return the currently hovered visible target, if any. */
+	hoveredTarget(): Target | undefined {
+		return this.hoveredKey === undefined ? undefined : this.findByKey(this.hoveredKey);
+	}
+
+	/** Change hover state and report whether the stable target changed. */
+	setHover(target: Target | undefined): boolean {
+		const next = target === undefined ? undefined : this.options.key(target);
+		if (this.hoveredKey === next) return false;
+		this.hoveredKey = next;
+		return true;
+	}
+
+	/** Return the union bounds of all currently visible targets. */
+	getBounds(): MouseRect | undefined {
+		if (this.targets.length === 0) return undefined;
+		const rects = this.targets.map((target) => this.options.rect(target));
+		const left = Math.min(...rects.map((rect) => rect.x));
+		const top = Math.min(...rects.map((rect) => rect.y));
+		const right = Math.max(...rects.map((rect) => rect.x + rect.width));
+		const bottom = Math.max(...rects.map((rect) => rect.y + rect.height));
+		return { x: left, y: top, width: right - left, height: bottom - top };
+	}
+
+	/**
+	 * Handle one normalized pointer event in absolute screen coordinates.
+	 * Primary-button release activates only the target that received the press.
+	 */
+	handleMouse(event: TuiMouseEvent, handlers: PointerInteractionHandlers<Target> = {}): boolean {
+		if (event.type === "leave") {
+			this.pressedTarget = undefined;
+			if (this.setHover(undefined)) handlers.onHoverChange?.(undefined);
+			return false;
+		}
+
+		const target = this.targetAt(event.screenCol, event.screenRow);
+		if (event.type === "enter" || event.type === "move") {
+			if (this.setHover(target)) handlers.onHoverChange?.(target);
+			return target !== undefined;
+		}
+
+		if (event.type === "press") {
+			if (event.button !== undefined && event.button !== 0) return false;
+			this.pressedTarget = target;
+			return target !== undefined;
+		}
+
+		if (event.type === "release") {
+			if (event.button !== undefined && event.button !== 0) return false;
+			const pressedTarget = this.pressedTarget;
+			this.pressedTarget = undefined;
+			if (pressedTarget === undefined) return target !== undefined;
+			if (target !== undefined && this.options.key(target) === this.options.key(pressedTarget)) {
+				handlers.onActivate?.(pressedTarget);
+			}
+			return true;
+		}
+
+		return target !== undefined;
+	}
+
+	/** Clear all targets and transient pointer state. */
+	clear(): void {
+		this.targets = [];
+		this.hoveredKey = undefined;
+		this.pressedTarget = undefined;
+	}
+
+	private findByKey(key: string): Target | undefined {
+		return this.targets.find((target) => this.options.key(target) === key);
+	}
+}
+
+function contains(rect: MouseRect, col: number, row: number): boolean {
+	return col >= rect.x && col < rect.x + rect.width && row >= rect.y && row < rect.y + rect.height;
+}

package/src/decoration/powerline-pill.ts

@@ -0,0 +1,104 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { sliceByColumn } from "@earendil-works/pi-tui";
+import { getTuiAppearance } from "../appearance.ts";
+import {
+	contrastBackgroundColor,
+	type TuiBackgroundPaint,
+	type TuiColor,
+	type TuiForegroundPaint,
+	tuiTheme,
+} from "../color/theme.ts";
+import { getTuiPillSeparators, type PillContent, pillIcon } from "./glyphs.ts";
+
+/**
+ * Resolve the effective ANSI background at a visible terminal column.
+ * @param line Styled terminal line to inspect.
+ * @param column Zero-based visible column whose active background is needed.
+ * @returns The last applicable background SGR sequence, or the default-background reset.
+ */
+export function backgroundAnsiAtColumn(line: string, column: number): string {
+	const prefix = sliceByColumn(line, 0, Math.max(0, column) + 1, true);
+	let background = "\x1b[49m";
+	const sgr = /\x1b\[([0-9;]*)m/gu;
+	for (const match of prefix.matchAll(sgr)) {
+		const params = match[1] === "" ? [0] : match[1]!.split(";").map(Number);
+		for (let index = 0; index < params.length; index += 1) {
+			const code = params[index];
+			if (code === undefined) continue;
+			if (code === 0 || code === 49) {
+				background = "\x1b[49m";
+			} else if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107)) {
+				background = `\x1b[${code}m`;
+			} else if (code === 48 && params[index + 1] === 5 && params[index + 2] !== undefined) {
+				background = `\x1b[48;5;${params[index + 2]}m`;
+				index += 2;
+			} else if (code === 48 && params[index + 1] === 2 && params[index + 4] !== undefined) {
+				background = `\x1b[48;2;${params[index + 2]};${params[index + 3]};${params[index + 4]}m`;
+				index += 4;
+			} else if (code === 38) {
+				// Skip extended foreground parameters. Their RGB/index values can
+				// otherwise look like basic background codes in this scan (for
+				// example `38;2;45;45;45m` contains the background code 45).
+				if (params[index + 1] === 5 && params[index + 2] !== undefined) index += 2;
+				else if (params[index + 1] === 2 && params[index + 4] !== undefined) index += 4;
+			}
+		}
+	}
+	return background;
+}
+
+/**
+ * Generate a pill surface that contrasts with its destination background.
+ * @param theme Active Pi theme used for semantic color generation and fallback background discovery.
+ * @param surroundingBackgroundAnsi ANSI state at the destination surface.
+ * @returns A resolved logical background suitable for `renderPill()`.
+ */
+export function contrastingPillBackground(theme: Theme, surroundingBackgroundAnsi: string): TuiColor {
+	const background = backgroundAnsiAtColumn(`${surroundingBackgroundAnsi} `, 1);
+	return contrastBackgroundColor(theme, background);
+}
+
+/**
+ * Render a semantic label whose caps exactly match its body background.
+ * @param theme Active Pi theme used to resolve semantic and explicit colors.
+ * @param content Required icon decision and label; the label may contain non-background terminal styling.
+ * @param background Semantic or resolved logical pill surface.
+ * @param foreground Semantic foreground or generated swatch for the label.
+ * @param surroundingBackground Semantic or explicit destination surface restored around the caps.
+ * @param surroundingBackgroundAnsi Exact destination ANSI background; takes precedence over `surroundingBackground`.
+ * @param rounded Whether to use Powerline caps; defaults to the active appearance setting.
+ * @returns ANSI-styled pill text with the destination background restored after both caps.
+ */
+export function renderPill(
+	theme: Theme,
+	content: PillContent,
+	background: TuiBackgroundPaint,
+	foreground: TuiForegroundPaint,
+	surroundingBackground?: TuiBackgroundPaint,
+	surroundingBackgroundAnsi?: string,
+	rounded = getTuiAppearance().powerline,
+): string {
+	const colors = tuiTheme(theme);
+	const destinationBackground =
+		surroundingBackgroundAnsi ?? (surroundingBackground ? colors.bgAnsi(surroundingBackground) : undefined);
+	const restore = destinationBackground ?? "\x1b[49m";
+	const capColor = colors.fgAnsi(typeof background === "string" ? colors.color(background) : background);
+	const effectiveForeground =
+		foreground === "text.primary"
+			? colors.contrastBackground(typeof background === "string" ? colors.color(background) : background)
+			: foreground;
+	const [leftSeparator, rightSeparator] = getTuiPillSeparators(rounded);
+	// compositeTuiLine resets the style immediately before an overlay. Restore
+	// the destination background before the left cap or its transparent corner
+	// is painted with the terminal default instead of the container surface.
+	const left = `${destinationBackground ?? ""}${capColor}${leftSeparator}\x1b[39m${destinationBackground ?? ""}`;
+	const glyph = pillIcon(content.icon);
+	const bodyContent = glyph
+		? content.label
+			? `${colors.fg(content.iconTone ?? effectiveForeground, glyph)} ${colors.fg(effectiveForeground, content.label)}`
+			: colors.fg(content.iconTone ?? effectiveForeground, glyph)
+		: colors.fg(effectiveForeground, content.label);
+	const body = colors.bg(background, bodyContent);
+	const right = `${restore}${capColor}${rightSeparator}\x1b[39m${restore}`;
+	return `${left}${body}${right}`;
+}