Merge branch 'builder' of https://github.com/Mist3rBru/clack into builder

Author: orochaa

.changeset/config.json

@@ -7,5 +7,5 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["@example/*"]
+  "ignore": []
 }

.changeset/red-walls-greet.md

@@ -0,0 +1,5 @@
+---
+'@clack/prompts': minor
+---
+
+add prompt `workflow` builder

examples/basic/index.ts renamed to examples/basic.ts

@@ -1,5 +1,5 @@
 {
-  "name": "@example/basic",
+  "name": "@clack/examples",
   "private": true,
   "version": "0.0.0",
   "type": "module",
@@ -9,8 +9,10 @@
     "picocolors": "^1.0.0"
   },
   "scripts": {
-    "start": "jiti ./index.ts",
-    "spinner": "jiti ./spinner.ts"
+    "basic": "jiti ./basic.ts",
+    "spinner": "jiti ./spinner.ts",
+    "changesets": "jiti ./changesets.ts",
+    "workflow": "jiti ./workflow.ts"
   },
   "devDependencies": {
     "jiti": "^1.17.0"

examples/basic/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../tsconfig.json"
+}

examples/changesets/index.ts renamed to examples/changesets.ts

@@ -0,0 +1,69 @@
+import * as p from '@clack/prompts';
+
+(async () => {
+	const results = await p
+		.workflow()
+		.step('path', () =>
+			p.text({
+				message: 'Where should we create your project?',
+				placeholder: './sparkling-solid',
+				validate: (value) => {
+					if (!value) return 'Please enter a path.';
+					if (value[0] !== '.') return 'Please enter a relative path.';
+				},
+			})
+		)
+		.step('password', () =>
+			p.password({
+				message: 'Provide a password',
+				validate: (value) => {
+					if (!value) return 'Please enter a password.';
+					if (value.length < 5) return 'Password should have at least 5 characters.';
+				},
+			})
+		)
+		.step('type', ({ results }) =>
+			p.select({
+				message: `Pick a project type within "${results.path}"`,
+				initialValue: 'ts',
+				maxItems: 5,
+				options: [
+					{ value: 'ts', label: 'TypeScript' },
+					{ value: 'js', label: 'JavaScript' },
+					{ value: 'rust', label: 'Rust' },
+					{ value: 'go', label: 'Go' },
+					{ value: 'python', label: 'Python' },
+					{ value: 'coffee', label: 'CoffeeScript', hint: 'oh no' },
+				],
+			})
+		)
+		.step('tools', () =>
+			p.multiselect({
+				message: 'Select additional tools.',
+				initialValues: ['prettier', 'eslint'],
+				options: [
+					{ value: 'prettier', label: 'Prettier', hint: 'recommended' },
+					{ value: 'eslint', label: 'ESLint', hint: 'recommended' },
+					{ value: 'stylelint', label: 'Stylelint' },
+					{ value: 'gh-action', label: 'GitHub Action' },
+				],
+			})
+		)
+		.step('install', ({ results }) =>
+			p.confirm({
+				message: 'Install dependencies?',
+				initialValue: false,
+			})
+		)
+		.run();
+
+	await p
+		.workflow()
+		.step('cancel', () => p.text({ message: 'Try cancel prompt (Ctrl + C):' }))
+		.step('afterCancel', () => p.text({ message: 'This will not appear!' }))
+		.onCancel(({ results }) => {
+			p.cancel('Workflow canceled');
+			process.exit(0);
+		})
+		.run();
+})();

examples/changesets/package.json

@@ -123,7 +123,7 @@ s.stop('Installed via npm');
 
 ## Utilities
 
-### Grouping
+### Group
 
 Grouping prompts together is a great way to keep your code organized. This accepts a JSON object with a name that can be used to reference the group later. The second argument is an optional but has a `onCancel` callback that will be called if the user cancels one of the prompts in the group.
 
