@effected/cli-kit 0.0.0-stage → 0.26.0

package/ui/Confirm.js

@@ -0,0 +1,244 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { lineText } from "./internal/lineText.js";
+import { useScreenCancel } from "./internal/ScreenContext.js";
+import { KeyHelp } from "./KeyHelp.js";
+import { KeyTable, useKeys } from "./KeyTable.js";
+import { Toggle } from "./Toggle.js";
+import { Styled, useGlyphs, useTerminalSize } from "./UiTheme.js";
+import { Viewport } from "./Viewport.js";
+
+// src/ui/Confirm.ts
+const assertUniqueKeys = (toggles) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const toggle of toggles) {
+		if (seen.has(toggle.key)) throw new Error(`@effected/cli-kit/ui: Confirm toggle keys must be unique; "${toggle.key}" repeats`);
+		seen.add(toggle.key);
+	}
+};
+const init = (options = {}) => {
+	const toggles = options.toggles ?? [];
+	assertUniqueKeys(toggles);
+	return {
+		confirmed: options.initial ?? false,
+		row: 0,
+		toggles,
+		submitted: false
+	};
+};
+const step = (state, action) => {
+	switch (action) {
+		case "up": return {
+			...state,
+			row: Math.max(0, state.row - 1)
+		};
+		case "down": return {
+			...state,
+			row: Math.min(state.toggles.length, state.row + 1)
+		};
+		case "toggle": return state.row === 0 ? state : {
+			...state,
+			toggles: state.toggles.map((toggle, index) => index === state.row - 1 ? {
+				...toggle,
+				value: !toggle.value
+			} : toggle)
+		};
+		case "yes": return {
+			...state,
+			confirmed: true
+		};
+		case "no": return {
+			...state,
+			confirmed: false
+		};
+		case "flip": return {
+			...state,
+			confirmed: !state.confirmed
+		};
+		case "submit": return {
+			...state,
+			submitted: true
+		};
+		case "cancel": return state;
+	}
+};
+const result = (state) => ({
+	confirmed: state.confirmed,
+	toggles: Object.fromEntries(state.toggles.map((toggle) => [toggle.key, toggle.value]))
+});
+/** The bindings; with no toggles the row and toggle keys stay bound (they do nothing) but leave the help line. */
+const bindings = (toggles) => KeyTable.make([
+	{
+		keys: [{ char: "y" }],
+		action: "yes",
+		help: "yes"
+	},
+	{
+		keys: [{ char: "n" }],
+		action: "no",
+		help: "no"
+	},
+	{
+		keys: ["left"],
+		action: "flip",
+		help: "flip"
+	},
+	{
+		keys: ["right"],
+		action: "flip",
+		help: "flip"
+	},
+	{
+		keys: ["up"],
+		action: "up",
+		help: "row",
+		hidden: !toggles
+	},
+	{
+		keys: ["down"],
+		action: "down",
+		help: "row",
+		hidden: !toggles
+	},
+	{
+		keys: ["space"],
+		action: "toggle",
+		help: "toggle",
+		hidden: !toggles
+	},
+	{
+		keys: ["enter"],
+		action: "submit",
+		help: "submit"
+	},
+	{
+		keys: [{ char: "q" }],
+		action: "cancel",
+		help: "cancel"
+	}
+]);
+const KEYS = bindings(true);
+const ANSWER_KEYS = bindings(false);
+/** The lines around the toggle rows: the question, the answer row and the help line. */
+const RESERVED = 3;
+/**
+* A yes/no question, optionally with extra on/off rows beneath it: a pure reducer, its key table, a view and a
+* ready-made screen.
+*
+* @remarks
+* The rows are the yes/no row first, then each toggle. `y` and `n` set the answer and `←`/`→` flip it, from any
+* row; `↑`/`↓` move between rows; space flips the highlighted toggle and does nothing on the yes/no row; enter
+* submits; `q` cancels with `"escape"`. Toggle keys must be unique; `init` throws, and `screen` dies, on a repeat.
+* With no toggles, the help line leaves out the row and toggle keys. Toggles that do not fit the terminal scroll
+* in a window under the answer row, so the question, the answer and the help line stay on screen.
+* The answer starts as no unless `initial` says otherwise, and `←`/`→` flip it whichever row is highlighted.
+*
+* A toggle passed conditionally is absent from the result when it was left out, so read it back with a fallback:
+*
+* ```ts
+* import { CliUi, Confirm } from "@effected/cli-kit/ui"
+* import { Effect } from "effect"
+*
+* const publish = (drafts: number) =>
+*   Effect.gen(function* () {
+*     const { confirmed, toggles } = yield* CliUi.run(
+*       Confirm.screen({
+*         message: "Publish the release?",
+*         toggles: drafts > 0 ? [{ key: "promote", label: `promote ${drafts} drafts to stable`, value: true }] : [],
+*       }),
+*     )
+*     const promote = toggles.promote ?? false
+*     return { confirmed, promote }
+*   })
+* ```
+*
+* @public
+*/
+var Confirm = class Confirm {
+	constructor() {}
+	/**
+	* A confirm with its answer (no by default) and toggles, on the yes/no row.
+	*
+	* @param options - the starting answer and the toggles
+	*/
+	static init = init;
+	/**
+	* Apply an action (see the class remarks for what each key does).
+	*
+	* @param state - where the confirm is
+	* @param action - the action
+	*/
+	static step = step;
+	/**
+	* The answer and every toggle's value by key.
+	*
+	* @param state - where the confirm is
+	*/
+	static result = result;
+	/** The keys: y yes, n no, ←/→ flip, ↑/↓ row, space toggle, enter submit, q cancel (the view hides row and toggle from its help when there are no toggles). */
+	static keys = KEYS;
+	/**
+	* Draw the confirm: the question, the answer row (`[Yes]  No` or ` Yes  [No]`, the chosen answer in brackets so it
+	* shows without colour, and in the accent token), a {@link Toggle} row per toggle, and the key help.
+	*
+	* @remarks
+	* Single-shot, like `Select.View`: the options are read once at mount.
+	*
+	* @param props - the question, the starting answer, the toggles and where the result goes
+	*/
+	static View = (props) => {
+		const { ink, react } = inkModules();
+		const glyphs = useGlyphs();
+		const { columns } = useTerminalSize();
+		const cancel = useScreenCancel();
+		const [state, setState] = react.useState(() => init({
+			...props.initial === void 0 ? {} : { initial: props.initial },
+			...props.toggles === void 0 ? {} : { toggles: props.toggles }
+		}));
+		const { onSubmit } = props;
+		react.useEffect(() => {
+			if (state.submitted) onSubmit(result(state));
+		}, [state.submitted]);
+		const keys = state.toggles.length === 0 ? ANSWER_KEYS : KEYS;
+		useKeys(keys, (action) => {
+			if (action === "cancel") cancel("escape");
+			else setState((current) => step(current, action));
+		});
+		const toggleRows = state.toggles.map((toggle) => ({
+			_tag: "Item",
+			key: toggle.key
+		}));
+		const numberOf = new Map(state.toggles.map((toggle, index) => [toggle.key, index]));
+		const ellipsis = { ellipsis: glyphs.ellipsis };
+		const lead = state.row === 0 ? glyphs.arrow : " ".repeat(Fmt.width(glyphs.arrow));
+		const answer = (label, chosen) => chosen ? react.createElement(Styled, { token: "accent" }, `[${label}]`) : react.createElement(ink.Text, null, ` ${label} `);
+		return react.createElement(ink.Box, { flexDirection: "column" }, react.createElement(Styled, { token: "emphasis" }, Fmt.truncate(lineText(props.message), columns, ellipsis)), react.createElement(ink.Text, null, `${lead} `, answer("Yes", state.confirmed), " ", answer("No", !state.confirmed)), state.toggles.length === 0 ? null : react.createElement(Viewport.View, {
+			rows: toggleRows,
+			state: Viewport.init(state.toggles.length, state.toggles.length, Math.max(0, state.row - 1)),
+			reserved: RESERVED,
+			renderRow: (row) => {
+				const index = row._tag === "Item" ? numberOf.get(row.key) ?? 0 : 0;
+				const toggle = state.toggles[index];
+				return react.createElement(Toggle.View, {
+					label: toggle?.label ?? "",
+					value: toggle?.value ?? false,
+					highlighted: state.row === index + 1
+				});
+			}
+		}), react.createElement(KeyHelp, { tables: [keys] }));
+	};
+	/**
+	* A ready-made screen for `CliUi.run`: the confirm, resolving with the answer and the toggles.
+	*
+	* @param options - the question, the starting answer and the toggles
+	*/
+	static screen = (options) => (control) => {
+		assertUniqueKeys(options.toggles ?? []);
+		return inkModules().react.createElement(Confirm.View, {
+			...options,
+			onSubmit: control.resolve
+		});
+	};
+};
+
+export { Confirm };

