From 0e66ce975c8ad1b2182078de95abb58cbc827146 Mon Sep 17 00:00:00 2001 From: "Willow (GHOST)" Date: Wed, 13 May 2026 00:29:11 +0100 Subject: [PATCH 1/2] docs: add jsdoc for `autocomplete`, `confirm`, and `path` prompts --- .changeset/yellow-bats-listen.md | 5 ++ packages/prompts/README.md | 27 ++++++++- packages/prompts/src/autocomplete.ts | 89 ++++++++++++++++++++++++---- packages/prompts/src/confirm.ts | 42 +++++++++++++ packages/prompts/src/path.ts | 46 +++++++++++++- 5 files changed, 192 insertions(+), 17 deletions(-) create mode 100644 .changeset/yellow-bats-listen.md diff --git a/.changeset/yellow-bats-listen.md b/.changeset/yellow-bats-listen.md new file mode 100644 index 00000000..1866f0fe --- /dev/null +++ b/.changeset/yellow-bats-listen.md @@ -0,0 +1,5 @@ +--- +"@clack/prompts": patch +--- + +docs: add jsdoc for `autocomplete`, `confirm`, and `path` prompts diff --git a/packages/prompts/README.md b/packages/prompts/README.md index e3655ad9..e72ac428 100644 --- a/packages/prompts/README.md +++ b/packages/prompts/README.md @@ -81,7 +81,7 @@ const secret = await password({ ### Confirm -The confirm component accepts a yes or no answer. The result is a boolean value of `true` or `false`. +The `confirm` prompt accepts a yes or no choice, returning a boolean value corresponding to the user's selection. ```js import { confirm } from '@clack/prompts'; @@ -125,7 +125,7 @@ const projectType = await select({ ### Autocomplete -The autocomplete component lets a user filter a list by typing, then choose one option from the matching results. By default, matching uses each option's `label`, `hint`, and `value`. The result is the selected option's `value`. +The `autocomplete` prompt combines text input with a searchable list of options. It's perfect for when you have a large list of options and want to help users find what they're looking for quickly. ```js import { autocomplete } from '@clack/prompts'; @@ -142,6 +142,27 @@ const framework = await autocomplete({ }); ``` +### Autocomplete Multi-Select + +The `autocompleteMultiselect` prompt combines the search functionality of [autocomplete](#autocomplete) with the ability to select multiple options. + +```js +import { autocomplete } from '@clack/prompts'; + +const framework = await autocomplete({ + message: 'Search for a framework', + options: [ + { value: 'next', label: 'Next.js', hint: 'React framework' }, + { value: 'astro', label: 'Astro', hint: 'Content-focused' }, + { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' }, + { value: 'remix', label: 'Remix', hint: 'Full stack framework' }, + { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' }, + ], + placeholder: 'Type to search...', + maxItems: 5, +}); +``` + ### Select Key The `selectKey` component lets a user choose an option by pressing its single-character string `value` key directly. @@ -226,7 +247,7 @@ const bio = await multiline({ ### Path -The path component offers filesystem path suggestions and returns the selected path as a string. When `directory: true` is set, only directories can be selected. +The `path` prompt extends [`autocomplete`](#autocomplete) to provide file and directory suggestions. ```js import { path } from '@clack/prompts'; diff --git a/packages/prompts/src/autocomplete.ts b/packages/prompts/src/autocomplete.ts index f840c717..da7a4184 100644 --- a/packages/prompts/src/autocomplete.ts +++ b/packages/prompts/src/autocomplete.ts @@ -41,45 +41,83 @@ function getSelectedOptions(values: T[], options: Option[]): Option[] { return results; } +/** + * Options for the {@link autocomplete} prompt. + */ interface AutocompleteSharedOptions extends CommonOptions { /** - * The message to display to the user. + * The prompt message or question shown to the user above the input. */ message: string; + /** - * Available options for the autocomplete prompt. + * The options to present, or a function that returns the options to present + * allowing for custom search/filtering. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#dynamic-options-getter */ options: Option[] | ((this: AutocompletePrompt>) => Option[]); + /** - * Maximum number of items to display at once. + * The maximum number of items/options to display in the autocomplete list at once. */ maxItems?: number; + /** - * Placeholder text to display when no input is provided. + * Placeholder text displayed when the search field is empty. When set, pressing + * tab copies the placeholder into the input. */ placeholder?: string; + /** - * Validates the value + * 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: Value | Value[] | undefined) => string | Error | undefined; + /** - * Custom filter function to match options against search input. - * If not provided, a default filter that matches label, hint, and value is used. + * Custom filter function to match options against the search input. */ filter?: (search: string, option: Option) => boolean; } export interface AutocompleteOptions extends AutocompleteSharedOptions { /** - * The initial selected value. + * The initially selected option from the list. */ initialValue?: Value; + /** - * The initial user input + * The starting value shown in the users input box. */ initialUserInput?: string; } +/** + * The `autocomplete` prompt combines a text input with a searchable list of options. + * It's perfect for when you have a large list of options and want to help users + * find what they're looking for quickly. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#autocomplete + * + * @example + * ```ts + * import { autocomplete } from '@clack/prompts'; + * + * const framework = await autocomplete({ + * message: 'Search for a framework', + * options: [ + * { value: 'next', label: 'Next.js', hint: 'React framework' }, + * { value: 'astro', label: 'Astro', hint: 'Content-focused' }, + * { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' }, + * { value: 'remix', label: 'Remix', hint: 'Full stack framework' }, + * { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' }, + * ], + * placeholder: 'Type to search...', + * maxItems: 5, + * }); + * ``` + */ export const autocomplete = (opts: AutocompleteOptions) => { const prompt = new AutocompletePrompt({ options: opts.options, @@ -223,20 +261,45 @@ export const autocomplete = (opts: AutocompleteOptions) => { return prompt.prompt() as Promise; }; -// Type definition for the autocompleteMultiselect component +/** + * Options for the {@link autocompleteMultiselect} prompt + */ export interface AutocompleteMultiSelectOptions extends AutocompleteSharedOptions { /** - * The initial selected values + * The initially selected option(s) from the list. */ initialValues?: Value[]; + /** - * If true, at least one option must be selected + * When `true` at least one option must be selected. + * @default false */ required?: boolean; } /** - * Integrated autocomplete multiselect - combines type-ahead filtering with multiselect in one UI + * The `autocompleteMultiselect` prompt combines the search functionality of autocomplete + * with the ability to select multiple options. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#autocomplete-multiselect + * + * @example + * ```ts + * import { autocompleteMultiselect } from '@clack/prompts'; + * + * const frameworks = await autocompleteMultiselect({ + * message: 'Select frameworks', + * options: [ + * { value: 'next', label: 'Next.js', hint: 'React framework' }, + * { value: 'astro', label: 'Astro', hint: 'Content-focused' }, + * { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' }, + * { value: 'remix', label: 'Remix', hint: 'Full stack framework' }, + * { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' }, + * ], + * placeholder: 'Type to search...', + * maxItems: 5, + * }); + * ``` */ export const autocompleteMultiselect = (opts: AutocompleteMultiSelectOptions) => { const formatOption = ( diff --git a/packages/prompts/src/confirm.ts b/packages/prompts/src/confirm.ts index 75b322ca..52cfd3e5 100644 --- a/packages/prompts/src/confirm.ts +++ b/packages/prompts/src/confirm.ts @@ -9,13 +9,55 @@ import { symbol, } from './common.js'; +/** + * Options for the {@link confirm} prompt. + */ export interface ConfirmOptions extends CommonOptions { + /** + * The prompt message or question shown to the user above the input. + */ message: string; + + /** + * The label to use for the active (true) option. + * @default 'Yes' + */ active?: string; + + /** + * The label to use for the inactive (false) option. + * @default 'No' + */ inactive?: string; + + /** + * The initial selected value (true or false). + * @default true + */ initialValue?: boolean; + + /** + * Whether to render the options vertically instead of horizontally. + * @default false + */ vertical?: boolean; } + +/** + * The `confirm` prompt accepts a yes or no choice, returning a boolean value + * corresponding to the user's selection. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#confirmation + * + * @example + * ```ts + * import { confirm } from '@clack/prompts'; + * + * const shouldProceed = await confirm({ + * message: 'Do you want to continue?', + * }); + * ``` + */ export const confirm = (opts: ConfirmOptions) => { const active = opts.active ?? 'Yes'; const inactive = opts.inactive ?? 'No'; diff --git a/packages/prompts/src/path.ts b/packages/prompts/src/path.ts index 70b8618e..2ce047b3 100644 --- a/packages/prompts/src/path.ts +++ b/packages/prompts/src/path.ts @@ -3,14 +3,58 @@ import { dirname, join } from 'node:path'; import { autocomplete } from './autocomplete.js'; import type { CommonOptions } from './common.js'; +/** + * Options for the {@link path} prompt. + */ export interface PathOptions extends CommonOptions { + /** + * The prompt message or question shown to the user above the input. + */ + message: string; + + /** + * The starting directory for path suggestions (defaults to current working directory). + */ root?: string; + + /** + * When `true` only **directories** appear in suggestions while you navigate. + */ directory?: boolean; + + /** + * The starting path shown when the prompt first renders, which users can edit + * before submitting. If not provided it will fall back to the given `root`, + * or the current working directory. + * + * In `directory` mode, if the initial value points to a directory that exists, + * pressing enter will submit the input instead of jumping to the first child. + */ initialValue?: string; - message: string; + + /** + * A function that validates the given path. 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 `path` prompt extends `autocomplete` to provide file and directory suggestions. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#path-selection + * + * @example + * ```ts + * import { path } from '@clack/prompts'; + * + * const result = await path({ + * message: 'Select a file:', + * root: process.cwd(), + * directory: false, + * }); + * ``` + */ export const path = (opts: PathOptions) => { const validate = opts.validate; From ee50ec601fd93401106044928a620e72f63f19e9 Mon Sep 17 00:00:00 2001 From: "Willow (GHOST)" Date: Wed, 13 May 2026 14:22:15 +0100 Subject: [PATCH 2/2] chore: apply suggestion Co-Authored-By: paul valladares <85648028+dreyfus92@users.noreply.github.com> --- packages/prompts/src/autocomplete.ts | 2 +- packages/prompts/src/confirm.ts | 2 +- packages/prompts/src/path.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/prompts/src/autocomplete.ts b/packages/prompts/src/autocomplete.ts index da7a4184..78227000 100644 --- a/packages/prompts/src/autocomplete.ts +++ b/packages/prompts/src/autocomplete.ts @@ -46,7 +46,7 @@ function getSelectedOptions(values: T[], options: Option[]): Option[] { */ interface AutocompleteSharedOptions extends CommonOptions { /** - * The prompt message or question shown to the user above the input. + * The message or question shown to the user above the input. */ message: string; diff --git a/packages/prompts/src/confirm.ts b/packages/prompts/src/confirm.ts index 52cfd3e5..2e537f1c 100644 --- a/packages/prompts/src/confirm.ts +++ b/packages/prompts/src/confirm.ts @@ -14,7 +14,7 @@ import { */ export interface ConfirmOptions extends CommonOptions { /** - * The prompt message or question shown to the user above the input. + * The message or question shown to the user above the input. */ message: string; diff --git a/packages/prompts/src/path.ts b/packages/prompts/src/path.ts index 2ce047b3..921a9fda 100644 --- a/packages/prompts/src/path.ts +++ b/packages/prompts/src/path.ts @@ -8,7 +8,7 @@ import type { CommonOptions } from './common.js'; */ export interface PathOptions extends CommonOptions { /** - * The prompt message or question shown to the user above the input. + * The message or question shown to the user above the input. */ message: string;