Introduce SingleTask component

[shauns]

WHY are these changes introduced?

This PR introduces a new UI component to simplify displaying loading indicators while awaiting promise resolution. See example usage below.

By using this component when "slow" asynchronous functions are run, we can present a more responsive experience: rather than being greeted by a blank screen or a pause in feedback, the loading bar reassures the developer that something is happening.

WHAT is this pull request doing?

• Adds a new SingleTask React component that shows a loading bar while a promise is in progress
• Implements renderSingleTask public API function that wraps the component for easy use
• Includes comprehensive test coverage for both the component and public API

The renderSingleTask function provides a simple way to display a loading indicator while awaiting a promise, and returns the promise's result when complete.

Example usage:

const result = await renderSingleTask({
  title: 'Uploading files',
  taskPromise: uploadFilesToServer()
});

How to test your changes?

1. Run the test suite: pnpm test packages/cli-kit/src/private/node/ui/components/SingleTask.test.tsx
2. Create a simple CLI command that uses renderSingleTask with a delayed promise to see the loading bar in action

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[shauns]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Disable TextAnimation in static contexts #5945
• Use renderSingleTask in app dev #5926
• Introduce SingleTask component #5925 👈 (View in Graphite)
• Add useExitOnCtrlC hook #5924
• Add LoadingBar UI component #5923
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	78.11% (+0.02% 🔼)	12543/16058
🟡	Branches	72.29% (+0.02% 🔼)	6081/8412
🟡	Functions	78.26% (+0.03% 🔼)	3286/4199
🟡	Lines	78.55% (+0.02% 🔼)	11871/15113

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / SingleTask.tsx	100%	100%	100%	100%

Test suite run success

2917 tests passing in 1263 suites.

Report generated by 🧪jest coverage report action from 0b86195

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/private/node/ui/components/LoadingBar.d.ts

import React from 'react';
interface LoadingBarProps {
    title: string;
    noColor?: boolean;
}
declare const LoadingBar: ({ title, noColor }: React.PropsWithChildren<LoadingBarProps>) => JSX.Element;
export { LoadingBar };

packages/cli-kit/dist/private/node/ui/components/SingleTask.d.ts

import React from 'react';
interface SingleTaskProps {
    title: string;
    taskPromise: Promise<unknown>;
    noColor?: boolean;
}
declare const SingleTask: ({ taskPromise, title, noColor }: React.PropsWithChildren<SingleTaskProps>) => JSX.Element | null;
export { SingleTask };

packages/cli-kit/dist/private/node/ui/hooks/use-exit-on-ctrl-c.d.ts

/**
 * This hook will cause the process to exit when the user presses Ctrl+C.
 */
export declare function useExitOnCtrlC(): void;

Existing type declarations

packages/cli-kit/dist/public/node/ui.d.ts

@@ -330,6 +330,21 @@ interface RenderTasksOptions {
  * Installing dependencies ...
  */
 export declare function renderTasks<TContext>(tasks: Task<TContext>[], { renderOptions }?: RenderTasksOptions): Promise<TContext>;
+/**
+ * Awaits a single promise and displays a loading bar while it's in progress. The promise's result is returned.
+ * @param options - Configuration object
+ * @param options.title - The title to display with the loading bar
+ * @param options.taskPromise - The promise to track
+ * @param renderOptions - Optional render configuration
+ * @returns The result of the promise
+ * @example
+ * ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ * Loading app ...
+ */
+export declare function renderSingleTask<T>({ title, taskPromise }: {
+    title: string;
+    taskPromise: Promise<T> | (() => Promise<T>);
+}, { renderOptions }?: RenderTasksOptions): Promise<T>;
 export interface RenderTextPromptOptions extends Omit<TextPromptProps, 'onSubmit'> {
     renderOptions?: RenderOptions;
 }

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/private/node/ui/components/LoadingBar.d.ts

import React from 'react';
interface LoadingBarProps {
    title: string;
    noColor?: boolean;
}
declare const LoadingBar: ({ title, noColor }: React.PropsWithChildren<LoadingBarProps>) => JSX.Element;
export { LoadingBar };

packages/cli-kit/dist/private/node/ui/components/SingleTask.d.ts

import React from 'react';
interface SingleTaskProps {
    title: string;
    taskPromise: Promise<unknown>;
    noColor?: boolean;
}
declare const SingleTask: ({ taskPromise, title, noColor }: React.PropsWithChildren<SingleTaskProps>) => JSX.Element | null;
export { SingleTask };

packages/cli-kit/dist/private/node/ui/hooks/use-exit-on-ctrl-c.d.ts

/**
 * This hook will cause the process to exit when the user presses Ctrl+C.
 */
export declare function useExitOnCtrlC(): void;

Existing type declarations

packages/cli-kit/dist/public/node/ui.d.ts

@@ -330,6 +330,21 @@ interface RenderTasksOptions {
  * Installing dependencies ...
  */
 export declare function renderTasks<TContext>(tasks: Task<TContext>[], { renderOptions }?: RenderTasksOptions): Promise<TContext>;
+/**
+ * Awaits a single promise and displays a loading bar while it's in progress. The promise's result is returned.
+ * @param options - Configuration object
+ * @param options.title - The title to display with the loading bar
+ * @param options.taskPromise - The promise to track
+ * @param renderOptions - Optional render configuration
+ * @returns The result of the promise
+ * @example
+ * ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ * Loading app ...
+ */
+export declare function renderSingleTask<T>({ title, taskPromise }: {
+    title: string;
+    taskPromise: Promise<T> | (() => Promise<T>);
+}, { renderOptions }?: RenderTasksOptions): Promise<T>;
 export interface RenderTextPromptOptions extends Omit<TextPromptProps, 'onSubmit'> {
     renderOptions?: RenderOptions;
 }

[gonzaloriestra]

I think we should add an example to kitchen-sink