From 6da59f1202c4c35e1f526435b0d78d3477cb24fd Mon Sep 17 00:00:00 2001 From: "Willow (GHOST)" Date: Wed, 13 May 2026 15:47:13 +0100 Subject: [PATCH] docs: add jsdoc for `box`, `group`, and `group-multi-select` --- .changeset/giant-doors-rest.md | 5 ++ packages/prompts/src/box.ts | 61 ++++++++++++++++++++ packages/prompts/src/group-multi-select.ts | 65 ++++++++++++++++++++++ packages/prompts/src/group.ts | 39 +++++++++++-- 4 files changed, 166 insertions(+), 4 deletions(-) create mode 100644 .changeset/giant-doors-rest.md diff --git a/.changeset/giant-doors-rest.md b/.changeset/giant-doors-rest.md new file mode 100644 index 00000000..e25ccf3e --- /dev/null +++ b/.changeset/giant-doors-rest.md @@ -0,0 +1,5 @@ +--- +"@clack/prompts": patch +--- + +docs: add jsdoc for `box`, `group`, and `group-multi-select` diff --git a/packages/prompts/src/box.ts b/packages/prompts/src/box.ts index e8f3b326..99d6f7c3 100644 --- a/packages/prompts/src/box.ts +++ b/packages/prompts/src/box.ts @@ -16,6 +16,9 @@ import { S_CORNER_TOP_RIGHT, } from './common.js'; +/** + * Alignment for content or titles within the box. + */ export type BoxAlignment = 'left' | 'center' | 'right'; type BoxSymbols = [topLeft: string, topRight: string, bottomLeft: string, bottomRight: string]; @@ -28,13 +31,49 @@ const roundedSymbols: BoxSymbols = [ ]; const squareSymbols: BoxSymbols = [S_BAR_START, S_BAR_START_RIGHT, S_BAR_END, S_BAR_END_RIGHT]; +/** + * Options for the {@link box} prompt. + */ export interface BoxOptions extends CommonOptions { + /** + * Alignment of the content (`'left'`, `'center'`, or `'right'`). + * @default 'left' + */ contentAlign?: BoxAlignment; + + /** + * Alignment of the title (`'left'`, `'center'`, or `'right'`). + * @default 'left' + */ titleAlign?: BoxAlignment; + + /** + * The width of the box, either `'auto'` to fit the content or a number for a fixed width. + * @default 'auto' + */ width?: number | 'auto'; + + /** + * Padding around the title. + * @default 1 + */ titlePadding?: number; + + /** + * Padding around the content. + * @default 2 + */ contentPadding?: number; + + /** + * Use rounded corners when `true`, square corners when `false`. + * @default true + */ rounded?: boolean; + + /** + * Custom function to style the border characters. + */ formatBorder?: (text: string) => string; } @@ -59,6 +98,28 @@ function getPaddingForLine( const defaultFormatBorder = (text: string) => text; +/** + * Renders a customizable box around text content. It's similar to {@link note} but offers + * more styling options. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#box + * + * @param message - The content to display inside the box. + * @param title - The title to display in the top border of the box. + * @param opts - Optional configuration for the box styling and behavior. + * + * @example + * ```ts + * import { box } from '@clack/prompts'; + * + * box('This is the content of the box', 'Box Title', { + * contentAlign: 'center', + * titleAlign: 'center', + * width: 'auto', + * rounded: true, + * }); + * ``` + */ export const box = (message = '', title = '', opts?: BoxOptions) => { const output: Writable = opts?.output ?? process.stdout; const columns = getColumns(output); diff --git a/packages/prompts/src/group-multi-select.ts b/packages/prompts/src/group-multi-select.ts index d8df0bfb..4ddc3d3f 100644 --- a/packages/prompts/src/group-multi-select.ts +++ b/packages/prompts/src/group-multi-select.ts @@ -12,16 +12,81 @@ import { import { limitOptions } from './limit-options.js'; import type { Option } from './select.js'; +/** + * Options for the {@link groupMultiselect} prompt. + */ export interface GroupMultiSelectOptions extends CommonOptions { + /** + * The message or question shown to the user above the input. + */ message: string; + + /** + * Grouped options to display. Each key is a group label, and each value is an array of options. + */ options: Record[]>; + + /** + * The initially selected option(s). + */ initialValues?: Value[]; + + /** + * The maximum number of items/options to display at once. + */ maxItems?: number; + + /** + * When `true` at least one option must be selected. + * @default true + */ required?: boolean; + + /** + * The value the cursor should be positioned at initially. + */ cursorAt?: Value; + + /** + * Whether entire groups can be selected at once. + * @default true + */ selectableGroups?: boolean; + + /** + * Number of blank lines between groups. + * @default 0 + */ groupSpacing?: number; } + +/** + * The `groupMultiselect` prompt extends the {@link multiselect} prompt to allow + * arranging distinct Multi-Selects, whilst keeping all of them interactive. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#group-multiselect + * + * @example + * ```ts + * import { groupMultiselect } from '@clack/prompts'; + * + * const result = await groupMultiselect({ + * message: 'Define your project', + * options: { + * 'Testing': [ + * { value: 'Jest', hint: 'JavaScript testing framework' }, + * { value: 'Playwright', hint: 'End-to-end testing' }, + * ], + * 'Language': [ + * { value: 'js', label: 'JavaScript', hint: 'Dynamic typing' }, + * { value: 'ts', label: 'TypeScript', hint: 'Static typing' }, + * ], + * }, + * }); + * ``` + * + * @param opts The options for the group multiselect prompt + */ export const groupMultiselect = (opts: GroupMultiSelectOptions) => { const { selectableGroups = true, groupSpacing = 0 } = opts; const opt = ( diff --git a/packages/prompts/src/group.ts b/packages/prompts/src/group.ts index 25e7365c..0e4b9246 100644 --- a/packages/prompts/src/group.ts +++ b/packages/prompts/src/group.ts @@ -4,18 +4,28 @@ type Prettify = { [P in keyof T]: T[P]; } & {}; +/** + * The return type of a {@link PromptGroup}. + * Resolves all prompt results, excluding the cancel symbol. + */ export type PromptGroupAwaitedReturn = { [P in keyof T]: Exclude, symbol>; }; +/** + * Options for the {@link group} utility. + */ export interface PromptGroupOptions { /** - * Control how the group can be canceled - * if one of the prompts is canceled. + * Called when any one of the prompts is canceled. */ onCancel?: (opts: { results: Prettify>> }) => void; } +/** + * A group of prompts to be displayed sequentially, with each prompt receiving + * the results of all previous prompts in the group. + */ export type PromptGroup = { [P in keyof T]: (opts: { results: Prettify>>>; @@ -23,8 +33,29 @@ export type PromptGroup = { }; /** - * Define a group of prompts to be displayed - * and return a results of objects within the group + * The `group` utility provides a consistent way to combine a series of prompts, + * combining each answer into one object. Each prompt receives the results of + * all previously completed prompts, and are displayed sequentially. + * + * @see https://bomb.sh/docs/clack/packages/prompts/#group + * + * @example + * ```ts + * import { group, text, password } from '@clack/prompts'; + * + * const account = await group({ + * email: () => text({ + * message: 'What is your email address?', + * }), + * username: ({ results }) => text({ + * message: 'What is your username?', + * placeholder: results.email?.replace(/@.+$/, '').toLowerCase() ?? '', + * }), + * password: () => password({ + * message: 'Define your password', + * }), + * }); + * ``` */ export const group = async ( prompts: PromptGroup,