caique/clack

import { CANCEL_SYMBOL, formatInstructionFooter, isCancel, … } from 'caique/clack';

function formatInstructionFooter(instructions: string[], hasGuide: boolean): string[];

function limitOptions<TOption>({ cursor, options, style, output, maxItems, columnPadding, rowPadding, }: LimitOptionsParams<TOption>): string[];

function updateSettings(updates: ClackSettings): void;

const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Answer<Value>;

const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Answer<Value[]>;

const cancel: (message?: string, opts?: CommonOptions) => void;

const CANCEL_SYMBOL: unique symbol;

const confirm: (opts: ConfirmOptions) => Answer<boolean>;

const date: (opts: DateOptions) => Answer<Date>;

const group: <T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>) => Promise<Prettify<PromptGroupAwaitedReturn<T>>>;

const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Answer<Value[]>;

const intro: (title?: string, opts?: CommonOptions) => void;

const isCancel: (value: unknown) => value is symbol;

const isCI: (runtime?: {
    env: PolicyRuntime["env"];
}) => boolean;

const isTTY: (output: {
    isTTY?: boolean;
}) => boolean;

const log: {
    message: (text?: string | string[], opts?: LogMessageOptions) => void;
    info: (text: string, opts?: LogMessageOptions) => void;
    success: (text: string, opts?: LogMessageOptions) => void;
    step: (text: string, opts?: LogMessageOptions) => void;
    warn: (text: string, opts?: LogMessageOptions) => void;
    /** An alias for `log.warn()`. */
    warning: (text: string, opts?: LogMessageOptions) => void;
    /** A failure: written under a quiet runtime too, because `--quiet` never hides one. */
    error: (text: string, opts?: LogMessageOptions) => void;
};

const multiline: (opts: MultiLineOptions) => Answer<string>;

const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Answer<Value[]>;

const MULTISELECT_INSTRUCTIONS: string[];

const note: (text?: string, title?: string, opts?: NoteOptions) => void;

const outro: (message?: string, opts?: CommonOptions) => void;

const password: (opts: PasswordOptions) => Answer<string>;

const path: (opts: PathOptions) => Answer<string>;

const S_BAR: string;

const S_BAR_END: string;

const S_BAR_END_RIGHT: string;

const S_BAR_H: string;

const S_BAR_START: string;

const S_BAR_START_RIGHT: string;

const S_CHECKBOX_ACTIVE: string;

const S_CHECKBOX_INACTIVE: string;

const S_CHECKBOX_SELECTED: string;

const S_CONNECT_LEFT: string;

const S_CORNER_BOTTOM_LEFT: string;

const S_CORNER_BOTTOM_RIGHT: string;

const S_CORNER_TOP_LEFT: string;

const S_CORNER_TOP_RIGHT: string;

const S_ERROR: string;

const S_INFO: string;

const S_PASSWORD_MASK: string;

const S_RADIO_ACTIVE: string;

const S_RADIO_INACTIVE: string;

const S_STEP_ACTIVE: string;

const S_STEP_CANCEL: string;

const S_STEP_ERROR: string;

const S_STEP_SUBMIT: string;

const S_SUCCESS: string;

const S_WARN: string;

const select: <Value>(opts: SelectOptions<Value>) => Answer<Value>;

const SELECT_INSTRUCTIONS: string[];

const selectKey: <Value extends string>(opts: SelectKeyOptions<Value>) => Answer<Value>;

const settings: {
    actions: Set<Action>;
    aliases: Map<string, Action>;
    messages: {
        cancel: string;
        error: string;
    };
    withGuide: boolean;
    accessible: boolean | undefined;
};

const spinner: (opts?: SpinnerOptions) => SpinnerResult;

const stream: {
    message: typeof streamed;
    info: (chunks: Chunks) => Promise<void>;
    success: (chunks: Chunks) => Promise<void>;
    step: (chunks: Chunks) => Promise<void>;
    warn: (chunks: Chunks) => Promise<void>;
    warning: (chunks: Chunks) => Promise<void>;
    error: (chunks: Chunks) => Promise<void>;
};

const symbol: (state: State) => string;

const symbolBar: (state: State) => string | undefined;

const tasks: (list: Task[], opts?: CommonOptions) => Promise<void>;

const text: (opts: TextOptions) => Answer<string>;

const unicode: boolean;

const unicodeOr: (glyph: string, fallback: string) => string;

interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValues?: Value[];
    required?: boolean;
}

interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValue?: Value;
    initialUserInput?: string;
    completeOnTab?: boolean;
}

interface ClackSettings {
    /** Extra keys for an action — `{ w: 'up' }` — which never replace an existing alias. */
    aliases?: Record<string, Action>;
    messages?: {
        cancel?: string;
        error?: string;
    };
    /** `false` draws every prompt without its left-hand guide. */
    withGuide?: boolean;
    /** `true` makes every spinner accessible (static lines) unless it says otherwise. */
    accessible?: boolean;
}

