From 1544c1399cc72dd37c4621a4be9e0d6aabe602f1 Mon Sep 17 00:00:00 2001 From: Simon Boudrias Date: Sun, 21 Jul 2024 14:25:22 -0400 Subject: [PATCH] Fix(@inquirer/checkbox) Typing of validate contains only choices + README update --- packages/checkbox/README.md | 46 +++++++++++++++++++++++++-------- packages/checkbox/src/index.mts | 2 +- 2 files changed, 36 insertions(+), 12 deletions(-) diff --git a/packages/checkbox/README.md b/packages/checkbox/README.md index 964a225be..54799ae5c 100644 --- a/packages/checkbox/README.md +++ b/packages/checkbox/README.md @@ -52,17 +52,41 @@ const answer = await checkbox({ ## Options -| Property | Type | Required | Description | -| -------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | `string` | yes | The question to ask | -| choices | `Array<{ value: string, name?: string, short?: string, disabled?: boolean \| string, checked?: boolean } \| Separator>` | yes | List of the available choices. The `value` will be returned as the answer, and used as display if no `name` is defined. Choices who're `disabled` will be displayed, but not selectable. `short` if defined will be used instead of `name` once submitted. | -| pageSize | `number` | no | By default, lists of choice longer than 7 will be paginated. Use this option to control how many choices will appear on the screen at once. | -| loop | `boolean` | no | Defaults to `true`. When set to `false`, the cursor will be constrained to the top and bottom of the choice list without looping. | -| required | `boolean` | no | When set to `true`, ensures at least one choice must be selected. | -| validate | `string\[\] => boolean \| string \| Promise` | no | On submit, validate the choices. When returning a string, it'll be used as the error message displayed to the user. Note: returning a rejected promise, we'll assume a code error happened and crash. | -| theme | [See Theming](#Theming) | no | Customize look of the prompt. | - -The `Separator` object can be used to render non-selectable lines in the choice list. By default it'll render a line, but you can provide the text as argument (`new Separator('-- Dependencies --')`). This option is often used to add labels to groups within long list of options. +| Property | Type | Required | Description | +| -------- | --------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| message | `string` | yes | The question to ask | +| choices | `Choice[]` | yes | List of the available choices. | +| pageSize | `number` | no | By default, lists of choice longer than 7 will be paginated. Use this option to control how many choices will appear on the screen at once. | +| loop | `boolean` | no | Defaults to `true`. When set to `false`, the cursor will be constrained to the top and bottom of the choice list without looping. | +| required | `boolean` | no | When set to `true`, ensures at least one choice must be selected. | +| validate | `async (Choice[]) => boolean \| string` | no | On submit, validate the choices. When returning a string, it'll be used as the error message displayed to the user. Note: returning a rejected promise, we'll assume a code error happened and crash. | +| theme | [See Theming](#Theming) | no | Customize look of the prompt. | + +`Separator` objects can be used in the `choices` array to render non-selectable lines in the choice list. By default it'll render a line, but you can provide the text as argument (`new Separator('-- Dependencies --')`). This option is often used to add labels to groups within long list of options. + +### `Choice` object + +The `Choice` object is typed as + +```ts +type Choice = { + value: Value; + name?: string; + short?: string; + checked?: boolean; + disabled?: boolean | string; +}; +``` + +Here's each property: + +- `value`: The value is what will be returned by `await select()`. +- `name`: This is the string displayed in the choice list. +- `short`: Once the prompt is done (press enter), we'll use `short` if defined to render next to the question. By default we'll use `name`. +- `checked`: If `true`, the option will be checked by default. +- `disabled`: Disallow the option from being selected. If `disabled` is a string, it'll be used as a help tip explaining why the choice isn't available. + +Also note the `choices` array can contain `Separator`s to help organize long lists. ## Theming diff --git a/packages/checkbox/src/index.mts b/packages/checkbox/src/index.mts index 8177cd581..3d7d8f099 100644 --- a/packages/checkbox/src/index.mts +++ b/packages/checkbox/src/index.mts @@ -71,7 +71,7 @@ type Config = { loop?: boolean; required?: boolean; validate?: ( - items: ReadonlyArray>, + choices: ReadonlyArray>, ) => boolean | string | Promise; theme?: PartialDeep>; };