package/ui/DocView.js

@@ -0,0 +1,76 @@
+import { identity } from "../internal/displayPath.js";
+import { Render } from "../Render.js";
+import { fromReact, inkModules } from "./internal/ink.js";
+import { screenContext } from "./internal/ScreenContext.js";
+import { useTerminalSize } from "./UiTheme.js";
+
+// src/ui/DocView.ts
+const OUTSIDE = "@effected/cli-kit/ui: DocView was drawn with no ctx outside a screen, a live view or a UiProvider, so it has no theme";
+/** The context a `DocView` builds from its tree's theme: the theme's own paint, so token overrides hold. */
+const contextOf = (theme, width, neutralize, displayPath) => ({
+	...neutralize ? { neutralizeWorkflowCommands: true } : {},
+	width,
+	audience: "human",
+	color: theme.color,
+	paint: theme.paint,
+	glyphs: theme.glyphs,
+	link: (_target, label) => label,
+	displayPath
+});
+/** The document's lines as the kit's own renderer lays them out: plain at colour `none`, painted otherwise. */
+const linesOf = (doc, ctx) => {
+	const document = Array.isArray(doc) ? doc : [doc];
+	const text = ctx.color === "none" ? Render.plain(document, ctx) : Render.ansi(document, ctx);
+	return text === "" ? [] : text.split("\n");
+};
+/** The view, memoised on its props and built on the loaded React, like every kit component. */
+const docView = fromReact((react) => {
+	const View = (props) => {
+		const { ink } = inkModules();
+		const screen = react.useContext(screenContext());
+		const { columns } = useTerminalSize();
+		const given = props.ctx;
+		const theme = screen?.theme;
+		const neutralize = screen?.neutralizeWorkflowCommands === true;
+		const displayPath = screen?.displayPath ?? identity;
+		if (given === void 0 && theme === void 0) throw new Error(OUTSIDE);
+		const ctx = react.useMemo(() => given ?? contextOf(theme, columns, neutralize, displayPath), [
+			given,
+			theme,
+			columns,
+			neutralize,
+			displayPath
+		]);
+		const lines = react.useMemo(() => linesOf(props.doc, ctx), [props.doc, ctx]);
+		return react.createElement(ink.Box, {
+			flexDirection: "column",
+			flexShrink: 0
+		}, ...lines.map((line, index) => react.createElement(ink.Text, {
+			key: index,
+			wrap: "truncate-end"
+		}, line === "" ? " " : line)));
+	};
+	View.displayName = "CliUiDocView";
+	return react.memo(View);
+});
+/**
+* The kit's document IR (`Doc`) drawn as Ink rows, laid out by the kit's own renderers, so a live view and a static
+* report show a document the same way.
+*
+* @remarks
+* The document is rendered with `Render.ansi` (`Render.plain` at colour `none`) at the width, and each line becomes
+* one Ink `Text` row cut with `wrap: "truncate-end"`, so Ink never re-wraps what the renderer laid out. Everything the
+* static renderers do holds: a collapsible is drawn open, an annotation is skipped, text from data is sanitised.
+*
+* Without a `ctx` the view takes its theme from the tree (a screen, a live view, or a `UiProvider`) and its width from
+* `useTerminalSize`, so it follows a resize; for an agent the theme is colourless, so the view is escape-free. Links
+* are off. The layout is memoised on the document's identity and the context: re-render with the same document, as a
+* live view's tick does, and the renderer does not run again; build a new document only when it changes.
+*
+* @param props - the document, and optionally the render context
+*
+* @public
+*/
+const DocView = (props) => inkModules().react.createElement(docView(), props);
+
+export { DocView };

