@effected/cli 0.10.0 → 0.11.0

package/ui/Select.js

@@ -0,0 +1,226 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { useScreenCancel } from "./internal/ScreenContext.js";
+import { Styled, useGlyphs, useTerminalSize, useTheme } from "./UiTheme.js";
+import { KeyTable, useKeys } from "./KeyTable.js";
+import { lineText } from "./internal/lineText.js";
+import { KeyHelp } from "./KeyHelp.js";
+import { Viewport } from "./Viewport.js";
+import { Option } from "effect";
+
+//#region src/ui/Select.ts
+const enabled = (choices, index) => index >= 0 && index < choices.length && choices[index]?.disabled !== true;
+/** The nearest enabled index from `from` in `direction`, or `undefined`. */
+const nearest = (choices, from, direction) => {
+	for (let index = from; index >= 0 && index < choices.length; index += direction) if (enabled(choices, index)) return index;
+};
+/** Move the viewport's cursor to `index`, one step at a time so its window follows. */
+const moveTo = (viewport, index) => {
+	let state = viewport;
+	while (state.cursor < index) state = Viewport.step(state, "down");
+	while (state.cursor > index) state = Viewport.step(state, "up");
+	return state;
+};
+const NO_ENABLED_CHOICE = "@effected/cli/ui: Select needs at least one enabled choice";
+const init = (choices, options = {}) => {
+	if (!choices.some((choice) => choice.disabled !== true)) throw new Error(NO_ENABLED_CHOICE);
+	const height = options.height ?? 10;
+	const start = options.initial ?? 0;
+	const first = nearest(choices, start, 1) ?? nearest(choices, start, -1) ?? 0;
+	return {
+		choices,
+		viewport: moveTo(Viewport.init(choices.length, height), first),
+		submitted: false
+	};
+};
+const step = (state, action) => {
+	const { choices, viewport } = state;
+	if (action === "cancel") return state;
+	if (action === "submit") return enabled(choices, viewport.cursor) ? {
+		...state,
+		submitted: true
+	} : state;
+	const last = choices.length - 1;
+	const paged = Viewport.step(viewport, action).cursor;
+	const target = action === "up" ? nearest(choices, viewport.cursor - 1, -1) : action === "down" ? nearest(choices, viewport.cursor + 1, 1) : action === "home" ? nearest(choices, 0, 1) : action === "end" ? nearest(choices, last, -1) : action === "pageup" ? nearest(choices, paged, -1) ?? nearest(choices, paged, 1) : nearest(choices, paged, 1) ?? nearest(choices, paged, -1);
+	return target === void 0 ? state : {
+		...state,
+		viewport: moveTo(viewport, target)
+	};
+};
+/** ↑/↓ shown; the page, home and end moves bound but hidden, so the help line fits 80 columns. */
+const KEYS = KeyTable.make([
+	{
+		keys: ["up"],
+		action: "up",
+		help: "move"
+	},
+	{
+		keys: ["down"],
+		action: "down",
+		help: "move"
+	},
+	{
+		keys: ["pageup"],
+		action: "pageup",
+		help: "page",
+		hidden: true
+	},
+	{
+		keys: ["pagedown"],
+		action: "pagedown",
+		help: "page",
+		hidden: true
+	},
+	{
+		keys: ["home"],
+		action: "home",
+		help: "top",
+		hidden: true
+	},
+	{
+		keys: ["end"],
+		action: "end",
+		help: "bottom",
+		hidden: true
+	},
+	{
+		keys: ["enter"],
+		action: "submit",
+		help: "choose"
+	},
+	{
+		keys: [{ char: "q" }],
+		action: "cancel",
+		help: "cancel"
+	}
+]);
+/** The text mark a disabled row carries at colour `none`, where the muted token paints nothing. */
+const DISABLED = " (disabled)";
+/** Lines around the list: the message above, the detail and the help line below. */
+const RESERVED = 3;
+/**
+* A single choice from a list: a pure reducer, its key table, a view, and a ready-made screen.
+*
+* @remarks
+* A select with no enabled choice is a programming error: `init` throws, and `screen` dies, saying so.
+*
+* @example
+* ```ts
+* import { CliUi, Select } from "@effected/cli/ui"
+* import { Effect } from "effect"
+*
+* const pickTarget = Effect.gen(function* () {
+* 	const target = yield* CliUi.run(
+* 		Select.screen({
+* 			message: "Deploy to which environment?",
+* 			choices: [
+* 				{ label: "staging", value: "staging" },
+* 				{ label: "production", value: "production", detail: "Needs approval" },
+* 			],
+* 		}),
+* 	)
+* 	return target
+* })
+* ```
+*
+* @public
+*/
+var Select = class Select {
+	constructor() {}
+	/**
+	* A select over `choices`, on the first enabled choice at or after `initial` (the nearest enabled one before it
+	* when none follows).
+	*
+	* @param choices - the choices
+	* @param options - the starting choice and the list height
+	*/
+	static init = init;
+	/**
+	* Apply an action: a move lands on the nearest enabled choice, never on a disabled one and never past either
+	* end; `"submit"` marks the highlighted choice chosen (a disabled one never is); `"cancel"` changes nothing here,
+	* because ending the screen is the view's job.
+	*
+	* @param state - where the select is
+	* @param action - the action
+	*/
+	static step = step;
+	/**
+	* The submitted value, or `None` before a submit.
+	*
+	* @param state - where the select is
+	*/
+	static chosen = (state) => {
+		const choice = state.choices[state.viewport.cursor];
+		return state.submitted && choice !== void 0 ? Option.some(choice.value) : Option.none();
+	};
+	/** The keys: the viewport's moves, enter choose, q cancel. */
+	static keys = KEYS;
+	/**
+	* Draw the select: the message, the list (the highlighted row in the accent token with the arrow glyph, disabled
+	* rows muted, and at colour `none` ending in ` (disabled)` instead, every row cut to the width with the glyph set's
+	* ellipsis), the highlighted choice's detail, and the
+	* key help. Enter calls `onSubmit` with the value; `q` cancels the screen with `"escape"`.
+	*
+	* Single-shot: the choices and the starting choice are read once, when the view mounts, and later changes to them
+	* are ignored; after a submit it stays as it is. Render a new view (a new screen) to ask again.
+	*
+	* @param props - the message, the choices, and where the chosen value goes
+	*/
+	static View = (props) => {
+		const { ink, react } = inkModules();
+		const glyphs = useGlyphs();
+		const theme = useTheme();
+		const { columns } = useTerminalSize();
+		const cancel = useScreenCancel();
+		const [state, setState] = react.useState(() => init(props.choices, {
+			...props.initial === void 0 ? {} : { initial: props.initial },
+			...props.height === void 0 ? {} : { height: props.height }
+		}));
+		const submitted = state.submitted;
+		const { onSubmit } = props;
+		react.useEffect(() => {
+			const choice = state.choices[state.viewport.cursor];
+			if (submitted && choice !== void 0) onSubmit(choice.value);
+		}, [submitted]);
+		useKeys(KEYS, (action) => {
+			if (action === "cancel") cancel("escape");
+			else setState((current) => step(current, action));
+		});
+		const rows = props.choices.map((_, index) => ({
+			_tag: "Item",
+			key: String(index)
+		}));
+		const blank = " ".repeat(Fmt.width(glyphs.arrow));
+		const renderRow = (row, highlighted) => {
+			const choice = row._tag === "Item" ? props.choices[Number(row.key)] : void 0;
+			const line = `${highlighted ? glyphs.arrow : blank} ${lineText(choice?.label ?? "")}`;
+			const text = choice?.disabled === true && theme.color === "none" ? `${Fmt.truncate(line, Math.max(0, columns - Fmt.width(DISABLED)), { ellipsis: glyphs.ellipsis })}${DISABLED}` : Fmt.truncate(line, columns, { ellipsis: glyphs.ellipsis });
+			if (highlighted) return react.createElement(Styled, { token: "accent" }, text);
+			if (choice?.disabled === true) return react.createElement(Styled, { token: "muted" }, text);
+			return react.createElement(ink.Text, null, text);
+		};
+		const detail = props.choices[state.viewport.cursor]?.detail;
+		return react.createElement(ink.Box, { flexDirection: "column" }, react.createElement(Styled, { token: "emphasis" }, Fmt.truncate(lineText(props.message), columns, { ellipsis: glyphs.ellipsis })), react.createElement(Viewport.View, {
+			rows,
+			state: state.viewport,
+			renderRow,
+			reserved: RESERVED
+		}), detail === void 0 ? null : react.createElement(Styled, { token: "muted" }, Fmt.truncate(lineText(detail), columns, { ellipsis: glyphs.ellipsis })), react.createElement(KeyHelp, { tables: [KEYS] }));
+	};
+	/**
+	* A ready-made screen for `CliUi.run`: the select, resolving with the chosen value.
+	*
+	* @param options - the message, the choices, the starting choice and the list height
+	*/
+	static screen = (options) => (control) => {
+		if (!options.choices.some((choice) => choice.disabled !== true)) throw new Error(NO_ENABLED_CHOICE);
+		return inkModules().react.createElement(Select.View, {
+			...options,
+			onSubmit: control.resolve
+		});
+	};
+};
+
+//#endregion
+export { Select };

