@hyperfrontend/questions 0.2.0 → 0.3.0

package/index.d.ts

@@ -1,13 +1,340 @@
 /**
- * Terminal prompting library with composable, functional API for text, select, confirm, and multiselect prompts.
- *
- * @module @hyperfrontend/questions
- */
-export type { Choice, ConfirmConfig, MultiselectConfig, PromptCancelledOutcome, PromptConfig, PromptFunction, PromptOutcome, PromptSubmittedOutcome, SelectConfig, TextConfig, } from './types';
-export { confirm } from './prompts/confirm';
-export { multiselect } from './prompts/multiselect';
-export { select } from './prompts/select';
-export { text } from './prompts/text';
-export { style } from './render';
-export { PromptResult } from './types';
-//# sourceMappingURL=index.d.ts.map
+ * Result state of a prompt interaction.
+ */
+declare const PromptResult: Readonly<{
+    /** User submitted a value */
+    readonly Submitted: "submitted";
+    /** User cancelled the prompt (Ctrl+C) */
+    readonly Cancelled: "cancelled";
+}>;
+/** Result state of a prompt interaction. */
+type PromptResult = (typeof PromptResult)[keyof typeof PromptResult];
+/**
+ * Base configuration shared by all prompts.
+ */
+interface PromptConfig {
+    /** The question message to display */
+    readonly message: string;
+    /** Stream to read input from (defaults to stdin) */
+    readonly input?: NodeJS.ReadStream;
+    /** Stream to write output to (defaults to stdout) */
+    readonly output?: NodeJS.WriteStream;
+}
+/**
+ * Outcome when user submits a value.
+ */
+interface PromptSubmittedOutcome<T> {
+    /** Submission result indicator */
+    readonly result: typeof PromptResult.Submitted;
+    /** The submitted value */
+    readonly value: T;
+}
+/**
+ * Outcome when user cancels the prompt.
+ */
+interface PromptCancelledOutcome {
+    /** Cancellation result indicator */
+    readonly result: typeof PromptResult.Cancelled;
+    /** No value on cancellation */
+    readonly value: undefined;
+}
+/**
+ * Outcome of a prompt interaction.
+ */
+type PromptOutcome<T> = PromptSubmittedOutcome<T> | PromptCancelledOutcome;
+/**
+ * A prompt function that asks a question and returns a value.
+ */
+type PromptFunction<TConfig extends PromptConfig, TValue> = (config: TConfig) => Promise<PromptOutcome<TValue>>;
+/**
+ * Choice item for select/multiselect prompts.
+ */
+interface Choice<T = string> {
+    /** Display label */
+    readonly label: string;
+    /** Value returned when selected */
+    readonly value: T;
+    /** Optional hint text shown after label */
+    readonly hint?: string;
+    /** Whether this choice is disabled */
+    readonly disabled?: boolean;
+}
+/**
+ * Configuration for text input prompts.
+ */
+interface TextConfig extends PromptConfig {
+    /** Default value if user submits empty input */
+    readonly initial?: string;
+    /** Validator function - return error message string to reject, undefined to accept */
+    readonly validate?: (value: string) => string | undefined;
+    /** Transform display of input (e.g., for password masking) */
+    readonly format?: (value: string) => string;
+    /** Dynamic message recomputed on every keystroke; overrides `message` when present */
+    readonly renderMessage?: (value: string) => string;
+}
+/**
+ * Configuration for confirmation prompts.
+ */
+interface ConfirmConfig extends PromptConfig {
+    /** Default value if user just presses enter */
+    readonly initial?: boolean;
+}
+/**
+ * Configuration for single-select prompts.
+ */
+interface SelectConfig<T = string> extends PromptConfig {
+    /** Available choices */
+    readonly choices: ReadonlyArray<Choice<T>>;
+    /** Index of initially selected choice */
+    readonly initial?: number;
+    /** Maximum number of visible choices (enables scrolling) */
+    readonly maxVisible?: number;
+    /** Enable type-to-filter */
+    readonly searchable?: boolean;
+}
+/**
+ * Configuration for multi-select prompts.
+ */
+interface MultiselectConfig<T = string> extends PromptConfig {
+    /** Available choices */
+    readonly choices: ReadonlyArray<Choice<T>>;
+    /** Indices of initially selected choices */
+    readonly initial?: ReadonlyArray<number>;
+    /** Maximum number of visible choices (enables scrolling) */
+    readonly maxVisible?: number;
+    /** Minimum required selections */
+    readonly min?: number;
+    /** Maximum allowed selections */
+    readonly max?: number;
+    /** Enable type-to-filter */
+    readonly searchable?: boolean;
+}
+
+/**
+ * Prompts for yes/no confirmation.
+ *
+ * Pure functional prompt that asks a yes/no question and returns a boolean.
+ * Supports default values and responds to y/Y/n/N keys. A pasted
+ * `y`/`yes`/`n`/`no` (trimmed, case-insensitive) is accepted; any other
+ * paste is ignored. The prompt repaints on terminal resize.
+ *
+ * @param config - Confirm prompt configuration
+ * @returns Promise resolving to boolean value or cancellation
+ *
+ * @example Basic confirmation
+ * ```typescript
+ * const outcome = await confirm({ message: 'Continue?' })
+ * if (outcome.result === 'submitted' && outcome.value) {
+ *   console.log('Proceeding...')
+ * }
+ * ```
+ *
+ * @example With default value
+ * ```typescript
+ * const outcome = await confirm({
+ *   message: 'Enable feature?',
+ *   initial: true, // Default to yes
+ * })
+ * ```
+ */
+declare function confirm(config: ConfirmConfig): Promise<PromptOutcome<boolean>>;
+
+/**
+ * Prompts for multiple selections from a list of choices.
+ *
+ * Pure functional prompt with arrow key navigation, space to toggle,
+ * scrolling support, min/max constraints, and optional type-to-filter
+ * search. In searchable mode, pasted text appends its first line to the
+ * filter query; pasting never toggles or submits. The prompt repaints on
+ * terminal resize, preserving cursor, selection, and scroll state.
+ *
+ * @param config - Multiselect prompt configuration
+ * @returns Promise resolving to array of selected values or cancellation
+ *
+ * @example Basic multiselect
+ * ```typescript
+ * const outcome = await multiselect({
+ *   message: 'Select toppings:',
+ *   choices: [
+ *     { label: 'Cheese', value: 'cheese' },
+ *     { label: 'Pepperoni', value: 'pepperoni' },
+ *     { label: 'Mushrooms', value: 'mushrooms' },
+ *   ],
+ * })
+ * if (outcome.result === 'submitted') {
+ *   console.log(`You selected: ${outcome.value.join(', ')}`)
+ * }
+ * ```
+ *
+ * @example With search and constraints
+ * ```typescript
+ * const outcome = await multiselect({
+ *   message: 'Select features:',
+ *   choices: features.map((f) => ({ label: f.name, value: f.id })),
+ *   searchable: true,
+ *   min: 1,
+ *   max: 5,
+ * })
+ * ```
+ *
+ * @example Pre-selected values
+ * ```typescript
+ * const outcome = await multiselect({
+ *   message: 'Select permissions:',
+ *   choices: permissions,
+ *   initial: [0, 2], // First and third choices pre-selected
+ * })
+ * ```
+ */
+declare function multiselect<T = string>(config: MultiselectConfig<T>): Promise<PromptOutcome<ReadonlyArray<T>>>;
+
+/**
+ * Prompts for single selection from a list of choices.
+ *
+ * Pure functional prompt with arrow key navigation, scrolling support,
+ * optional disabled choices, and optional type-to-filter search. In
+ * searchable mode, pasted text appends its first line to the filter query.
+ * The prompt repaints on terminal resize, preserving cursor and scroll
+ * state.
+ *
+ * @param config - Select prompt configuration
+ * @returns Promise resolving to selected value or cancellation
+ *
+ * @example Basic select
+ * ```typescript
+ * const outcome = await select({
+ *   message: 'Choose a color:',
+ *   choices: [
+ *     { label: 'Red', value: 'red' },
+ *     { label: 'Green', value: 'green' },
+ *     { label: 'Blue', value: 'blue' },
+ *   ],
+ * })
+ * if (outcome.result === 'submitted') {
+ *   console.log(`You chose: ${outcome.value}`)
+ * }
+ * ```
+ *
+ * @example With hints and disabled options
+ * ```typescript
+ * const outcome = await select({
+ *   message: 'Select plan:',
+ *   choices: [
+ *     { label: 'Free', value: 'free', hint: '$0/month' },
+ *     { label: 'Pro', value: 'pro', hint: '$10/month' },
+ *     { label: 'Enterprise', value: 'enterprise', disabled: true },
+ *   ],
+ *   initial: 1, // Start on Pro
+ * })
+ * ```
+ *
+ * @example With search
+ * ```typescript
+ * const outcome = await select({
+ *   message: 'Pick a project:',
+ *   choices: projects.map((p) => ({ label: p.name, value: p.id })),
+ *   searchable: true,
+ * })
+ * ```
+ */
+declare function select<T = string>(config: SelectConfig<T>): Promise<PromptOutcome<T>>;
+
+/**
+ * Prompts for text input with optional validation.
+ *
+ * Pure functional prompt that reads text from the user with support for
+ * default values, input validation, and display formatting. Pasted text is
+ * sanitized (newlines collapse to spaces, control characters are removed)
+ * and inserted at the cursor without ever auto-submitting. The prompt
+ * repaints on terminal resize, preserving value, cursor, and any
+ * validation error.
+ *
+ * @param config - Text prompt configuration
+ * @returns Promise resolving to submitted value or cancellation
+ *
+ * @example Basic text input
+ * ```typescript
+ * const outcome = await text({ message: 'What is your name?' })
+ * if (outcome.result === 'submitted') {
+ *   console.log(`Hello, ${outcome.value}!`)
+ * }
+ * ```
+ *
+ * @example With validation
+ * ```typescript
+ * const outcome = await text({
+ *   message: 'Enter email:',
+ *   validate: (value) => {
+ *     if (!value.includes('@')) return 'Must be a valid email'
+ *     return undefined
+ *   },
+ * })
+ * ```
+ *
+ * @example Password input with masking
+ * ```typescript
+ * const outcome = await text({
+ *   message: 'Password:',
+ *   format: (value) => '*'.repeat(value.length),
+ * })
+ * ```
+ */
+declare function text(config: TextConfig): Promise<PromptOutcome<string>>;
+
+/**
+ * Style functions for ANSI text formatting.
+ */
+declare const style: Readonly<{
+    /**
+     * Applies bold styling to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in bold ANSI codes
+     */
+    bold: (text: string) => string;
+    /**
+     * Applies dim styling to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in dim ANSI codes
+     */
+    dim: (text: string) => string;
+    /**
+     * Applies cyan color to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in cyan ANSI codes
+     */
+    cyan: (text: string) => string;
+    /**
+     * Applies green color to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in green ANSI codes
+     */
+    green: (text: string) => string;
+    /**
+     * Applies yellow color to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in yellow ANSI codes
+     */
+    yellow: (text: string) => string;
+    /**
+     * Applies red color to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in red ANSI codes
+     */
+    red: (text: string) => string;
+    /**
+     * Applies gray color to text.
+     *
+     * @param text - Text to style
+     * @returns Text wrapped in gray ANSI codes
+     */
+    gray: (text: string) => string;
+}>;
+
+export { PromptResult, confirm, multiselect, select, style, text };
+export type { Choice, ConfirmConfig, MultiselectConfig, PromptCancelledOutcome, PromptConfig, PromptFunction, PromptOutcome, PromptSubmittedOutcome, SelectConfig, TextConfig };