package/ui/KeyHelp.js

@@ -0,0 +1,61 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { lineText } from "./internal/lineText.js";
+import { KeyTable } from "./KeyTable.js";
+import { Styled, useGlyphs, useTerminalSize } from "./UiTheme.js";
+
+// src/ui/KeyHelp.ts
+/** The fewest cells worth giving the widget's own keys when the line is cut; below it they are left out. */
+const MIN_OWN = 4;
+/**
+* A one-line footer naming every visible binding of the given tables, then the root keys:
+* `↑/↓ move · space toggle · enter continue · esc cancel`.
+*
+* @remarks
+* Drawn from the same tables that dispatch the keys, so the help cannot name a key the screen ignores. Neighbouring
+* rows with the same help share one entry (`↑/↓ move`). It stays one line, cut to the terminal width with the glyph
+* set's ellipsis; when it must be cut, the widget's own keys give way and the root hint (`esc cancel`) stays whole at
+* the end. Painted with the `muted` token; labels follow the screen's glyph set.
+*
+* @param props - the tables, and whether to append the root keys
+*
+* @public
+*/
+const KeyHelp = (props) => {
+	const glyphs = useGlyphs();
+	const { columns } = useTerminalSize();
+	const separator = glyphs.kind === "unicode" ? " · " : " | ";
+	const rowsOf = (tables) => {
+		const rows = [];
+		for (const drawn of tables.flatMap((table) => table.help(glyphs))) {
+			const row = {
+				label: lineText(drawn.label),
+				help: lineText(drawn.help)
+			};
+			const previous = rows.at(-1);
+			if (previous !== void 0 && previous.help === row.help) previous.label = `${previous.label}/${row.label}`;
+			else rows.push({ ...row });
+		}
+		return rows;
+	};
+	const ownRows = rowsOf(props.tables);
+	const rootRows = props.root === false ? [] : rowsOf([KeyTable.root]);
+	const lastOwn = ownRows.at(-1);
+	const firstRoot = rootRows[0];
+	if (lastOwn !== void 0 && firstRoot !== void 0 && lastOwn.help === firstRoot.help) {
+		rootRows[0] = {
+			label: `${lastOwn.label}/${firstRoot.label}`,
+			help: firstRoot.help
+		};
+		ownRows.pop();
+	}
+	const own = ownRows.map((row) => `${row.label} ${row.help}`).join(separator);
+	const root = rootRows.map((row) => `${row.label} ${row.help}`).join(separator);
+	const whole = [own, root].filter((part) => part !== "").join(separator);
+	const ellipsis = { ellipsis: glyphs.ellipsis };
+	const room = columns - Fmt.width(separator) - Fmt.width(root);
+	const line = Fmt.width(whole) <= columns || root === "" || own === "" ? Fmt.truncate(whole, columns, ellipsis) : room >= MIN_OWN ? `${Fmt.truncate(own, room, ellipsis)}${separator}${root}` : Fmt.truncate(root, columns, ellipsis);
+	return inkModules().react.createElement(Styled, { token: "muted" }, line);
+};
+
+export { KeyHelp };

