@estebanforge/pi-tui-dialogs 0.1.1 → 0.1.3

package/README.md

@@ -12,6 +12,12 @@ Dialog pattern adapted from
 - `frameDialog` / `dialogHeight` / `DIALOG_OPTIONS` — shared rounded frame:
   title in the top border, body, footer line above the bottom border, padded to
   a stable height so centered overlays do not jump between views.
+- `dialogBlocked(title)` — the pi 1.5.1 overlay `blocked` option payload
+  (`{ kind: "question", message: title }`): pi reports the overlay as waiting
+  on user input (OSC 7501) until `done()`, also while hidden. `dialogMenu`,
+  `dialogInput`, and `dialogChoice` pass it for you; hand-rolled overlays can
+  spread it into their own `ctx.ui.custom` options. Hosts older than pi 1.5.1
+  ignore the field.
 - `DialogMenu` / `dialogMenu` — framed menu with `label │ value` rows, a
   counter line, a muted help panel for the selected row, optional tab groups
   (left/right to switch) and type-to-search within the active tab. Rows with
@@ -20,12 +26,18 @@ Dialog pattern adapted from
 - `dialogInput` — framed single-line input with placeholder, help lines, and
   optional `validate`: return an error string to keep the dialog open with the
   message inline, return `undefined` to accept.
+- `dialogChoice` — framed single-choice modal: one decision statement (wraps),
+  a closed option list of 1 to `MAX_CHOICE_OPTIONS` (10) options with unique
+  values and an optional preselect. Enter resolves the chosen option's value;
+  esc resolves `undefined` (the escape hatch). Caller-contract violations (0
+  or >10 options, duplicate values, unknown preselect) throw before any
+  overlay opens.
 - `canOpenDialog` — headless guard for non-TUI modes.
 
 ## Usage
 
 ```ts
-import { canOpenDialog, dialogInput, dialogMenu, DialogMenu } from "@estebanforge/pi-tui-dialogs";
+import { canOpenDialog, dialogChoice, dialogInput, dialogMenu, DialogMenu } from "@estebanforge/pi-tui-dialogs";
 
 await ctx.ui.custom(
 	(host, theme, _keys, done) =>
@@ -47,6 +59,20 @@ await ctx.ui.custom(
 );
 ```
 