@@ -156,3 +156,32 @@ const group = await p.group(
 
 console.log(group.name, group.age, group.color);
 ```
+
+### Workflow
+
+Just like `group`, but on builder way, so you can choose which one fits better.
+
+```js
+import * as p from '@clack/prompts';
+
+const results = await p
+  .workflow()
+  .step('name', () => p.text({ message: 'What is your name?' }))
+  .step('age', () => p.text({ message: 'What is your age?' }))
+  .step('color', ({ results }) =>
+    p.multiselect({
+      message: `What is your favorite color ${results.name}?`,
+      options: [
+        { value: 'red', label: 'Red' },
+        { value: 'green', label: 'Green' },
+        { value: 'blue', label: 'Blue' },
+      ],
+    })
+  )
+  .onCancel(() => {
+    p.cancel('Workflow canceled');
+    process.exit(0);
+  })
+  .run();
+console.log(results.name, results.age, results.color);
+```

examples/changesets/tsconfig.json

@@ -878,36 +878,38 @@ function ansiRegex() {
 	return new RegExp(pattern, 'g');
 }
 
-export type PromptGroupAwaitedReturn<T> = {
+type Prettify<T> = {
+	[P in keyof T]: T[P];
+} & {};
+
+export type PromptGroupAwaitedReturn<T> = Prettify<{
 	[P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
+}>;
+
+export type PromptWithOptions<TResults, TReturn> = (opts: {
+	results: PromptGroupAwaitedReturn<TResults>;
+}) => TReturn;
+
+export type PromptGroup<T> = {
+	[P in keyof T]: PromptWithOptions<Partial<Omit<T, P>>, void | Promise<T[P] | void>>;
 };
 
 export interface PromptGroupOptions<T> {
 	/**
 	 * Control how the group can be canceled
 	 * if one of the prompts is canceled.
 	 */
-	onCancel?: (opts: { results: Prettify<Partial<PromptGroupAwaitedReturn<T>>> }) => void;
+	onCancel?: PromptWithOptions<Partial<T>, void>;
 }
 
-type Prettify<T> = {
-	[P in keyof T]: T[P];
-} & {};
-
-export type PromptGroup<T> = {
-	[P in keyof T]: (opts: {
-		results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
-	}) => void | Promise<T[P] | void>;
-};
-
 /**
  * Define a group of prompts to be displayed
  * and return a results of objects within the group
  */
 export const group = async <T>(
 	prompts: PromptGroup<T>,
 	opts?: PromptGroupOptions<T>
-): Promise<Prettify<PromptGroupAwaitedReturn<T>>> => {
+): Promise<PromptGroupAwaitedReturn<T>> => {
 	const results = {} as any;
 	const promptNames = Object.keys(prompts);
 
@@ -931,3 +933,51 @@ export const group = async <T>(
 
 	return results;
 };
+
+type NextWorkflowBuilder<
+	TResults extends Record<string, unknown>,
+	TKey extends string,
+	TResult
+> = WorkflowBuilder<
+	{
+		[Key in keyof TResults]: Key extends TKey ? TResult : TResults[Key];
+	} & {
+		[Key in TKey]: TResult;
+	}
+>;
+
+class WorkflowBuilder<TResults extends Record<string, unknown> = {}> {
+	private results: TResults = {} as TResults;
+	private prompts: Record<string, PromptWithOptions<TResults, unknown>> = {};
+	private cancelCallback: PromptWithOptions<Partial<TResults>, void> | undefined;
+
+	public step<TKey extends string, TResult>(
+		key: TKey extends keyof TResults ? never : TKey,
+		prompt: PromptWithOptions<TResults, TResult>
+	): NextWorkflowBuilder<TResults, TKey, TResult> {
+		this.prompts[key] = prompt;
+		return this as NextWorkflowBuilder<TResults, TKey, TResult>;
+	}
+
+	public onCancel(cb: PromptWithOptions<Partial<TResults>, void>): WorkflowBuilder<TResults> {
+		this.cancelCallback = cb;
+		return this;
+	}
+
+	public async run(): Promise<PromptGroupAwaitedReturn<TResults>> {
+		for (const [key, prompt] of Object.entries(this.prompts)) {
+			const result = await prompt({ results: this.results as any });
+			if (isCancel(result)) {
+				this.cancelCallback?.({ results: this.results as any });
+				continue;
+			}
+			//@ts-ignore
+			this.results[key] = result;
+		}
+		return this.results as PromptGroupAwaitedReturn<TResults>;
+	}
+}
+
+export const workflow = () => {
+	return new WorkflowBuilder();
+};