@effected/cli 0.10.0 → 0.12.0

package/ui/TextInput.js

@@ -0,0 +1,290 @@
+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 segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+/** The grapheme boundary before `at`: the start of the grapheme `at` is in or just after; 0 at the start. */
+const previous = (value, at) => {
+	let boundary = 0;
+	for (const { index } of segmenter.segment(value)) {
+		if (index >= at) break;
+		boundary = index;
+	}
+	return boundary;
+};
+/** The grapheme boundary after `at`: the end of the grapheme that starts at or contains `at`; the length at the end. */
+const following = (value, at) => {
+	for (const { index, segment } of segmenter.segment(value)) {
+		const end = index + segment.length;
+		if (end > at) return end;
+	}
+	return value.length;
+};
+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)];
+};
+/**
+* The value masked either side of the cursor, one `mask` per grapheme of the whole value: the graphemes that start
+* before the cursor, then the rest, so the two always add up to the value's graphemes, wherever the cursor is.
+*/
+const maskedAround = (value, cursor, mask) => {
+	let before = 0;
+	let total = 0;
+	for (const { index } of segmenter.segment(value)) {
+		total++;
+		if (index < cursor) before++;
+	}
+	return [mask.repeat(before), mask.repeat(total - before)];
+};
+/** 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 the grapheme before or after it; left and right move it a grapheme, home and end to either end, 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), or one mask per grapheme in its place with `mask`, 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 latched = react.useRef(false);
+		if (state.value === "") latched.current = false;
+		else if (typeof props.mask === "function" && !latched.current && props.mask(state.value)) latched.current = true;
+		const masking = typeof props.mask === "function" ? latched.current : props.mask;
+		const mask = masking === void 0 || masking === false ? void 0 : masking === true ? glyphs.kind === "unicode" ? "•" : "*" : lineText(masking);
+		const [shownBefore, shownAfter] = mask === void 0 ? [state.value.slice(0, state.cursor), state.value.slice(state.cursor)] : maskedAround(state.value, state.cursor, mask);
+		const [before, after] = windowAround(shownBefore, shownAfter, 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.
+	*
+	* @remarks
+	* With `mask`, a secret is drawn as one mask per grapheme and never as itself, while the screen still resolves with
+	* the real text:
+	*
+	* ```ts
+	* const token = CliUi.run(TextInput.screen({ message: "Token reference?", mask: true }), { clear: true })
+	* ```
+	*
+	* @param options - the message, the starting text, the placeholder, the validator and the mask
+	*/
+	static screen = (options) => (control) => inkModules().react.createElement(TextInput.View, {
+		...options,
+		onSubmit: control.resolve
+	});
+};
+
+//#endregion
+export { TextInput };

package/ui/Toggle.js

@@ -0,0 +1,32 @@
+import { Fmt } from "../Fmt.js";
+import { inkModules } from "./internal/ink.js";
+import { Styled, useGlyphs, useTerminalSize } from "./UiTheme.js";
+import { lineText } from "./internal/lineText.js";
+
+//#region src/ui/Toggle.ts
+/**
+* An on/off row: a check glyph and a label.
+*
+* @public
+*/
+var Toggle = class {
+	constructor() {}
+	/**
+	* Draw a toggle row: `◉` on or `◯` off (`[x]` and `[ ]` under ASCII glyphs), then the label, cut to the width with
+	* the glyph set's ellipsis. A highlighted row starts with the arrow glyph and is painted with the accent token.
+	*
+	* @param props - the label, the value and whether the row is highlighted
+	*/
+	static View = (props) => {
+		const { ink, react } = inkModules();
+		const glyphs = useGlyphs();
+		const { columns } = useTerminalSize();
+		const check = props.value ? glyphs.kind === "unicode" ? "◉" : "[x]" : glyphs.kind === "unicode" ? "◯" : "[ ]";
+		const lead = props.highlighted ? glyphs.arrow : " ".repeat(Fmt.width(glyphs.arrow));
+		const text = Fmt.truncate(`${lead} ${check} ${lineText(props.label)}`, columns, { ellipsis: glyphs.ellipsis });
+		return props.highlighted ? react.createElement(Styled, { token: "accent" }, text) : react.createElement(ink.Text, null, text);
+	};
+};
+
+//#endregion
+export { Toggle };

package/ui/UiKey.js

