@topcli/prompts 3.0.0 → 3.1.0

package/README.md

@@ -170,7 +170,36 @@ Use `options.caseSensitive` to make autocomplete filters case sensitive. Default
 
 Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)).
 
-Use `options.skip` to skip prompt. It will return the first choice.
+Use `options.skip` to skip prompt. It will return the first non-separator choice.
+
+Use `Separator` items in `choices` to visually group options. Separators are not selectable and are skipped during keyboard navigation. When `autocomplete` is active and the user has typed a filter, separators are hidden.
+
+```js
+import { select } from "@topcli/prompts";
+
+const framework = await select("Choose a framework", {
+  choices: [
+    { type: "separator", label: "Frontend" },
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+    { type: "separator", label: "Backend" },
+    { value: "express", label: "Express" },
+    { value: "fastify", label: "Fastify" },
+  ]
+});
+```
+
+Use `choice.disabled` to mark a choice as non-selectable.
+
+```js
+const runner = await select("Choose a runner", {
+  choices: [
+    { value: "node", label: "Node.js" },
+    { value: "bun", label: "Bun", disabled: "not available" },
+    { value: "deno", label: "Deno", disabled: true }
+  ]
+});
+```
 
 ### `multiselect()`
 
@@ -193,6 +222,10 @@ Use `options.signal` to set an `AbortSignal` (throws a [AbortError](#aborterror)
 
 Use `options.skip` to skip prompt. It will return `options.preSelectedChoices` if given, `[]` otherwise.
 
+Use `Separator` items in `choices` to visually group options. Separators are not selectable and are skipped during keyboard navigation. When `autocomplete` is active and the user has typed a filter, separators are hidden.
+
+Use `choice.disabled` to mark a choice as non-selectable.
+
 ### `confirm()`
 
 ```ts
@@ -287,10 +320,16 @@ export interface Choice<T = any> {
   value: T;
   label: string;
   description?: string;
+  disabled?: boolean | string;
+}
+
+export interface Separator {
+  type: "separator";
+  label?: string;
 }
 
 export interface SelectOptions<T extends string> extends AbstractPromptOptions {
-  choices: (Choice<T> | T)[];
+  choices: (Choice<T> | T | Separator)[];
   maxVisible?: number;
   ignoreValues?: (T | number | boolean)[];
   validators?: PromptValidator<string>[];
@@ -299,7 +338,7 @@ export interface SelectOptions<T extends string> extends AbstractPromptOptions {
 }
 
 export interface MultiselectOptions<T extends string> extends AbstractPromptOptions {
-  choices: (Choice<T> | T)[];
+  choices: (Choice<T> | T | Separator)[];
   maxVisible?: number;
   preSelectedChoices?: (Choice<T> | T)[];
   validators?: PromptValidator<string[]>[];