@orkestrel/terminal 0.0.14 → 0.0.15

package/dist/src/server/index.d.cts

@@ -1,20 +1,20 @@
-import { FieldChoice } from '@orkestrel/form';
-import { FieldControl } from '@orkestrel/form';
-import { FieldValue } from '@orkestrel/form';
-import { FormField } from '@orkestrel/form';
-import { FormInterface } from '@orkestrel/form';
-import { FormValues } from '@orkestrel/form';
-import { PromptTheme } from '@orkestrel/terminal';
-import { PromptThemeOptions } from '@orkestrel/terminal';
-import { StreamTargetInterface } from '@orkestrel/console/server';
-import { StylerInterface } from '@orkestrel/console';
-import { TerminalInterface } from '@orkestrel/terminal';
-import { TextField } from '@orkestrel/form';
+import type { FieldChoice } from '@orkestrel/form';
+import type { FieldControl } from '@orkestrel/form';
+import type { FieldValue } from '@orkestrel/form';
+import type { FormField } from '@orkestrel/form';
+import type { FormInterface } from '@orkestrel/form';
+import type { FormValues } from '@orkestrel/form';
+import type { PromptTheme } from '@orkestrel/terminal';
+import type { PromptThemeOptions } from '@orkestrel/terminal';
+import type { StreamTargetInterface } from '@orkestrel/console/server';
+import type { StylerInterface } from '@orkestrel/console';
+import type { TerminalInterface } from '@orkestrel/terminal';
+import type { TextField } from '@orkestrel/form';
 
 /**
- * Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the WHOLE previous (possibly
- * multi-line `select` / `checkbox`) view in one write before the new view is rendered, so a redraw
- * never leaves orphaned rows below.
+ * Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the whole previous view,
+ * which a `select` or `checkbox` can spread over several lines, in one write before the new view is
+ * rendered, so a redraw never leaves orphaned rows behind.
  */
 export declare const CLEAR_DOWN: string;
 
@@ -28,12 +28,12 @@ export declare const CLEAR_DOWN: string;
 export declare const CONTROL_HINTS: Readonly<Partial<Record<FieldControl, string>>>;
 
 /**
- * Creates the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside
- * the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the broker
- * PARKS a live form until somebody elsewhere answers it, a `Terminal` answers one HERE: it walks the
- * form's fields in schema order, drives each control's pure reducer over raw-mode stdin, binds every
- * answer through the form's own `fill`, and submits. It is the only impure part of the terminal
- * stack.
+ * Creates the interactive terminal form driver — the local-keyboard arm of the terminal trio,
+ * beside the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the
+ * broker parks a live form until somebody elsewhere answers it, a `Terminal` answers one here: it
+ * walks the form's fields in schema order, drives each control's pure reducer over raw-mode stdin,
+ * binds every answer through the form's own `fill`, and submits. It is the only impure part of the
+ * terminal stack.
  *
  * @param options - See {@link TerminalOptions}
  * @returns A {@link TerminalInterface} whose `ask` drives one whole form over the resolved streams
@@ -53,29 +53,47 @@ export declare const CONTROL_HINTS: Readonly<Partial<Record<FieldControl, string
  * - **Non-TTY fallback.** A piped stream cannot enter raw mode, so the same walk runs over
  *   `node:readline` line input.
  *
- * @example
+ * @example Ask one form at this keyboard
  * ```ts
  * import { createForm } from '@orkestrel/form'
+ * import { isTerminalError } from '@orkestrel/terminal'
  * import { createTerminal } from '@orkestrel/terminal/server'
  *
- * const terminal = createTerminal()
- * const values = await terminal.ask(
- * 	createForm({
- * 		label: 'Sign up',
- * 		fields: [
- * 			{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
- * 			{ control: 'confirm', name: 'terms', label: 'I accept the terms' },
- * 		],
- * 	}),
- * )
+ * const terminal = createTerminal() // process.stdin / process.stdout by default
+ * const form = createForm({
+ * 	label: 'Sign up',
+ * 	fields: [
+ * 		{ control: 'text', name: 'name', label: 'Your name', rule: { required: true, minimum: 2 } },
+ * 		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+ * 		{ control: 'password', name: 'token', label: 'Token' },
+ * 		{ control: 'confirm', name: 'terms', label: 'Accept the terms', rule: { required: true } },
+ * 		{
+ * 			control: 'select',
+ * 			name: 'role',
+ * 			label: 'Role',
+ * 			choices: [
+ * 				{ value: 'admin', label: 'Admin' },
+ * 				{ value: 'viewer', label: 'Viewer', help: 'read-only' },
+ * 			],
+ * 		},
+ * 	],
+ * })
+ *
+ * try {
+ * 	const values = await terminal.ask(form)
+ * 	deploy(values)
+ * } catch (error) {
+ * 	// Ctrl-c: the walk ended, and the form is still `editing` for whoever owns it.
+ * 	if (isTerminalError(error) && error.code === 'CANCEL') form.destroy()
+ * }
  * ```
  */
 export declare function createTerminal(options?: TerminalOptions): TerminalInterface;
 
 /**
- * Holds the cursor-UP sequence TEMPLATE (`ESC[{count}A`) — {@link import('./helpers.js').renderCursorUp}
- * interpolates the `{count}` placeholder with the number of lines to climb. Kept as a template so
- * the count stays out of the constant.
+ * Holds the cursor-up sequence template (`ESC[{count}A`) —
+ * {@link import('./helpers.js').renderCursorUp} interpolates the `{count}` placeholder with the
+ * number of lines to climb. Kept as a template so the count stays out of the constant.
  */
 export declare const CSI_UP: string;
 
