@oclif/multi-stage-output 0.3.4 → 0.4.1-dev.0

package/README.md

@@ -8,6 +8,14 @@
 
 This is a framework for showing multi-stage output in the terminal. It's integrated with oclif's builtin [Performance](https://oclif.io/docs/performance/) capabilities so that perf metrics are automatically captured for each stage.
 
+![Demo](./assets/demo.gif?raw=true 'Demo')
+
+# Features
+
+- Integrated Performance Tracking: this is integrated with oclif's builtin [Performance](https://oclif.io/docs/performance/) capabilities so that perf metrics are automatically captured for each stage.
+- Responsive Design: elements will be added or removed based on the height of the terminal window. It even resizes itself if you resize the screen while the command is running.
+- CI Friendly Output: a simpler output will be shown inside non-tty environments like CI systems to avoid any excessive output that might be hard to read in CI logs.
+
 # Examples
 
 You can see examples of how to use it in the [examples](./examples/) directory.
@@ -18,6 +26,153 @@ You can run any of these with the following:
 node --loader=ts-node/esm examples/basic.ts
 ```
 
+# Usage
+
+## Basic Usage
+
+```typescript
+const ms = new MultiStageOutput({
+  jsonEnabled: false,
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  title: 'Basic Example',
+})
+// goto `stage 1`
+ms.goto('stage 1')
+// do some stuff
+
+// goto `stage 2`
+ms.goto('stage 2')
+
+// As a convenience, use .next() to goto the next stage
+ms.next()
+
+// stop the multi-stage output from running anymore. Pass in an Error if applicable.
+ms.stop()
+```
+
+## Adding information blocks before or after the stages output.
+
+You can add blocks on information before or after the list of stages. There are 3 kinds of information that can be displayed:
+
+- `message`: a simple string message
+- `static-key-value`: a simple key:value pair, e.g. `name: Foo`. If the value is undefined, the key will not be shown.
+- `dynamic-key-value`: a key:value pair where the value is expected to come in at an unknown time. This will display a spinner until the value is provided. If `.stop` is called with an error before the value is provided, then a `✘` will be displayed.
+
+```typescript
+const ms = new MultiStageOutput<{message: string; staticValue: string; dynamicValue: string}>({
+  jsonEnabled: false,
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  // preStagesBlock will be displayed BEFORE the list of stages
+  postStagesBlock: [
+    {
+      get: (data) => data?.message,
+      type: 'message',
+    },
+  ],
+  // postStagesBlock will be displayed AFTER the list of stages
+  postStagesBlock: [
+    {
+      get: (data) => data?.staticValue,
+      label: 'Static',
+      type: 'static-key-value',
+    },
+    {
+      get: (data) => data?.dynamicValue,
+      label: 'Dynamic',
+      type: 'dynamic-key-value',
+    },
+  ],
+})
+// Goto `stage 1` and provide partial data to use for the information blocks
+ms.goto('stage 1', {message: 'This is a message', staticValue: 'This is a static key:value pair'})
+
+// Provide more data to use
+ms.updateData({dynamicValue: 'This is a dynamic key:value pair'})
+
+// Goto `stage 2` and provide more partial data
+ms.goto('stage 2')
+
+// Goto stage 3
+ms.goto('stage 3')
+
+ms.stop()
+```
+
+## Adding information blocks on a specific stage
+
+You can also add information blocks onto specific stages, which will nest the information underneath the stage.
+
+```typescript
+const ms = new MultiStageOutput<{message: string; staticValue: string; dynamicValue: string}>({
+  jsonEnabled: false,
+  stageSpecificBlock: [
+    // This will be nested underneath `stage 1`
+    {
+      get: (data) => data?.message,
+      stage: 'one',
+      type: 'message',
+    },
+    // This will be nested underneath `stage 2`
+    {
+      get: (data) => data?.staticValue,
+      label: 'Static',
+      stage: 'two',
+      type: 'static-key-value',
+    },
+    // This will be nested underneath `stage 1`
+    {
+      get: (data) => data?.dynamicValue,
+      label: 'Dynamic',
+      stage: 'one',
+      type: 'dynamic-key-value',
+    },
+  ],
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  title: 'Stage-Specific Information Block Example',
+})
+
+ms.goto('stage 1', {message: 'This is a message', staticValue: 'This is a static key:value pair'})
+
+ms.goto('stage 2', {dynamicValue: 'This is a dynamic key:value pair'})
+
+ms.goto('stage 3')
+
+ms.stop()
+```
+
+## Customizing the Design
+
+You can customize the design of the multi-stage output using the `design` property:
+
+```typescript
+const ms = new MultiStageOutput({
+  jsonEnabled: false,
+  stages: ['stage 1', 'stage 2', 'stage 3'],
+  title: 'Basic Example',
+  design: {
+    title: {
+      textColor: 'red',
+    }
+    icons: {
+      completed: {
+        figure: 'C',
+        paddingLeft: 1,
+        color: '#00FF00'
+      }
+    }
+  }
+})
+```
+
+See [`Design`](./src/design.ts) for all the options available to you.
+
+## Other Options
+
+- `showElapsedTime`: Optional. Whether or not to show the `Elapsed Time` at the bottom. Defaults to `true`
+- `showStageTime`: Optional. Whether or not to show the time for each stage. Defaults to `true`
+- `title`: Optional. The title to show at the top.
+- `timerUnit`: The unit to use for the elapsed time and stage time. Can be `ms` or `s`. Defaults to `ms`
+
 # Contributing
 
 See the [contributing guide](./CONRTIBUTING.md).

package/lib/components/divider.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-export declare function Divider({ dividerChar, dividerColor, padding, textColor, textPadding: titlePadding, title, width, }: {
+export declare function Divider({ dividerChar, dividerColor, padding, terminalWidth, textColor, textPadding, title, width, }: {
     readonly title?: string;
     readonly width?: number | 'full';
     readonly padding?: number;
@@ -7,4 +7,5 @@ export declare function Divider({ dividerChar, dividerColor, padding, textColor,
     readonly textPadding?: number;
     readonly dividerChar?: string;
     readonly dividerColor?: string;
+    readonly terminalWidth?: number;
 }): React.ReactNode;

package/lib/components/divider.js

@@ -3,11 +3,17 @@ import React from 'react';
 const getSideDividerWidth = (width, titleWidth) => (width - titleWidth) / 2;
 const getNumberOfCharsPerWidth = (char, width) => width / char.length;
 const PAD = ' ';
-export function Divider({ dividerChar = '─', dividerColor = 'dim', padding = 1, textColor, textPadding: titlePadding = 1, title = '', width = 50, }) {
-    const titleString = title ? `${PAD.repeat(titlePadding) + title + PAD.repeat(titlePadding)}` : '';
+export function Divider({ dividerChar = '─', dividerColor = 'dim', padding = 1, terminalWidth = process.stdout.columns ?? 80, textColor, textPadding = 1, title = '', width = 50, }) {
+    const titleString = title ? `${PAD.repeat(textPadding) + title + PAD.repeat(textPadding)}` : '';
     const titleWidth = titleString.length;
-    const terminalWidth = process.stdout.columns ?? 80;
-    const widthToUse = width === 'full' ? terminalWidth - titlePadding : width > terminalWidth ? terminalWidth : width;
+    const widthToUse = width === 'full'
+        ? // if the width is `full`, use the terminal width minus the padding and title padding
+            terminalWidth - textPadding - padding
+        : // otherwise, if the provided width is greater than the terminal width, use the terminal width minus the padding and title paddding
+            width > terminalWidth
+                ? terminalWidth - textPadding - padding
+                : // otherwise, use the provided width
+                    width;
     const dividerWidth = getSideDividerWidth(widthToUse, titleWidth);
     const numberOfCharsPerSide = getNumberOfCharsPerWidth(dividerChar, dividerWidth);
     const dividerSideString = dividerChar.repeat(numberOfCharsPerSide);

package/lib/components/spinner.d.ts

@@ -1,6 +1,6 @@
 import { type SpinnerName } from 'cli-spinners';
 import React from 'react';
-import { IconProps } from './icon.js';
+import { RequiredDesign } from '../design.js';
 type UseSpinnerProps = {
     /**
      * Type of a spinner.
@@ -19,13 +19,13 @@ type SpinnerProps = UseSpinnerProps & {
     readonly labelPosition?: 'left' | 'right';
 };
 export declare function Spinner({ isBold, label, labelPosition, type }: SpinnerProps): React.ReactElement;
-export declare function SpinnerOrError({ error, failedIcon, labelPosition, ...props }: SpinnerProps & {
+export declare function SpinnerOrError({ design, error, labelPosition, ...props }: SpinnerProps & {
     readonly error?: Error;
-    readonly failedIcon: IconProps;
+    readonly design: RequiredDesign;
 }): React.ReactElement;
 export declare function SpinnerOrErrorOrChildren({ children, error, ...props }: SpinnerProps & {
     readonly children?: React.ReactNode;
     readonly error?: Error;
-    readonly failedIcon: IconProps;
+    readonly design: RequiredDesign;
 }): React.ReactElement;
 export {};

package/lib/components/spinner.js

@@ -31,13 +31,13 @@ export function Spinner({ isBold, label, labelPosition = 'right', type }) {
             " ",
             label)));
 }
-export function SpinnerOrError({ error, failedIcon, labelPosition = 'right', ...props }) {
+export function SpinnerOrError({ design, error, labelPosition = 'right', ...props }) {
     if (error) {
         return (React.createElement(Box, null,
             props.label && labelPosition === 'left' && React.createElement(Text, null,
                 props.label,
                 " "),
-            React.createElement(Icon, { icon: failedIcon }),
+            React.createElement(Icon, { icon: design.icons.failed }),
             props.label && labelPosition === 'right' && React.createElement(Text, null,
                 " ",
                 props.label)));

package/lib/components/stages.d.ts

@@ -24,6 +24,10 @@ type Info<T extends Record<string, unknown>> = {
      * Whether the value should be bold.
      */
     bold?: boolean;
+    /**
+     * Set to `true` to prevent this key-value pair or message from being collapsed when the window is too short. Defaults to false.
+     */
+    neverCollapse?: boolean;
 };
 export type KeyValuePair<T extends Record<string, unknown>> = Info<T> & {
     /**
@@ -48,18 +52,39 @@ export type FormattedKeyValue = {
     readonly value: string | undefined;
     readonly stage?: string;
     readonly type: 'dynamic-key-value' | 'static-key-value' | 'message';
+    readonly neverCollapse?: boolean;
 };
 export type StagesProps = {
+    readonly compactionLevel?: number;
     readonly design?: RequiredDesign;
     readonly error?: Error | undefined;
+    readonly hasElapsedTime?: boolean;
+    readonly hasStageTime?: boolean;
     readonly postStagesBlock?: FormattedKeyValue[];
     readonly preStagesBlock?: FormattedKeyValue[];
     readonly stageSpecificBlock?: FormattedKeyValue[];
-    readonly title?: string;
-    readonly hasElapsedTime?: boolean;
-    readonly hasStageTime?: boolean;
-    readonly timerUnit?: 'ms' | 's';
     readonly stageTracker: StageTracker;
+    readonly timerUnit?: 'ms' | 's';
+    readonly title?: string;
+};
+/**
+ * Determine the level of compaction required to render the stages component within the terminal height.
+ *
+ * Compaction levels:
+ * 0 - hide nothing
+ * 1 - only show one stage at a time, with stage specific info nested under the stage
+ * 2 - hide the elapsed time
+ * 3 - hide the title
+ * 4 - hide the pre-stages block
+ * 5 - hide the post-stages block
+ * 6 - put the stage specific info directly next to the stage
+ * 7 - hide the stage-specific block
+ * 8 - reduce the padding between boxes
+ * @returns the compaction level based on the number of lines that will be displayed
+ */
+export declare function determineCompactionLevel({ design, hasElapsedTime, hasStageTime, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, title, }: StagesProps, rows: number, columns: number): {
+    compactionLevel: number;
+    totalHeight: number;
 };
-export declare function Stages({ design, error, hasElapsedTime, hasStageTime, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, timerUnit, title, }: StagesProps): React.ReactNode;
+export declare function Stages({ compactionLevel, design, error, hasElapsedTime, hasStageTime, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, timerUnit, title, }: StagesProps): React.ReactNode;
 export {};

package/lib/components/stages.js

@@ -1,5 +1,5 @@
 import { capitalCase } from 'change-case';
-import { Box, Text } from 'ink';
+import { Box, Text, useStdout } from 'ink';
 import React from 'react';
 import { constructDesignParams } from '../design.js';
 import { Divider } from './divider.js';
@@ -33,7 +33,7 @@ function StageInfos({ design, error, keyValuePairs, stage, }) {
         if (kv.type === 'dynamic-key-value') {
             return (React.createElement(Box, { key: key },
                 React.createElement(Icon, { icon: design.icons.info }),
-                React.createElement(SpinnerOrErrorOrChildren, { error: error, label: `${kv.label}:`, labelPosition: "left", type: design.spinners.info, failedIcon: design.icons.failed }, kv.value && (React.createElement(Text, { bold: kv.isBold, color: kv.color }, kv.value)))));
+                React.createElement(SpinnerOrErrorOrChildren, { error: error, label: `${kv.label}:`, labelPosition: "left", type: design.spinners.info, design: design }, kv.value && (React.createElement(Text, { bold: kv.isBold, color: kv.color }, kv.value)))));
         }
         if (kv.type === 'static-key-value') {
             return (React.createElement(Box, { key: key },
@@ -50,7 +50,7 @@ function Infos({ design, error, keyValuePairs, }) {
             return React.createElement(SimpleMessage, { key: key, ...kv });
         }
         if (kv.type === 'dynamic-key-value') {
-            return (React.createElement(SpinnerOrErrorOrChildren, { key: key, error: error, label: `${kv.label}:`, labelPosition: "left", type: design.spinners.info, failedIcon: design.icons.failed }, kv.value && (React.createElement(Text, { bold: kv.isBold, color: kv.color }, kv.value))));
+            return (React.createElement(SpinnerOrErrorOrChildren, { key: key, error: error, label: `${kv.label}:`, labelPosition: "left", type: design.spinners.info, design: design }, kv.value && (React.createElement(Text, { bold: kv.isBold, color: kv.color }, kv.value))));
         }
         if (kv.type === 'static-key-value') {
             return React.createElement(StaticKeyValue, { key: key, ...kv });
@@ -58,29 +58,248 @@ function Infos({ design, error, keyValuePairs, }) {
         return false;
     });
 }
-export function Stages({ design = constructDesignParams(), error, hasElapsedTime = true, hasStageTime = true, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, timerUnit = 'ms', title, }) {
-    return (React.createElement(Box, { flexDirection: "column", paddingTop: 1, paddingBottom: 1 },
-        title && React.createElement(Divider, { title: title, ...design.title }),
-        preStagesBlock && preStagesBlock.length > 0 && (React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingTop: 1 },
-            React.createElement(Infos, { design: design, error: error, keyValuePairs: preStagesBlock }))),
-        React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingTop: 1 }, [...stageTracker.entries()].map(([stage, status]) => (React.createElement(Box, { key: stage, flexDirection: "column" },
-            React.createElement(Box, null,
-                (status === 'current' || status === 'failed') && (React.createElement(SpinnerOrError, { error: error, label: capitalCase(stage), type: design.spinners.stage, failedIcon: design.icons.failed })),
-                status === 'skipped' && (React.createElement(Icon, { icon: design.icons.skipped },
-                    React.createElement(Text, { color: "dim" },
-                        capitalCase(stage),
-                        " - Skipped"))),
-                status === 'completed' && (React.createElement(Icon, { icon: design.icons.completed },
-                    React.createElement(Text, null, capitalCase(stage)))),
-                status === 'pending' && (React.createElement(Icon, { icon: design.icons.pending },
-                    React.createElement(Text, null, capitalCase(stage)))),
-                status !== 'pending' && status !== 'skipped' && hasStageTime && (React.createElement(Box, null,
-                    React.createElement(Text, null, " "),
-                    React.createElement(Timer, { color: "dim", isStopped: status === 'completed', unit: timerUnit })))),
-            stageSpecificBlock && stageSpecificBlock.length > 0 && status !== 'pending' && status !== 'skipped' && (React.createElement(StageInfos, { design: design, error: error, keyValuePairs: stageSpecificBlock, stage: stage })))))),
-        postStagesBlock && postStagesBlock.length > 0 && (React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingTop: 1 },
-            React.createElement(Infos, { design: design, error: error, keyValuePairs: postStagesBlock }))),
-        hasElapsedTime && (React.createElement(Box, { marginLeft: 1 },
+function CompactStage({ design, direction = 'row', error, stage, stageSpecificBlock, stageTracker, status, }) {
+    if (status !== 'current')
+        return false;
+    return (React.createElement(Box, { flexDirection: direction },
+        React.createElement(SpinnerOrError, { error: error, label: `[${stageTracker.indexOf(stage) + 1}/${stageTracker.size}] ${capitalCase(stage)}`, type: design.spinners.stage, design: design }),
+        stageSpecificBlock && stageSpecificBlock.length > 0 && (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(StageInfos, { design: design, error: error, keyValuePairs: stageSpecificBlock, stage: stage })))));
+}
+function Stage({ design, error, stage, status, }) {
+    return (React.createElement(Box, null,
+        (status === 'current' || status === 'failed') && (React.createElement(SpinnerOrError, { error: error, label: capitalCase(stage), type: design.spinners.stage, design: design })),
+        status === 'skipped' && (React.createElement(Icon, { icon: design.icons.skipped },
+            React.createElement(Text, { color: "dim" },
+                capitalCase(stage),
+                " - Skipped"))),
+        status !== 'skipped' && status !== 'failed' && status !== 'current' && (React.createElement(Icon, { icon: design.icons[status] },
+            React.createElement(Text, null, capitalCase(stage))))));
+}
+function StageEntries({ compactionLevel, design, error, hasStageTime, stageSpecificBlock, stageTracker, timerUnit, }) {
+    return (React.createElement(React.Fragment, null, [...stageTracker.entries()].map(([stage, status]) => (React.createElement(Box, { key: stage, flexDirection: "column" },
+        React.createElement(Box, null,
+            compactionLevel === 0 ? (React.createElement(Stage, { stage: stage, status: status, design: design, error: error })) : (
+            // Render the stage name, spinner, and stage specific info
+            React.createElement(CompactStage, { stage: stage, status: status, design: design, error: error, stageSpecificBlock: stageSpecificBlock, stageTracker: stageTracker, direction: compactionLevel >= 6 ? 'row' : 'column' })),
+            status !== 'pending' && status !== 'skipped' && hasStageTime && (React.createElement(Box, { display: compactionLevel === 0 ? 'flex' : status === 'current' ? 'flex' : 'none' },
+                React.createElement(Text, null, " "),
+                React.createElement(Timer, { color: "dim", isStopped: status === 'completed', unit: timerUnit })))),
+        compactionLevel === 0 &&
+            stageSpecificBlock &&
+            stageSpecificBlock.length > 0 &&
+            status !== 'pending' &&
+            status !== 'skipped' && (React.createElement(StageInfos, { design: design, error: error, keyValuePairs: stageSpecificBlock, stage: stage })))))));
+}
+function filterInfos(infos, compactionLevel, cutOff) {
+    return infos.filter((info) => {
+        // return true to keep the info
+        if (compactionLevel < cutOff || info.neverCollapse) {
+            return true;
+        }
+        return false;
+    });
+}
+/**
+ * Determine the level of compaction required to render the stages component within the terminal height.
+ *
+ * Compaction levels:
+ * 0 - hide nothing
+ * 1 - only show one stage at a time, with stage specific info nested under the stage
+ * 2 - hide the elapsed time
+ * 3 - hide the title
+ * 4 - hide the pre-stages block
+ * 5 - hide the post-stages block
+ * 6 - put the stage specific info directly next to the stage
+ * 7 - hide the stage-specific block
+ * 8 - reduce the padding between boxes
+ * @returns the compaction level based on the number of lines that will be displayed
+ */
+export function determineCompactionLevel({ design = constructDesignParams(), hasElapsedTime, hasStageTime, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, title, }, rows, columns) {
+    const calculateHeightOfBlock = (block) => {
+        if (!block)
+            return 0;
+        return block.reduce((acc, info) => {
+            if (info.type === 'message') {
+                if (!info.value)
+                    return acc;
+                if (info.value.length > columns) {
+                    // if the message is longer than the terminal width, add the number of lines
+                    return acc + Math.ceil(info.value.length / columns);
+                }
+                // if the message is multiline, add the number of lines
+                return acc + info.value.split('\n').length;
+            }
+            const { label = '', value } = info;
+            // if there's no value we still add 1 for the label
+            if (!value)
+                return acc + 1;
+            if (label.length + Number(': '.length) + value.length > columns) {
+                // if the value is longer than the terminal width, add the number of lines
+                return acc + Math.ceil(value.length / columns);
+            }
+            return acc + value.split('\n').length;
+        }, 0);
+    };
+    const calculateHeightOfStage = (stage) => {
+        const status = stageTracker.get(stage) ?? 'pending';
+        const skipped = status === 'skipped' ? ' - Skipped' : '';
+        // We don't have access to the exact stage time, so we're taking a conservative estimate of
+        // 10 characters + 1 character for the space between the stage and timer,
+        // examples: 999ms (5), 59.99s (6), 59m 59.99s (10), 23h 59m (7)
+        const stageTimeLength = hasStageTime ? 11 : 0;
+        if (
+        // 1 for the left margin
+        1 +
+            design.icons[status].paddingLeft +
+            design.icons[status].figure.length +
+            design.icons[status].paddingRight +
+            stage.length +
+            skipped.length +
+            stageTimeLength >
+            columns) {
+            return Math.ceil(stage.length / columns);
+        }
+        return 1;
+    };
+    const calculateWidthOfCompactStage = (stage) => {
+        const status = stageTracker.get(stage) ?? 'current';
+        // We don't have access to the exact stage time, so we're taking a conservative estimate of
+        // 7 characters + 1 character for the space between the stage and timer,
+        // examples: 999ms (5), 59s (3), 59m 59s (7), 23h 59m (7)
+        const stageTimeLength = hasStageTime ? 8 : 0;
+        const firstStageSpecificBlock = stageSpecificBlock?.find((block) => block.stage === stage);
+        const firstStageSpecificBlockLength = firstStageSpecificBlock?.type === 'message'
+            ? (firstStageSpecificBlock?.value?.length ?? 0)
+            : (firstStageSpecificBlock?.label?.length ?? 0) + (firstStageSpecificBlock?.value?.length ?? 0) + 2;
+        const width = 
+        // 1 for the left margin
+        1 +
+            design.icons[status].paddingLeft +
+            design.icons[status].figure.length +
+            design.icons[status].paddingRight +
+            `[${stageTracker.indexOf(stage) + 1}/${stageTracker.size}] ${stage}`.length +
+            stageTimeLength +
+            firstStageSpecificBlockLength;
+        return width;
+    };
+    const stagesHeight = [...stageTracker.values()].reduce((acc, stage) => acc + calculateHeightOfStage(stage), 0);
+    const preStagesBlockHeight = calculateHeightOfBlock(preStagesBlock);
+    const postStagesBlockHeight = calculateHeightOfBlock(postStagesBlock);
+    const stageSpecificBlockHeight = calculateHeightOfBlock(stageSpecificBlock);
+    // 3 at minimum because: 1 for marginTop on entire component, 1 for marginBottom on entire component, 1 for paddingBottom on StageEntries
+    const paddings = 3 + (preStagesBlock ? 1 : 0) + (postStagesBlock ? 1 : 0) + (title ? 1 : 0);
+    const totalHeight = stagesHeight +
+        preStagesBlockHeight +
+        postStagesBlockHeight +
+        stageSpecificBlockHeight +
+        (title ? 1 : 0) +
+        (hasElapsedTime ? 1 : 0) +
+        paddings +
+        // add one for good measure - iTerm2 will flicker on every render if the height is exactly the same as the terminal height so it's better to be safe
+        1;
+    let cLevel = 0;
+    const levels = [
+        // 1: only show one stage at a time, with stage specific info nested under the stage
+        (remainingHeight) => remainingHeight - stagesHeight + 1,
+        // 2: hide the elapsed time
+        (remainingHeight) => remainingHeight - 1,
+        // 3: hide the title (subtract 1 for title and 1 for paddingBottom)
+        (remainingHeight) => remainingHeight - 2,
+        // 4: hide the pre-stages block (subtract 1 for paddingBottom)
+        (remainingHeight) => remainingHeight - preStagesBlockHeight - 1,
+        // 5: hide the post-stages block
+        (remainingHeight) => remainingHeight - postStagesBlockHeight,
+        // 6: put the stage specific info directly next to the stage
+        (remainingHeight) => remainingHeight - stageSpecificBlockHeight,
+        // 7: hide the stage-specific block
+        (remainingHeight) => remainingHeight - stageSpecificBlockHeight,
+        // 8: reduce the padding between boxes
+        (remainingHeight) => remainingHeight - 1,
+    ];
+    let remainingHeight = totalHeight;
+    while (cLevel < 8 && remainingHeight >= rows) {
+        remainingHeight = levels[cLevel](remainingHeight);
+        cLevel++;
+    }
+    // It's possible that the collapsed stage might extend beyond the terminal width.
+    // If so, we need to bump the compaction level up to 7 so that the stage specific info is hidden
+    if (cLevel === 6 && stageTracker.current && calculateWidthOfCompactStage(stageTracker.current) >= columns) {
+        cLevel = 7;
+    }
+    return {
+        compactionLevel: cLevel,
+        totalHeight,
+    };
+}
+export function Stages({ compactionLevel, design = constructDesignParams(), error, hasElapsedTime = true, hasStageTime = true, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, timerUnit = 'ms', title, }) {
+    const { stdout } = useStdout();
+    const [levelOfCompaction, setLevelOfCompaction] = React.useState(determineCompactionLevel({
+        hasElapsedTime,
+        hasStageTime,
+        postStagesBlock,
+        preStagesBlock,
+        stageSpecificBlock,
+        stageTracker,
+        title,
+    }, stdout.rows - 1, stdout.columns).compactionLevel);
+    React.useEffect(() => {
+        setLevelOfCompaction(determineCompactionLevel({
+            hasElapsedTime,
+            hasStageTime,
+            postStagesBlock,
+            preStagesBlock,
+            stageSpecificBlock,
+            stageTracker,
+            title,
+        }, stdout.rows - 1, stdout.columns).compactionLevel);
+    }, [
+        compactionLevel,
+        hasElapsedTime,
+        hasStageTime,
+        postStagesBlock,
+        preStagesBlock,
+        stageSpecificBlock,
+        stageTracker,
+        stdout.columns,
+        stdout.rows,
+        title,
+    ]);
+    React.useEffect(() => {
+        const handler = () => {
+            setLevelOfCompaction(determineCompactionLevel({
+                hasElapsedTime,
+                hasStageTime,
+                postStagesBlock,
+                preStagesBlock,
+                stageSpecificBlock,
+                stageTracker,
+                title,
+            }, stdout.rows - 1, stdout.columns).compactionLevel);
+        };
+        stdout.on('resize', handler);
+        return () => {
+            stdout.removeListener('resize', handler);
+        };
+    });
+    // if compactionLevel is provided, use that instead of the calculated level
+    const actualLevelOfCompaction = compactionLevel ?? levelOfCompaction;
+    // filter out the info blocks based on the compaction level
+    const preStages = filterInfos(preStagesBlock ?? [], actualLevelOfCompaction, 4);
+    const postStages = filterInfos(postStagesBlock ?? [], actualLevelOfCompaction, 5);
+    const stageSpecific = filterInfos(stageSpecificBlock ?? [], actualLevelOfCompaction, 7);
+    // Reduce padding if the compaction level is 8
+    const padding = actualLevelOfCompaction === 8 ? 0 : 1;
+    return (React.createElement(Box, { flexDirection: "column", marginTop: padding, marginBottom: padding },
+        actualLevelOfCompaction < 3 && title && (React.createElement(Box, { paddingBottom: padding },
+            React.createElement(Divider, { title: title, ...design.title, terminalWidth: stdout.columns }))),
+        preStages && preStages.length > 0 && (React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingBottom: padding },
+            React.createElement(Infos, { design: design, error: error, keyValuePairs: preStages }))),
+        React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingBottom: padding },
+            React.createElement(StageEntries, { compactionLevel: actualLevelOfCompaction, design: design, error: error, hasStageTime: hasStageTime, stageSpecificBlock: stageSpecific, stageTracker: stageTracker, timerUnit: timerUnit })),
+        postStages && postStages.length > 0 && (React.createElement(Box, { flexDirection: "column", marginLeft: 1 },
+            React.createElement(Infos, { design: design, error: error, keyValuePairs: postStages }))),
+        hasElapsedTime && (React.createElement(Box, { marginLeft: 1, display: actualLevelOfCompaction < 2 ? 'flex' : 'none' },
             React.createElement(Text, null, "Elapsed Time: "),
             React.createElement(Timer, { unit: timerUnit })))));
 }

package/lib/design.d.ts

@@ -3,7 +3,7 @@ import { IconProps } from './components/icon.js';
 export type Design = {
     icons?: {
         /**
-         * Icon to display for a completed stage. Defaults to '✔'
+         * Icon to display for a completed stage. Defaults to green '✔'
          */
         completed?: IconProps;
         /**
@@ -13,21 +13,33 @@ export type Design = {
          */
         current?: IconProps;
         /**
-         * Icon to display for a failed stage. Defaults to '✘'
+         * Icon to display for a failed stage. Defaults to red '✘'
          */
         failed?: IconProps;
         /**
-         * Icon to display for a pending stage. Defaults to '◼'
+         * Icon to display for a pending stage. Defaults to dim '◼'
          */
         pending?: IconProps;
         /**
-         * Icon to display for a skipped stage. Defaults to '◯'
+         * Icon to display for a skipped stage. Defaults to dim '◯'
          */
         skipped?: IconProps;
         /**
          * Icon to display for stage specific information. Defaults to '▸'
          */
         info?: IconProps;
+        /**
+         * Icon to display for a aborted stage. Defaults to red '◼'
+         */
+        aborted?: IconProps;
+        /**
+         * Icon to display for a paused stage. Defaults to magenta '●'
+         */
+        paused?: IconProps;
+        /**
+         * Icon to display for an async stage. Defaults to magenta '▶'
+         */
+        async?: IconProps;
     };
     title?: {
         /**

package/lib/design.js

@@ -2,6 +2,20 @@ import figures from 'figures';
 export function constructDesignParams(design) {
     return {
         icons: {
+            aborted: {
+                color: 'red',
+                figure: figures.squareSmallFilled,
+                paddingLeft: 0,
+                paddingRight: 0,
+                ...design?.icons?.current,
+            },
+            async: {
+                color: 'magenta',
+                figure: figures.play,
+                paddingLeft: 0,
+                paddingRight: 0,
+                ...design?.icons?.current,
+            },
             completed: {
                 color: 'green',
                 figure: figures.tick,
@@ -30,6 +44,13 @@ export function constructDesignParams(design) {
                 paddingRight: 1,
                 ...design?.icons?.info,
             },
+            paused: {
+                color: 'magenta',
+                figure: figures.bullet,
+                paddingLeft: 0,
+                paddingRight: 1,
+                ...design?.icons?.current,
+            },
             pending: {
                 color: 'dim',
                 figure: figures.squareSmallFilled,

package/lib/multi-stage-output.d.ts

@@ -1,5 +1,6 @@
 import { KeyValuePair, SimpleMessage, StageInfoBlock } from './components/stages.js';
 import { Design } from './design.js';
+import { StageStatus } from './stage-tracker.js';
 export type MultiStageOutputOptions<T extends Record<string, unknown>> = {
     /**
      * Stages to render.
@@ -51,28 +52,76 @@ export type MultiStageOutputOptions<T extends Record<string, unknown>> = {
     readonly jsonEnabled: boolean;
 };
 export declare class MultiStageOutput<T extends Record<string, unknown>> implements Disposable {
-    private ciInstance;
+    private readonly ciInstance;
     private data?;
     private readonly design;
     private readonly hasElapsedTime?;
     private readonly hasStageTime?;
-    private inkInstance;
+    private readonly inkInstance;
     private readonly postStagesBlock?;
     private readonly preStagesBlock?;
     private readonly stages;
     private readonly stageSpecificBlock?;
-    private stageTracker;
+    private readonly stageTracker;
     private stopped;
     private readonly timerUnit?;
     private readonly title?;
     constructor({ data, design, jsonEnabled, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }: MultiStageOutputOptions<T>);
+    /**
+     * Stop multi-stage output from running with a failed status.
+     */
+    error(): void;
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as completed.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     goto(stage: string, data?: Partial<T>): void;
+    /**
+     * Moves to the next stage of the process.
+     *
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     next(data?: Partial<T>): void;
-    stop(error?: Error): void;
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as skipped.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
+    skipTo(stage: string, data?: Partial<T>): void;
+    /**
+     * Stop multi-stage output from running.
+     *
+     * The stage currently running will be changed to the provided `finalStatus`.
+     *
+     * @param finalStatus - The status to set the current stage to.
+     * @returns void
+     */
+    stop(finalStatus?: StageStatus): void;
     [Symbol.dispose](): void;
+    /**
+     * Updates the data of the component.
+     *
+     * @param data - The partial data object to update the component's data with.
+     * @returns void
+     */
     updateData(data: Partial<T>): void;
     private formatKeyValuePairs;
     /** shared method to populate everything needed for Stages cmp */
     private generateStagesInput;
+    private rerender;
     private update;
 }

package/lib/multi-stage-output.js

@@ -77,7 +77,7 @@ class CIMultiStageOutput {
                     this.lastUpdateTime = Date.now();
                     if (!this.startTimes.has(stage))
                         this.startTimes.set(stage, Date.now());
-                    ux.stdout(`${this.design.icons.current} ${capitalCase(stage)}...`);
+                    ux.stdout(`${this.design.icons.current.figure} ${capitalCase(stage)}...`);
                     this.printInfo(this.preStagesBlock, 3);
                     this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
                     this.printInfo(this.postStagesBlock, 3);
@@ -91,16 +91,16 @@ class CIMultiStageOutput {
                         const startTime = this.startTimes.get(stage);
                         const elapsedTime = startTime ? Date.now() - startTime : 0;
                         const displayTime = readableTime(elapsedTime, this.timerUnit);
-                        ux.stdout(`${this.design.icons[status]} ${capitalCase(stage)} (${displayTime})`);
+                        ux.stdout(`${this.design.icons[status].figure} ${capitalCase(stage)} (${displayTime})`);
                         this.printInfo(this.preStagesBlock, 3);
                         this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
                         this.printInfo(this.postStagesBlock, 3);
                     }
                     else if (status === 'skipped') {
-                        ux.stdout(`${this.design.icons[status]} ${capitalCase(stage)} - Skipped`);
+                        ux.stdout(`${this.design.icons[status].figure} ${capitalCase(stage)} - Skipped`);
                     }
                     else {
-                        ux.stdout(`${this.design.icons[status]} ${capitalCase(stage)}`);
+                        ux.stdout(`${this.design.icons[status].figure} ${capitalCase(stage)}`);
                         this.printInfo(this.preStagesBlock, 3);
                         this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
                         this.printInfo(this.postStagesBlock, 3);
@@ -177,6 +177,23 @@ export class MultiStageOutput {
             this.inkInstance = render(React.createElement(Stages, { ...this.generateStagesInput() }));
         }
     }
+    /**
+     * Stop multi-stage output from running with a failed status.
+     */
+    error() {
+        this.stop('failed');
+    }
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as completed.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     goto(stage, data) {
         if (this.stopped)
             return;
@@ -186,37 +203,85 @@ export class MultiStageOutput {
         // prevent going to a previous stage
         if (this.stages.indexOf(stage) < this.stages.indexOf(this.stageTracker.current ?? this.stages[0]))
             return;
-        this.update(stage, data);
+        this.update(stage, 'completed', data);
     }
+    /**
+     * Moves to the next stage of the process.
+     *
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
     next(data) {
         if (this.stopped)
             return;
         const nextStageIndex = this.stages.indexOf(this.stageTracker.current ?? this.stages[0]) + 1;
         if (nextStageIndex < this.stages.length) {
-            this.update(this.stages[nextStageIndex], data);
+            this.update(this.stages[nextStageIndex], 'completed', data);
         }
     }
-    stop(error) {
+    /**
+     * Go to a stage, marking any stages in between the current stage and the provided stage as skipped.
+     *
+     * If the stage does not exist or is before the current stage, nothing will happen.
+     *
+     * If the stage is the same as the current stage, the data will be updated.
+     *
+     * @param stage Stage to go to
+     * @param data - Optional data to pass to the next stage.
+     * @returns void
+     */
+    skipTo(stage, data) {
+        if (this.stopped)
+            return;
+        // ignore non-existent stages
+        if (!this.stages.includes(stage))
+            return;
+        // prevent going to a previous stage
+        if (this.stages.indexOf(stage) < this.stages.indexOf(this.stageTracker.current ?? this.stages[0]))
+            return;
+        this.update(stage, 'skipped', data);
+    }
+    /**
+     * Stop multi-stage output from running.
+     *
+     * The stage currently running will be changed to the provided `finalStatus`.
+     *
+     * @param finalStatus - The status to set the current stage to.
+     * @returns void
+     */
+    stop(finalStatus = 'completed') {
         if (this.stopped)
             return;
         this.stopped = true;
-        this.stageTracker.refresh(this.stageTracker.current ?? this.stages[0], { hasError: Boolean(error), isStopping: true });
+        this.stageTracker.refresh(this.stageTracker.current ?? this.stages[0], {
+            finalStatus,
+        });
         if (isInCi) {
             this.ciInstance?.stop(this.stageTracker);
             return;
         }
-        const stagesInput = { ...this.generateStagesInput(), ...(error ? { error } : {}) };
-        this.inkInstance?.rerender(React.createElement(Stages, { ...stagesInput }));
+        // The underlying components expect an Error, although they don't currently use anything on the error - they check if it exists.
+        // Instead of refactoring the components to take a boolean, we pass in a placeholder Error,
+        // which, gives us the flexibility in the future to pass in an actual Error if we want
+        const error = finalStatus === 'failed' ? new Error('Error') : undefined;
+        const stagesInput = { ...this.generateStagesInput({ compactionLevel: 0 }), ...(error ? { error } : {}) };
+        this.inkInstance?.rerender(React.createElement(Stages, { ...stagesInput, compactionLevel: 0 }));
         this.inkInstance?.unmount();
     }
     [Symbol.dispose]() {
         this.inkInstance?.unmount();
     }
+    /**
+     * Updates the data of the component.
+     *
+     * @param data - The partial data object to update the component's data with.
+     * @returns void
+     */
     updateData(data) {
         if (this.stopped)
             return;
         this.data = { ...this.data, ...data };
-        this.update(this.stageTracker.current ?? this.stages[0], data);
+        this.rerender();
     }
     formatKeyValuePairs(infoBlock) {
         return (infoBlock?.map((info) => {
@@ -224,6 +289,7 @@ export class MultiStageOutput {
             return {
                 color: info.color,
                 isBold: info.bold,
+                neverCollapse: info.neverCollapse,
                 type: info.type,
                 value: formattedData,
                 ...(info.type === 'message' ? {} : { label: info.label }),
@@ -232,8 +298,10 @@ export class MultiStageOutput {
         }) ?? []);
     }
     /** shared method to populate everything needed for Stages cmp */
-    generateStagesInput() {
+    generateStagesInput(opts) {
+        const { compactionLevel } = opts ?? {};
         return {
+            compactionLevel,
             design: this.design,
             hasElapsedTime: this.hasElapsedTime,
             hasStageTime: this.hasStageTime,
@@ -245,9 +313,7 @@ export class MultiStageOutput {
             title: this.title,
         };
     }
-    update(stage, data) {
-        this.data = { ...this.data, ...data };
-        this.stageTracker.refresh(stage);
+    rerender() {
         if (isInCi) {
             this.ciInstance?.update(this.stageTracker, this.data);
         }
@@ -255,4 +321,9 @@ export class MultiStageOutput {
             this.inkInstance?.rerender(React.createElement(Stages, { ...this.generateStagesInput() }));
         }
     }
+    update(stage, bypassStatus, data) {
+        this.data = { ...this.data, ...data };
+        this.stageTracker.refresh(stage, { bypassStatus });
+        this.rerender();
+    }
 }

package/lib/stage-tracker.d.ts

@@ -1,14 +1,21 @@
-export type StageStatus = 'pending' | 'current' | 'completed' | 'skipped' | 'failed';
+export type StageStatus = 'aborted' | 'async' | 'completed' | 'current' | 'failed' | 'paused' | 'pending' | 'skipped';
 export declare class StageTracker {
+    private stages;
     current: string | undefined;
     private map;
     private markers;
     constructor(stages: readonly string[] | string[]);
+    get size(): number;
     entries(): IterableIterator<[string, StageStatus]>;
     get(stage: string): StageStatus | undefined;
+    getCurrent(): {
+        stage: string;
+        status: StageStatus;
+    } | undefined;
+    indexOf(stage: string): number;
     refresh(nextStage: string, opts?: {
-        hasError?: boolean;
-        isStopping?: boolean;
+        finalStatus?: StageStatus;
+        bypassStatus?: StageStatus;
     }): void;
     set(stage: string, status: StageStatus): void;
     values(): IterableIterator<StageStatus>;

package/lib/stage-tracker.js

@@ -1,17 +1,33 @@
 import { Performance } from '@oclif/core/performance';
 export class StageTracker {
+    stages;
     current;
     map = new Map();
     markers = new Map();
     constructor(stages) {
+        this.stages = stages;
         this.map = new Map(stages.map((stage) => [stage, 'pending']));
     }
+    get size() {
+        return this.map.size;
+    }
     entries() {
         return this.map.entries();
     }
     get(stage) {
         return this.map.get(stage);
     }
+    getCurrent() {
+        if (this.current) {
+            return {
+                stage: this.current,
+                status: this.map.get(this.current),
+            };
+        }
+    }
+    indexOf(stage) {
+        return this.stages.indexOf(stage);
+    }
     refresh(nextStage, opts) {
         const stages = [...this.map.keys()];
         for (const stage of stages) {
@@ -19,15 +35,9 @@ export class StageTracker {
                 continue;
             if (this.map.get(stage) === 'failed')
                 continue;
-            // .stop() was called with an error => set the stage to failed
-            if (nextStage === stage && opts?.hasError) {
-                this.set(stage, 'failed');
-                this.stopMarker(stage);
-                continue;
-            }
-            // .stop() was called without an error => set the stage to completed
-            if (nextStage === stage && opts?.isStopping) {
-                this.set(stage, 'completed');
+            // .stop() was called with a finalStatus
+            if (nextStage === stage && opts?.finalStatus) {
+                this.set(stage, opts.finalStatus);
                 this.stopMarker(stage);
                 continue;
             }
@@ -40,12 +50,12 @@ export class StageTracker {
                 }
                 continue;
             }
-            // any stage before the current stage should be marked as skipped if it's still pending
+            // any pending stage before the current stage should be marked using opts.bypassStatus
             if (stages.indexOf(stage) < stages.indexOf(nextStage) && this.map.get(stage) === 'pending') {
-                this.set(stage, 'skipped');
+                this.set(stage, opts?.bypassStatus ?? 'completed');
                 continue;
             }
-            // any stage before the current stage should be as completed (if it hasn't been marked as skipped or failed yet)
+            // any stage before the current stage should be marked as completed (if it hasn't been marked as skipped or failed yet)
             if (stages.indexOf(nextStage) > stages.indexOf(stage)) {
                 this.set(stage, 'completed');
                 this.stopMarker(stage);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/multi-stage-output",
   "description": "Terminal output for oclif commands with multiple stages",
-  "version": "0.3.4",
+  "version": "0.4.1-dev.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/multi-stage-output/issues",
   "dependencies": {
@@ -30,7 +30,7 @@
     "eslint-config-xo-react": "^0.27.0",
     "eslint-plugin-react": "^7.34.3",
     "eslint-plugin-react-hooks": "^4.6.2",
-    "husky": "^9.1.3",
+    "husky": "^9.1.5",
     "ink-testing-library": "^4.0.0",
     "lint-staged": "^15",
     "mocha": "^10.7.3",