@@ -0,0 +1,44 @@
+//#region src/ui/UiKey.ts
+const named = (name) => ({
+	_tag: "Named",
+	name
+});
+const CONTROL = /[\u0000-\u001f\u007f]/;
+/**
+* Normalising Ink's input into {@link UiKey}s.
+*
+* @public
+*/
+const UiKey = {
+	fromInk: (input, key) => {
+		if (key.upArrow) return named("up");
+		if (key.downArrow) return named("down");
+		if (key.leftArrow) return named("left");
+		if (key.rightArrow) return named("right");
+		if (key.pageUp) return named("pageup");
+		if (key.pageDown) return named("pagedown");
+		if (key.home) return named("home");
+		if (key.end) return named("end");
+		if (key.return) return named("enter");
+		if (key.escape) return named("escape");
+		if (key.ctrl && input === "c") return named("ctrl+c");
+		if (key.tab) return named(key.shift ? "shift+tab" : "tab");
+		if (key.backspace) return named("backspace");
+		if (key.delete) return named("delete");
+		if (key.ctrl || key.meta) return void 0;
+		if (input === " ") return named("space");
+		if (input === "" || CONTROL.test(input)) return void 0;
+		return {
+			_tag: "Char",
+			char: input
+		};
+	},
+	named,
+	char: (char) => ({
+		_tag: "Char",
+		char
+	})
+};
+
+//#endregion
+export { UiKey };

package/ui/UiProvider.js

@@ -0,0 +1,60 @@
+import { inkModules } from "./internal/ink.js";
+import { screenContext } from "./internal/ScreenContext.js";
+import { uiProviders } from "./internal/UiProviders.js";
+
+//#region src/ui/UiProvider.ts
+/**
+* Provide the kit's context to an Ink tree the kit did not mount, so `useTheme`, `useGlyphs`, `Styled` and
+* `useTerminalSize` work in it.
+*
+* @remarks
+* Take the value from `CliUi.context`, which also loads Ink and React: the provider and the kit's hooks render with
+* the modules the kit loaded. A screen mounted by `CliUi.run` already has this context.
+*
+* With `size`, `useTerminalSize` reads it instead of the stdout Ink draws on, less one column and one row as ever.
+* Give it to Ink's `renderToString`, whose terminal hooks see the process's own stdout rather than the width it lays
+* out at: `renderToString(tree, { columns })` with `size: { columns, rows }` keeps the kit's widgets cut to that
+* width. A tree given a `size` no longer follows the terminal's resizes.
+*
+* Standalone, there is no screen to end: a kit widget's own quit key, such as `Select`'s `q`, does nothing, and an
+* input handler a kit widget registers is called as is, so what it throws escapes as Ink leaves it. Nested inside a `CliUi.run` screen, it overrides only the theme, the glyphs and the size: the screen's
+* cancel and its defect route pass through, so `q` still cancels and a throwing handler is still the screen's defect.
+* Ink's colour level is the host's: `Styled` passes the theme's props, none at colour `none`.
+*
+* @param props - the context, and the tree
+*
+* @public
+*/
+const UiProvider = (props) => {
+	const { react } = inkModules();
+	const { theme, glyphs, size } = props.value;
+	const columns = size?.columns;
+	const rows = size?.rows;
+	const parent = react.useContext(screenContext());
+	const cancel = parent?.cancel;
+	const die = parent?.die;
+	const neutralize = props.value.neutralizeWorkflowCommands === true || parent?.neutralizeWorkflowCommands === true;
+	const value = react.useMemo(() => ({
+		theme,
+		glyphs,
+		...columns === void 0 || rows === void 0 ? {} : { size: {
+			columns,
+			rows
+		} },
+		...cancel === void 0 ? {} : { cancel },
+		...die === void 0 ? {} : { die },
+		...neutralize ? { neutralizeWorkflowCommands: true } : {}
+	}), [
+		theme,
+		glyphs,
+		columns,
+		rows,
+		cancel,
+		die,
+		neutralize
+	]);
+	return uiProviders(value, props.children);
+};
+
+//#endregion
+export { UiProvider };

package/ui/UiStreams.js

@@ -0,0 +1,18 @@
+import { processStreams } from "./internal/processStreams.js";
+import { Context } from "effect";
+
+//#region src/ui/UiStreams.ts
+/**
+* The streams a screen mounts on, the process's own standard streams by default.
+*
+* @remarks
+* A `Context.Reference`, so it never appears in `R`: the default reads the process streams when first used, never
+* at import, and a test provides in-memory streams with `Effect.provideService(UiStreams, streams)`. `./ui` binds
+* Node's process streams.
+*
+* @public
+*/
+var UiStreams = class extends Context.Reference("@effected/cli/ui/UiStreams", { defaultValue: () => processStreams() }) {};
+
+//#endregion
+export { UiStreams };

package/ui/UiTheme.js

