caique 0.2.0 → 0.3.1

package/dist/inquirer-keys.d.ts

@@ -0,0 +1,31 @@
+/** What `node:readline` hands a keypress listener. Widened to what the predicates read. */
+export interface KeypressEvent {
+    name: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+    sequence?: string;
+}
+/** The two named keybinding sets the incumbent understands. Anything else is ignored. */
+export type Keybinding = 'emacs' | 'vim';
+/**
+ * `INQUIRER_KEYBINDINGS` split on whitespace or commas, lowercased, unknown names dropped
+ * and duplicates collapsed — so `'vim emacs unknown vim'` is `['vim', 'emacs']`.
+ */
+export declare function getDefaultKeybindings(): Keybinding[];
+/** The up arrow always; `k` under vim; `Ctrl-P` under emacs. Nothing else, ever. */
+export declare const isUpKey: (key: KeypressEvent, keybindings?: readonly Keybinding[]) => boolean;
+/** The down arrow always; `j` under vim; `Ctrl-N` under emacs. */
+export declare const isDownKey: (key: KeypressEvent, keybindings?: readonly Keybinding[]) => boolean;
+/** The space bar. */
+export declare const isSpaceKey: (key: KeypressEvent) => boolean;
+/** Backspace. */
+export declare const isBackspaceKey: (key: KeypressEvent) => boolean;
+/** Tab. */
+export declare const isTabKey: (key: KeypressEvent) => boolean;
+/** A digit. `name` is a single character for these, so a substring test is the whole test. */
+export declare const isNumberKey: (key: KeypressEvent) => boolean;
+/** Enter, under either name readline gives it. */
+export declare const isEnterKey: (key: KeypressEvent) => boolean;
+/** Whether shift was held. Returns the flag itself, so an absent flag reads as `false`. */
+export declare const isShiftKey: (key: KeypressEvent) => boolean;

package/dist/inquirer-keys.js

@@ -0,0 +1,22 @@
+import { processRuntime } from './runtime.js';
+const KEYBINDINGS = new Set(['emacs', 'vim']);
+const isKeybinding = (value) => KEYBINDINGS.has(value);
+export function getDefaultKeybindings() {
+    const env = processRuntime().env['INQUIRER_KEYBINDINGS'];
+    if (env === undefined || env === '')
+        return [];
+    return [
+        ...new Set(env
+            .toLowerCase()
+            .split(/[\s,]+/)
+            .filter(isKeybinding)),
+    ];
+}
+export const isUpKey = (key, keybindings = []) => key.name === 'up' || (keybindings.includes('vim') && key.name === 'k') || (keybindings.includes('emacs') && key.ctrl === true && key.name === 'p');
+export const isDownKey = (key, keybindings = []) => key.name === 'down' || (keybindings.includes('vim') && key.name === 'j') || (keybindings.includes('emacs') && key.ctrl === true && key.name === 'n');
+export const isSpaceKey = (key) => key.name === 'space';
+export const isBackspaceKey = (key) => key.name === 'backspace';
+export const isTabKey = (key) => key.name === 'tab';
+export const isNumberKey = (key) => '1234567890'.includes(key.name);
+export const isEnterKey = (key) => key.name === 'enter' || key.name === 'return';
+export const isShiftKey = (key) => key.shift === true;

