@theme-registry/refract 0.1.3 → 0.1.4

package/dist/build/prompt.d.ts

@@ -10,10 +10,36 @@ export interface Choice<T> {
     /** Trailing grey note — what this option means. */
     readonly hint?: string;
 }
+/** The keys a list prompt understands, after decoding an stdin chunk. */
+export type ListKey = "up" | "down" | "space" | "submit" | "all" | "cancel" | "none";
+/** Decode a raw stdin chunk into a {@link ListKey}. Arrows arrive as escape sequences; j/k mirror vim. */
+export declare function decodeKey(chunk: string): ListKey;
 /**
- * A prompt session. Holds one readline interface for the whole interview so stdin is opened and
- * closed exactly once; `interactive` is false when there's no TTY, and every ask short-circuits to
- * its default.
+ * Split one stdin chunk into the keys it contains.
+ *
+ * A held-down arrow key, or fast typing, delivers several sequences in a single `data` event — so
+ * decoding the chunk as one key would swallow all but the first and make the list feel like it drops
+ * input. Escape sequences (`ESC [ <letter>`) are taken as a unit; everything else is one key each.
+ */
+export declare function decodeKeys(chunk: string): ListKey[];
+/** Where a list prompt currently stands. */
+export interface ListState {
+    readonly cursor: number;
+    readonly selected: ReadonlySet<number>;
+    readonly done: boolean;
+    readonly cancelled: boolean;
+}
+/**
+ * Advance a list prompt by one key. Pure — no I/O — so navigation is testable without a terminal.
+ *
+ * The cursor **wraps** at both ends: with six options, up from the first should land on the last
+ * rather than stick. `space` and `a` toggle only in multi mode; in single mode Enter is the commit,
+ * so space would be ambiguous.
+ */
+export declare function applyKey(state: ListState, key: ListKey, count: number, multi: boolean): ListState;
+/**
+ * A prompt session. Holds at most one readline interface, so stdin is opened and closed once;
+ * `interactive` is false when there's no TTY, and every ask short-circuits to its default.
  */
 export declare class Prompter {
     private rl;
@@ -22,17 +48,29 @@ export declare class Prompter {
     private get io();
     close(): void;
     private question;
-    /** Print a line to stdout. Kept on the prompter so command code never touches `process.stdout`. */
+    /** Raw write, no newline — for cursor control during a live render. */
+    private out;
+    /** Print a line. Kept on the prompter so command code never touches `process.stdout`. */
     write(line?: string): void;
     /** Free-text, with a default shown in the prompt. Blank input takes the default. */
     text(label: string, fallback: string, validate?: (v: string) => string | undefined): Promise<string>;
     /** A number, validated as finite. */
     number(label: string, fallback: number, validate?: (v: number) => string | undefined): Promise<number>;
-    /** Pick one. Answers are 1-based indices; blank takes the default (the first choice unless given). */
+    /** Pick one — arrows to move, Enter to choose. */
     select<T>(label: string, choices: readonly Choice<T>[], defaultIndex?: number): Promise<T>;
+    /** Pick any — arrows to move, space to toggle, `a` for all/none, Enter to confirm. */
+    multiselect<T>(label: string, choices: readonly Choice<T>[], preselected: readonly number[]): Promise<T[]>;
     /**
-     * Pick any. Answers are comma-separated indices; blank keeps the pre-selected set, and an explicit
-     * `none` clears it — otherwise there'd be no way to deselect everything with a line-based prompt.
+     * The raw-mode list loop. Renders in place: each keypress rewinds over the block just drawn and
+     * repaints it, so the list stays put instead of scrolling the terminal away.
+     *
+     * Any readline interface is closed first — it would otherwise swallow the keystrokes we need.
+     * `cleanup` always restores the terminal (raw mode off, cursor shown), including on cancel, so a
+     * Ctrl-C can't leave the shell in a state where typing is invisible.
      */
-    multiselect<T>(label: string, choices: readonly Choice<T>[], preselected: readonly number[]): Promise<T[]>;
+    private runList;
+    /** Line-mode fallback: pick one by number. */
+    private selectByNumber;
+    /** Line-mode fallback: pick any by comma-separated numbers. */
+    private multiselectByNumber;
 }