@@ -0,0 +1,119 @@
+import { inkModules } from "./internal/ink.js";
+import { screenContext } from "./internal/ScreenContext.js";
+
+//#region src/ui/UiTheme.ts
+const OUTSIDE = "@effected/cli/ui: a theme hook was used outside a screen mounted by CliUi.run or a UiProvider";
+const useScreen = () => {
+	const screen = inkModules().react.useContext(screenContext());
+	if (screen === void 0) throw new Error(OUTSIDE);
+	return screen;
+};
+/**
+* The Ink `Text` props for `style` at `color`.
+*
+* @remarks
+* At `"none"` it gives no styling props at all, not even bold or dim, so a frame is escape-free by construction;
+* Ink's colour level held at 0 is the backstop. A flag set to `false` adds no prop.
+*
+* Omit `color` in an Ink tree the kit did not mount, which has no colour level of its own to pass: every prop is
+* emitted, as at any level but `"none"`, and Ink's own chalk gates what reaches the terminal.
+*
+* @param style - the resolved style
+* @param color - the stream's colour level; omitted, every prop is emitted for Ink's chalk to gate
+*
+* @public
+*/
+const inkProps = (style, color) => color === "none" ? {} : {
+	...style.fg === void 0 ? {} : { color: style.fg },
+	...style.bold === true ? { bold: true } : {},
+	...style.dim === true ? { dimColor: true } : {},
+	...style.italic === true ? { italic: true } : {},
+	...style.underline === true ? { underline: true } : {}
+};
+/**
+* The theme of the stream the mounted screen draws on.
+*
+* @remarks
+* A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+*
+* @public
+*/
+const useTheme = () => useScreen().theme;
+/**
+* The glyph set of the mounted screen, so a component draws Unicode or ASCII glyphs to match the rest of the output.
+*
+* @remarks
+* A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+*
+* @public
+*/
+const useGlyphs = () => useScreen().glyphs;
+/**
+* Text painted with a theme token or style, through the mounted screen's theme.
+*
+* @remarks
+* Its children are drawn as given. The kit's widgets sanitise every string they draw from data (escapes removed,
+* line breaks folded) before handing it here; text a consumer passes to `Styled`, or to Ink's own `Text`, is the
+* consumer's to sanitise, with `Fmt.sanitize`. Ink keeps the escape sequences it is handed, so text from data drawn
+* unsanitised can paint colour at colour `none` or plant a hyperlink, and a line break in it adds a row the screen's
+* height budget did not count.
+*
+* @param props - the token or style, and the text
+*
+* @public
+*/
+const Styled = (props) => {
+	const theme = useTheme();
+	const { ink, react } = inkModules();
+	return react.createElement(ink.Text, inkProps(theme.style(props.token), theme.color), props.children);
+};
+/** A reported size, or `fallback` when it is unknown: absent, or not positive (a pty `script` opens reports 0x0). */
+const known = (reported, fallback) => reported !== void 0 && reported > 0 ? reported : fallback;
+/**
+* The usable terminal size: the stdout Ink draws on, less one column and one row, re-read on every render and when
+* the terminal resizes; or, under a `UiProvider` given a `size`, that size less one column and one row.
+*
+* @remarks
+* A width or height the stream does not report, or reports as 0 (a pty that `script` opens says `0 0`), is unknown and
+* reads as 80 columns by 24 rows, so a screen never lays itself out at width 0. This is not Ink's own fallback, which
+* first asks the process's terminal (`terminal-size`: the tty, `COLUMNS`, `tput`) and only then uses 80x24; the kit
+* reads no `process` here. On a 0x0 pty with `COLUMNS=50`, Ink lays out at 50 while these rows are cut at 79.
+*
+* The override exists for Ink's `renderToString`, whose `useStdout` is the process's own stdout whatever width it
+* lays out at; without it, the kit's widgets would cut their rows to the wrong width there.
+*
+* Never feed `columns` into a `Box`'s `width`. On a resize Ink re-lays out the tree it already has and repaints
+* before React re-renders with the new size, so a width taken from this hook is one paint stale. After a shrink,
+* that stale, wider frame wraps in the narrower terminal and leaves a copy stranded above the live one. For a
+* one-column margin use `marginRight: 1`, which Ink recomputes within its own resize. Text cut to `columns` lags the
+* same paint, so give a long row Ink's `wrap: "truncate-end"` too: on a shrink Ink then clips it rather than letting
+* the terminal wrap it.
+*
+* A React hook: call it from a component rendered inside an Ink tree; it needs no screen, but reads a `UiProvider`'s
+* size when there is one.
+*
+* @public
+*/
+const useTerminalSize = () => {
+	const { ink, react } = inkModules();
+	const { stdout } = ink.useStdout();
+	const override = react.useContext(screenContext())?.size;
+	const [, redraw] = react.useReducer((count) => count + 1, 0);
+	const followsStdout = override === void 0;
+	react.useEffect(() => {
+		if (!followsStdout) return void 0;
+		stdout.on("resize", redraw);
+		return () => {
+			stdout.off("resize", redraw);
+		};
+	}, [stdout, followsStdout]);
+	const columns = override?.columns ?? stdout.columns;
+	const rows = override?.rows ?? stdout.rows;
+	return {
+		columns: Math.max(1, known(columns, 80) - 1),
+		rows: Math.max(1, known(rows, 24) - 1)
+	};
+};
+
+//#endregion
+export { Styled, inkProps, useGlyphs, useTerminalSize, useTheme };