package/dist/inquirer-screen.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Everything between a rendered string and the bytes a terminal receives: the escape
+ * sequences, the muteable output stream, and the screen manager that erases what it drew
+ * last time before it draws again.
+ *
+ * ## Why the escape sequences are written out here
+ *
+ * `@inquirer/core` takes them from `@inquirer/ansi`, and the suite imports `cursorShow`,
+ * `cursorLeft` and `eraseLines` from that package to assert against our output — so these
+ * are not ours to choose. The one case that compares a raw frame byte for byte (`allow
+ * cleaning the prompt after completion`) is what proves they are right.
+ *
+ * The cursor-visibility sequence is the exception and comes from `closeout`, which owns it
+ * across the family. The rest are CSI, which `paratext` states as out of scope, so there is
+ * no family subpath to take them from and they are stated here.
+ *
+ * ## Why there is a stream class here
+ *
+ * The incumbent wraps a caller's output in `mute-stream` so `readline` can write its own
+ * terminal setup and then be silenced, leaving the screen manager as the only thing that
+ * draws. That is a real behaviour rather than a dependency detail — muting is what stops
+ * readline echoing a password — and caique reaches nothing outside this repository, so the
+ * twenty lines of it live here. It is an old-style `Stream` on purpose: `create-prompt`
+ * branches on whether the *input* has `readableFlowing`, and a caller who passes a classic
+ * stream must get the synchronous first render the incumbent gives them.
+ */
+import { Stream } from 'node:stream';
+/** Move the cursor to the first column. */
+export declare const cursorLeft = "\u001B[G";
+/**
+ * Show the cursor — taken from `closeout`, not spelled again here.
+ *
+ * `inline-implementation-lock.test.ts` is what insists on that, and it is right to: this
+ * package already carried a hand-written copy of `?25l`/`?25h` once, and removing it found
+ * that caique never restored the cursor on a signal at all. A third copy for a façade would
+ * be the same defect wearing a compatibility badge.
+ */
+export declare const cursorShow = "\u001B[?25h";
+/** Move the cursor up `rows` rows. Zero is no sequence at all, not a zero-length move. */
+export declare const cursorUp: (rows?: number) => string;
+/** Move the cursor down `rows` rows. */
+export declare const cursorDown: (rows?: number) => string;
+/** Move the cursor to column `x` (zero-based), or to `(x, y)` when a row is given. */
+export declare const cursorTo: (x: number, y?: number) => string;
+/** Erase `lines` lines, ending on the first column of the topmost one. */
+export declare const eraseLines: (lines: number) => string;
+/**
+ * A writable stream that can be told to stop writing, and to start again.
+ *
+ * Declared as the four members the screen manager actually touches rather than as
+ * `NodeJS.WritableStream`: `end()`'s full overload set is three signatures wide and none of
+ * them is what a muted stream means by ending.
+ */
+export interface Muteable {
+    write: (chunk: string | Uint8Array) => boolean;
+    mute: () => void;
+    unmute: () => void;
+    columns?: number | undefined;
+    rows?: number | undefined;
+}
+/**
+ * The incumbent's `mute-stream`, reduced to what a prompt uses.
+ *
+ * Classic `Stream`, emitting `data`, so `pipe()` reaches the caller's real output and so
+ * `'readableFlowing' in stream` is false — which is the test `create-prompt` uses to decide
+ * whether stale buffered input needs a tick to drain before the first render.
+ *
+ * `columns` and `rows` read through to whatever it is piped to: a terminal's size belongs
+ * to the terminal, and a test double that declares ten thousand columns must be believed.
+ */
+export declare class MuteStream extends Stream implements Muteable {
+    #private;
+    muted: boolean;
+    writable: boolean;
+    readable: boolean;
+    get columns(): number | undefined;
+    get rows(): number | undefined;
+    get isTTY(): boolean;
+    mute(): void;
+    unmute(): void;
+    pipe<T extends NodeJS.WritableStream>(dest: T, options?: {
+        end?: boolean;
+    }): T;
+    write(chunk: string | Uint8Array): boolean;
+    end(chunk?: string | Uint8Array): this;
+}
+/**
+ * The width to wrap at: what the output says, then `COLUMNS`, then eighty.
+ *
+ * `cli-width`'s order, minus the `tty.getWindowSize` fallback it keeps for a stream that
+ * reports no `columns` at all — a stream that knows its width reports it, and one that does
+ * not is not necessarily the process's own terminal.
+ */
+export declare function outputWidth(output: {
+    columns?: number | undefined;
+} | undefined): number;
+/**
+ * Hard-wrap every line at `width`, keeping escape sequences intact and trailing whitespace
+ * off. `linegauge/wrap` is this repository's port of `wrap-ansi`, graded against it.
+ */
+export declare function breakLines(content: string, width: number): string;
+/** The readline interface the screen manager drives, narrowed to what it touches. */
+export interface ScreenReadline {
+    line: string;
+    output: Muteable;
+    setPrompt: (prompt: string) => void;
+    getCursorPos: () => {
+        rows: number;
+        cols: number;
+    };
+    close: () => void;
+}
+/**
+ * Draws a prompt and erases what it drew last time.
+ *
+ * The arithmetic is the incumbent's, and it has to be: `getScreen({ raw: true })` compares a
+ * whole frame against `eraseLines(1) + cursorLeft + cursorShow`, so an extra `cursorTo` or a
+ * missing newline is a failing case rather than a cosmetic difference.
+ */
+export declare class ScreenManager {
+    #private;
+    constructor(rl: ScreenReadline);
+    /** Draw `content`, with `bottomContent` below the cursor line. */
+    render(content: string, bottomContent?: string): void;
+    /** Re-issue the horizontal move when readline has moved the cursor under a muted stream. */
+    checkCursorPos(): void;
+    /** Settle: leave the answer on screen, or erase it, and give the cursor back either way. */
+    done({ clearContent }: {
+        clearContent: boolean;
+    }): void;
+}

