@effected/cli 0.10.0 → 0.12.0

package/ui/Select.js

@@ -0,0 +1,230 @@
+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.
+	*
+	* @remarks
+	* A choice's `detail` is drawn only while that choice is highlighted, as one muted line under the list, so the others'
+	* details are not on screen until the cursor reaches them. 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 };