package/ui/KeyTable.js

@@ -0,0 +1,198 @@
+import { graphemes } from "../internal/displayWidth.js";
+import { inkModules } from "./internal/ink.js";
+import { useScreenGuard } from "./internal/ScreenContext.js";
+import { UiKey } from "./UiKey.js";
+import { Option } from "effect";
+
+// src/ui/KeyTable.ts
+/** Arrows under a Unicode glyph set; everything else, and everything under ASCII, as words. */
+const ARROWS = {
+	up: "↑",
+	down: "↓",
+	left: "←",
+	right: "→"
+};
+const WORDS = {
+	up: "up",
+	down: "down",
+	left: "left",
+	right: "right",
+	enter: "enter",
+	space: "space",
+	tab: "tab",
+	"shift+tab": "shift+tab",
+	backspace: "backspace",
+	delete: "del",
+	escape: "esc",
+	"ctrl+c": "ctrl+c",
+	home: "home",
+	end: "end",
+	pageup: "pgup",
+	pagedown: "pgdn"
+};
+const labelOf = (key, glyphs) => {
+	if (typeof key !== "string") return key.char;
+	return (glyphs.kind === "unicode" ? ARROWS[key] : void 0) ?? WORDS[key];
+};
+/** A typed space is only ever reported as the named space key, so a `{ char: " " }` binding means `"space"`. */
+const normalise = (key) => typeof key !== "string" && key.char === " " ? "space" : key;
+/** Two keys shadow each other in help when they would match the same press, so a char compares in NFC as matching does. */
+const identity = (key) => typeof key === "string" ? `named:${key}` : `char:${key.char.normalize("NFC")}`;
+const bound = (binding, key) => typeof binding === "string" ? key._tag === "Named" && key.name === binding : key._tag === "Char" && key.char.normalize("NFC") === binding.char.normalize("NFC");
+/**
+* The keys a widget understands, as data: the one source both for dispatching input and for the help line, so the
+* two cannot drift apart.
+*
+* @remarks
+* Read it with {@link useKeys}, whose handler must step from current state, never render-closure state: several keys
+* from one stdin read are dispatched before React re-renders.
+*
+* @public
+*/
+var KeyTable = class KeyTable {
+	/** The bindings, in priority order. */
+	bindings;
+	constructor(bindings) {
+		this.bindings = bindings;
+	}
+	/**
+	* A table from its bindings. When two bindings share a key, the first wins. A `{ char: " " }` key is stored as
+	* the named `"space"`, the only form in which Ink reports a space.
+	*
+	* @param bindings - the bindings, in priority order
+	*/
+	static make = (bindings) => new KeyTable(bindings.map((binding) => ({
+		...binding,
+		keys: binding.keys.map(normalise)
+	})));
+	/**
+	* The keys every screen has: Esc cancels with `"escape"` (help: cancel), and Ctrl-C cancels with `"interrupt"`,
+	* bound but hidden. `q` is never a root key: it belongs to a widget's own table, so a text input can type it.
+	*/
+	static root = new KeyTable([{
+		keys: ["escape"],
+		action: "escape",
+		help: "cancel"
+	}, {
+		keys: ["ctrl+c"],
+		action: "interrupt",
+		help: "interrupt",
+		hidden: true
+	}]);
+	/**
+	* The action of the first binding that holds `key`, or `None`.
+	*
+	* @param key - the key pressed
+	*/
+	match = (key) => {
+		for (const binding of this.bindings) if (binding.keys.some((candidate) => bound(candidate, key))) return Option.some(binding.action);
+		return Option.none();
+	};
+	/**
+	* The help rows of every binding not hidden that can still fire, in order, labelled for `glyphs`: `↑/↓` under
+	* Unicode, `up/down` under ASCII.
+	*
+	* @remarks
+	* A key an earlier binding already holds (hidden or not) can never fire a later one, so a later binding is
+	* labelled with its remaining keys only, and left out when none remain.
+	*
+	* @param glyphs - the glyph set the labels are drawn with
+	*/
+	help = (glyphs) => {
+		const taken = /* @__PURE__ */ new Set();
+		const rows = [];
+		for (const binding of this.bindings) {
+			const live = binding.keys.filter((key) => !taken.has(identity(key)));
+			for (const key of binding.keys) taken.add(identity(key));
+			if (binding.hidden === true || live.length === 0) continue;
+			rows.push({
+				label: live.map((key) => labelOf(key, glyphs)).join("/"),
+				help: binding.help
+			});
+		}
+		return rows;
+	};
+};
+/** What a character of coalesced text is as a key: a line break is enter, and so on; another control is nothing. */
+const keyOfCharacter = (character) => {
+	if (character === "\r" || character === "\n" || character === "\r\n") return UiKey.named("enter");
+	if (character === "	") return UiKey.named("tab");
+	if (character === " ") return UiKey.named("space");
+	if (character === "" || character === "\b") return UiKey.named("backspace");
+	return UiKey.fromInk(character, PLAIN);
+};
+/** Ink's key flags for plain typed text: none set. */
+const PLAIN = {
+	upArrow: false,
+	downArrow: false,
+	leftArrow: false,
+	rightArrow: false,
+	pageDown: false,
+	pageUp: false,
+	home: false,
+	end: false,
+	return: false,
+	escape: false,
+	ctrl: false,
+	shift: false,
+	tab: false,
+	backspace: false,
+	delete: false,
+	meta: false,
+	super: false,
+	hyper: false,
+	capsLock: false,
+	numLock: false
+};
+/**
+* The keys in one Ink input. Ink hands text read in one go to `useInput` as one string with no key flag (`"yy"`, or
+* `"y\r"` with no `return`), so text of more than one code point is split into a key per code point; a named key,
+* or a Ctrl or Meta combination, is the one key it is.
+*/
+const keysOf = (input, key) => {
+	const single = UiKey.fromInk(input, key);
+	if (single?._tag === "Named" || key.ctrl || key.meta) return single === void 0 ? [] : [single];
+	const characters = graphemes(input);
+	if (characters.length <= 1) return single === void 0 ? [] : [single];
+	return characters.flatMap((character) => {
+		const pressed = keyOfCharacter(character);
+		return pressed === void 0 ? [] : [pressed];
+	});
+};
+/**
+* Read the keys of `table` and dispatch the action each one matches; keys the table does not bind are ignored.
+*
+* @remarks
+* One Ink `useInput` per call, and nothing else reads input.
+*
+* Text read in one go (`"yy"`, `"y\r"`) reaches Ink's `useInput` as one string; it is split here into a key per
+* grapheme (a decomposed letter or a ZWJ emoji is one key), a line break (CR, LF or CR LF) as one enter, a tab as tab, a
+* space as space, so `{ char: "y" }` matches each `y`. A `{ char }` binding matches in NFC, whichever form was typed.
+* A bracketed paste never reaches it: the screen takes pastes on Ink's paste channel, so pasted text cannot press a
+* widget's keys (a pasted `q` does not cancel); `TextInput` reads pastes as text.
+*
+* Several keys from one stdin read (a fast typist, a held arrow, a terminal that batches) are each dispatched
+* before React re-renders, so `dispatch` must never step from state captured in the render that created it: the
+* second key would see the first key's starting point and repeat its move. Step with a functional update
+* (`setState((current) => step(current, action))`), a `useReducer` dispatch, or a ref the handler itself advances.
+*
+* Inside a screen mounted by `CliUi.run`, a `dispatch` that throws ends the screen as a defect carrying the error, as a
+* component that throws in render does; it never escapes as an uncaught exception.
+*
+* @param table - the keys to read
+* @param dispatch - receives each matched action
+* @param options - whether the keys are read
+*
+* @public
+*/
+const useKeys = (table, dispatch, options = {}) => {
+	const guard = useScreenGuard();
+	inkModules().ink.useInput(guard((input, key) => {
+		for (const pressed of keysOf(input, key)) {
+			const action = table.match(pressed);
+			if (Option.isSome(action)) dispatch(action.value);
+		}
+	}), { isActive: options.isActive ?? true });
+};
+
+export { KeyTable, useKeys };