@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/components/input.ts

@@ -2,6 +2,11 @@ import { BracketedPasteHandler, decodeReencodedPasteControls } from "../brackete
 import { getKeybindings } from "../keybindings";
 import { extractPrintableText, matchesKey } from "../keys";
 import { KillRing } from "../kill-ring";
+import type { TspInputProps } from "@oh-my-pi/pi-wire";
+import { node } from "../native/describe";
+import { sameProps } from "../native/memo";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeNode } from "../native/node";
 import { SpaceHoldGesture } from "../space-hold";
 import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
 import { cursorColumnWindow } from "./scroll-viewport";
@@ -58,6 +63,8 @@ export class Input implements Component, Focusable {
 	prompt = "> ";
 	/** Render the editable value as bullets while retaining the real value internally. */
 	mask = false;
+	/** Dim hint a native terminal shows while the value is empty. */
+	placeholder: string | undefined;
 	onSubmit?: (value: string) => void;
 	onEscape?: () => void;
 	/** Space-bar push-to-talk; set its `handler` to enable it. */
@@ -81,9 +88,17 @@ export class Input implements Component, Focusable {
 	/** Code units of the current volatile speech-to-text preview (see {@link setVolatileText}). */
 	#volatileTextLen = 0;
 
+	#native?: { props: TspInputProps; node: NativeNode };
+
 	getValue(): string {
 		return this.#value;
 	}
+
+	/** The caret as a UTF-16 offset into {@link getValue}. */
+	getCursor(): number {
+		return this.#cursor;
+	}
+
 	/** Return bounded input content and cursor state for debug inspection. */
 	debugState(): Record<string, unknown> {
 		return {
@@ -112,7 +127,14 @@ export class Input implements Component, Focusable {
 		return this.#useTerminalCursor;
 	}
 
-	handleInput(data: string): void {
+	/**
+	 * Apply one key: the editor's text bindings (motion, deletion, kill ring,
+	 * undo), pastes and printable text. Returns whether the key was the
+	 * field's: false for keys it has no binding for, and for cancel/submit
+	 * without an `onEscape`/`onSubmit`, so a host (a list's search field) can
+	 * route everything else on.
+	 */
+	handleInput(data: string): boolean {
 		// Handle bracketed paste mode
 		const paste = this.#pasteHandler.process(data);
 		if (paste.handled) {
@@ -122,77 +144,79 @@ export class Input implements Component, Focusable {
 					this.handleInput(paste.remaining);
 				}
 			}
-			return;
+			return true;
 		}
 
 		// Space-hold push-to-talk: a sustained space bar starts/stops STT instead of typing spaces.
 		switch (this.spaceHold.process(matchesKey(data, "space"))) {
 			case "type":
 				this.#insertCharacter(" ");
-				return;
+				return true;
 			case "swallow":
-				return;
+				return true;
 		}
 
 		const kb = getKeybindings();
 
 		// Escape/Cancel
 		if (kb.matches(data, "tui.select.cancel")) {
-			if (this.onEscape) this.onEscape();
-			return;
+			if (!this.onEscape) return false;
+			this.onEscape();
+			return true;
 		}
 
 		// Undo
 		if (kb.matches(data, "tui.editor.undo")) {
 			this.#undo();
-			return;
+			return true;
 		}
 
 		// Submit
 		if (kb.matches(data, "tui.input.submit") || data === "\n") {
-			if (this.onSubmit) this.onSubmit(this.#value);
-			return;
+			if (!this.onSubmit) return false;
+			this.onSubmit(this.#value);
+			return true;
 		}
 
 		// Deletion
 		if (kb.matches(data, "tui.editor.deleteCharBackward")) {
 			this.#handleBackspace();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteCharForward")) {
 			this.#handleForwardDelete();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteWordBackward")) {
 			this.#deleteWordBackwards();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteWordForward")) {
 			this.#deleteWordForward();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteToLineStart")) {
 			this.#deleteToLineStart();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteToLineEnd")) {
 			this.#deleteToLineEnd();
-			return;
+			return true;
 		}
 
 		// Kill ring actions
 		if (kb.matches(data, "tui.editor.yank")) {
 			this.#yank();
-			return;
+			return true;
 		}
 		if (kb.matches(data, "tui.editor.yankPop")) {
 			this.#yankPop();
-			return;
+			return true;
 		}
 
 		// Cursor movement
@@ -204,7 +228,7 @@ export class Input implements Component, Focusable {
 				const lastGrapheme = graphemes[graphemes.length - 1];
 				this.#cursor -= lastGrapheme ? lastGrapheme.segment.length : 1;
 			}
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorRight")) {
@@ -215,36 +239,36 @@ export class Input implements Component, Focusable {
 				const firstGrapheme = graphemes[0];
 				this.#cursor += firstGrapheme ? firstGrapheme.segment.length : 1;
 			}
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorLineStart")) {
 			this.#lastAction = null;
 			this.#cursor = 0;
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorLineEnd")) {
 			this.#lastAction = null;
 			this.#cursor = this.#value.length;
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorWordLeft")) {
 			this.#moveWordBackwards();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorWordRight")) {
 			this.#moveWordForwards();
-			return;
+			return true;
 		}
 
 		// Regular character input, including Kitty CSI-u text-producing sequences.
 		const printableText = extractPrintableText(data);
-		if (printableText) {
-			this.#insertCharacter(printableText);
-		}
+		if (!printableText) return false;
+		this.#insertCharacter(printableText);
+		return true;
 	}
 
 	/** Apply terminal paste semantics to text from non-bracketed paste transports
@@ -484,6 +508,33 @@ export class Input implements Component, Focusable {
 		// No cached state to invalidate currently
 	}
 
+	/**
+	 * An `input` with the value, the caret as a UTF-16 offset and the prompt;
+	 * the terminal draws the caret, scrolls horizontally and places the IME.
+	 * A masked input sends one bullet per grapheme, with the caret mapped onto
+	 * them, so the secret never leaves the process.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		let value = this.#value;
+		let cursor = this.#cursor;
+		if (this.mask) {
+			const graphemes = [...segmenter.segment(this.#value)];
+			value = "•".repeat(graphemes.length);
+			cursor = graphemes.filter(grapheme => grapheme.index < this.#cursor).length;
+		}
+		const prompt = plainText(this.prompt);
+		const props: TspInputProps = {
+			text: value,
+			cursor,
+			prompt: prompt || undefined,
+			placeholder: this.placeholder,
+		};
+		if (this.#native && sameProps(this.#native.props, props)) return this.#native.node;
+		const described = node("input", props);
+		this.#native = { props, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		width = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
 		// Calculate visible window

package/src/components/key-value-list.ts

@@ -1,3 +1,6 @@
+import { compactText, styleSpans } from "../native/spans";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 
@@ -31,6 +34,7 @@ export class KeyValueList implements Component {
 	#rows: readonly KeyValueRow[];
 	readonly #options: KeyValueListOptions;
 	#cache: { width: number; epoch: number; lines: readonly string[] } | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(rows: readonly KeyValueRow[], options: KeyValueListOptions) {
 		this.#rows = rows;
@@ -41,11 +45,25 @@ export class KeyValueList implements Component {
 		if (this.#rows === rows) return false;
 		this.#rows = rows;
 		this.#cache = undefined;
+		this.#native = undefined;
 		return true;
 	}
 
 	invalidate(): void {
 		this.#cache = undefined;
+		this.#native = undefined;
+	}
+
+	/** An aligned `kv` grid; label width and value wrapping are the terminal's. */
+	describe(_cx: DescribeContext): NativeNode {
+		this.#native ??= node("kv", {
+			layout: "grid",
+			items: this.#rows.map(row => ({
+				k: compactText(styleSpans(singleLine(row.label), row.labelStyle)),
+				v: compactText(styleSpans(singleLine(row.value), row.valueStyle)),
+			})),
+		});
+		return this.#native;
 	}
 
 	render(width: number): readonly string[] {

package/src/components/layout/geometry.ts

@@ -1,3 +1,4 @@
+import type { TspProps, TspSpace } from "@oh-my-pi/pi-wire";
 import type { MouseRoutable } from "../../mouse";
 import type { Component } from "../../tui";
 import { padding, truncateToWidth, visibleWidth } from "../../utils";
@@ -51,6 +52,49 @@ export interface LayoutAllocation {
 	max?: number;
 }
 
+const kNativeAdapter = Symbol("layout.nativeAdapter");
+type AdaptedRenderer = LayoutRenderer & { [kNativeAdapter]?: Component };
+
+/**
+ * Describe child for layout content: components describe themselves; a lazy
+ * row renderer becomes a stable adapter component the native engine renders
+ * as a `rows` fallback (it can only produce width-bound rows).
+ */
+export function nativeLayoutChild(content: LayoutContent): Component {
+	if (typeof content !== "function") return content;
+	const adapted = content as AdaptedRenderer;
+	adapted[kNativeAdapter] ??= { render: width => content(width, undefined) };
+	return adapted[kNativeAdapter];
+}
+
+/** Spacing step standing in for a textual gap decoration (the terminal draws no divider glyphs). */
+export function nativeLayoutGap(decoration: LayoutDecoration | undefined): TspSpace | undefined {
+	const length = layoutDecorationText(decoration).length;
+	if (length === 0) return undefined;
+	if (length === 1) return "xs";
+	if (length === 2) return "sm";
+	return "md";
+}
+
+/** Flex props for one layout slot along `axis` (`w` for rows, `h` for stacks). */
+export function nativeSlotProps(
+	axis: "w" | "h",
+	slot: { fixed?: number; grow?: number; min?: number; max?: number },
+): TspProps<"col"> {
+	const bound = (cells: number): { w: `${number}ch` } | { h: `${number}lines` } =>
+		axis === "w" ? { w: `${cells}ch` } : { h: `${cells}lines` };
+	const fixed = optionalLayoutSize(slot.fixed);
+	if (fixed !== undefined) return { grow: 0, shrink: 0, min: bound(fixed), max: bound(fixed) };
+	const min = optionalLayoutSize(slot.min);
+	const max = optionalLayoutSize(slot.max);
+	return {
+		grow: slot.grow === undefined ? undefined : layoutSize(slot.grow),
+		basis: "content",
+		min: min === undefined || min === 0 ? undefined : bound(min),
+		max: max === undefined ? undefined : bound(max),
+	};
+}
+
 /** 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;

package/src/components/layout/row.ts

@@ -1,4 +1,6 @@
 import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import { col, row } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
 import type { Component } from "../../tui";
 import { padding, visibleWidth } from "../../utils";
 import {
@@ -15,6 +17,9 @@ import {
 	type LayoutInsets,
 	type LayoutRect,
 	layoutSize,
+	nativeLayoutChild,
+	nativeLayoutGap,
+	nativeSlotProps,
 	optionalLayoutSize,
 	renderLayoutContent,
 	uniqueLayoutComponents,
@@ -87,6 +92,7 @@ export class Row implements Component, MouseRoutable {
 	#frames: LayoutRect[] = [];
 	#memo: RowMemo | undefined;
 	#ignoreTight = false;
+	#native: { children: RowChild[]; gap: LayoutDecoration | undefined; node: NativeNode } | undefined;
 
 	constructor(options: RowOptions) {
 		this.#children = options.children.map(child => ({ ...child, padding: { ...child.padding } }));
@@ -168,6 +174,30 @@ export class Row implements Component, MouseRoutable {
 		}
 	}
 
+	/**
+	 * A flex `row`: each child sits in a slot carrying its width bounds
+	 * (fixed → min = max `ch`, else grow/min/max). Decorations become gap
+	 * spacing; clipping and the exact row budget are the terminal's.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const cached = this.#native;
+		if (cached?.children === this.#children && cached.gap === this.#gap) return cached.node;
+		const slots = this.#children.map(child =>
+			col(
+				[nativeLayoutChild(child.content)],
+				nativeSlotProps("w", {
+					fixed: child.width,
+					grow: child.width === undefined ? layoutSize(child.grow, 1) : undefined,
+					min: child.minWidth,
+					max: child.maxWidth,
+				}),
+			),
+		);
+		const described = row(slots, { gap: nativeLayoutGap(this.#gap), align: this.#align });
+		this.#native = { children: this.#children, gap: this.#gap, node: described };
+		return described;
+	}
+
 	/** 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++) {

package/src/components/layout/split-pane.ts

@@ -1,4 +1,7 @@
 import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import type { TspProps } from "@oh-my-pi/pi-wire";
+import { col, node, row } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
 import type { Component } from "../../tui";
 import { visibleWidth } from "../../utils";
 import {
@@ -11,6 +14,9 @@ import {
 	type LayoutRect,
 	layoutRatio,
 	layoutSize,
+	nativeLayoutChild,
+	nativeLayoutGap,
+	nativeSlotProps,
 	optionalLayoutSize,
 	uniqueLayoutComponents,
 } from "./geometry";
@@ -88,6 +94,16 @@ export class SplitPane implements Component, MouseRoutable {
 	#measureMemo: SplitMeasureMemo | undefined;
 	#rowMode: "split" | PaneSide = "split";
 	#rowLeftWidth = -1;
+	#native:
+		| {
+				leftSize: SplitPaneSize;
+				rightMinWidth: number;
+				narrowPane: PaneSide | undefined;
+				divider: LayoutDecoration | undefined;
+				height: number | undefined;
+				node: NativeNode;
+		  }
+		| undefined;
 
 	constructor(options: SplitPaneOptions) {
 		this.#left = options.left;
@@ -268,6 +284,55 @@ export class SplitPane implements Component, MouseRoutable {
 		return geometry;
 	}
 
+	/**
+	 * Two flex slots in a `row`: the left pane fixed (`ch`) or a fraction of
+	 * the width within its bounds, the right pane growing from its minimum.
+	 * With a narrow pane configured the row may wrap, stacking the panes on
+	 * narrow terminals instead of hiding one.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const cached = this.#native;
+		if (
+			cached?.leftSize === this.#leftSize &&
+			cached.rightMinWidth === this.#rightMinWidth &&
+			cached.narrowPane === this.#narrowPane &&
+			cached.divider === this.#divider &&
+			cached.height === this.#height
+		) {
+			return cached.node;
+		}
+		const size = this.#leftSize;
+		const leftProps: TspProps<"col"> =
+			size.fixed !== undefined
+				? nativeSlotProps("w", { fixed: size.fixed })
+				: {
+						...nativeSlotProps("w", { grow: 0, min: size.min, max: size.max }),
+						basis: layoutRatio(size.ratio, 0.5),
+					};
+		const rightProps = nativeSlotProps("w", { grow: 1, min: this.#rightMinWidth });
+		const height = this.#height;
+		const described = row(
+			[
+				node("col", leftProps, [nativeLayoutChild(this.#left)], "left"),
+				node("col", rightProps, [nativeLayoutChild(this.#right)], "right"),
+			],
+			{ gap: nativeLayoutGap(this.#divider), align: this.#align, wrap: this.#narrowPane !== undefined },
+		);
+		const result =
+			height === undefined
+				? described
+				: col([described], { min: { h: `${height}lines` }, max: { h: `${height}lines` } });
+		this.#native = {
+			leftSize: size,
+			rightMinWidth: this.#rightMinWidth,
+			narrowPane: this.#narrowPane,
+			divider: this.#divider,
+			height,
+			node: result,
+		};
+		return result;
+	}
+
 	/** Translate a split-local point into pane-local coordinates. */
 	locate(line: number, col: number): SplitPaneHit | undefined {
 		const panes: readonly [PaneSide, LayoutContent, LayoutRect | undefined][] = [

package/src/components/layout/stack.ts

@@ -1,4 +1,6 @@
 import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import { col } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
 import type { Component } from "../../tui";
 import { padding } from "../../utils";
 import {
@@ -13,6 +15,8 @@ import {
 	type LayoutInsets,
 	type LayoutRect,
 	layoutSize,
+	nativeLayoutChild,
+	nativeSlotProps,
 	optionalLayoutSize,
 	renderLayoutContent,
 	uniqueLayoutComponents,
@@ -76,6 +80,7 @@ export class Stack implements Component, MouseRoutable {
 	#frames: LayoutRect[] = [];
 	#memo: StackMemo | undefined;
 	#ignoreTight = false;
+	#native: { children: StackChild[]; height: number | undefined; node: NativeNode } | undefined;
 
 	constructor(options: StackOptions) {
 		this.#children = options.children.map(child => ({ ...child, padding: { ...child.padding } }));
@@ -141,6 +146,28 @@ export class Stack implements Component, MouseRoutable {
 		}
 	}
 
+	/**
+	 * A `col` of slots carrying each child's height bounds (fixed → min = max
+	 * `lines`, else grow/min/max); an exact stack height bounds the column.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const cached = this.#native;
+		if (cached?.children === this.#children && cached.height === this.#height) return cached.node;
+		const slots = this.#children.map(child =>
+			col(
+				[nativeLayoutChild(child.content)],
+				nativeSlotProps("h", { fixed: child.height, grow: child.grow, min: child.minHeight, max: child.maxHeight }),
+			),
+		);
+		const height = this.#height;
+		const described = col(
+			slots,
+			height === undefined ? undefined : { min: { h: `${height}lines` }, max: { h: `${height}lines` } },
+		);
+		this.#native = { children: this.#children, height, node: described };
+		return described;
+	}
+
 	/** Translate a stack-local point into a child's local coordinates. */
 	locate(line: number, col: number): StackHit | undefined {
 		for (let index = 0; index < this.#frames.length; index++) {