interface CommonOptions {
    input?: NodeJS.ReadableStream;
    output?: NodeJS.WritableStream & SizedOutput;
    signal?: AbortSignal;
    withGuide?: boolean;
    /**
     * Static, screen-reader friendly output (clack 1.9.0): plain lines, appended, with no glyph,
     * guide or escape. Unset, the setting decides, and then `ACCESSIBLE` in the environment.
     */
    accessible?: boolean;
    /**
     * The caller's runtime — burgee's `ctx.runtime` — and the one way `--quiet` reaches this port
     * (`caique-quiet-seam` R1). With `quiet`, the writers that decorate draw nothing; prompts
     * ignore it. Its `env` is the one `CI` is read from. It carries no streams, so `input` and
     * `output` still default to the process's. Never read from the environment: a caller passes it.
     */
    runtime?: PolicyRuntime;
}

interface ConfirmOptions extends CommonOptions {
    message: string;
    active?: string;
    inactive?: string;
    initialValue?: boolean;
    vertical?: boolean;
}

interface DateOptions extends CommonOptions {
    message: string;
    format?: DateFormat;
    locale?: string;
    defaultValue?: Date;
    initialValue?: Date;
    minDate?: Date;
    maxDate?: Date;
    validate?: Validate<Date>;
}

interface GroupMultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Record<string, Option<Value>[]>;
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    selectableGroups?: boolean;
    groupSpacing?: number;
    showInstructions?: boolean;
}

interface LimitOptionsParams<TOption> extends CommonOptions {
    /** The list to display. */
    options: TOption[];
    /** The index of the active option. */
    cursor: number;
    /** Renders one option, told whether it is the active one. */
    style: (option: TOption, active: boolean) => string;
    /** The most options to show, before the terminal's own height is taken into account. */
    maxItems?: number | undefined;
    /** Columns taken by something else on the line — a bar, an indent. */
    columnPadding?: number | undefined;
    /** Rows taken by something else on the screen — a message, a footer. */
    rowPadding?: number | undefined;
}

interface LogMessageOptions extends CommonOptions {
    symbol?: string;
    spacing?: number;
    secondarySymbol?: string;
}

interface MultiLineOptions extends TextOptions {
    /** Draw a `[ submit ]` button, reached with tab, instead of submitting on a second enter. */
    showSubmit?: boolean;
}

interface MultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    showInstructions?: boolean;
}

interface NoteOptions extends CommonOptions {
    /** Applied to every line of the message. */
    format?: (line: string) => string;
}

interface PasswordOptions extends CommonOptions {
    message: string;
    mask?: string;
    validate?: Validate<string>;
    clearOnError?: boolean;
}

interface PathOptions extends CommonOptions {
    message: string;
    root?: string;
    directory?: boolean;
    initialValue?: string;
    validate?: Validate<string>;
}

interface PromptGroupOptions<T> {
    /** Called when a prompt in the group is cancelled, with the answers so far. */
    onCancel?: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<T>>>;
    }) => void;
}

interface SelectKeyOptions<Value extends string> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    caseSensitive?: boolean;
}

interface SelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    maxItems?: number;
    showInstructions?: boolean;
}

interface SizedOutput {
    columns?: number;
    rows?: number;
    isTTY?: boolean;
}

interface SpinnerOptions extends CommonOptions {
    indicator?: 'dots' | 'timer';
    onCancel?: () => void;
    cancelMessage?: string;
    errorMessage?: string;
    frames?: string[];
    delay?: number;
    styleFrame?: (frame: string) => string;
    /**
     * A spinner style as data — flagstaff's `lookupSpinner(name)`, or a plugin's `spinners` entry —
     * in place of `frames` and `delay`: on a terminal its frames turn at its interval, and anywhere
     * else its `static` is printed where the first frame would be (U3). caique imports no registry:
     * the program that has both hands one to the other (D-20261027-prompt-spinner-composed).
     */
    style?: {
        readonly frames: readonly string[];
        readonly interval: number;
        readonly static: string;
    };
}

interface SpinnerResult {
    start(msg?: string): void;
    stop(msg?: string): void;
    cancel(msg?: string): void;
    error(msg?: string): void;
    message(msg?: string): void;
    clear(): void;
    readonly isCancelled: boolean;
}

interface Task {
    title: string;
    task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>;
    enabled?: boolean;
}

interface TextOptions extends CommonOptions {
    message: string;
    placeholder?: string;
    defaultValue?: string;
    initialValue?: string;
    validate?: Validate<string>;
}

type DateFormat = 'YMD' | 'MDY' | 'DMY';

type Option<Value> = Value extends Primitive ? {
    value: Value;
    label?: string;
    hint?: string;
    disabled?: boolean;
} : {
    value: Value;
    label: string;
    hint?: string;
    disabled?: boolean;
};

type PromptGroup<T> = {
    [P in keyof T]: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
    }) => undefined | Promise<T[P] | undefined>;
};

type PromptGroupAwaitedReturn<T> = {
    [P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
};