+A closed choice reads the same way:
+
+```ts
+const engine = await dialogChoice(ctx, "Choose your engine", {
+	description: "Which engine runs your turns? Switch anytime with /engine.",
+	options: [
+		{ value: "fast", label: "Fast", description: "default · lighter" },
+		{ value: "deep", label: "Deep", description: "downloads a big binary" },
+	],
+	selected: "fast",
+});
+// engine === undefined means esc: decide later, persist nothing.
+```
+
 Plain library, no Pi entrypoint: depend on it and Pi installs it transitively.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-tui-dialogs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Framed TUI dialog kit for @estebanforge Pi extensions: bordered settings menus with label/value columns, help panel, tabs, type-to-search, and validated input dialogs. Dialog pattern adapted from pi-subagent-manager (MIT). Plain library, no Pi entrypoint: consumers depend on it and Pi installs it transitively.",
   "keywords": [
     "pi",
@@ -33,7 +33,7 @@
     ".": "./src/index.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.5.1",
     "@earendil-works/pi-tui": "^1.0.0"
   },
   "peerDependenciesMeta": {

package/src/choice.ts

@@ -0,0 +1,153 @@
+// Framed single-choice modal: one decision statement plus a closed list of
+// options, esc cancels. SelectList inside the shared frame. Pattern extracted
+// from pi-antigravity-bridge's first-run engine picker.
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { wrapTextWithAnsi, type SelectItem, SelectList } from "@earendil-works/pi-tui";
+import { DIALOG_OPTIONS, dialogBlocked, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
+import type { DialogContext } from "./menu.js";
+
+/** Hard cap on the option list. A closed choice stays scannable; past ten
+ *  options the caller should filter or paginate before asking. */
+export const MAX_CHOICE_OPTIONS = 10;
+
+/** One closed choice. Values are the resolved contract: they must be unique
+ *  and stable across releases (callers persist them). */
+export interface ChoiceOption {
+	value: string;
+	label: string;
+	/** One-line hint under the label; the list truncates long lines. */
+	description?: string;
+}
+
+export interface ChoiceDialogOptions {
+	/** Options in answer order; the first is preselected unless `selected`. */
+	options: ChoiceOption[];
+	/** What the user is deciding; wraps to the frame width. */
+	description?: string;
+	/** Preselected option value; must match one option. */
+	selected?: string;
+	/** Footer hint; default "↑↓ navigate · enter select · esc cancel". */
+	footer?: string | readonly string[];
+}
+
+/** Caller-contract validation. Throws before any overlay opens: a choice
+ *  modal rendered with 0 options, duplicate values, or a bogus preselect is
+ *  a programming error, not a user-facing state. Used directly by ChoiceView
+ *  (sync throw) and by dialogChoice (which rejects). */
+export function assertChoiceOptions(options: ChoiceOption[], selected?: string): void {
+	if (options.length < 1) {
+		throw new RangeError(`dialogChoice needs at least 1 option, got ${options.length}`);
+	}
+	if (options.length > MAX_CHOICE_OPTIONS) {
+		throw new RangeError(`dialogChoice takes at most ${MAX_CHOICE_OPTIONS} options, got ${options.length}`);
+	}
+	const seen = new Set<string>();
+	for (const option of options) {
+		if (seen.has(option.value)) {
+			throw new RangeError(`dialogChoice options have duplicate value "${option.value}"`);
+		}
+		seen.add(option.value);
+	}
+	if (selected !== undefined && !seen.has(selected)) {
+		throw new RangeError(`dialogChoice selected "${selected}" matches no option`);
+	}
+}
+
+/** Hostable framed choice component. `done` resolves the decision: the
+ *  chosen value, or undefined on esc. Render it inside your own overlay and
+ *  route input to it while it is active. */
+export class ChoiceView {
+	private readonly list: SelectList;
+	private settled = false;
+
+	constructor(
+		private host: DialogHost,
+		private theme: Theme,
+		readonly title: string,
+		readonly options: ChoiceDialogOptions,
+		private readonly done: (value: string | undefined) => void,
+	) {
+		assertChoiceOptions(options.options, options.selected);
+		const items: SelectItem[] = options.options.map((option) => ({
+			value: option.value,
+			label: dialogText(option.label),
+			description: option.description === undefined ? undefined : dialogText(option.description),
+		}));
+		this.list = new SelectList(items, items.length, {
+			selectedPrefix: (t: string) => theme.fg("accent", t),
+			selectedText: (t: string) => theme.fg("accent", t),
+			description: (t: string) => theme.fg("muted", t),
+			scrollInfo: (t: string) => theme.fg("dim", t),
+			noMatch: (t: string) => theme.fg("warning", t),
+		});
+		if (options.selected !== undefined) {
+			this.list.setSelectedIndex(items.findIndex((item) => item.value === options.selected));
+		}
+		this.list.onSelect = (item) => this.finish(item.value);
+		this.list.onCancel = () => this.finish(undefined);
+	}
+
+	private finish(value: string | undefined): void {
+		if (this.settled) return;
+		this.settled = true;
+		this.done(value);
+	}
+
+	handleInput(data: string): void {
+		this.list.handleInput(data);
+		this.host.requestRender();
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const inner = Math.max(1, width - 4);
+		const height = dialogHeight(this.host);
+		const descriptionLines = this.options.description
+			? wrapTextWithAnsi(dialogText(this.options.description), inner).map((line) =>
+					this.theme.fg("muted", ` ${line}`),
+				)
+			: [];
+		// Window the list to what the frame can actually show (DialogMenu's
+		// viewport rule). frameDialog clips the body to height - 4; without
+		// this the SelectList would render all options and let the selection
+		// move into clipped, invisible lines on short terminals or with long
+		// descriptions. The - 3 covers the two blank separators plus the
+		// "(n/m)" scroll line SelectList appends whenever the list is windowed
+		// (clipping that line hides the position hint). maxVisible is
+		// compile-time private on SelectList but a plain field at runtime;
+		// re-assigning it per render is the intended windowing knob (the
+		// constructor value only sized the initial view).
+		const listBudget = Math.max(1, height - 4 - descriptionLines.length - 3);
+		(this.list as unknown as { maxVisible: number }).maxVisible = listBudget;
+		return frameDialog(
+			this.theme,
+			width,
+			dialogHeight(this.host),
+			this.title,
+			[
+				"",
+				...descriptionLines,
+				"",
+				...this.list.render(inner).map((line) => ` ${line}`),
+			],
+			this.options.footer ?? "↑↓ navigate · enter select · esc cancel",
+		);
+	}
+}
+
+/** Run one framed choice overlay. Resolves with the chosen option value, or
+ *  undefined when cancelled (esc). Contract violations reject the promise
+ *  before the overlay opens. */
+export async function dialogChoice(
+	ctx: DialogContext,
+	title: string,
+	options: ChoiceDialogOptions,
+): Promise<string | undefined> {
+	// Fail before the overlay opens so a bad caller contract cannot flash UI.
+	assertChoiceOptions(options.options, options.selected);
+	return ctx.ui.custom<string | undefined>(
+		(host, theme, _keys, done) => new ChoiceView(host, theme, title, options, done),
+		{ ...DIALOG_OPTIONS, blocked: dialogBlocked(title) },
+	);
+}

package/src/frame.ts

@@ -23,6 +23,14 @@ export const DIALOG_OPTIONS = {
 	},
 } as const;
 
+/** Blocked program status (OSC 7501) for a dialog overlay: pi reports the
+ *  overlay as waiting on user input until done(), also while hidden. Hosts
+ *  older than pi 1.5.1 ignore the field. Pi's own selectors use the same
+ *  convention: kind "question", message = dialog title. */
+export function dialogBlocked(title: string): { kind: "question"; message: string } {
+	return { kind: "question", message: title };
+}
+
 /** Strip ANSI and control characters from untrusted row text. */
 export function dialogText(text: string): string {
 	return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f-\x9f]/g, " ");

