feat: add usage for prompt

Add (optional) `usage` to `prompt` options in the `@clack/core`.
Add usage support for `multiselect` and `groupMultiselect` in the `@clack/prompts`.

Author: uynilo9

.changeset/wicked-pears-begin.md

@@ -0,0 +1,7 @@
+---
+"@clack/prompts": minor
+"@clack/core": minor
+---
+
+Add (optional) `usage` to `prompt` options in the `@clack/core`.
+Add usage support for `multiselect` and `groupMultiselect` in the `@clack/prompts`.

packages/core/src/prompts/prompt.ts

@@ -16,6 +16,7 @@ import {
 
 export interface PromptOptions<TValue, Self extends Prompt<TValue>> {
 	render(this: Omit<Self, 'prompt'>): string | undefined;
+	usage?: boolean | string;
 	initialValue?: any;
 	initialUserInput?: string;
 	validate?: ((value: TValue | undefined) => string | Error | undefined) | undefined;

packages/prompts/src/group-multi-select.ts

@@ -14,6 +14,7 @@ import type { Option } from './select.js';
 export interface GroupMultiSelectOptions<Value> extends CommonOptions {
 	message: string;
 	options: Record<string, Option<Value>[]>;
+	usage?: boolean | string;
 	initialValues?: Value[];
 	required?: boolean;
 	cursorAt?: Value;
@@ -77,6 +78,18 @@ export const groupMultiselect = <Value>(opts: GroupMultiSelectOptions<Value>) =>
 		const unselectedCheckbox = isItem || selectableGroups ? color.dim(S_CHECKBOX_INACTIVE) : '';
 		return `${spacingPrefix}${color.dim(prefix)}${unselectedCheckbox} ${color.dim(label)}`;
 	};
+
+	const defaultUsageMessage = `${color.reset(
+		color.dim(
+			`Press ${color.gray(color.bgWhite(color.inverse(' space ')))} to select, ${color.gray(
+				color.bgWhite(color.inverse(' enter '))
+			)} to submit`
+		)
+	)}`;
+
+	const usage = opts.usage ?? false;
+	const usageMessage = typeof usage === 'string' ? usage : defaultUsageMessage;
+
 	const required = opts.required ?? true;
 
 	return new GroupMultiSelectPrompt({
@@ -90,13 +103,7 @@ export const groupMultiselect = <Value>(opts: GroupMultiSelectOptions<Value>) =>
 		selectableGroups,
 		validate(selected: Value[] | undefined) {
 			if (required && (selected === undefined || selected.length === 0))
-				return `Please select at least one option.\n${color.reset(
-					color.dim(
-						`Press ${color.gray(color.bgWhite(color.inverse(' space ')))} to select, ${color.gray(
-							color.bgWhite(color.inverse(' enter '))
-						)} to submit`
-					)
-				)}`;
+				return `Please select at least one option.\n${defaultUsageMessage}`;
 		},
 		render() {
 			const title = `${color.gray(S_BAR)}\n${symbol(this.state)}  ${opts.message}\n`;
@@ -180,7 +187,14 @@ export const groupMultiselect = <Value>(opts: GroupMultiSelectOptions<Value>) =>
 						})
 						.join(`\n${color.cyan(S_BAR)}`);
 					const optionsPrefix = optionsText.startsWith('\n') ? '' : '  ';
-					return `${title}${color.cyan(S_BAR)}${optionsPrefix}${optionsText}\n${color.cyan(S_BAR_END)}\n`;
+					const footer =
+						this.state === 'initial' && usage
+							? usageMessage
+									.split('\n')
+									.map((ln, i) => (i === 0 ? `${color.cyan(S_BAR_END)} ${ln}` : `   ${ln}`))
+									.join('\n')
+							: color.cyan(S_BAR_END);
+					return `${title}${color.cyan(S_BAR)}${optionsPrefix}${optionsText}\n${footer}\n`;
 				}
 			}
 		},

packages/prompts/src/multi-select.ts

@@ -16,6 +16,7 @@ import type { Option } from './select.js';
 export interface MultiSelectOptions<Value> extends CommonOptions {
 	message: string;
 	options: Option<Value>[];
+	usage?: boolean | string;
 	initialValues?: Value[];
 	maxItems?: number;
 	required?: boolean;
@@ -69,6 +70,18 @@ export const multiselect = <Value>(opts: MultiSelectOptions<Value>) => {
 		}
 		return `${color.dim(S_CHECKBOX_INACTIVE)} ${computeLabel(label, color.dim)}`;
 	};
+
+	const defaultUsageMessage = `${color.reset(
+		color.dim(
+			`Press ${color.gray(color.bgWhite(color.inverse(' space ')))} to select, ${color.gray(
+				color.bgWhite(color.inverse(' enter '))
+			)} to submit`
+		)
+	)}`;
+
+	const usage = opts.usage ?? false;
+	const usageMessage = typeof usage === 'string' ? usage : defaultUsageMessage;
+
 	const required = opts.required ?? true;
 
 	return new MultiSelectPrompt({
@@ -81,13 +94,7 @@ export const multiselect = <Value>(opts: MultiSelectOptions<Value>) => {
 		cursorAt: opts.cursorAt,
 		validate(selected: Value[] | undefined) {
 			if (required && (selected === undefined || selected.length === 0))
-				return `Please select at least one option.\n${color.reset(
-					color.dim(
-						`Press ${color.gray(color.bgWhite(color.inverse(' space ')))} to select, ${color.gray(
-							color.bgWhite(color.inverse(' enter '))
-						)} to submit`
-					)
-				)}`;
+				return `Please select at least one option.\n${defaultUsageMessage}`;
 		},
 		render() {
 			const wrappedMessage = wrapTextWithPrefix(
@@ -161,6 +168,13 @@ export const multiselect = <Value>(opts: MultiSelectOptions<Value>) => {
 				}
 				default: {
 					const prefix = `${color.cyan(S_BAR)}  `;
+					const footer =
+						this.state === 'initial' && usage
+							? usageMessage
+									.split('\n')
+									.map((ln, i) => (i === 0 ? `${color.cyan(S_BAR_END)} ${ln}` : `   ${ln}`))
+									.join('\n')
+							: color.cyan(S_BAR_END);
 					// Calculate rowPadding: title lines + footer lines (S_BAR_END + trailing newline)
 					const titleLineCount = title.split('\n').length;
 					const footerLineCount = 2; // S_BAR_END + trailing newline
@@ -172,7 +186,7 @@ export const multiselect = <Value>(opts: MultiSelectOptions<Value>) => {
 						columnPadding: prefix.length,
 						rowPadding: titleLineCount + footerLineCount,
 						style: styleOption,
-					}).join(`\n${prefix}`)}\n${color.cyan(S_BAR_END)}\n`;
+					}).join(`\n${prefix}`)}\n${footer}\n`;
 				}
 			}
 		},