From 7553b9cfab65cf633183100a1652bd5ed72787a6 Mon Sep 17 00:00:00 2001 From: "Willow (GHOST)" Date: Wed, 29 Apr 2026 18:23:37 +0100 Subject: [PATCH] docs: add jsdoc for `text`, `password`, and `multiline` prompts --- .changeset/five-chicken-hide.md | 5 ++++ packages/prompts/README.md | 4 +-- packages/prompts/src/multi-line.ts | 26 ++++++++++++++++++ packages/prompts/src/password.ts | 36 +++++++++++++++++++++++++ packages/prompts/src/text.ts | 43 ++++++++++++++++++++++++++++++ 5 files changed, 112 insertions(+), 2 deletions(-) create mode 100644 .changeset/five-chicken-hide.md diff --git a/.changeset/five-chicken-hide.md b/.changeset/five-chicken-hide.md new file mode 100644 index 00000000..72313816 --- /dev/null +++ b/.changeset/five-chicken-hide.md @@ -0,0 +1,5 @@ +--- +"@clack/prompts": patch +--- + +docs: add jsdoc for `text`, `password`, and `multiline` prompts diff --git a/packages/prompts/README.md b/packages/prompts/README.md index 7a4ae381..e3655ad9 100644 --- a/packages/prompts/README.md +++ b/packages/prompts/README.md @@ -65,7 +65,7 @@ const meaning = await text({ ### Password -The password component behaves like `text`, but masks the input as the user types. +The password prompt behaves like the [`text`](#text) prompt, but masks the input as the user types. ```js import { password } from '@clack/prompts'; @@ -201,7 +201,7 @@ const basket = await groupMultiselect({ ### Multi-Line Text -The multi-line text component accepts multiple lines of text input. By default, pressing `Enter` twice submits the input. +The multi-line prompt accepts multiple lines of text input. By default, pressing `Enter` twice submits the input. ```js import { multiline } from '@clack/prompts'; diff --git a/packages/prompts/src/multi-line.ts b/packages/prompts/src/multi-line.ts index 4eac8d8b..1491ee09 100644 --- a/packages/prompts/src/multi-line.ts +++ b/packages/prompts/src/multi-line.ts @@ -3,10 +3,36 @@ import { MultiLinePrompt, settings, wrapTextWithPrefix } from '@clack/core'; import { S_BAR, S_BAR_END, symbol } from './common.js'; import type { TextOptions } from './text.js'; +/** + * Options for the {@link multiline} prompt + */ export interface MultiLineOptions extends TextOptions { + /** + * When enabled it shows a `[ submit ]` button that can be focused with tab. + * By default, pressing `Enter` twice submits the input + * + * @default false + */ showSubmit?: boolean; } +/** + * The multi-line prompt accepts multiple lines of text input. + * By default, pressing `Enter` twice submits the input. + * + * @todo docs + * + * @example + * ```ts + * import { multiline } from '@clack/prompts'; + * + * const bio = await multiline({ + * message: 'Enter your bio', + * placeholder: 'Tell us about yourself...', + * showSubmit: true, + * }); + * ``` + */ export const multiline = (opts: MultiLineOptions) => { return new MultiLinePrompt({ validate: opts.validate, diff --git a/packages/prompts/src/password.ts b/packages/prompts/src/password.ts index 693a1710..94d96c71 100644 --- a/packages/prompts/src/password.ts +++ b/packages/prompts/src/password.ts @@ -2,12 +2,48 @@ import { styleText } from 'node:util'; import { PasswordPrompt, settings } from '@clack/core'; import { type CommonOptions, S_BAR, S_BAR_END, S_PASSWORD_MASK, symbol } from './common.js'; +/** + * Options for the {@link password} prompt + */ export interface PasswordOptions extends CommonOptions { + /** + * The prompt message or question shown to the user above the input. + */ message: string; + + /** + * Character to use for masking input. + * @default ▪/• + */ mask?: string; + + /** + * A function that validates user input. Return a `string` or `Error` to show as a + * validation error, or `undefined` to accept the result. + */ validate?: (value: string | undefined) => string | Error | undefined; + + /** + * When enabled it causes the input to be cleared if/when validation fails. + * @default false + */ clearOnError?: boolean; } + +/** + * The password prompt behaves like the {@link text} prompt, but the input is masked. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#password-input + * + * @example + * ```ts + * import { password } from '@clack/prompts'; + * + * const result = await password({ + * message: 'Enter your password', + * }); + * ``` + */ export const password = (opts: PasswordOptions) => { return new PasswordPrompt({ validate: opts.validate, diff --git a/packages/prompts/src/text.ts b/packages/prompts/src/text.ts index 250fd8fd..46fae406 100644 --- a/packages/prompts/src/text.ts +++ b/packages/prompts/src/text.ts @@ -2,14 +2,57 @@ import { styleText } from 'node:util'; import { settings, TextPrompt } from '@clack/core'; import { type CommonOptions, S_BAR, S_BAR_END, symbol } from './common.js'; +/** + * Options for the {@link text} prompt + */ export interface TextOptions extends CommonOptions { + /** + * The prompt message or question shown to the user above the input. + */ message: string; + + /** + * A visual hint shown when the field has no content. + */ placeholder?: string; + + /** + * A fallback value returned when the user provides nothing (empty input). + */ defaultValue?: string; + + /** + * The starting value shown when the prompt first renders. + * Users can edit this value before submitting. + */ initialValue?: string; + + /** + * A function that validates user input. Return a `string` or `Error` to show as a + * validation error, or `undefined` to accept the result. + */ validate?: (value: string | undefined) => string | Error | undefined; } +/** + * The text prompt accepts a single line of text. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#text-input + * + * @example + * ```ts + * import { text } from '@clack/prompts'; + * + * const name = await text({ + * message: 'What is your name?', + * placeholder: 'John Doe', + * validate: (value) => { + * if (!value || value.length < 2) return 'Name must be at least 2 characters'; + * return undefined; + * }, + * }); + * ``` + */ export const text = (opts: TextOptions) => { return new TextPrompt({ validate: opts.validate,