package/ui/Tabs.js

@@ -0,0 +1,202 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { Styled, useGlyphs, useTerminalSize, useTheme } from "./UiTheme.js";
+import { KeyTable, useKeys } from "./KeyTable.js";
+import { lineText } from "./internal/lineText.js";
+
+//#region src/ui/Tabs.ts
+const step = (index, count, action) => {
+	if (count <= 0) return index;
+	if (action === "prev") return (index - 1 + count) % count;
+	if (action === "next") return (index + 1) % count;
+	return action.jump >= 0 && action.jump < count ? action.jump : index;
+};
+/** Plain digits jump: 1 is the first tab, 9 the ninth, 0 the tenth. Bound, but left out of the help line. */
+const DIGITS = [
+	"1",
+	"2",
+	"3",
+	"4",
+	"5",
+	"6",
+	"7",
+	"8",
+	"9",
+	"0"
+].map((digit, index) => ({
+	keys: [{ char: digit }],
+	action: { jump: index },
+	help: "jump",
+	hidden: true
+}));
+const table = (prev, next) => KeyTable.make([
+	{
+		keys: [prev],
+		action: "prev",
+		help: "switch"
+	},
+	{
+		keys: [next],
+		action: "next",
+		help: "switch"
+	},
+	{
+		keys: ["tab"],
+		action: "next",
+		help: "switch"
+	},
+	{
+		keys: ["shift+tab"],
+		action: "prev",
+		help: "switch"
+	},
+	...DIGITS
+]);
+const ROW_KEYS = table("left", "right");
+const COLUMN_KEYS = table("up", "down");
+/** The tabs from `from` to `to` that fit `width` around `active`, widening right then left in turn. */
+const fitAround = (widths, active, gap, width) => {
+	let from = active;
+	let to = active;
+	let used = widths[active] ?? 0;
+	let grew = true;
+	while (grew) {
+		grew = false;
+		const right = widths[to + 1];
+		if (right !== void 0 && used + gap + right <= width) {
+			to++;
+			used += gap + right;
+			grew = true;
+		}
+		const left = widths[from - 1];
+		if (left !== void 0 && used + gap + left <= width) {
+			from--;
+			used += gap + left;
+			grew = true;
+		}
+	}
+	return {
+		from,
+		to
+	};
+};
+/**
+* A row (or column) of tabs, for a consumer's own screen.
+*
+* @remarks
+* Not a screen: render `Tabs.View` inside a consumer's own screen. Its keys come from one `useKeys`, so there is a
+* single input reader. Tab and Shift-Tab cycle whenever the tabs are focused, and plain digits jump, so a screen that
+* hosts Tabs beside another widget reading Tab, arrows or digits (a `TextInput`, say) must decide who has the keys:
+* pass `isFocused: false` to the Tabs while the other widget is being typed into. When unfocused, Tabs reads no key
+* and is drawn muted.
+*
+* @public
+*/
+var Tabs = class {
+	constructor() {}
+	/**
+	* The tab an action lands on: `"prev"` and `"next"` wrap at both ends; `{ jump }` moves to that index and does
+	* nothing when it is out of range.
+	*
+	* @param index - the active tab
+	* @param count - how many tabs there are
+	* @param action - the action
+	*/
+	static step = step;
+	/** The keys of a row: `←`/`→` and Tab/Shift-Tab switch, plain digits 1–9 jump, 0 is the tenth tab. */
+	static keys = ROW_KEYS;
+	/** The keys of a column: `↑`/`↓` in place of `←`/`→`. */
+	static columnKeys = COLUMN_KEYS;
+	/**
+	* Draw the tabs: the active one in the accent token, bold and underlined; the others plain; every tab muted while
+	* unfocused. At colour `"none"`, where all of that vanishes, the active tab is bracketed, `[Alpha]`, and the others
+	* padded a space each side. A row wider than the terminal shows the tabs that fit around the active one, with the
+	* glyph set's ellipsis at a cut edge, so it never wraps.
+	*
+	* @remarks
+	* Controlled when `value` is given: a key calls `onChange` and the active tab moves only when `value` does.
+	* Uncontrolled otherwise, starting at `defaultValue` or the first tab. Either way `onChange` fires once on mount
+	* with the starting tab.
+	*
+	* @param props - the tabs and how they behave
+	*/
+	static View = (props) => {
+		const { ink, react } = inkModules();
+		const glyphs = useGlyphs();
+		const theme = useTheme();
+		const { columns } = useTerminalSize();
+		const indexOf = (name) => name === void 0 ? -1 : props.tabs.findIndex((tab) => tab.name === name);
+		const [own, setOwn] = react.useState(() => Math.max(0, indexOf(props.defaultValue)));
+		const controlled = props.value !== void 0;
+		const index = controlled ? Math.max(0, indexOf(props.value)) : own;
+		const focused = props.isFocused ?? true;
+		const column = props.direction === "column";
+		const { onChange } = props;
+		const at = react.useRef(index);
+		at.current = index;
+		const drawn = react.useRef(index);
+		drawn.current = index;
+		const announced = react.useRef(false);
+		react.useEffect(() => {
+			if (announced.current) return;
+			announced.current = true;
+			const first = props.tabs[index];
+			if (first !== void 0) onChange?.(first.name, index);
+		}, []);
+		useKeys(column ? COLUMN_KEYS : ROW_KEYS, (action) => {
+			const from = at.current;
+			const next = step(from, props.tabs.length, action);
+			const tab = props.tabs[next];
+			if (next === from || tab === void 0) return;
+			at.current = next;
+			if (controlled) queueMicrotask(() => {
+				at.current = drawn.current;
+			});
+			else setOwn(next);
+			onChange?.(tab.name, next);
+		}, { isActive: focused });
+		const labelOf = (position) => `${props.showIndex === true ? `${position + 1}. ` : ""}${lineText(props.tabs[position]?.label ?? "")}`;
+		const plain = theme.color === "none";
+		const marks = plain ? 2 : 0;
+		const marked = (position, text) => plain ? position === index ? `[${text}]` : ` ${text} ` : text;
+		const draw = (position, text) => {
+			if (!focused) return react.createElement(Styled, {
+				key: position,
+				token: position === index ? {
+					...theme.style("muted"),
+					underline: true
+				} : "muted"
+			}, text);
+			return position === index ? react.createElement(Styled, {
+				key: position,
+				token: {
+					...theme.style("accent"),
+					bold: true,
+					underline: true
+				}
+			}, text) : react.createElement(ink.Text, { key: position }, text);
+		};
+		if (column) return react.createElement(ink.Box, { flexDirection: "column" }, ...props.tabs.map((_, position) => react.createElement(ink.Box, { key: position }, draw(position, marked(position, Fmt.truncate(labelOf(position), Math.max(1, columns - marks), { ellipsis: glyphs.ellipsis }))))));
+		const separator = lineText(props.separator ?? (glyphs.kind === "unicode" ? " │ " : " | "));
+		const labels = props.tabs.map((_, position) => marked(position, labelOf(position)));
+		const mark = Fmt.width(glyphs.ellipsis);
+		const { from, to } = labels.reduce((sum, label) => sum + Fmt.width(label), 0) + Fmt.width(separator) * (labels.length - 1) <= columns ? {
+			from: 0,
+			to: labels.length - 1
+		} : fitAround(labels.map((label) => Fmt.width(label)), index, Fmt.width(separator), Math.max(1, columns - 2 * mark));
+		const children = [];
+		if (from > 0) children.push(glyphs.ellipsis);
+		for (let position = from; position <= to; position++) {
+			if (position > from) children.push(separator);
+			const room = Math.max(1, columns - (from > 0 ? mark : 0) - (to < labels.length - 1 ? mark : 0));
+			const label = labels[position] ?? "";
+			const cut = () => marked(position, Fmt.truncate(labelOf(position), Math.max(1, room - marks), { ellipsis: glyphs.ellipsis }));
+			children.push(draw(position, from === to && Fmt.width(label) > room ? cut() : label));
+		}
+		if (to < labels.length - 1) children.push(glyphs.ellipsis);
+		return react.createElement(ink.Text, { wrap: "truncate-end" }, ...children);
+	};
+};
+
+//#endregion
+export { Tabs };

