import type { ReactElement } from "react";
import { Fmt } from "../Fmt.js";
import type { Screen } from "./CliUi.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 { Styled, useGlyphs, useTerminalSize } from "./UiTheme.js";
import type { ViewportMove, ViewportRow, ViewportState } from "./Viewport.js";
import { Viewport } from "./Viewport.js";
/**
* One item of a {@link MultiSelect} section.
*
* @public
*/
export interface MultiSelectItem {
/** Identifies the item within its section. */
readonly key: string;
/** What the row shows. */
readonly label: string;
/** What selecting it returns. */
readonly value: A;
/** A line shown, muted, beneath the list while this item is highlighted. */
readonly detail?: string;
/** Whether it starts selected. */
readonly selected?: boolean;
}
/**
* A titled group of items; the title is a header the cursor never stops on.
*
* @public
*/
export interface MultiSelectSection {
/** The header. */
readonly title: string;
/** The items, in order. */
readonly items: ReadonlyArray>;
}
/**
* Where a {@link MultiSelect} is: its sections, which items are selected, the viewport over the items, and whether
* it was submitted.
*
* @remarks
* Items are numbered across sections in order, section by section; `chosen` holds those numbers.
*
* @public
*/
export interface MultiSelectState {
/** The sections. */
readonly sections: ReadonlyArray>;
/** The selected items, by their number across all sections. */
readonly chosen: ReadonlySet;
/** The highlighted item and the window over the list; it counts items only, never headers. */
readonly viewport: ViewportState;
/** Whether enter was pressed. */
readonly submitted: boolean;
}
/**
* What a key does in a {@link MultiSelect}.
*
* @public
*/
export type MultiSelectAction = ViewportMove | "toggle" | "toggleSection" | "submit" | "cancel";
/**
* Options for {@link MultiSelect.init}.
*
* @public
*/
export interface MultiSelectInitOptions {
/** How many rows the list shows at most; the terminal height also limits it. 10 by default. */
readonly height?: number;
}
/**
* Options for {@link MultiSelect.screen}.
*
* @public
*/
export interface MultiSelectScreenOptions {
/** The question, shown above the list. */
readonly message: string;
/** The sections. */
readonly sections: ReadonlyArray>;
/** How many rows the list shows at most. */
readonly height?: number;
}
/**
* Props of {@link MultiSelect.View}.
*
* @public
*/
export interface MultiSelectViewProps extends MultiSelectScreenOptions {
/** Receives the selected values, in section then item order, when enter is pressed. */
readonly onSubmit: (values: ReadonlyArray) => void;
}
/** Every item with its section's index, numbered across sections in order. */
const flatten = (
sections: ReadonlyArray>,
): ReadonlyArray<{ readonly section: number; readonly item: MultiSelectItem }> =>
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: ReadonlyArray>): void => {
const seen = new Set();
for (const { item } of flatten(sections)) {
if (seen.has(item.key)) {
throw new Error(
`@effected/cli-kit/ui: MultiSelect item keys must be unique across sections; "${item.key}" repeats`,
);
}
seen.add(item.key);
}
};
const init = (
sections: ReadonlyArray>,
options: MultiSelectInitOptions = {},
): MultiSelectState => {
assertUniqueKeys(sections);
const items = flatten(sections);
const chosen = new Set(items.flatMap((entry, index) => (entry.item.selected === true ? [index] : [])));
return { sections, chosen, viewport: Viewport.init(items.length, options.height ?? 10), submitted: false };
};
const step = (state: MultiSelectState, action: MultiSelectAction): MultiSelectState => {
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 === undefined) return state;
const members = items.flatMap((entry, index) => (entry.section === section ? [index] : []));
// Any unselected member selects the whole section; a fully selected section is cleared.
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: MultiSelectState): ReadonlyArray =>
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 = 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-kit/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
*/
export class MultiSelect {
private 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 readonly init: (
sections: ReadonlyArray>,
options?: MultiSelectInitOptions,
) => MultiSelectState = 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 readonly step: (state: MultiSelectState, action: MultiSelectAction) => MultiSelectState = step;
/**
* The selected values, in section order and then item order, however they were toggled.
*
* @param state - where the multi-select is
*/
static readonly selected: (state: MultiSelectState) => ReadonlyArray = selected;
/** The keys: ↑/↓ move (page, home and end too), space toggle, a toggle section, enter continue, q cancel. */
static readonly keys: KeyTable = 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 readonly View = (props: MultiSelectViewProps): ReactElement => {
const { ink, react } = inkModules();
const glyphs = useGlyphs();
const { columns } = useTerminalSize();
const cancel = useScreenCancel();
const [state, setState] = react.useState(() =>
init(props.sections, props.height === undefined ? {} : { height: props.height }),
);
const { onSubmit } = props;
// Deliberately keyed on `submitted` alone: the effect runs in the render where it flipped, whose closure
// already holds that render's state and onSubmit.
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);
// Rows are keyed by the item's own key (unique, checked at init), which is also the React key of the row.
const numberOf = new Map(items.map((entry, index) => [entry.item.key, index] as const));
const rows: ReadonlyArray = props.sections.flatMap((section) => [
{ _tag: "Header" as const, label: section.title },
...section.items.map((item) => ({ _tag: "Item" as const, 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: ViewportRow, highlighted: boolean): ReactElement => {
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 === undefined
? 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 readonly screen =
(options: MultiSelectScreenOptions): Screen> =>
(control) => {
// Checked before mounting, so a repeated key dies rather than drawing an ambiguous list.
assertUniqueKeys(options.sections);
return inkModules().react.createElement(MultiSelect.View, { ...options, onSubmit: control.resolve });
};
}