From dc9084b5ada02bc20015ca2f083336876e6c31f7 Mon Sep 17 00:00:00 2001
From: Daniel Imms <2193314+Tyriar@users.noreply.github.com>
Date: Thu, 9 Jan 2025 05:32:36 -0800
Subject: [PATCH] Progress polish

Fixes #5287
Fixes #5288
Fixes #5289
---
 addons/addon-progress/src/ProgressAddon.ts    |  5 +--
 .../typings/addon-progress.d.ts               | 36 +++++++++++++------
 2 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/addons/addon-progress/src/ProgressAddon.ts b/addons/addon-progress/src/ProgressAddon.ts
index 24e57860..175d7af0 100644
--- a/addons/addon-progress/src/ProgressAddon.ts
+++ b/addons/addon-progress/src/ProgressAddon.ts
@@ -37,8 +37,9 @@ export class ProgressAddon implements ITerminalAddon, IProgressApi {
   private _seqHandler: IDisposable | undefined;
   private _st: ProgressType = ProgressType.REMOVE;
   private _pr = 0;
-  private _onChange: Emitter<IProgressState> | undefined;
-  public onChange: Event<IProgressState> | undefined;
+  // HACK: This uses ! to align with the API, this should be fixed when 5283 is resolved
+  private _onChange!: Emitter<IProgressState>;
+  public onChange!: Event<IProgressState>;
 
   public dispose(): void {
     this._seqHandler?.dispose();
diff --git a/addons/addon-progress/typings/addon-progress.d.ts b/addons/addon-progress/typings/addon-progress.d.ts
index 923a2aa3..bcc383a2 100644
--- a/addons/addon-progress/typings/addon-progress.d.ts
+++ b/addons/addon-progress/typings/addon-progress.d.ts
@@ -3,9 +3,7 @@
  * @license MIT
  */
 
-import { Terminal, ITerminalAddon, IDisposable } from '@xterm/xterm';
-import type { Event } from 'vs/base/common/event';
-
+import { Terminal, ITerminalAddon, IDisposable, IEvent } from '@xterm/xterm';
 
 declare module '@xterm/addon-progress' {
   /**
@@ -13,7 +11,7 @@ declare module '@xterm/addon-progress' {
    * sequence.
    */
   export class ProgressAddon implements ITerminalAddon, IDisposable {
-    
+
     /**
      * Creates a new progress addon
      */
@@ -24,7 +22,7 @@ declare module '@xterm/addon-progress' {
      * @param terminal The terminal the addon is being loaded in.
      */
     public activate(terminal: Terminal): void;
-    
+
     /**
      * Disposes the addon.
      */
@@ -33,22 +31,38 @@ declare module '@xterm/addon-progress' {
     /**
      * An event that fires when the tracked progress changes.
      */
-    public readonly onChange: Event<IProgressState> | undefined;
+    public readonly onChange: IEvent<IProgressState> | undefined;
 
     /**
-     * Gets or sets the current progress tracked by the addon.
-     * This can also be used to reset a stuck progress indicator
-     * back to initial with `{state: 0, value: 0}`
-     * or to restore an indicator.
+     * Gets or sets the current progress tracked by the addon. This can be used
+     * to reset a stuck progress indicator back to initial with
+     * `{ state: 0, value: 0 }` or to restore an indicator.
      */
     public progress: IProgressState;
   }
-  
+
   /**
    * Progress state tracked by the addon.
    */
   export interface IProgressState {
+    /**
+     * The progress state.
+     *
+     * - `0`: No progress. Setting this will resets progress value to 0
+     *   regardless of the {@link value} used.
+     * - `1`: Normal percentage-based from 0 to 100.
+     * - `2`: Error with an optional progress value from 0 to 100.
+     * - `3`: Indeterminate progress, any progress value will be ignored. This
+     *   is used to indicate work is happening but a percentage value cannot be
+     *   determined.
+     * - `4`: Pause or warning state with an optional progress value.
+     */
     state: 0 | 1 | 2 | 3 | 4;
+
+    /**
+     * The percentage value of progress from 0 to 100. See {@link state} for
+     * whether this is relevant.
+     */
     value: number;
   }
 }