@@ -105,11 +123,11 @@ export declare const FALLBACK_EDITOR_HINT = "(end of input finishes)";
 export declare const FALLBACK_SELECT_HINT = "Enter a number";
 
 /**
- * Projects any field the walk reads as a LINE OF TEXT into the {@link TextField} the text reducer
- * takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`,
- * `time`, `datetime`, `color`, and one `file` entry. The label carries that control's format cue
- * from {@link CONTROL_HINTS}, and a declared `default` becomes the line a bare return submits. The
- * projection carries no rule, because the AUTHORITATIVE form still evaluates the answer this line
+ * Projects any field the walk reads as a line of text into the {@link TextField} the text reducer
+ * takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`, `time`,
+ * `datetime`, `color`, and one `file` entry. The label carries that control's format cue from
+ * {@link CONTROL_HINTS}, and a declared `default` becomes the line a bare return submits. The
+ * projection carries no rule, because the authoritative form still evaluates the answer this line
  * binds; it exists only so one reducer covers every one of them.
  *
  * @param field - The field being read
@@ -127,7 +145,7 @@ export declare function fieldToText(field: FormField): TextField;
 export declare const FILE_HINT = "One path per line, blank to finish";
 
 /**
- * Returns the choices a `select` or `checkbox` field SHOWS but refuses — the complement of
+ * Returns the choices a `select` or `checkbox` field shows but refuses — the complement of
  * {@link filterEnabled}, rendered by {@link renderUnavailableLine} above the list so a reader sees
  * why a declared choice is missing from it.
  *
@@ -137,7 +155,7 @@ export declare const FILE_HINT = "One path per line, blank to finish";
 export declare function filterDisabled(choices: readonly FieldChoice[]): readonly FieldChoice[];
 
 /**
- * Returns the choices a `select` or `checkbox` field actually OFFERS — the form refuses a disabled
+ * Returns the choices a `select` or `checkbox` field actually offers — the form refuses a disabled
  * choice's value at every door, including a fill, so the walk never puts one in front of the
  * cursor. Pair with {@link filterDisabled} to tell the reader what was withheld.
  *
@@ -166,24 +184,30 @@ export declare function filterEnabled(choices: readonly FieldChoice[]): readonly
  * - `isTTY` — `true` on a real terminal, absent or `false` when piped to a file or another process.
  */
 export declare interface InputStreamInterface {
+    /** Subscribes a `'data'` chunk listener — the irreducible event seam. */
     on(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    /** Unsubscribes that listener. The driver always pairs it, so no listener leaks. */
     off(event: 'data', listener: (chunk: string | Uint8Array) => void): void;
+    /** Switches the TTY in and out of raw mode. Absent on a piped stream. */
     setRawMode?(mode: boolean): void;
+    /** Starts the flow of `'data'` events. */
     resume?(): void;
+    /** Stops it again on cleanup. */
     pause?(): void;
+    /** Reports whether the stream is a real terminal; absent or false when piped. */
     readonly isTTY?: boolean;
 }
 
 /**
- * Checks whether `value` is a usable {@link InputStreamInterface} — a record with callable `on` / `off`
- * `'data'` subscription methods. A total type guard: it NEVER throws and returns `false`
- * for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`,
- * or a fake TTY a test injects) to the exact slice the driver reads — no `as`.
+ * Checks whether `value` is a usable {@link InputStreamInterface} — a record with callable `on` /
+ * `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for
+ * anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`,
+ * or a fake TTY a test injects) to the exact slice the driver reads, never an assertion.
  *
  * @remarks
  * Only `on` / `off` are required (the irreducible event seam); `setRawMode` / `resume` / `pause` /
  * `isTTY` are optional on {@link InputStreamInterface}, so their absence does not disqualify a stream
- * — a piped, non-TTY stream is still a valid input, just one the driver reads through the readline
+ * — a piped, non-TTY stream is still a valid input, one the driver reads through the readline
  * fallback rather than raw mode.
  *
  * @param value - Any value crossing the boundary (a process stream, an injected fake, `unknown`)
@@ -193,11 +217,11 @@ export declare function isInputStream(value: unknown): value is InputStreamInter
 
 /**
  * Checks whether `value` is a Node {@link NodeJS.ReadableStream} — a total structural guard
- * checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires
- * as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing
- * it to readline (never an `as`), so a real piped `process.stdin` (or a `PassThrough` a test injects)
- * crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that
- * isn't a full readable.
+ * checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface`
+ * requires as its `input`. The non-TTY fallback narrows the resolved input stream through this
+ * before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a
+ * `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns
+ * `false` for a minimal fake that isn't a full readable.
  *
  * @param value - The resolved input stream (or any value crossing the boundary)
  * @returns True if `value` has the readable methods readline needs; false otherwise
@@ -205,10 +229,10 @@ export declare function isInputStream(value: unknown): value is InputStreamInter
 export declare function isReadable(value: unknown): value is NodeJS.ReadableStream;
 
 /**
- * Counts the terminal LINES a rendered prompt `view` occupies — one more than its newline count
- * (a view with no newline is a single line; N newlines span N+1 lines). The basis of the in-place
- * re-render: the driver records the line count of the view it just wrote so the next redraw knows how
- * far up to move the cursor before overwriting. Total; an empty string is one (empty) line.
+ * Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so
+ * a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of
+ * the in-place re-render: the driver records the line count of the view it wrote so the next redraw
+ * knows how far up to move the cursor before overwriting. Total; an empty string is one empty line.
  *
  * @param view - The rendered (possibly multi-line, possibly ANSI-styled) view string
  * @returns The number of lines the view spans (always at least 1)
@@ -219,20 +243,20 @@ export declare function lineCount(view: string): number;
 export declare const LOCKED_MARK = "(locked)";
 
 /**
- * Returns the full reposition-and-clear prefix to write BEFORE re-rendering a prompt view in place — given
- * the line count of the PREVIOUS view, it moves the cursor up over those lines, returns it to column
- * 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean
- * region (no orphaned rows from a taller previous view). Pure; the driver writes this immediately
- * followed by the new view.
+ * Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place
+ * — given the line count of the previous view, it moves the cursor up over those lines, returns it
+ * to column 0, and erases everything from there to the end of the screen, so the next view is drawn
+ * on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes
+ * this immediately followed by the new view.
  *
  * @remarks
- * For the FIRST render `previousLines` is `1` (the cursor sits on the line the prompt opened on) so
- * the prefix is just a carriage return + clear-down — the prompt draws from the current line. For a
- * subsequent render it climbs `previousLines - 1` lines (the cursor is on the LAST line of the prior
+ * For the first render `previousLines` is `1` (the cursor sits on the line the prompt opened on) so
+ * the prefix is a carriage return + clear-down — the prompt draws from the current line. For a
+ * subsequent render it climbs `previousLines - 1` lines (the cursor is on the last line of the prior
  * view) before clearing. Keeping the math here (not in the driver) makes the re-render unit-testable
  * without a real terminal.
  *
- * @param previousLines - The line count of the view currently on screen (from {@link lineCount})
+ * @param previousLines - The line count of the view on screen (from {@link lineCount})
  * @returns The control-sequence prefix to write before the new view
  */
 export declare function redrawPrefix(previousLines: number): string;
@@ -246,10 +270,10 @@ export declare function redrawPrefix(previousLines: number): string;
 export declare const REFUSAL_MESSAGE = "Enter a value this field accepts";
 
 /**
- * Returns the cursor-UP control sequence that moves the cursor up `count` lines (`ESC[{count}A`) — or the
- * empty string when `count` is zero or negative (no movement needed, and `ESC[0A` is a wasted write).
- * The pure step the in-place re-render uses to climb back over the previous view before clearing it.
- * Total.
+ * Returns the cursor-up control sequence that moves the cursor up `count` lines (`ESC[{count}A`),
+ * or the empty string when `count` is zero or negative, because no movement is needed and `ESC[0A`
+ * is a wasted write. The pure step the in-place re-render uses to climb back over the previous view
+ * before clearing it. Total.
  *
  * @param count - How many lines to move the cursor up
  * @returns The `ESC[{count}A` sequence, or `''` when `count <= 0`
@@ -268,9 +292,9 @@ export declare function renderCursorUp(count: number): string;
 export declare function renderGroupHeader(styler: StylerInterface, theme: PromptTheme, label: string): string;
 
 /**
- * Renders the read-only line a LOCKED field shows — its label, the {@link LOCKED_MARK}, and the
- * answer the form already holds. The walk writes this instead of a prompt, because the field is still
- * validated and still submitted but must not be edited here.
+ * Renders the read-only line a locked field shows — its label, the {@link LOCKED_MARK}, and the
+ * answer the form already holds. The walk writes this instead of a prompt, because the field is
+ * still validated and still submitted but must not be edited here.
  *
  * @param styler - The console styler that renders each role
  * @param theme - The resolved prompt theme
@@ -293,7 +317,7 @@ export declare function renderLockedLine(styler: StylerInterface, theme: PromptT
 export declare function renderNumberedList(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
 
 /**
- * Renders the line listing an OPEN select's offered values above its text prompt — a suggestion
+ * Renders the line listing an open select's offered values above its text prompt — a suggestion
  * list, because an open select admits an answer the list does not offer.
  *
  * @param styler - The console styler that renders each role
@@ -314,15 +338,18 @@ export declare function renderSuggestionLine(styler: StylerInterface, theme: Pro
  */
 export declare function renderUnavailableLine(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]): string;
 