package/dist/inquirer-screen.js

@@ -0,0 +1,122 @@
+import { Stream } from 'node:stream';
+import { stripVTControlCharacters } from 'node:util';
+import { SHOW_CURSOR } from 'closeout/cursor';
+import { wrap } from 'linegauge/wrap';
+import { processRuntime } from './runtime.js';
+const ESC = '[';
+export const cursorLeft = `${ESC}G`;
+export const cursorShow = SHOW_CURSOR;
+export const cursorUp = (rows = 1) => (rows > 0 ? `${ESC}${String(rows)}A` : '');
+export const cursorDown = (rows = 1) => (rows > 0 ? `${ESC}${String(rows)}B` : '');
+export const cursorTo = (x, y) => (typeof y === 'number' && !Number.isNaN(y) ? `${ESC}${String(y + 1)};${String(x + 1)}H` : `${ESC}${String(x + 1)}G`);
+const eraseLine = `${ESC}2K`;
+export const eraseLines = (lines) => (lines > 0 ? (eraseLine + cursorUp(1)).repeat(lines - 1) + eraseLine + cursorLeft : '');
+const DEFAULT_WIDTH = 80;
+const DECIMAL = 10;
+export class MuteStream extends Stream {
+    muted = false;
+    writable = true;
+    readable = true;
+    #dest;
+    get columns() {
+        return this.#dest?.columns;
+    }
+    get rows() {
+        return this.#dest?.rows;
+    }
+    get isTTY() {
+        return this.#dest?.isTTY ?? false;
+    }
+    mute() {
+        this.muted = true;
+    }
+    unmute() {
+        this.muted = false;
+    }
+    pipe(dest, options) {
+        this.#dest = dest;
+        return super.pipe(dest, options);
+    }
+    write(chunk) {
+        if (this.muted)
+            return true;
+        this.emit('data', chunk);
+        return true;
+    }
+    end(chunk) {
+        if (chunk !== undefined && !this.muted)
+            this.emit('data', chunk);
+        this.emit('end');
+        return this;
+    }
+}
+export function outputWidth(output) {
+    const declared = output?.columns;
+    if (typeof declared === 'number' && declared > 0)
+        return declared;
+    const fromEnv = Number.parseInt(processRuntime().env['COLUMNS'] ?? '', DECIMAL);
+    return Number.isNaN(fromEnv) || fromEnv <= 0 ? DEFAULT_WIDTH : fromEnv;
+}
+export function breakLines(content, width) {
+    return content
+        .split('\n')
+        .flatMap((line) => wrap(line, width, { trim: false, wordWrap: false })
+        .split('\n')
+        .map((row) => row.trimEnd()))
+        .join('\n');
+}
+const height = (content) => content.split('\n').length;
+const lastLine = (content) => content.split('\n').pop() ?? '';
+export class ScreenManager {
+    #height = 0;
+    #extraLinesUnderPrompt = 0;
+    #cursorPos;
+    #rl;
+    constructor(rl) {
+        this.#rl = rl;
+        this.#cursorPos = rl.getCursorPos();
+    }
+    #write(content) {
+        this.#rl.output.unmute();
+        this.#rl.output.write(content);
+        this.#rl.output.mute();
+    }
+    render(content, bottomContent = '') {
+        const promptLine = lastLine(content);
+        const rawPromptLine = stripVTControlCharacters(promptLine);
+        let prompt = rawPromptLine;
+        if (this.#rl.line.length > 0)
+            prompt = prompt.slice(0, -this.#rl.line.length);
+        this.#rl.setPrompt(prompt);
+        this.#cursorPos = this.#rl.getCursorPos();
+        const width = outputWidth(this.#rl.output);
+        const wrapped = breakLines(content, width);
+        const wrappedBottom = breakLines(bottomContent, width);
+        const body = rawPromptLine.length % width === 0 ? `${wrapped}\n` : wrapped;
+        let output = body + (wrappedBottom ? `\n${wrappedBottom}` : '');
+        const promptLineUpDiff = Math.floor(rawPromptLine.length / width) - this.#cursorPos.rows;
+        const bottomContentHeight = promptLineUpDiff + (wrappedBottom ? height(wrappedBottom) : 0);
+        if (bottomContentHeight > 0)
+            output += cursorUp(bottomContentHeight);
+        output += cursorTo(this.#cursorPos.cols);
+        this.#write(cursorDown(this.#extraLinesUnderPrompt) + eraseLines(this.#height) + output);
+        this.#extraLinesUnderPrompt = bottomContentHeight;
+        this.#height = height(output);
+    }
+    checkCursorPos() {
+        const cursorPos = this.#rl.getCursorPos();
+        if (cursorPos.cols !== this.#cursorPos.cols) {
+            this.#write(cursorTo(cursorPos.cols));
+            this.#cursorPos = cursorPos;
+        }
+    }
+    done({ clearContent }) {
+        this.#rl.setPrompt('');
+        let output = cursorDown(this.#extraLinesUnderPrompt);
+        output += clearContent ? eraseLines(this.#height) : '\n';
+        output += cursorLeft;
+        output += cursorShow;
+        this.#write(output);
+        this.#rl.close();
+    }
+}

package/dist/inquirer-theme.d.ts

@@ -0,0 +1,58 @@
+import { type Keybinding } from './inquirer-keys.js';
+/** `figures.tick`. */
+export declare const TICK: string;
+/**
+ * `figures.line`, the box-drawing dash a `Separator` is made of.
+ *
+ * Not conditional, and that is not an oversight: `figures` replaces a fixed list of symbols
+ * on a console without unicode, and `line` is not on it. Only `tick` above is.
+ */
+export declare const LINE = "\u2500";
+/** The lifecycle a prompt reports through `theme.prefix`. Open, so a caller may add states. */
+export type Status = 'loading' | 'idle' | 'done' | (string & {});
+/** The prefix a prompt draws: one string for every state, or one per state. */
+export type ThemePrefix = string | Record<string, string>;
+/** The spinner `usePrefix` runs while a prompt reports `loading`. */
+export interface ThemeSpinner {
+    interval: number;
+    frames: string[];
+}
+/** The style functions a prompt reaches for. Named exactly as the incumbent names them. */
+export interface ThemeStyle {
+    answer: (text: string) => string;
+    message: (text: string, status: Status) => string;
+    error: (text: string) => string;
+    defaultAnswer: (text: string) => string;
+    help: (text: string) => string;
+    highlight: (text: string) => string;
+    key: (text: string) => string;
+}
+/** The whole theme, as a prompt sees it after `makeTheme` has merged the defaults in. */
+export interface Theme {
+    prefix: ThemePrefix;
+    spinner: ThemeSpinner;
+    keybindings: Keybinding[];
+    style: ThemeStyle;
+}
+/** What a caller may hand `makeTheme`: any subset, nested. */
+export type PartialTheme<Extension = object> = Partial<Omit<Theme, 'style' | 'spinner'>> & {
+    spinner?: Partial<ThemeSpinner>;
+    style?: Partial<ThemeStyle>;
+} & Partial<Extension>;
+/**
+ * The incumbent's defaults, byte for byte where a byte is observable.
+ *
+ * `styleText` is `node:util`'s, which is the whole colour dependency: roundel owns colour
+ * for caique's own widgets, and reaching for it here would put a second policy on a subpath
+ * whose job is to behave like somebody else's package.
+ */
+export declare const defaultTheme: Theme;
+/** The defaults with the environment's keybindings folded in, read fresh on every call. */
+export declare function getDefaultTheme(): Theme;
+/**
+ * Merge any number of partial themes over the defaults, last one winning per leaf.
+ *
+ * `null` and `undefined` entries are dropped rather than merged, because a prompt passes
+ * `config.theme` straight through and a caller who set no theme passes `undefined`.
+ */
+export declare function makeTheme<Extension = object>(...themes: readonly (PartialTheme<Extension> | undefined)[]): Theme & Extension;

package/dist/inquirer-theme.js

@@ -0,0 +1,51 @@
+import { styleText } from 'node:util';
+import { getDefaultKeybindings } from './inquirer-keys.js';
+import { processRuntime } from './runtime.js';
+const env = processRuntime().env;
+const UNICODE = process.platform !== 'win32' || env['WT_SESSION'] !== undefined || env['TERM_PROGRAM'] === 'vscode' || env['TERM'] === 'xterm-256color';
+export const TICK = UNICODE ? '✔' : '√';
+export const LINE = '─';
+const SPINNER_INTERVAL_MS = 80;
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const defaultTheme = {
+    prefix: { idle: styleText('blue', '?'), done: styleText('green', TICK) },
+    spinner: { interval: SPINNER_INTERVAL_MS, frames: FRAMES.map((frame) => styleText('yellow', frame)) },
+    keybindings: [],
+    style: {
+        answer: (text) => styleText('cyan', text),
+        message: (text) => styleText('bold', text),
+        error: (text) => styleText('red', `> ${text}`),
+        defaultAnswer: (text) => styleText('dim', `(${text})`),
+        help: (text) => styleText('dim', text),
+        highlight: (text) => styleText('cyan', text),
+        key: (text) => styleText('cyan', styleText('bold', `<${text}>`)),
+    },
+};
+export function getDefaultTheme() {
+    return { ...defaultTheme, keybindings: getDefaultKeybindings() };
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    let proto = value;
+    let next = Object.getPrototypeOf(proto);
+    while (next !== null) {
+        proto = next;
+        next = Object.getPrototypeOf(proto);
+    }
+    return Object.getPrototypeOf(value) === proto;
+}
+function deepMerge(...objects) {
+    const output = {};
+    for (const object of objects) {
+        for (const [key, value] of Object.entries(object)) {
+            const previous = output[key];
+            output[key] = isPlainObject(previous) && isPlainObject(value) ? deepMerge(previous, value) : value;
+        }
+    }
+    return output;
+}
+export function makeTheme(...themes) {
+    const toMerge = [getDefaultTheme(), ...themes.filter((theme) => theme != null)];
+    return deepMerge(...toMerge);
+}

package/dist/inquirer.d.ts

@@ -0,0 +1,72 @@
+import { type PromptReadline } from './inquirer-hooks.js';
+import { type KeypressEvent } from './inquirer-keys.js';
+import { type PartialTheme, type Status } from './inquirer-theme.js';
+/**
+ * A non-choice in a list of choices.
+ *
+ * `isSeparator` is a duck type rather than an `instanceof` check, and deliberately so: a
+ * caller who built `{ type: 'separator', separator: '----' }` by hand — or who has two
+ * copies of the package in their tree — must still have it recognised. One of the three
+ * graded cases is exactly that object literal.
+ */
+export declare class Separator {
+    readonly separator: string;
+    readonly type = "separator";
+    constructor(separator?: string);
+    /** Whether `choice` is a separator — by shape, never by class. */
+    static isSeparator(choice: unknown): choice is Separator;
+}
+/**
+ * The prefix a prompt draws, and the spinner that replaces it while the prompt is loading.
+ *
+ * The 300 ms delay before the spinner appears is not decoration: it is what stops a prompt
+ * that resolves quickly from flickering a frame of spinner on its way past, and the graded
+ * case advances fake timers by exactly `delay + interval` to see the first frame.
+ */
+export declare function usePrefix({ status, theme }: {
+    status?: Status;
+    theme?: PartialTheme;
+}): string;
+/**
+ * Register a keypress handler for as long as the prompt is rendering.
+ *
+ * `ignore` rather than only `removeListener`, because readline emits every keypress in one
+ * `data` event synchronously: a handler removed during that burst would still be called for
+ * the keys already queued behind the one that settled the prompt. Two graded cases — "after
+ * the prompt is done" and "after the prompt is aborted" — are that exact race.
+ */
+export declare function useKeypress(userHandler: (event: KeypressEvent, rl: PromptReadline) => void | Promise<void>): void;
+/** What a render function returns: one string, or a body and a line below the cursor. */
+export type ViewFunction<Value, Config> = (config: Config, done: (value: Value) => void) => string | [string, string | undefined];
+/** The streams and lifetime a caller may hand a prompt. */
+export interface Context {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    clearPromptOnDone?: boolean;
+    signal?: AbortSignal;
+}
+/** The promise a prompt returns: cancellable, so a caller can take the question back. */
+export type CancelablePromise<Value> = Promise<Value> & {
+    cancel: () => void;
+};
+/** A prompt, ready to be called with its config. */
+export type Prompt<Value, Config> = (config: Config, context?: Context) => CancelablePromise<Value>;
+/**
+ * Turn a render function into a prompt.
+ *
+ * Two lines, because the interesting half is `runPrompt` and the only thing this one adds
+ * is the call site — captured now rather than at the throw, since the error a render
+ * function gets for returning nothing names the file `createPrompt` was called from.
+ */
+export declare function createPrompt<Value, Config>(view: ViewFunction<Value, Config>): Prompt<Value, Config>;
+/**
+ * The rest of `@inquirer/core`'s surface, re-exported from the modules that hold it.
+ *
+ * At the end of the file rather than the top because `import-next/exports-last` says so,
+ * and the rule is right about this one: a reader arriving at `caique/inquirer` wants the
+ * prompt loop first and the vocabulary list last.
+ */
+export { AbortPromptError, CancelPromptError, ExitPromptError, HookError, ValidationError } from './inquirer-errors.js';
+export { useEffect, useMemo, useRef, useState, type SetState } from './inquirer-hooks.js';
+export { getDefaultKeybindings, isBackspaceKey, isDownKey, isEnterKey, isNumberKey, isShiftKey, isSpaceKey, isTabKey, isUpKey, type Keybinding, type KeypressEvent, } from './inquirer-keys.js';
+export { defaultTheme, getDefaultTheme, makeTheme, type PartialTheme, type Status, type Theme } from './inquirer-theme.js';