package/src/index.ts

@@ -2,6 +2,7 @@
 // adapted from pi-subagent-manager (MIT); see LICENSE for attribution.
 export {
 	DIALOG_OPTIONS,
+	dialogBlocked,
 	dialogHeight,
 	dialogText,
 	frameDialog,
@@ -17,3 +18,11 @@ export {
 	type DialogTab,
 } from "./menu.js";
 export { dialogInput, InputView, type DialogInputOptions } from "./input.js";
+export {
+	assertChoiceOptions,
+	ChoiceView,
+	dialogChoice,
+	MAX_CHOICE_OPTIONS,
+	type ChoiceDialogOptions,
+	type ChoiceOption,
+} from "./choice.js";

package/src/input.ts

@@ -4,7 +4,7 @@
 // (MIT, Copyright (c) 2026 pi-subagent contributors).
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Input, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { DIALOG_OPTIONS, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
+import { DIALOG_OPTIONS, dialogBlocked, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
 import type { DialogContext } from "./menu.js";
 
 export interface DialogInputOptions {
@@ -102,6 +102,6 @@ export function dialogInput(
 ): Promise<string | undefined> {
 	return ctx.ui.custom<string | undefined>(
 		(host, theme, _keys, done) => new InputView(host, theme, title, options, done),
-		DIALOG_OPTIONS,
+		{ ...DIALOG_OPTIONS, blocked: dialogBlocked(title) },
 	);
 }

package/src/menu.ts

@@ -5,7 +5,7 @@
 // contributors.
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { getKeybindings, matchesKey, Key, truncateToWidth, visibleWidth, wrapTextWithAnsi, type SettingItem } from "@earendil-works/pi-tui";
-import { DIALOG_OPTIONS, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
+import { DIALOG_OPTIONS, dialogBlocked, dialogHeight, dialogText, frameDialog, type DialogHost } from "./frame.js";
 
 /** A menu row is a pi-tui SettingItem; `onEdit` additionally opens a custom
  *  editor (input dialog, submenu) on Enter and keeps the menu open. Rows with
@@ -250,7 +250,7 @@ export function dialogMenu(
 	return ctx.ui.custom(
 		(host, theme, _keys, done) =>
 			new DialogMenu(host, theme, { title, rows, ...options }, done),
-		DIALOG_OPTIONS,
+		{ ...DIALOG_OPTIONS, blocked: dialogBlocked(title) },
 	);
 }