-/** Holds the lead on the line listing an open `select`'s offered values, which a typed answer may ignore. */
+/**
+ * Holds the lead on the line listing an open `select`'s offered values, which a typed answer can
+ * ignore.
+ */
 export declare const SUGGESTION_LEAD = "Suggestions";
 
 /**
- * Checks whether an input stream can be driven in RAW mode — it both reports `isTTY === true` AND
- * exposes a callable `setRawMode`. The {@link import('./Terminal.js').Terminal} probes this to choose its path:
- * `true` ⇒ the interactive raw-mode prompts (arrow-key navigation, live re-render); `false` ⇒ the
- * `node:readline` line-input fallback (a piped / non-terminal stream cannot enter raw mode). Total —
- * never throws.
+ * Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and
+ * exposes a callable `setRawMode`. The {@link import('./Terminal.js').Terminal} probes this to
+ * choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a
+ * live re-render; false selects the `node:readline` line-input fallback, because a piped or
+ * non-terminal stream cannot enter raw mode. Total — never throws.
  *
  * @param input - The resolved {@link InputStreamInterface}
  * @returns True if the stream is a TTY with `setRawMode`; false otherwise
@@ -330,12 +357,13 @@ export declare const SUGGESTION_LEAD = "Suggestions";
 export declare function supportsRawMode(input: InputStreamInterface): boolean;
 
 /**
- * Implements {@link TerminalInterface} for a human at this machine's keyboard — the interactive form
- * DRIVER, and the only impure part of the terminal stack. {@link ask} walks one
- * form's fields in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching
- * pure reducer, renders each returned view in place, and binds every answer through the form's own
- * `fill`. It owns no form logic: the schema, the rules, the values, and the settlement all belong to
- * the form it is given, and this class owns only raw mode, the cursor, and the re-render.
+ * Implements {@link TerminalInterface} for a human at this machine's keyboard — the interactive
+ * form driver, and the only impure part of the terminal stack. {@link ask} walks one form's fields
+ * in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching pure reducer,
+ * renders each returned view in place, binds every answer through the form's own `fill`, and
+ * re-asks what the form refused. It owns no form logic: the schema, the rules, the values, and the
+ * settlement all belong to the form it is given, and this class owns only raw mode, the cursor, and
+ * the re-render.
  *
  * @remarks
  * See {@link TerminalInterface} for the driving contract. The walk itself:
@@ -347,12 +375,11 @@ export declare function supportsRawMode(input: InputStreamInterface): boolean;
  *   `open` means the answer need not come from the list.
  * - **The binding projects through `matchesAnswer`.** Every answer is filled as
  *   `fill(name, matchesAnswer(value) ? value : undefined)` after `parseValue` has coerced it to the
- *   control's own shape, so a bare return on a field with no default binds as ABSENCE and the
+ *   control's own shape, so a bare return on a field with no default binds as absence and the
  *   form's `required` rule refuses it. A typed answer the control cannot hold binds as absence and
  *   invalidates the field, so the walk asks again with the reason on screen.
- * - **Visibility is honored.** A `hidden` field and a field currently in `form.disabled` are
- *   skipped; a `locked` field renders read-only; entering a new group writes its label as a section
- *   header.
+ * - **Visibility is honored.** A `hidden` field and a field in `form.disabled` are skipped; a
+ *   `locked` field renders read-only; entering a new group writes its label as a section header.
  * - **Refusal re-asks.** After the walk the form is submitted. A refusal re-walks only the erroring
  *   fields the walk can edit and submits again. When every erroring field is one the walk cannot
  *   edit — hidden, locked, or disabled — the form is abandoned instead, because asking again could
@@ -384,8 +411,8 @@ export declare class Terminal implements TerminalInterface {
  *   the rendered output. That is the console module's own boundary shape, so one target drives a
  *   console sink and this driver alike.
  * - `theme` — the glyphs and role styles every rendered line is painted with, merged over
- *   {@link import('@src/core').DEFAULT_PROMPT_THEME} leaf by leaf by
- *   {@link import('@src/core').createPromptTheme}. Supplying one icon or one role leaves every
+ *   {@link import('@orkestrel/terminal').DEFAULT_PROMPT_THEME} leaf by leaf by
+ *   {@link import('@orkestrel/terminal').createPromptTheme}. Supplying one icon or one role leaves every
  *   other slot at its default.
  */
 export declare interface TerminalOptions {
@@ -394,7 +421,10 @@ export declare interface TerminalOptions {
     readonly theme?: PromptThemeOptions;
 }
 
-/** Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a reader sees why one is missing from the list below. */
+/**
+ * Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a
+ * reader sees why one is missing from the list it heads.
+ */
 export declare const UNAVAILABLE_LEAD = "Unavailable";
 
 /**