[READ-ONLY] Mirror of https://github.com/bombshell-dev/clack. Effortlessly build beautiful command-line apps
bomb.sh/docs/clack/basics/getting-started/
cli
command-line
command-line-app
node
prompt
prompts
docs: add jsdoc for `date`, `limit-options`, and `messages` (#546)
authored by
Willow (GHOST)
and committed by
GitHub
(May 31, 2026, 6:42 AM -0700)
56e9d670
0d45e99a
+167
-6
+5
.changeset/twenty-rockets-lose.md
+5
.changeset/twenty-rockets-lose.md
+6
-6
packages/prompts/README.md
+6
-6
packages/prompts/README.md
···
93
93
94
94
### Date
95
95
96
-
The date component accepts a calendar date and returns a `Date` value.
96
+
The `date` prompt provides an interactive date picker, allowing users to navigate between year, month, and day segments and increment/decrement values using keyboard controls.
97
97
98
98
```js
99
99
import { date } from '@clack/prompts';
100
100
101
-
const dueDate = await date({
102
-
message: 'Pick a due date.',
103
-
format: 'YMD',
104
-
minDate: new Date(Date.UTC(2026, 0, 1)),
105
-
maxDate: new Date(Date.UTC(2026, 11, 31)),
101
+
const birthday = await date({
102
+
message: 'Pick your birthday',
103
+
minDate: new Date('1900-01-01'),
104
+
initialValue: new Date(),
105
+
maxDate: new Date(),
106
106
});
107
107
```
108
108
+53
packages/prompts/src/date.ts
+53
packages/prompts/src/date.ts
···
5
5
6
6
export type { DateFormat };
7
7
8
+
/**
9
+
* Options for the {@link date} prompt.
10
+
*/
8
11
export interface DateOptions extends CommonOptions {
12
+
/**
13
+
* The message or question shown to the user above the input.
14
+
*/
9
15
message: string;
16
+
17
+
/**
18
+
* The date format for the input segments.
19
+
* @deafult based on locale
20
+
*/
10
21
format?: DateFormat;
22
+
23
+
/**
24
+
* The BCP 47 language tag to use for formatting
25
+
* @see https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag
26
+
* @example "en-GB"
27
+
*/
11
28
locale?: string;
29
+
30
+
/**
31
+
* The default value returned when the user doesn't select a date.
32
+
*/
12
33
defaultValue?: Date;
34
+
35
+
/**
36
+
* The starting date shown when the prompt first renders.
37
+
* Users can edit this value before submitting.
38
+
*/
13
39
initialValue?: Date;
40
+
41
+
/**
42
+
* The minimum allowed date for validation.
43
+
*/
14
44
minDate?: Date;
45
+
46
+
/**
47
+
* The maximum allowed date for validation.
48
+
*/
15
49
maxDate?: Date;
16
50
17
51
/**
···
22
56
validate?: Validate<Date>;
23
57
}
24
58
59
+
/**
60
+
* The `date` prompt provides an interactive date picker, allowing users
61
+
* to navigate between year, month, and day segments and
62
+
* increment/decrement values using keyboard controls.
63
+
*
64
+
* @see https://bomb.sh/docs/clack/packages/prompts/#date-input
65
+
*
66
+
* @example
67
+
* ```ts
68
+
* import { date } from '@clack/prompts';
69
+
*
70
+
* const birthday = await date({
71
+
* message: 'Pick your birthday',
72
+
* minDate: new Date('1900-01-01'),
73
+
* initialValue: new Date(),
74
+
* maxDate: new Date(),
75
+
* });
76
+
* ```
77
+
*/
25
78
export const date = (opts: DateOptions) => {
26
79
const validate = opts.validate;
27
80
return new DatePrompt({
+55
packages/prompts/src/limit-options.ts
+55
packages/prompts/src/limit-options.ts
···
3
3
import { wrapAnsi } from 'fast-wrap-ansi';
4
4
import type { CommonOptions } from './common.js';
5
5
6
+
/**
7
+
* Options for the {@link limitOptions} function.
8
+
*/
6
9
export interface LimitOptionsParams<TOption> extends CommonOptions {
10
+
/**
11
+
* The list of options to display.
12
+
*/
7
13
options: TOption[];
14
+
15
+
/**
16
+
* The index of the currently active/selected option.
17
+
*/
8
18
cursor: number;
19
+
20
+
/**
21
+
* A function that styles the given option string.
22
+
*
23
+
* @param option - The option string to style.
24
+
* @param active - Whether the option is currently selected.
25
+
*/
9
26
style: (option: TOption, active: boolean) => string;
27
+
28
+
/**
29
+
* Maximum number of options to display at once.
30
+
* @default Infinity
31
+
*/
10
32
maxItems?: number;
33
+
34
+
/**
35
+
* Number of columns to reserve for padding.
36
+
* @default 0
37
+
*/
11
38
columnPadding?: number;
39
+
40
+
/**
41
+
* Number of rows to reserve for padding.
42
+
* @default 4
43
+
*/
12
44
rowPadding?: number;
13
45
}
14
46
···
38
70
return { lineCount, removals };
39
71
};
40
72
73
+
/**
74
+
* Trims an option list to what fits the terminal, while keeping the active
75
+
* option (cursor) visible using a Clack style sliding window.
76
+
*
77
+
* @returns The lines to render.
78
+
*
79
+
* @see https://bomb.sh/docs/clack/packages/prompts/#limitoptions
80
+
*
81
+
* @example
82
+
* ```ts
83
+
* import { limitOptions } from '@clack/prompts';
84
+
* import { styleText } from 'node:util';
85
+
*
86
+
* const options = ['apple', 'banana', 'cherry', 'date'];
87
+
* const lines = limitOptions({
88
+
* options,
89
+
* cursor: 2,
90
+
* maxItems: 8,
91
+
* style: (opt, active) =>
92
+
* active ? styleText('cyan', opt) : styleText('dim', opt),
93
+
* });
94
+
* ```
95
+
*/
41
96
export const limitOptions = <TOption>({
42
97
cursor,
43
98
options,
+48
packages/prompts/src/messages.ts
+48
packages/prompts/src/messages.ts
···
3
3
import { settings } from '@clack/core';
4
4
import { type CommonOptions, S_BAR, S_BAR_END, S_BAR_START } from './common.js';
5
5
6
+
/**
7
+
* The `cancel` function defines an interruption of an interaction
8
+
* and therefore its end.
9
+
*
10
+
* @param title Optional closing message to be displayed.
11
+
* @param opts Additional configuration options.
12
+
*
13
+
* @see https://bomb.sh/docs/clack/packages/prompts/#cancel
14
+
*
15
+
* @example
16
+
* ```ts
17
+
* import { cancel } from '@clack/prompts';
18
+
* import process from 'node:process';
19
+
*
20
+
* cancel('Installation canceled');
21
+
* process.exit(1);
22
+
* ```
23
+
*/
6
24
export const cancel = (message = '', opts?: CommonOptions) => {
7
25
const output: Writable = opts?.output ?? process.stdout;
8
26
const hasGuide = opts?.withGuide ?? settings.withGuide;
···
10
28
output.write(`${prefix}${styleText('red', message)}\n\n`);
11
29
};
12
30
31
+
/**
32
+
* The `intro` function defines the beginning of an interaction.
33
+
*
34
+
* @param title Optional title to be displayed.
35
+
* @param opts Additional configuration options.
36
+
*
37
+
* @see https://bomb.sh/docs/clack/packages/prompts/#intro
38
+
*
39
+
* @example
40
+
* ```ts
41
+
* import { intro } from '@clack/prompts';
42
+
*
43
+
* intro('Welcome to clack');
44
+
* ```
45
+
*/
13
46
export const intro = (title = '', opts?: CommonOptions) => {
14
47
const output: Writable = opts?.output ?? process.stdout;
15
48
const hasGuide = opts?.withGuide ?? settings.withGuide;
···
17
50
output.write(`${prefix}${title}\n`);
18
51
};
19
52
53
+
/**
54
+
* The `outro` function defines the end of an interaction.
55
+
*
56
+
* @param title Optional closing message to be displayed.
57
+
* @param opts Additional configuration options.
58
+
*
59
+
* @see https://bomb.sh/docs/clack/packages/prompts/#outro
60
+
*
61
+
* @example
62
+
* ```ts
63
+
* import { outro } from '@clack/prompts';
64
+
*
65
+
* outro('All operations are finished');
66
+
* ```
67
+
*/
20
68
export const outro = (message = '', opts?: CommonOptions) => {
21
69
const output: Writable = opts?.output ?? process.stdout;
22
70
const hasGuide = opts?.withGuide ?? settings.withGuide;