progress-addon

.eslintrc.json

@@ -23,6 +23,8 @@
       "addons/addon-image/src/tsconfig.json",
       "addons/addon-image/test/tsconfig.json",
       "addons/addon-ligatures/src/tsconfig.json",
+      "addons/addon-progress/src/tsconfig.json",
+      "addons/addon-progress/test/tsconfig.json",
       "addons/addon-search/src/tsconfig.json",
       "addons/addon-search/test/tsconfig.json",
       "addons/addon-serialize/src/tsconfig.json",

.github/workflows/ci.yml

@@ -44,6 +44,9 @@ jobs:
           ./addons/addon-ligatures/lib/* \
           ./addons/addon-ligatures/out/* \
           ./addons/addon-ligatures/out-*/* \
+          ./addons/addon-progress/lib/* \
+          ./addons/addon-progress/out/* \
+          ./addons/addon-progress/out-*/* \
           ./addons/addon-search/lib/* \
           ./addons/addon-search/out/* \
           ./addons/addon-search/out-*/* \
@@ -212,6 +215,8 @@ jobs:
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-fit
     - name: Integration tests (addon-image)
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-image
+    - name: Integration tests (addon-progress)
+      run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-progress
     - name: Integration tests (addon-search)
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-search
     - name: Integration tests (addon-serialize)

addons/addon-progress/.gitignore

@@ -0,0 +1,2 @@
+lib
+node_modules

addons/addon-progress/.npmignore

