feat(@clack/core,@clack/prompts): Multiline text input

.changeset/ninety-seals-teach.md

@@ -0,0 +1,6 @@
+---
+"@clack/prompts": minor
+"@clack/core": minor
+---
+
+Add new multiline prompt for multi-line text input.

examples/changesets/index.ts

@@ -70,7 +70,7 @@ async function main() {
 		}
 	);
 
-	const message = await p.text({
+	const message = await p.multiline({
 		placeholder: 'Summary',
 		message: 'Please enter a summary for this change',
 	});

packages/core/src/index.ts

@@ -6,6 +6,8 @@ export type { DateFormat, DateOptions, DateParts } from './prompts/date.js';
 export { default as DatePrompt } from './prompts/date.js';
 export type { GroupMultiSelectOptions } from './prompts/group-multiselect.js';
 export { default as GroupMultiSelectPrompt } from './prompts/group-multiselect.js';
+export type { MultiLineOptions } from './prompts/multi-line.js';
+export { default as MultiLinePrompt } from './prompts/multi-line.js';
 export type { MultiSelectOptions } from './prompts/multi-select.js';
 export { default as MultiSelectPrompt } from './prompts/multi-select.js';
 export type { PasswordOptions } from './prompts/password.js';

packages/core/src/prompts/multi-line.ts

@@ -0,0 +1,138 @@
+import type { Key } from 'node:readline';
+import { styleText } from 'node:util';
+import { findTextCursor } from '../utils/cursor.js';
+import { type Action, settings } from '../utils/index.js';
+import Prompt, { type PromptOptions } from './prompt.js';
+
+export interface MultiLineOptions extends PromptOptions<string, MultiLinePrompt> {
+	placeholder?: string;
+	defaultValue?: string;
+	showSubmit?: boolean;
+}
+
+export default class MultiLinePrompt extends Prompt<string> {
+	#lastKeyWasReturn = false;
+	#showSubmit: boolean;
+	public focused: 'editor' | 'submit' = 'editor';
+
+	get userInputWithCursor() {
+		if (this.state === 'submit') {
+			return this.userInput;
+		}
+		const userInput = this.userInput;
+		if (this.cursor >= userInput.length) {
+			return `${userInput}█`;
+		}
+		const s1 = userInput.slice(0, this.cursor);
+		const s2 = userInput[this.cursor];
+		const s3 = userInput.slice(this.cursor + 1);
+		if (s2 === '\n') return `${s1}█\n${s3}`;
+		return `${s1}${styleText('inverse', s2)}${s3}`;
+	}
+	get cursor() {
+		return this._cursor;
+	}
+	#insertAtCursor(char: string) {
+		if (this.userInput.length === 0) {
+			this._setUserInput(char);
+			return;
+		}
+		this._setUserInput(
+			this.userInput.slice(0, this.cursor) + char + this.userInput.slice(this.cursor)
+		);
+	}
+	#handleCursor(key?: Action) {
+		const text = this.value ?? '';
+		switch (key) {
+			case 'up':
+				this._cursor = findTextCursor(this._cursor, 0, -1, text);
+				return;
+			case 'down':
+				this._cursor = findTextCursor(this._cursor, 0, 1, text);
+				return;
+			case 'left':
+				this._cursor = findTextCursor(this._cursor, -1, 0, text);
+				return;
+			case 'right':
+				this._cursor = findTextCursor(this._cursor, 1, 0, text);
+				return;
+		}
+	}
+
+	protected override _shouldSubmit(_char: string | undefined, _key: Key): boolean {
+		if (this.#showSubmit) {
+			if (this.focused === 'submit') {
+				return true;
+			}
+			this.#insertAtCursor('\n');
+			this._cursor++;
+			return false;
+		}
+		const wasReturn = this.#lastKeyWasReturn;
+		this.#lastKeyWasReturn = true;
+		if (wasReturn) {
+			if (this.userInput[this.cursor - 1] === '\n') {
+				this._setUserInput(
+					this.userInput.slice(0, this.cursor - 1) + this.userInput.slice(this.cursor)
+				);
+				this._cursor--;
+			}
+			return true;
+		}
+		this.#insertAtCursor('\n');
+		this._cursor++;
+		return false;
+	}
+
+	constructor(opts: MultiLineOptions) {
+		super(opts, false);
+		this.#showSubmit = opts.showSubmit ?? false;
+
+		this.on('key', (char, key) => {
+			if (key?.name && settings.actions.has(key.name as Action)) {
+				this.#handleCursor(key.name as Action);
+				return;
+			}
+			if (char === '\t' && this.#showSubmit) {
+				this.focused = this.focused === 'editor' ? 'submit' : 'editor';
+				return;
+			}
+			if (key?.name === 'return') {
+				return;
+			}
+			this.#lastKeyWasReturn = false;
+			if (key?.name === 'backspace' && this.cursor > 0) {
+				this._setUserInput(
+					this.userInput.slice(0, this.cursor - 1) + this.userInput.slice(this.cursor)
+				);
+				this._cursor--;
+				return;
+			}
+			if (key?.name === 'delete' && this.cursor < this.userInput.length) {
+				this._setUserInput(
+					this.userInput.slice(0, this.cursor) + this.userInput.slice(this.cursor + 1)
+				);
+				return;
+			}
+			if (char) {
+				if (this.#showSubmit && this.focused === 'submit') {
+					this.focused = 'editor';
+				}
+				this.#insertAtCursor(char ?? '');
+				this._cursor++;
+			}
+		});
+
+		this.on('userInput', (input) => {
+			this._setValue(input);
+		});
+		this.on('finalize', () => {
+			if (!this.value) {
+				this.value = opts.defaultValue;
+			}
+			if (this.value === undefined) {
+				this.value = '';
+			}
+		});
+	}
+}