package/ui/TextInput.js

@@ -0,0 +1,250 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { useScreenGuard } from "./internal/ScreenContext.js";
+import { Styled, useGlyphs, useTerminalSize } from "./UiTheme.js";
+import { UiKey } from "./UiKey.js";
+import { KeyTable } from "./KeyTable.js";
+import { lineText } from "./internal/lineText.js";
+import { KeyHelp } from "./KeyHelp.js";
+
+//#region src/ui/TextInput.ts
+const init = (options = {}) => {
+	const value = options.initial ?? "";
+	return {
+		value,
+		cursor: value.length,
+		submitted: false
+	};
+};
+const isHigh = (code) => code >= 55296 && code <= 56319;
+const isLow = (code) => code >= 56320 && code <= 57343;
+/** The code-point boundary before `at`: one code unit back, two when that would land inside a surrogate pair. */
+const previous = (value, at) => at >= 2 && isLow(value.charCodeAt(at - 1)) && isHigh(value.charCodeAt(at - 2)) ? at - 2 : Math.max(0, at - 1);
+/** The code-point boundary after `at`. */
+const following = (value, at) => at + 1 < value.length && isHigh(value.charCodeAt(at)) && isLow(value.charCodeAt(at + 1)) ? at + 2 : Math.min(value.length, at + 1);
+const insert = (state, text) => ({
+	value: state.value.slice(0, state.cursor) + text + state.value.slice(state.cursor),
+	cursor: state.cursor + text.length,
+	submitted: false
+});
+const CONTROLS = /([\u0000-\u001f\u007f])/;
+const PASTE_CONTROLS = /[\u0000-\u001f\u007f]/g;
+/**
+* The keys one Ink input holds. Text read in one go (a fast typist, a paste) reaches `useInput` as one string, controls
+* and all, so it is split at its control characters: the printable runs are typed whole, `\r` is enter (and ends the
+* input: text after a submit is not typed into a submitted field), a backspace byte is backspace, a line feed is a
+* space (a pasted line break separates words in a one-line field), and a tab or any other control is dropped. A named
+* key, or a Ctrl or Meta combination, is the one key Ink reported.
+*/
+const typedKeys = (input, key) => {
+	const single = UiKey.fromInk(input, key);
+	if (single?._tag === "Named" || key.ctrl || key.meta || !CONTROLS.test(input) || [...input].length < 2) return single === void 0 ? [] : [single];
+	const keys = [];
+	for (const piece of input.split(CONTROLS)) {
+		if (piece === "") continue;
+		if (piece === "\r") {
+			keys.push(UiKey.named("enter"));
+			break;
+		}
+		if (piece === "" || piece === "\b") keys.push(UiKey.named("backspace"));
+		else if (piece === "\n") keys.push(UiKey.char(" "));
+		else if (!CONTROLS.test(piece)) keys.push(UiKey.char(piece));
+	}
+	return keys;
+};
+const step = (state, key) => {
+	if (key._tag === "Char") return insert(state, key.char);
+	const { value, cursor } = state;
+	switch (key.name) {
+		case "space": return insert(state, " ");
+		case "backspace": {
+			if (cursor === 0) return state;
+			const from = previous(value, cursor);
+			return {
+				value: value.slice(0, from) + value.slice(cursor),
+				cursor: from,
+				submitted: false
+			};
+		}
+		case "delete": return cursor === value.length ? state : {
+			value: value.slice(0, cursor) + value.slice(following(value, cursor)),
+			cursor,
+			submitted: false
+		};
+		case "left": return {
+			...state,
+			cursor: previous(value, cursor),
+			submitted: false
+		};
+		case "right": return {
+			...state,
+			cursor: following(value, cursor),
+			submitted: false
+		};
+		case "home": return {
+			...state,
+			cursor: 0,
+			submitted: false
+		};
+		case "end": return {
+			...state,
+			cursor: value.length,
+			submitted: false
+		};
+		case "enter": return {
+			...state,
+			submitted: true
+		};
+		default: return state;
+	}
+};
+/** Take code points from the end of `text` while they fit in `width` cells. */
+const tail = (text, width) => {
+	const points = [...text];
+	let out = "";
+	let used = 0;
+	for (let index = points.length - 1; index >= 0; index--) {
+		const point = points[index] ?? "";
+		const cells = Fmt.width(point);
+		if (used + cells > width) break;
+		out = point + out;
+		used += cells;
+	}
+	return out;
+};
+/** Take code points from the start of `text` while they fit in `width` cells. */
+const head = (text, width) => {
+	let out = "";
+	let used = 0;
+	for (const point of text) {
+		const cells = Fmt.width(point);
+		if (used + cells > width) break;
+		out += point;
+		used += cells;
+	}
+	return out;
+};
+/**
+* The text either side of the cursor, scrolled so the line fits `width` cells and the cursor stays in view: a cut
+* edge is marked with the ellipsis, the text after the cursor keeps up to a third of the room, and the text before
+* it the rest.
+*/
+const windowAround = (before, after, width, ellipsis) => {
+	if (Fmt.width(before) + Fmt.width(after) <= width) return [before, after];
+	const mark = Fmt.width(ellipsis);
+	const beforeRoom = width - Math.min(Fmt.width(after), Math.floor(width / 3));
+	const shownBefore = Fmt.width(before) <= beforeRoom ? before : beforeRoom > mark ? `${ellipsis}${tail(before, beforeRoom - mark)}` : tail(before, Math.max(0, beforeRoom));
+	const room = Math.max(0, width - Fmt.width(shownBefore));
+	return [shownBefore, Fmt.width(after) <= room ? after : room > mark ? `${head(after, room - mark)}${ellipsis}` : head(after, room)];
+};
+/** Shown in the help line only; the input reads every key itself. */
+const HELP = KeyTable.make([{
+	keys: ["enter"],
+	action: "submit",
+	help: "submit"
+}]);
+/**
+* One line of text: a pure reducer, a view and a ready-made screen.
+*
+* @remarks
+* Every typed character is text, `q` included: the input binds no letter, so Esc and Ctrl-C are the screen's root
+* keys and still cancel with `"escape"` and `"interrupt"`.
+*
+* @example
+* ```ts
+* import { CliUi, TextInput } from "@effected/cli/ui"
+* import { Effect } from "effect"
+*
+* const askName = Effect.gen(function* () {
+* 	const name = yield* CliUi.run(
+* 		TextInput.screen({
+* 			message: "Package name?",
+* 			placeholder: "my-package",
+* 			validate: (value) => (value.trim() === "" ? "A name is required" : undefined),
+* 		}),
+* 	)
+* 	return name
+* })
+* ```
+*
+* @public
+*/
+var TextInput = class TextInput {
+	constructor() {}
+	/**
+	* An input holding `initial`, the cursor after it.
+	*
+	* @param options - the starting text
+	*/
+	static init = init;
+	/**
+	* Apply a key: a typed character (any, `q` included) or space is inserted at the cursor; backspace and delete
+	* remove around it; left, right, home and end move it, clamped to the text; enter marks it submitted. Every other
+	* key changes nothing.
+	*
+	* @param state - where the input is
+	* @param key - the key pressed
+	*/
+	static step = step;
+	/**
+	* Draw the input: the message, the value with the cursor shown as `▏` (`|` under ASCII glyphs, so it stays visible
+	* without colour), the placeholder while empty, a validation message in the error token, and the key help. Enter
+	* submits when `validate` passes; otherwise its message is shown until the next key other than enter, or a paste.
+	*
+	* @remarks
+	* Text read in one go (a fast typist) is typed as it reads: printable runs are inserted whole, a return submits
+	* what came before it (anything after it is dropped), a backspace byte deletes, a line feed becomes a space, and a
+	* tab or other control character is dropped. A bracketed paste is inserted as text, its line breaks as spaces, and
+	* never submits.
+	*
+	* @param props - the message, the starting text, the placeholder, the validator and where the value goes
+	*/
+	static View = (props) => {
+		const { ink, react } = inkModules();
+		const glyphs = useGlyphs();
+		const { columns } = useTerminalSize();
+		const [state, setState] = react.useState(() => init(props.initial === void 0 ? {} : { initial: props.initial }));
+		const [error, setError] = react.useState(void 0);
+		const { validate, onSubmit } = props;
+		react.useEffect(() => {
+			if (!state.submitted) return;
+			const problem = validate?.(state.value);
+			if (problem === void 0) onSubmit(state.value);
+			else {
+				setError(problem);
+				setState((current) => ({
+					...current,
+					submitted: false
+				}));
+			}
+		}, [state.submitted]);
+		const guard = useScreenGuard();
+		ink.usePaste(guard((text) => {
+			const typed = text.replace(/\r\n|\r|\n/g, " ").replace(PASTE_CONTROLS, "");
+			if (typed === "") return;
+			setError(void 0);
+			setState((current) => step(current, UiKey.char(typed)));
+		}));
+		ink.useInput(guard((input, key) => {
+			const keys = typedKeys(input, key);
+			if (keys.some((pressed) => pressed._tag === "Named" && (pressed.name === "escape" || pressed.name === "ctrl+c"))) return;
+			if (keys.some((pressed) => !(pressed._tag === "Named" && pressed.name === "enter"))) setError(void 0);
+			for (const pressed of keys) setState((current) => step(current, pressed));
+		}));
+		const cursorGlyph = glyphs.kind === "unicode" ? "▏" : "|";
+		const [before, after] = windowAround(state.value.slice(0, state.cursor), state.value.slice(state.cursor), columns - Fmt.width(cursorGlyph), glyphs.ellipsis);
+		return react.createElement(ink.Box, { flexDirection: "column" }, react.createElement(Styled, { token: "emphasis" }, Fmt.truncate(lineText(props.message), columns, { ellipsis: glyphs.ellipsis })), react.createElement(ink.Text, null, before, cursorGlyph, after, state.value === "" && props.placeholder !== void 0 ? react.createElement(Styled, { token: "muted" }, Fmt.truncate(lineText(props.placeholder), Math.max(0, columns - Fmt.width(cursorGlyph)), { ellipsis: glyphs.ellipsis })) : null), error === void 0 ? null : react.createElement(Styled, { token: "error" }, Fmt.truncate(lineText(error), columns, { ellipsis: glyphs.ellipsis })), react.createElement(KeyHelp, { tables: [HELP] }));
+	};
+	/**
+	* A ready-made screen for `CliUi.run`: the input, resolving with the submitted text.
+	*
+	* @param options - the message, the starting text, the placeholder and the validator
+	*/
+	static screen = (options) => (control) => inkModules().react.createElement(TextInput.View, {
+		...options,
+		onSubmit: control.resolve
+	});
+};
+
+//#endregion
+export { TextInput };