@@ -0,0 +1,32 @@
+# Blacklist - exclude everything except npm defaults such as LICENSE, etc
+*
+!*/
+
+# Whitelist - lib/
+!lib/**/*.d.ts
+
+!lib/**/*.js
+!lib/**/*.js.map
+
+!lib/**/*.mjs
+!lib/**/*.mjs.map
+
+!lib/**/*.css
+
+# Whitelist - src/
+!src/**/*.ts
+!src/**/*.d.ts
+
+!src/**/*.js
+!src/**/*.js.map
+
+!src/**/*.css
+
+# Blacklist - src/ test files
+src/**/*.test.ts
+src/**/*.test.d.ts
+src/**/*.test.js
+src/**/*.test.js.map
+
+# Whitelist - typings/
+!typings/*.d.ts

addons/addon-progress/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

addons/addon-progress/README.md

@@ -0,0 +1,81 @@
+## @xterm/addon-progress
+
+An xterm.js addon providing an interface for ConEmu's progress sequence.
+See https://conemu.github.io/en/AnsiEscapeCodes.html#ConEmu_specific_OSC for sequence details.
+
+
+### Install
+
+```bash
+npm install --save @xterm/addon-progress
+```
+
+
+### Usage
+
+```ts
+import { Terminal } from '@xterm/xterm';
+import { ProgressAddon } from '@xterm/addon-progress';
+
+const terminal = new Terminal();
+const progressAddon = new ProgressAddon();
+terminal.loadAddon(progressAddon);
+progressAddon.register((state: number, value: number) => {
+  // state: 0-4 integer (see below for meaning)
+  // value: 0-100 integer (percent value)
+
+  // do your visualisation based on state/progress here
+  ...
+});
+```
+
+### Sequence
+
+The sequence to set progress information has the following format:
+
+```plain
+ESC ] 9 ; 4 ; <state> ; <progress value> BEL
+```
+
+where state is a decimal number in 0 to 4 and progress value is a decimal number in 0 to 100.
+The states have the following meaning:
+
+- 0: Remove any progress indication. Also resets progress value to 0. A given progress value will be ignored.
+- 1: Normal state to set a progress value. The value should be in 0..100, greater values are clamped to 100.
+  If the value is omitted, it will be set to 0.
+- 2: Error state with an optional progress value. An omitted value will be set to 0,
+  which has a special meaning using the last active value.
+- 3: Actual progress is "indeterminate", any progress value will be ignored. Meant to be used to indicate
+  a running task without progress information (e.g. by a spinner). A previously set progress value
+  by any other state sequence will be left untouched.
+- 4: Pause or warning state with an optional progress value. An omitted value will be set to 0,
+  which has a special meaning using the last active value.
+
+The addon resolves most of those semantic nuances and will provide these ready-to-go values:
+- For the remove state (0) any progress value wont be parsed, thus is even allowed to contain garbage.
+  It will always emit `{state: 0, value: 0}`.
+- For the set state (1) an omitted value will be set to 0 emitting `{state: 1, value: 0}`.
+  If a value was given, it must be decimal digits only, any characters outside will mark the whole sequence
+  as faulty (no sloppy integer parsing). The value will be clamped to max 100 giving
+  `{state: 1, value: parsedAndClampedValue}`.
+- For the error and pause state (2 & 4) an omitted or zero value will emit `{state: 2|4, value: lastValue}`.
+  If a value was given, it must be decimal digits only, any characters outside will mark the whole sequence
+  as faulty (no sloppy integer parsing). The value will be clamped to max 100 giving
+  `{state: 2|4, value: parsedAndClampedValue}`.
+- For the indeterminate state (3) a value notion will be ignored.
+  It still emits the value as `{state: 3, value: lastValue}`. Keep in mind not use that value while
+  that state is active, as a task might have entered that state without a proper reset at the beginning.
+
+### API
+
+The addon exposes the following API endpoints:
+- `public register(handler: ProgressHandler): IDisposable;` \
+  Registers your actual progress handler, where you gonna do the visual progress visualisation.
+  The handler will get called upon valid progress sequences with 2 arguments as `(state, value) => {}`.
+  Returns a disposable to unregister the handler later on by calling its `dispose()` method.
+- `public progress: IProgress;`
+  A getter/setter for the current progress information. Can be used to read the last seen progress information.
+  This can also be used to clean up stuck progress indicators by setting the value back to initial, e.g.: 
+  ```typescript
+  progressAddon.progress = {state: 0, value: 0};
+  ```

addons/addon-progress/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@xterm/addon-progress",
+  "version": "0.1.0",
+  "author": {
+    "name": "The xterm.js authors",
+    "url": "https://xtermjs.org/"
+  },
+  "main": "lib/addon-progress.js",
+  "module": "lib/addon-progress.mjs",
+  "types": "typings/addon-progress.d.ts",
+  "repository": "https://github.com/xtermjs/xterm.js/tree/master/addons/addon-progress",
+  "license": "MIT",
+  "keywords": [
+    "terminal",
+    "xterm",
+    "xterm.js"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p .",
+    "prepackage": "npm run build",
+    "package": "../../node_modules/.bin/webpack",
+    "prepublishOnly": "npm run package",
+    "start": "node ../../demo/start"
+  },
+  "peerDependencies": {
+    "@xterm/xterm": "^5.0.0"
+  }
+}

addons/addon-progress/src/ProgressAddon.ts

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import type { Terminal, ITerminalAddon, IDisposable } from '@xterm/xterm';
+import type { ProgressAddon as IProgressApi, IProgress, ProgressHandler } from '@xterm/addon-progress';
+
+
+const enum ProgressState {
+  REMOVE = 0,
+  SET = 1,
+  ERROR = 2,
+  INDETERMINATE = 3,
+  PAUSE = 4
+}
+
+
+/**
+ * Strict integer parsing, only decimal digits allowed.
+ */
+function toInt(s: string): number {
+  let v = 0;
+  for (let i = 0; i < s.length; ++i) {
+    const c = s.charCodeAt(i);
+    if (c < 0x30 || 0x39 < c) {
+      return -1;
+    }
+    v = v * 10 + c - 48;
+  }
+  return v;
+}
+
+
+export class ProgressAddon implements ITerminalAddon, IProgressApi {
+  private _seqHandler: IDisposable | undefined;
+  private _st: ProgressState = ProgressState.REMOVE;
+  private _pr = 0;
+  private _handlers: ProgressHandler[] = [];
+
+  public dispose(): void {
+    this._seqHandler?.dispose();
+    this._handlers.length = 0;
+  }
+
+  public activate(terminal: Terminal): void {
+    this._seqHandler = terminal.parser.registerOscHandler(9, data => {
+      if (!data.startsWith('4;')) {
+        return false;
+      }
+      const parts = data.split(';');
+
+      if (parts.length > 3) {
+        return true;  // faulty sequence, just exit
+      }
+      if (parts.length === 2) {
+        parts.push('');
+      }
+      const st = toInt(parts[1]);
+      const pr = toInt(parts[2]);
+
+      switch (st) {
+        case ProgressState.REMOVE:
+          this.progress = { state: st, value: 0 };
+          break;
+        case ProgressState.SET:
+          if (pr < 0) return true;  // faulty sequence, just exit
+          this.progress = { state: st, value: pr };
+          break;
+        case ProgressState.ERROR:
+        case ProgressState.PAUSE:
+          if (pr < 0) return true;  // faulty sequence, just exit
+          this.progress = { state: st, value: pr || this._pr };
+          break;
+        case ProgressState.INDETERMINATE:
+          this.progress = { state: st, value: this._pr };
+          break;
+      }
+      return true;
+    });
+  }
+
+  public register(handler: ProgressHandler): IDisposable {
+    const handlers = this._handlers;
+    handlers.push(handler);
+    return {
+      dispose: () => {
+        const idx = handlers.indexOf(handler);
+        if (idx !== -1) {
+          handlers.splice(idx, 1);
+        }
+      }
+    };
+  }
+
+  public get progress(): IProgress {
+    return { state: this._st, value: this._pr };
+  }
+
+  public set progress(progress: IProgress) {
+    if (0 <= progress.state && progress.state <= 4)
+    {
+      this._st = progress.state;
+      this._pr = Math.min(Math.max(progress.value, 0), 100);
+
+      // call progress handlers
+      for (let i = 0; i < this._handlers.length; ++i) {
+        this._handlers[i](this._st, this._pr);
+      }
+    } else {
+      console.warn(`progress state out of bounds, not applied`);
+    }
+  }
+}

addons/addon-progress/src/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2021",
+    "lib": [
+      "dom",
+      "es2015"
+    ],
+    "rootDir": ".",
+    "outDir": "../out",
+    "sourceMap": true,
+    "removeComments": true,
+    "strict": true,
+    "types": [
+      "../../../node_modules/@types/mocha"
+    ],
+    "paths": {
+      "browser/*": [
+        "../../../src/browser/*"
+      ],
+      "@xterm/addon-progress": [
+        "../typings/addon-progress.d.ts"
+      ]
+    }
+  },
+  "include": [
+    "./**/*",
+    "../../../typings/xterm.d.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../src/browser"
+    }
+  ]
+}