packages/core/src/prompts/prompt.ts

@@ -179,6 +179,10 @@ export default class Prompt<TValue> {
 		return char === '\t';
 	}
 
+	protected _shouldSubmit(_char: string | undefined, _key: Key): boolean {
+		return true;
+	}
+
 	protected _setValue(value: TValue | undefined): void {
 		this.value = value;
 		this.emit('value', this.value);
@@ -225,7 +229,7 @@ export default class Prompt<TValue> {
 		// Call the key event handler and emit the key event
 		this.emit('key', char?.toLowerCase(), key);
 
-		if (key?.name === 'return') {
+		if (key?.name === 'return' && this._shouldSubmit(char, key)) {
 			if (this.opts.validate) {
 				const problem = this.opts.validate(this.value);
 				if (problem) {

packages/core/src/utils/cursor.ts

@@ -16,3 +16,41 @@ export function findCursor<T extends { disabled?: boolean }>(
 	}
 	return clampedCursor;
 }
+
+export function findTextCursor(
+	cursor: number,
+	deltaX: number,
+	deltaY: number,
+	value: string
+): number {
+	const lines = value.split('\n');
+	let cursorY = 0;
+	let cursorX = cursor;
+
+	for (const line of lines) {
+		if (cursorX <= line.length) {
+			break;
+		}
+		cursorX -= line.length + 1;
+		cursorY++;
+	}
+
+	cursorY = Math.max(0, Math.min(lines.length - 1, cursorY + deltaY));
+
+	cursorX = Math.min(cursorX, lines[cursorY].length) + deltaX;
+	while (cursorX < 0 && cursorY > 0) {
+		cursorY--;
+		cursorX += lines[cursorY].length + 1;
+	}
+	while (cursorX > lines[cursorY].length && cursorY < lines.length - 1) {
+		cursorX -= lines[cursorY].length + 1;
+		cursorY++;
+	}
+	cursorX = Math.max(0, Math.min(lines[cursorY].length, cursorX));
+
+	let newCursor = 0;
+	for (let i = 0; i < cursorY; i++) {
+		newCursor += lines[i].length + 1;
+	}
+	return newCursor + cursorX;
+}

packages/core/src/utils/index.ts

@@ -102,7 +102,8 @@ export function wrapTextWithPrefix(
 	output: Writable | undefined,
 	text: string,
 	prefix: string,
-	startPrefix: string = prefix
+	startPrefix: string = prefix,
+	lineFormatter?: (line: string, index: number) => string
 ): string {
 	const columns = getColumns(output ?? stdout);
 	const wrapped = wrapAnsi(text, columns - prefix.length, {
@@ -112,7 +113,8 @@ export function wrapTextWithPrefix(
 	const lines = wrapped
 		.split('\n')
 		.map((line, index) => {
-			return `${index === 0 ? startPrefix : prefix}${line}`;
+			const lineString = lineFormatter ? lineFormatter(line, index) : line;
+			return `${index === 0 ? startPrefix : prefix}${lineString}`;
 		})
 		.join('\n');
 	return lines;