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 }); }; }