eiac/xterm.js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

initial commit

Browse Source
This commit is contained in:
Jörg Breitbart
2024-12-15 18:57:03 +01:00
parent e826f6b69f
commit 6bb2210a91
19 changed files with 698 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
addons/addon-progress/.gitignore
+2
View File
@@ -0,0 +1,2 @@
lib
node_modules
addons/addon-progress/.npmignore
+32
View File
@@ -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
+19
View File
@@ -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
+81
View File
@@ -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, value} => {
// 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
+28
View File
@@ -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
+114
View File
@@ -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
+35
View File
@@ -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"
}
]
}
addons/addon-progress/test/ProgressAddon.test.ts
+129
View File
@@ -0,0 +1,129 @@
/**
* Copyright (c) 2024 The xterm.js authors. All rights reserved.
* @license MIT
*/
import test from '@playwright/test';
import { deepStrictEqual } from 'assert';
import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils';
let ctx: ITestContext;
test.beforeAll(async ({ browser }) => {
ctx = await createTestContext(browser);
ctx.page.setViewportSize({ width: 1024, height: 768 });
await openTerminal(ctx);
});
test.afterAll(async () => await ctx.page.close());
test.describe('ProgressAddon', () => {
test.beforeEach(async function(): Promise<any> {
await ctx.page.evaluate(`
window.progressStack = [];
window.term.reset();
window.progressAddon?.dispose();
window.progressAddon = new ProgressAddon();
window.term.loadAddon(window.progressAddon);
window.progressAddon.register((state, value) => window.progressStack.push({state, value}));
`);
});
test('initial values should be 0;0', async () => {
deepStrictEqual(await ctx.page.evaluate('window.progressAddon.progress'), {state: 0, value: 0});
});
test('state 0: remove', async () => {
// no value
await ctx.proxy.write('\x1b]9;4;0\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 0, value: 0}]);
// value ignored
await ctx.proxy.write('\x1b]9;4;0;12\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 0, value: 0}, {state: 0, value: 0}]);
});
test('state 1: set', async () => {
// set 10%
await ctx.proxy.write('\x1b]9;4;1;10\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 10}]);
// set 50%
await ctx.proxy.write('\x1b]9;4;1;50\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 10}, {state: 1, value: 50}]);
// set 23%
await ctx.proxy.write('\x1b]9;4;1;23\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 10}, {state: 1, value: 50}, {state: 1, value: 23}]);
});
test('state 1: set - special sequence handling', async () => {
// missing progress value defaults to 0
await ctx.proxy.write('\x1b]9;4;1\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 0}]);
// malformed progress value get ignored
await ctx.proxy.write('\x1b]9;4;1;12x\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 0}]);
// out of bounds gets clamped to 100
await ctx.proxy.write('\x1b]9;4;1;123\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 0}, {state: 1, value: 100}]);
});
test('state 2: error - preserve previous value on empty/0', async () => {
// set value to 12
await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
// omitted/empty/0 value emits previous value
await ctx.proxy.write('\x1b]9;4;2\x1b\\');
await ctx.proxy.write('\x1b]9;4;2;\x1b\\');
await ctx.proxy.write('\x1b]9;4;2;0\x1b\\');
deepStrictEqual(
await ctx.page.evaluate('window.progressStack'),
[{state: 1, value: 12}, {state: 2, value: 12}, {state: 2, value: 12}, {state: 2, value: 12}]
);
});
test('state 2: error - with new value', async () => {
// set value to 12
await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
// new value updates clamped
await ctx.proxy.write('\x1b]9;4;2;25\x1b\\');
await ctx.proxy.write('\x1b]9;4;2;123\x1b\\');
deepStrictEqual(
await ctx.page.evaluate('window.progressStack'),
[{state: 1, value: 12}, {state: 2, value: 25}, {state: 2, value: 100}]
);
});
test('state 3: indeterminate - keeps value untouched', async () => {
// set value to 12
await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
// new value updates clamped
await ctx.proxy.write('\x1b]9;4;3\x1b\\');
await ctx.proxy.write('\x1b]9;4;3;123\x1b\\');
deepStrictEqual(
await ctx.page.evaluate('window.progressStack'),
[{state: 1, value: 12}, {state: 3, value: 12}, {state: 3, value: 12}]
);
});
test('state 4: pause - preserve previous value on empty/0', async () => {
// set value to 12
await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
// omitted/empty/0 value emits previous value
await ctx.proxy.write('\x1b]9;4;4\x1b\\');
await ctx.proxy.write('\x1b]9;4;4;\x1b\\');
await ctx.proxy.write('\x1b]9;4;4;0\x1b\\');
deepStrictEqual(
await ctx.page.evaluate('window.progressStack'),
[{state: 1, value: 12}, {state: 4, value: 12}, {state: 4, value: 12}, {state: 4, value: 12}]
);
});
test('state 4: pause - with new value', async () => {
// set value to 12
await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
// new value updates clamped
await ctx.proxy.write('\x1b]9;4;4;25\x1b\\');
await ctx.proxy.write('\x1b]9;4;4;123\x1b\\');
deepStrictEqual(
await ctx.page.evaluate('window.progressStack'),
[{state: 1, value: 12}, {state: 4, value: 25}, {state: 4, value: 100}]
);
});
test('invalid sequences should not emit anything', async () => {
// illegal state
await ctx.proxy.write('\x1b]9;4;5;12\x1b\\');
// illegal chars in value
await ctx.proxy.write('\x1b]9;4;1; 123xxxx\x1b\\');
deepStrictEqual(await ctx.page.evaluate('window.progressStack'), []);
});
});
addons/addon-progress/test/playwright.config.ts
+35
View File
@@ -0,0 +1,35 @@
import { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
testDir: '.',
timeout: 10000,
projects: [
{
name: 'ChromeStable',
use: {
browserName: 'chromium',
channel: 'chrome'
}
},
{
name: 'FirefoxStable',
use: {
browserName: 'firefox'
}
},
{
name: 'WebKit',
use: {
browserName: 'webkit'
}
}
],
reporter: 'list',
webServer: {
command: 'npm run start',
port: 3000,
timeout: 120000,
reuseExistingServer: !process.env.CI
}
};
export default config;
addons/addon-progress/test/tsconfig.json
+41
View File
@@ -0,0 +1,41 @@
{
"compilerOptions": {
"module": "commonjs",
"target": "ESNext",
"lib": [
"es2021",
],
"rootDir": ".",
"outDir": "../out-test",
"sourceMap": true,
"removeComments": true,
"baseUrl": ".",
"paths": {
"common/*": [
"../../../src/common/*"
],
"browser/*": [
"../../../src/browser/*"
]
},
"strict": true,
"types": [
"../../../node_modules/@types/node"
]
},
"include": [
"./**/*",
"../../../typings/xterm.d.ts"
],
"references": [
{
"path": "../../../src/common"
},
{
"path": "../../../src/browser"
},
{
"path": "../../../test/playwright"
}
]
}
addons/addon-progress/tsconfig.json
+8
View File
@@ -0,0 +1,8 @@
{
"files": [],
"include": [],
"references": [
{ "path": "./src" },
{ "path": "./test" }
]
}
addons/addon-progress/typings/addon-progress.d.ts
Vendored
+30
View File
@@ -0,0 +1,30 @@
/**
* Copyright (c) 2024 The xterm.js authors. All rights reserved.
* @license MIT
*/
import { Terminal, ITerminalAddon, IDisposable } from '@xterm/xterm';
declare module '@xterm/addon-progress' {
/** xterm.js addon providing an interface for ConEmu's progress sequence */
export class ProgressAddon implements ITerminalAddon {
constructor();
public activate(terminal: Terminal): void;
public dispose(): void;
/** register progress handler */
public register(handler: ProgressHandler): IDisposable;
/** getter / setter for current progress */
public progress: IProgress;
}
/** progress object interface */
export interface IProgress {
state: 0 | 1 | 2 | 3 | 4;
value: number;
}
/** Progress handler type */
export type ProgressHandler = (state: 0 | 1 | 2 | 3 | 4, value: number) => void;
}
addons/addon-progress/webpack.config.js
+33
View File
@@ -0,0 +1,33 @@
/**
* Copyright (c) 2024 The xterm.js authors. All rights reserved.
* @license MIT
*/
const path = require('path');
const addonName = 'ProgressAddon';
const mainFile = 'addon-progress.js';
module.exports = {
entry: `./out/${addonName}.js`,
devtool: 'source-map',
module: {
rules: [
{
test: /\.js$/,
use: ["source-map-loader"],
enforce: "pre",
exclude: /node_modules/
}
]
},
output: {
filename: mainFile,
path: path.resolve('./lib'),
library: addonName,
libraryTarget: 'umd',
// Force usage of globalThis instead of global / self. (This is cross-env compatible)
globalObject: 'globalThis',
},
mode: 'production'
};