@effected/cli 0.9.0 → 0.11.0

package/ui/DocView.js

@@ -0,0 +1,74 @@
+import { Render } from "../Render.js";
+import { fromReact, inkModules } from "./internal/ink.js";
+import { screenContext } from "./internal/ScreenContext.js";
+import { useTerminalSize } from "./UiTheme.js";
+
+//#region src/ui/DocView.ts
+const OUTSIDE = "@effected/cli/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) => ({
+	...neutralize ? { neutralizeWorkflowCommands: true } : {},
+	width,
+	audience: "human",
+	color: theme.color,
+	paint: theme.paint,
+	glyphs: theme.glyphs,
+	link: (_target, label) => label,
+	displayPath: (absolute) => absolute
+});
+/** 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;
+		if (given === void 0 && theme === void 0) throw new Error(OUTSIDE);
+		const ctx = react.useMemo(() => given ?? contextOf(theme, columns, neutralize), [
+			given,
+			theme,
+			columns,
+			neutralize
+		]);
+		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);
+
+//#endregion
+export { DocView };

package/ui/KeyHelp.js

@@ -0,0 +1,62 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { Styled, useGlyphs, useTerminalSize } from "./UiTheme.js";
+import { KeyTable } from "./KeyTable.js";
+import { lineText } from "./internal/lineText.js";
+
+//#region 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);
+};
+
+//#endregion
+export { KeyHelp };

package/ui/KeyTable.js

@@ -0,0 +1,199 @@
+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";
+
+//#region 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 });
+};
+
+//#endregion
+export { KeyTable, useKeys };

package/ui/MultiSelect.js

@@ -0,0 +1,260 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { useScreenCancel } from "./internal/ScreenContext.js";
+import { Styled, useGlyphs, useTerminalSize } 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";
+
+//#region src/ui/MultiSelect.ts
+/** Every item with its section's index, numbered across sections in order. */
+const flatten = (sections) => sections.flatMap((section, index) => section.items.map((item) => ({
+	section: index,
+	item
+})));
+/** Throws when two items, in any sections, share a key: keys identify rows. */
+const assertUniqueKeys = (sections) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const { item } of flatten(sections)) {
+		if (seen.has(item.key)) throw new Error(`@effected/cli/ui: MultiSelect item keys must be unique across sections; "${item.key}" repeats`);
+		seen.add(item.key);
+	}
+};
+const init = (sections, options = {}) => {
+	assertUniqueKeys(sections);
+	const items = flatten(sections);
+	return {
+		sections,
+		chosen: new Set(items.flatMap((entry, index) => entry.item.selected === true ? [index] : [])),
+		viewport: Viewport.init(items.length, options.height ?? 10),
+		submitted: false
+	};
+};
+const step = (state, action) => {
+	const items = flatten(state.sections);
+	const cursor = state.viewport.cursor;
+	switch (action) {
+		case "cancel": return state;
+		case "submit": return {
+			...state,
+			submitted: true
+		};
+		case "toggle": {
+			if (items.length === 0) return state;
+			const chosen = new Set(state.chosen);
+			if (chosen.has(cursor)) chosen.delete(cursor);
+			else chosen.add(cursor);
+			return {
+				...state,
+				chosen
+			};
+		}
+		case "toggleSection": {
+			const section = items[cursor]?.section;
+			if (section === void 0) return state;
+			const members = items.flatMap((entry, index) => entry.section === section ? [index] : []);
+			const fill = members.some((index) => !state.chosen.has(index));
+			const chosen = new Set(state.chosen);
+			for (const index of members) if (fill) chosen.add(index);
+			else chosen.delete(index);
+			return {
+				...state,
+				chosen
+			};
+		}
+		default: return {
+			...state,
+			viewport: Viewport.step(state.viewport, action)
+		};
+	}
+};
+const selected = (state) => flatten(state.sections).flatMap((entry, index) => state.chosen.has(index) ? [entry.item.value] : []);
+/** ↑/↓ shown; the page, home and end moves bound but hidden, so the line names space, a, enter and esc at 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: ["space"],
+		action: "toggle",
+		help: "toggle"
+	},
+	{
+		keys: [{ char: "a" }],
+		action: "toggleSection",
+		help: "toggle section"
+	},
+	{
+		keys: ["enter"],
+		action: "submit",
+		help: "continue"
+	},
+	{
+		keys: [{ char: "q" }],
+		action: "cancel",
+		help: "cancel"
+	}
+]);
+/** Lines around the list: the message above, the detail and the help line below. */
+const RESERVED = 3;
+/**
+* Several choices from sectioned lists: a pure reducer, its key table, a view and a ready-made screen.
+*
+* Item keys must be unique across all sections; `init` throws, and `screen` dies, on a repeat.
+*
+* @remarks
+* The cursor moves over items only; section titles are headers drawn by the viewport, which keeps a scrolled-off
+* header visible. Submitting with nothing selected resolves an empty list, which is a result, not a cancel.
+*
+* @example
+* ```ts
+* import { CliUi, MultiSelect } from "@effected/cli/ui"
+* import { Effect } from "effect"
+*
+* const pickFeatures = Effect.gen(function* () {
+* 	const features = yield* CliUi.run(
+* 		MultiSelect.screen({
+* 			message: "Which features?",
+* 			sections: [
+* 				{
+* 					title: "Tooling",
+* 					items: [
+* 						{ key: "lint", label: "Linting", value: "lint", selected: true },
+* 						{ key: "test", label: "Tests", value: "test" },
+* 					],
+* 				},
+* 			],
+* 		}),
+* 	)
+* 	return features
+* })
+* ```
+*
+* @public
+*/
+var MultiSelect = class MultiSelect {
+	constructor() {}
+	/**
+	* A multi-select over `sections`, each item starting as its own `selected` flag says, on the first item.
+	*
+	* @param sections - the sections
+	* @param options - the list height
+	*/
+	static init = init;
+	/**
+	* Apply an action: a viewport move over the items; `"toggle"` flips the highlighted item; `"toggleSection"`
+	* selects every item of the highlighted item's section while any is unselected, and clears them all otherwise;
+	* `"submit"` marks it submitted; `"cancel"` changes nothing here, because ending the screen is the view's job.
+	*
+	* @param state - where the multi-select is
+	* @param action - the action
+	*/
+	static step = step;
+	/**
+	* The selected values, in section order and then item order, however they were toggled.
+	*
+	* @param state - where the multi-select is
+	*/
+	static selected = selected;
+	/** The keys: ↑/↓ move (page, home and end too), space toggle, a toggle section, enter continue, q cancel. */
+	static keys = KEYS;
+	/**
+	* Draw the multi-select: the message, the sections (each item a check glyph, `◉`/`◯` or `[x]`/`[ ]` under ASCII,
+	* then its label cut to the width; the highlighted one in the accent token with the arrow glyph), the highlighted
+	* item's detail, and the key help. Enter calls `onSubmit` with the selected values; `q` cancels with `"escape"`.
+	*
+	* @remarks
+	* Single-shot, like `Select.View`: the sections are read once at mount.
+	*
+	* @param props - the message, the sections, and where the selection goes
+	*/
+	static View = (props) => {
+		const { ink, react } = inkModules();
+		const glyphs = useGlyphs();
+		const { columns } = useTerminalSize();
+		const cancel = useScreenCancel();
+		const [state, setState] = react.useState(() => init(props.sections, props.height === void 0 ? {} : { height: props.height }));
+		const { onSubmit } = props;
+		react.useEffect(() => {
+			if (state.submitted) onSubmit(selected(state));
+		}, [state.submitted]);
+		useKeys(KEYS, (action) => {
+			if (action === "cancel") cancel("escape");
+			else setState((current) => step(current, action));
+		});
+		const items = flatten(props.sections);
+		const numberOf = new Map(items.map((entry, index) => [entry.item.key, index]));
+		const rows = props.sections.flatMap((section) => [{
+			_tag: "Header",
+			label: section.title
+		}, ...section.items.map((item) => ({
+			_tag: "Item",
+			key: item.key
+		}))]);
+		const on = glyphs.kind === "unicode" ? "◉" : "[x]";
+		const off = glyphs.kind === "unicode" ? "◯" : "[ ]";
+		const blank = " ".repeat(Fmt.width(glyphs.arrow));
+		const ellipsis = { ellipsis: glyphs.ellipsis };
+		const renderRow = (row, highlighted) => {
+			if (row._tag === "Header") return react.createElement(Styled, { token: "emphasis" }, Fmt.truncate(lineText(row.label), columns, ellipsis));
+			const index = numberOf.get(row.key) ?? -1;
+			const entry = items[index];
+			const text = Fmt.truncate(`${highlighted ? glyphs.arrow : blank} ${state.chosen.has(index) ? on : off} ${lineText(entry?.item.label ?? "")}`, columns, ellipsis);
+			return highlighted ? react.createElement(Styled, { token: "accent" }, text) : react.createElement(ink.Text, null, text);
+		};
+		const detail = items[state.viewport.cursor]?.item.detail;
+		return react.createElement(ink.Box, { flexDirection: "column" }, react.createElement(Styled, { token: "emphasis" }, Fmt.truncate(lineText(props.message), columns, 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)), react.createElement(KeyHelp, { tables: [KEYS] }));
+	};
+	/**
+	* A ready-made screen for `CliUi.run`: the multi-select, resolving with the selected values (`[]` when none are).
+	*
+	* @param options - the message, the sections and the list height
+	*/
+	static screen = (options) => (control) => {
+		assertUniqueKeys(options.sections);
+		return inkModules().react.createElement(MultiSelect.View, {
+			...options,
+			onSubmit: control.resolve
+		});
+	};
+};
+
+//#endregion
+export { MultiSelect };