docs: add jsdoc for autocomplete, confirm, and path prompts

.changeset/yellow-bats-listen.md

@@ -0,0 +1,5 @@
+---
+"@clack/prompts": patch
+---
+
+docs: add jsdoc for `autocomplete`, `confirm`, and `path` prompts

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';

packages/prompts/src/autocomplete.ts

@@ -41,45 +41,83 @@ function getSelectedOptions<T>(values: T[], options: Option<T>[]): Option<T>[] {
 	return results;
 }
 
+/**
+ * Options for the {@link autocomplete} prompt.
+ */
 interface AutocompleteSharedOptions<Value> extends CommonOptions {
 	/**
-	 * The message to display to the user.
+	 * The 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<Value>[] | ((this: AutocompletePrompt<Option<Value>>) => Option<Value>[]);
+
 	/**
-	 * 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<Value>) => boolean;
 }
 
 export interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Value> {
 	/**
-	 * 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 = <Value>(opts: AutocompleteOptions<Value>) => {
 	const prompt = new AutocompletePrompt({
 		options: opts.options,
@@ -223,20 +261,45 @@ export const autocomplete = <Value>(opts: AutocompleteOptions<Value>) => {
 	return prompt.prompt() as Promise<Value | symbol>;
 };
 
-// Type definition for the autocompleteMultiselect component
+/**
+ * Options for the {@link autocompleteMultiselect} prompt
+ */
 export interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
 	/**
-	 * 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 = <Value>(opts: AutocompleteMultiSelectOptions<Value>) => {
 	const formatOption = (

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 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';

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 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;