/** @jsxRuntime automatic */ /** @jsxImportSource @alchemy.run/sigil */ import { measureElement, useCursor, useInput, usePaste, useStdout, type DOMElement, type ProgramStatusKind, } from "@alchemy.run/sigil"; import { stringWidth } from "@alchemy.run/sigil/ansi"; import { useEffect, useLayoutEffect, useRef, useState } from "@alchemy.run/sigil/react"; import type { JSX, ReactNode } from "react"; import { copyToClipboard } from "../../../Util/Terminal.ts"; import { theme } from "../../../Util/Theme.ts"; import type { Choice, CycleChoice } from "../types.ts"; import { useCliEnvironment, useGlyphs, useKeyGlyphs } from "./Environment.tsx"; import { KeyBar, Spinner } from "./Feedback.tsx"; import { Box, overflowListWindow } from "./Layout.tsx"; import { useAlchemyStatus } from "./ProgramStatus.ts"; import { Link, Text } from "./Typography.tsx"; export interface TerminalKey { readonly up: boolean; readonly down: boolean; readonly left: boolean; readonly right: boolean; readonly home: boolean; readonly end: boolean; readonly pageUp: boolean; readonly pageDown: boolean; readonly enter: boolean; readonly escape: boolean; readonly backspace: boolean; readonly delete: boolean; readonly tab: boolean; readonly shift: boolean; readonly ctrl: boolean; readonly meta: boolean; } /** Backend facade for custom screens; callers never need to import Sigil. */ export const useTerminalInput = ( handler: (input: string, key: TerminalKey) => void, options?: { readonly active?: boolean }, ) => useInput( (input, key) => handler(input, { up: key.upArrow, down: key.downArrow, left: key.leftArrow, right: key.rightArrow, home: key.home, end: key.end, pageUp: key.pageUp, pageDown: key.pageDown, enter: key.return, escape: key.escape, backspace: key.backspace, delete: key.delete, tab: key.tab, shift: key.shift, ctrl: key.ctrl, meta: key.meta, }), { isActive: options?.active ?? true }, ); /** Bracketed-paste input scoped the same way as {@link useTerminalInput}. */ export const useTerminalPaste = ( handler: (text: string) => void, options?: { readonly active?: boolean }, ) => { usePaste(handler, { isActive: options?.active ?? true }); }; export const useTerminalSize = () => { const { columns, rows } = useCliEnvironment(); return { columns, rows }; }; export const useListNavigation = (length: number, initialIndex = 0) => { const [cursor, setCursor] = useState(initialIndex); const clamped = Math.max(0, Math.min(cursor, Math.max(0, length - 1))); const move = (delta: number) => setCursor((current) => { if (length === 0) return 0; // Clamp before wrapping: after a filter shrinks the list the raw state // can point past the end, and wrapping from there jumps arbitrarily. const base = Math.max(0, Math.min(current, length - 1)); return (((base + delta) % length) + length) % length; }); return { cursor: clamped, move, setCursor } as const; }; /** Step `delta` rows from `cursor`, wrapping and skipping disabled rows. */ export const moveSkippingDisabled = ( disabled: ReadonlyArray, cursor: number, delta: number, ): number => { const length = disabled.length; if (length === 0) return 0; for (let offset = 1; offset <= length; offset++) { const next = (((cursor + delta * offset) % length) + length) % length; if (!disabled[next]) return next; } return cursor; }; /** * Jump to `target` (clamped, no wrap), settling on the nearest enabled row in * the jump direction and falling back to the other direction. Used for * Home/End and PageUp/PageDown in list prompts. */ export const jumpSkippingDisabled = ( disabled: ReadonlyArray, cursor: number, target: number, ): number => { const clamped = Math.max(0, Math.min(disabled.length - 1, target)); if (!disabled[clamped]) return clamped; const direction = clamped >= cursor ? 1 : -1; for (let next = clamped + direction; next >= 0 && next < disabled.length; next += direction) { if (!disabled[next]) return next; } for (let next = clamped - direction; next >= 0 && next < disabled.length; next -= direction) { if (!disabled[next]) return next; } return cursor; }; /** "↑ N more" / "↓ N more" indicator row shared by windowed prompt lists. */ function OverflowRow({ direction, count, }: { readonly direction: "up" | "down"; readonly count: number; }) { const glyphs = useGlyphs(); if (count <= 0) return null; return ( {" "} {direction === "up" ? glyphs.overflowUp : glyphs.overflowDown} {count} more ); } /** * List-cursor column shared by every focusable row (prompt lists, the * edit-accounts list, the profile dashboard): the focused row carries the * pointer glyph, every other row a same-width blank so labels stay aligned. * Focus is a shape, not a tint, so it survives ASCII and no-colour terminals. */ export function Pointer({ focused }: { readonly focused: boolean }) { const glyphs = useGlyphs(); return ( {focused ? glyphs.pointer : " "} ); } /** * Focused rows paint their label in the same brand colour as the pointer so * the cursor reads as one block; unfocused labels stay the plain foreground, * leaving green to status glyphs alone. */ const focusedLabelColor = (focused: boolean): string | undefined => focused ? theme.paint.focus : undefined; /** * Width of the label column when descriptions sit beside labels: the widest * label plus one cell, so every description starts in the same column * (labels and descriptions read as two columns rather than a ragged sentence). * Sticky/heading rows are excluded — they never carry a description. */ const labelColumnWidth = ( labels: ReadonlyArray<{ readonly label: string; readonly sticky?: boolean }>, ): number => Math.max(0, ...labels.map(({ label, sticky }) => (sticky ? 0 : stringWidth(label)))) + 1; export interface MenuProps { readonly choices: ReadonlyArray>; readonly cursor: number; readonly selected?: ReadonlySet; readonly visibleCount?: number; readonly empty?: string; readonly descriptionPlacement?: "below" | "inline"; } /** Pure menu presentation used by select prompts and custom applications. */ export function Menu({ choices, cursor, selected, visibleCount = 12, empty = "No choices.", descriptionPlacement = "inline", }: MenuProps): JSX.Element { const glyphs = useGlyphs(); if (choices.length === 0) return {empty}; // A sticky heading renders outside the window, in addition to the overflow // rows the shared windowing already reserves. const { start, end } = overflowListWindow(choices.length, cursor, visibleCount); const stickyIndex = start === 0 ? -1 : choices.findLastIndex((choice, index) => index < start && choice.sticky); const visible = [ ...(stickyIndex === -1 ? [] : [stickyIndex]), ...Array.from({ length: end - start }, (_, offset) => start + offset), ]; const alignDescriptions = descriptionPlacement === "inline" && choices.some((choice) => choice.description !== undefined); const labelWidth = alignDescriptions ? labelColumnWidth(choices) : undefined; return ( {visible.map((index) => { const choice = choices[index]; if (choice === undefined) return null; const focused = index === cursor; const checked = selected?.has(index); const disabled = choice.disabled !== undefined && choice.disabled !== false; const previous = choices[index - 1]; const showGroup = choice.group !== undefined && (index === start || previous?.group !== choice.group); return ( {showGroup ? ( {choice.group.toUpperCase()} ) : null} {selected === undefined ? null : ( {checked ? glyphs.checked : glyphs.unchecked} )} {choice.label} {choice.description === undefined ? null : ( {choice.description} )} {typeof choice.disabled === "string" ? ( {choice.disabled} ) : null} ); })} ); } export interface TextFieldProps { readonly placeholder?: string; /** Text Tab fills into the empty field, e.g. the prompt's default. */ readonly completion?: string; readonly initialValue?: string; readonly value?: string; readonly mask?: string; readonly onSubmit: (value: string) => void; readonly onChange?: (value: string) => void; readonly onCancel?: () => void; readonly active?: boolean; readonly ariaLabel?: string; } const graphemeSegmenter = new Intl.Segmenter(); /** * Split into user-perceived characters so cursor movement and deletion never * land inside a surrogate pair or emoji cluster. */ const toGraphemes = (value: string): ReadonlyArray => Array.from(graphemeSegmenter.segment(value), (segment) => segment.segment); /** * Normalize text before inserting it into a single-line field. Sigil reports * bracketed paste separately, but pasted content can still contain newlines, * tabs or other control characters that do not belong in the value. */ export const sanitizeTextInsert = (input: string): string => // eslint-disable-next-line no-control-regex input.replace(/[\u0000-\u001f\u007f]/g, ""); /** Readline-style whitespace word boundary to the left of `cursor`. */ const wordBoundaryLeft = (chars: ReadonlyArray, cursor: number): number => { let index = cursor; while (index > 0 && chars[index - 1] === " ") index--; while (index > 0 && chars[index - 1] !== " ") index--; return index; }; /** Readline-style whitespace word boundary to the right of `cursor`. */ const wordBoundaryRight = (chars: ReadonlyArray, cursor: number): number => { let index = cursor; while (index < chars.length && chars[index] === " ") index++; while (index < chars.length && chars[index] !== " ") index++; return index; }; /** * Horizontal scroll window for a single-line field: which grapheme range fits * in `avail` display cells while keeping the cursor visible. One cell is * reserved for the cursor sitting past the last character. */ const visibleWindow = ( chars: ReadonlyArray, cursor: number, avail: number, ): { readonly start: number; readonly end: number } => { const budget = Math.max(1, avail - 1); const widths = chars.map((char) => stringWidth(char)); let before = 0; for (let index = 0; index < cursor; index++) before += widths[index] ?? 0; let start = 0; if (before > budget) { // Scrolled: pin the cursor near the right edge of the window. let used = 0; while (start < cursor && before - used > budget) { used += widths[start] ?? 0; start++; } } let end = start; let total = 0; while (end < chars.length && total + (widths[end] ?? 0) <= budget) { total += widths[end] ?? 0; end++; } return { start, end }; }; /** * Single-line editor with insertion, deletion, home/end, word-wise movement * and the common readline kill bindings (Ctrl+U/K/W, Alt+Backspace). Long * values scroll horizontally instead of wrapping, so the terminal cursor * always sits on the field's own row. */ export function TextField({ placeholder, completion, initialValue = "", value: controlledValue, mask, onSubmit, onChange, onCancel, active, ariaLabel, }: TextFieldProps) { // Prompts are serialized by the Sigil renderer, so an enabled field owns // the input stream outright — no Sigil focus negotiation. (Coupling this to // useFocus({autoFocus}) silently disabled the field whenever any other // focusable was already mounted.) const inputActive = active ?? true; const [internalValue, setInternalValue] = useState(initialValue); const value = controlledValue ?? internalValue; const chars = toGraphemes(value); const [cursor, setCursor] = useState(() => toGraphemes(controlledValue ?? initialValue).length); const fieldRef = useRef(null); const [metrics, setMetrics] = useState({ x: 0, y: 0, measured: false }); const { setCursorPosition } = useCursor(); const { columns } = useCliEnvironment(); useEffect(() => { setCursor((current) => Math.min(current, toGraphemes(value).length)); }, [value]); const update = (nextChars: ReadonlyArray, nextCursor: number) => { const next = nextChars.join(""); if (controlledValue === undefined) setInternalValue(next); setCursor(Math.max(0, Math.min(nextChars.length, nextCursor))); onChange?.(next); }; useTerminalInput( (input, key) => { if (key.enter) onSubmit(value); else if (key.escape) onCancel?.(); else if (key.left) setCursor(key.ctrl || key.meta ? wordBoundaryLeft(chars, cursor) : Math.max(0, cursor - 1)); else if (key.right) setCursor( key.ctrl || key.meta ? wordBoundaryRight(chars, cursor) : Math.min(chars.length, cursor + 1), ); // Sigil distinguishes physical Backspace from Delete. else if (key.backspace && cursor > 0) { const target = key.meta ? wordBoundaryLeft(chars, cursor) : cursor - 1; update([...chars.slice(0, target), ...chars.slice(cursor)], target); } else if (key.delete && cursor < chars.length) update([...chars.slice(0, cursor), ...chars.slice(cursor + 1)], cursor); else if (key.ctrl && input === "d" && cursor < chars.length) update([...chars.slice(0, cursor), ...chars.slice(cursor + 1)], cursor); else if (key.ctrl && input === "w" && cursor > 0) { const target = wordBoundaryLeft(chars, cursor); update([...chars.slice(0, target), ...chars.slice(cursor)], target); } else if (key.ctrl && input === "u") update(chars.slice(cursor), 0); else if (key.ctrl && input === "k") update(chars.slice(0, cursor), cursor); else if (key.home || (key.ctrl && input === "a")) setCursor(0); else if (key.end || (key.ctrl && input === "e")) setCursor(chars.length); else if (key.meta && input === "b") setCursor(wordBoundaryLeft(chars, cursor)); else if (key.meta && input === "f") setCursor(wordBoundaryRight(chars, cursor)); else if (key.tab && completion !== undefined && chars.length === 0) { const completed = toGraphemes(completion); update(completed, completed.length); } else if (!key.ctrl && !key.meta && !key.tab) { const inserted = toGraphemes(sanitizeTextInsert(input)); if (inserted.length > 0) { update( [...chars.slice(0, cursor), ...inserted, ...chars.slice(cursor)], cursor + inserted.length, ); } } }, { active: inputActive }, ); useTerminalPaste( (pasted) => { const inserted = toGraphemes(sanitizeTextInsert(pasted)); if (inserted.length === 0) return; update( [...chars.slice(0, cursor), ...inserted, ...chars.slice(cursor)], cursor + inserted.length, ); }, { active: inputActive }, ); const shownChars = mask === undefined ? chars : chars.map(() => mask); // Available width = terminal width minus the field's left offset. The box's // own measured width is useless here: it shrinks to its content (flexGrow // only affects height in a column parent), so using it collapses the scroll // window to whatever is currently typed. const avail = Math.max(4, columns - (metrics.measured ? metrics.x : 0) - 1); const { start, end } = visibleWindow(shownChars, cursor, avail); const display = shownChars.length === 0 ? (placeholder ?? " ") : `${shownChars.slice(start, end).join("")}${cursor === shownChars.length ? " " : ""}`; // Cursor placement must happen DURING render: useCursor only records the // position in a ref and propagates it to the renderer from an insertion // effect, which runs BEFORE layout effects in the same commit. Setting the // position from a layout effect therefore paints every frame with the // previous keystroke's cursor (off by one while typing and erasing). The // ref write is render-safe — propagation is commit-gated, so abandoned // concurrent renders never reach the terminal. setCursorPosition( inputActive && metrics.measured ? { x: metrics.x + stringWidth(shownChars.slice(start, cursor).join("")), y: metrics.y, } : undefined, ); // Measuring stays post-layout: the Box ref only exists after mutation. // A metrics change re-renders, which re-runs the render-time cursor // placement above with the fresh offsets. useLayoutEffect(() => { if (fieldRef.current === null) return; const { x, y } = measureElement(fieldRef.current); setMetrics((current) => current.measured && current.x === x && current.y === y ? current : { x, y, measured: true }, ); }); return ( {display} ); } export interface CycleListProps { readonly choices: ReadonlyArray>; readonly cursor: number; readonly indices: ReadonlyArray; readonly visibleCount?: number; } const stateColor = (variant: CycleChoice["states"][number]["variant"]) => variant === undefined || variant === "neutral" ? undefined : theme.color[variant === "error" ? "danger" : variant]; export function CycleList({ choices, cursor, indices, visibleCount = 12, }: CycleListProps) { const glyphs = useGlyphs(); const { start, end } = overflowListWindow(choices.length, cursor, visibleCount); const labelWidth = labelColumnWidth(choices); // The state word ("add", "remove", …) gets its own column too, so the // descriptions line up whether or not a row's current state carries one. const stateWidth = Math.max( 0, ...choices.flatMap((choice) => choice.states.map((state) => (state.label === undefined ? 0 : stringWidth(state.label))), ), ); return ( {choices.slice(start, end).map((choice, offset) => { const index = start + offset; const state = choice.states[indices[index] ?? 0]; const focused = index === cursor; const color = stateColor(state?.variant); return ( {state?.icon ?? glyphs.bullet} {choice.label} {stateWidth === 0 ? null : ( {state?.label === undefined ? null : {state.label}} )} {choice.description === undefined ? null : ( {choice.description} )} ); })} ); } export const useCycleNavigation = (stateCounts: ReadonlyArray) => { const { cursor, move, setCursor } = useListNavigation(stateCounts.length); const [indices, setIndices] = useState>(() => stateCounts.map(() => 0)); const cycle = (delta: number) => setIndices((current) => current.map((value, index) => { if (index !== cursor) return value; const count = stateCounts[index] ?? 0; return count <= 0 ? 0 : (value + delta + count) % count; }), ); return { cursor, indices, move, setCursor, cycle } as const; }; export interface BrowserLoginWaitProps { readonly message: string; readonly waitingLabel: string; readonly url: string; /** Short code the user confirms on the login page. */ readonly code?: string; readonly openFailed?: boolean; /** Open the login URL again from the waiting screen. */ readonly onOpen?: () => Promise; /** Allow Enter to switch to manual code entry. */ readonly allowManualInput: boolean; readonly inputLabel?: string; readonly placeholder?: string; readonly validate?: (value: string) => string | Error | undefined; readonly onSubmit: (value: string) => void; readonly onCancel: () => void; } /** * Yes/no keyboard handling shared by `InlineConfirm` and the confirm prompt * screen: arrows/tab toggle, Enter commits, y/n answer directly. */ export const useConfirmKeys = ({ initialValue = false, active, onSubmit, onCancel, }: { readonly initialValue?: boolean; readonly active?: boolean; readonly onSubmit: (value: boolean) => void; readonly onCancel?: () => void; }): boolean => { const [value, setValue] = useState(initialValue); useTerminalInput( (input, key) => { if (key.escape) onCancel?.(); else if (key.left || key.right || key.tab || key.up || key.down) setValue((current) => !current); else if (key.enter) onSubmit(value); else if (key.ctrl || key.meta) return; else if (input.toLowerCase() === "y") onSubmit(true); else if (input.toLowerCase() === "n") onSubmit(false); }, { active: active ?? true }, ); return value; }; type InlineConfirmProps = { readonly message: string; readonly initialValue?: boolean; readonly confirmLabel?: string; readonly cancelLabel?: string; readonly active?: boolean; readonly onSubmit: (value: boolean) => void; readonly onCancel?: () => void; }; export function InlineConfirm({ message, initialValue = false, confirmLabel = "Yes", cancelLabel = "No", active, onSubmit, onCancel, }: InlineConfirmProps) { const keys = useKeyGlyphs(); const value = useConfirmKeys({ initialValue, active, onSubmit, onCancel }); return ( {message} ); } export interface ChoiceGroupProps { readonly choices: ReadonlyArray<{ readonly value: Value; readonly label: string; readonly description?: string; }>; readonly value: Value; readonly orientation?: "horizontal" | "vertical"; readonly active?: boolean; readonly onChange?: (value: Value) => void; } export function ChoiceGroup({ choices, value, orientation = "horizontal", active = true, onChange, }: ChoiceGroupProps) { const selected = Math.max( 0, choices.findIndex((choice) => choice.value === value), ); useTerminalInput( (_input, key) => { if (onChange === undefined || choices.length === 0) return; const previous = key.tab && key.shift ? true : orientation === "horizontal" ? key.left : key.up; const next = key.tab || (orientation === "horizontal" ? key.right : key.down); if (!previous && !next) return; const delta = previous ? -1 : 1; const index = (selected + delta + choices.length) % choices.length; onChange(choices[index]!.value); }, { active: active && onChange !== undefined }, ); return ( {choices.map((choice) => { const selected = choice.value === value; return ( {choice.label} {choice.description === undefined ? null : ( · {choice.description} )} ); })} ); } /** Browser login waiting screen with URL controls and manual-entry fallback. */ export function BrowserLoginWait({ message, waitingLabel, url, code, openFailed = false, onOpen, allowManualInput, inputLabel, placeholder, validate, onSubmit, onCancel, }: BrowserLoginWaitProps) { const { stdout } = useStdout(); const glyphs = useGlyphs(); const keyGlyphs = useKeyGlyphs(); const [manual, setManual] = useState(false); const [copied, setCopied] = useState(false); const [browserFailed, setBrowserFailed] = useState(openFailed); const [error, setError] = useState(); const copiedTimer = useRef | undefined>(undefined); useEffect( () => () => { clearTimeout(copiedTimer.current); }, [], ); // Ctrl+C is handled centrally by the screen runner (SigilRuntime.run). useTerminalInput((input, key) => { if (manual) { if (key.escape) { setError(undefined); setManual(false); } return; } const shortcut = input.toLowerCase(); if (key.enter && allowManualInput) setManual(true); else if (key.escape) onCancel(); // Ctrl+C must fall through to the runner's cancel guard, not copy the URL. else if (key.ctrl || key.meta) return; else if (shortcut === "o" && onOpen !== undefined) { setBrowserFailed(false); void onOpen().catch(() => setBrowserFailed(true)); } else if (shortcut === "c") { copyToClipboard(url, stdout ?? process.stdout); setCopied(true); clearTimeout(copiedTimer.current); copiedTimer.current = setTimeout(() => setCopied(false), 2000); } }); if (manual) { const manualInputLabel = inputLabel ?? "Paste the authorization code or callback URL"; return ( { setError(undefined); setManual(false); }} onChange={() => setError(undefined)} onSubmit={(value) => { const problem = validate?.(value); if (problem !== undefined) { setError(problem instanceof Error ? problem.message : problem); } else { onSubmit(value); } }} /> ); } return ( {code === undefined ? null : ( Code {code} )} {browserFailed ? ( {glyphs.warning} Could not open the browser. Copy and open the URL manually. ) : null} {url} ); } export type PromptFrameProps = { readonly message: string; /** * What the prompt waits for, reported as OSC 7501 `blocked` while it is * shown: approvals are `permission`, logins `auth`. * @default "question" */ readonly blocked?: ProgramStatusKind; readonly description?: ReactNode; readonly children: JSX.Element; readonly layout?: "inline" | "stacked"; readonly error?: string; readonly keys?: ReadonlyArray; }; export function PromptFrame({ message, blocked = "question", description, children, layout = "stacked", error, keys, }: PromptFrameProps) { const glyphs = useGlyphs(); useAlchemyStatus({ state: "blocked", kind: blocked, msg: message }); // The active-step glyph shares the heading's brand colour: `◆ question` is // the step being answered, `✓ question` (AnsweredPrompt) one that is done. const heading = (suffix = "") => ( {glyphs.active} {message} {suffix} ); return ( {layout === "inline" ? ( {heading(":")} {children} {description === undefined ? null : ( {description} )} ) : ( <> {heading()} {description === undefined ? null : ( {description} )} {/* Children sit directly under the heading, indented like the answered lines' text; grouping is carried by indentation, not by a rail. */} {children} )} {error === undefined ? null : ( {glyphs.error} {error} )} {keys === undefined ? null : } ); } export const filterChoices = (choices: ReadonlyArray>, query: string) => { const normalized = query.trim().toLowerCase(); const indexed = choices.map((choice, index) => ({ choice, index })); return normalized === "" ? indexed : indexed.filter(({ choice }) => `${choice.group ?? ""} ${choice.label} ${choice.description ?? ""}` .toLowerCase() .includes(normalized), ); }; /** Stable selected-index set for multiselect widgets. */ export const useSelectedChoices = ( choices: ReadonlyArray>, initialValues: ReadonlyArray, ) => useState>( () => new Set( initialValues.flatMap((value) => { const index = choices.findIndex((choice) => choice.value === value); return index === -1 || choices[index]?.disabled ? [] : [index]; }), ), );