diff --git a/.eslintrc.json b/.eslintrc.json index 6031c195ef..427c7a16d6 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -9,6 +9,7 @@ "project": [ "src/browser/tsconfig.json", "src/common/tsconfig.json", + "src/headless/tsconfig.json", "test/api/tsconfig.json", "test/benchmark/tsconfig.json", "addons/xterm-addon-attach/src/tsconfig.json", diff --git a/azure-pipelines.yml b/azure-pipelines.yml index f4220176e3..c87496b2bc 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -164,5 +164,7 @@ jobs: displayName: Cache node modules - script: yarn --frozen-lockfile displayName: 'Install dependencies and build' + - script: node ./bin/package_headless.js + displayName: 'Package xterm-headless' - script: NPM_AUTH_TOKEN="$(NPM_AUTH_TOKEN)" node ./bin/publish.js displayName: 'Package and publish to npm' diff --git a/bin/package_headless.js b/bin/package_headless.js new file mode 100644 index 0000000000..d002a95ecd --- /dev/null +++ b/bin/package_headless.js @@ -0,0 +1,57 @@ +/** + * Copyright (c) 2021 The xterm.js authors. All rights reserved. + * @license MIT + */ + +const { exec } = require('child_process'); +const fs = require('fs'); +const { join } = require('path'); + +const repoRoot = join(__dirname, '..'); +const headlessRoot = join(repoRoot, 'headless'); + +console.log('> headless/package.json'); +const xtermPackageJson = require('../package.json'); +const xtermHeadlessPackageJson = { + ...xtermPackageJson, + name: 'xterm-headless', + description: 'A headless terminal component that runs in Node.js', + main: 'lib-headless/xterm-headless.js', + types: 'typings/xterm-headless.d.ts', +}; +delete xtermHeadlessPackageJson['scripts']; +delete xtermHeadlessPackageJson['devDependencies']; +delete xtermHeadlessPackageJson['style']; +fs.writeFileSync(join(headlessRoot, 'package.json'), JSON.stringify(xtermHeadlessPackageJson, null, 1)); +console.log(fs.readFileSync(join(headlessRoot, 'package.json')).toString()); + +console.log('> headless/typings/'); +mkdirF(join(headlessRoot, 'typings')); +fs.copyFileSync( + join(repoRoot, 'typings/xterm-headless.d.ts'), + join(headlessRoot, 'typings/xterm-headless.d.ts') +); + +console.log('> headless/logo-full.png'); +fs.copyFileSync( + join(repoRoot, 'logo-full.png'), + join(headlessRoot, 'logo-full.png') +); + +function mkdirF(p) { + if (!fs.existsSync(p)) { + fs.mkdirSync(p); + } +} + +console.log('> Publish dry run'); +exec('npm publish --dry-run', { cwd: headlessRoot }, (error, stdout, stderr) => { + if (error) { + console.log(`error: ${error.message}`); + return; + } + if (stderr) { + console.error(`stderr:\n${stderr}`); + } + console.log(`stdout:\n${stdout}`); +}); diff --git a/bin/publish.js b/bin/publish.js index 64336fdc7c..3c729f6c1b 100644 --- a/bin/publish.js +++ b/bin/publish.js @@ -22,6 +22,7 @@ const changedFiles = getChangedFilesInCommit('HEAD'); let isStableRelease = false; if (changedFiles.some(e => e.search(/^addons\//) === -1)) { isStableRelease = checkAndPublishPackage(path.resolve(__dirname, '..')); + checkAndPublishPackage(path.resolve(__dirname, '../headless')); } // Publish addons if any files were changed inside of the addon diff --git a/headless/.gitignore b/headless/.gitignore new file mode 100644 index 0000000000..f1cf6c8d83 --- /dev/null +++ b/headless/.gitignore @@ -0,0 +1,4 @@ +lib-headless/ +typings/ +logo-full.png +./package.json diff --git a/headless/.npmignore b/headless/.npmignore new file mode 100644 index 0000000000..c6b33260f7 --- /dev/null +++ b/headless/.npmignore @@ -0,0 +1,5 @@ +# Include +!typings/*.d.ts + +# Exclude +test/ diff --git a/headless/README.md b/headless/README.md new file mode 100644 index 0000000000..1d2d61568c --- /dev/null +++ b/headless/README.md @@ -0,0 +1,31 @@ +# [![xterm.js logo](logo-full.png)](https://xtermjs.org) + +⚠ This package is experimental + +`xterm-headless` is a headless terminal that can be run in node.js. This is useful in combination with the frontend [`xterm`](https://www.npmjs.com/package/xterm) for example to keep track of a terminal's state on a remote server where the process is hosted. + +## Getting Started + +First, you need to install the module, we ship exclusively through npm, so you need that installed and then add xterm.js as a dependency by running: + +```sh +npm install xterm-headless +``` + +Then import as you would a regular node package. The recommended way to load `xterm-headless` is with TypeScript and the ES6 module syntax: + +```javascript +import { Terminal } from 'xterm-headless'; +``` + +## API + +The full API for `xterm-headless` is contained within the [TypeScript declaration file](https://github.com/xtermjs/xterm.js/blob/master/typings/xterm-headless.d.ts), use the branch/tag picker in GitHub (`w`) to navigate to the correct version of the API. + +Note that some APIs are marked *experimental*, these are added to enable experimentation with new ideas without committing to support it like a normal [semver](https://semver.org/) API. Note that these APIs can change radically between versions, so be sure to read release notes if you plan on using experimental APIs. + +### Addons + +Addons in `xterm-headless` work the [same as in `xterm`](https://github.com/xtermjs/xterm.js/blob/master/README.md#addons) with the one caveat being that the addon needs to be packaged for node.js and not use any DOM APIs. + +Currently no official addons are packaged on npm. diff --git a/headless/package.json b/headless/package.json new file mode 100644 index 0000000000..d53761e7a7 --- /dev/null +++ b/headless/package.json @@ -0,0 +1,9 @@ +{ + "name": "xterm-headless", + "description": "A headless terminal component that runs in Node.js", + "version": "4.13.0-alpha3", + "main": "lib-headless/xterm-headless.js", + "types": "typings/xterm-headless.d.ts", + "repository": "https://github.com/xtermjs/xterm.js", + "license": "MIT" +} \ No newline at end of file diff --git a/package.json b/package.json index bab93bf4d3..71a0f3080a 100644 --- a/package.json +++ b/package.json @@ -10,6 +10,8 @@ "scripts": { "prepackage": "npm run build", "package": "webpack", + "package-headless": "webpack --config ./webpack.config.headless.js", + "postpackage-headless": "node ./bin/package_headless.js", "start": "node demo/start", "start-debug": "node --inspect-brk demo/start", "lint": "eslint -c .eslintrc.json --max-warnings 0 --ext .ts src/ addons/", diff --git a/src/browser/Terminal.ts b/src/browser/Terminal.ts index 5aed701ad4..004f231479 100644 --- a/src/browser/Terminal.ts +++ b/src/browser/Terminal.ts @@ -113,8 +113,8 @@ export class Terminal extends CoreTerminal implements ITerminal { public get onSelectionChange(): IEvent { return this._onSelectionChange.event; } private _onTitleChange = new EventEmitter(); public get onTitleChange(): IEvent { return this._onTitleChange.event; } - private _onBell = new EventEmitter(); - public get onBell (): IEvent { return this._onBell.event; } + private _onBell = new EventEmitter(); + public get onBell(): IEvent { return this._onBell.event; } private _onFocus = new EventEmitter(); public get onFocus(): IEvent { return this._onFocus.event; } diff --git a/src/browser/public/Terminal.ts b/src/browser/public/Terminal.ts index adfee5448a..6af9db71e9 100644 --- a/src/browser/public/Terminal.ts +++ b/src/browser/public/Terminal.ts @@ -5,12 +5,12 @@ import { Terminal as ITerminalApi, ITerminalOptions, IMarker, IDisposable, ILinkMatcherOptions, ITheme, ILocalizableStrings, ITerminalAddon, ISelectionPosition, IBufferNamespace as IBufferNamespaceApi, IParser, ILinkProvider, IUnicodeHandling, FontWeight } from 'xterm'; import { ITerminal } from 'browser/Types'; -import { Terminal as TerminalCore } from '../Terminal'; -import * as Strings from '../LocalizableStrings'; +import { Terminal as TerminalCore } from 'browser/Terminal'; +import * as Strings from 'browser/LocalizableStrings'; import { IEvent } from 'common/EventEmitter'; import { ParserApi } from 'common/public/ParserApi'; import { UnicodeApi } from 'common/public/UnicodeApi'; -import { AddonManager } from './AddonManager'; +import { AddonManager } from 'common/public/AddonManager'; import { BufferNamespaceApi } from 'common/public/BufferNamespaceApi'; export class Terminal implements ITerminalApi { @@ -30,17 +30,17 @@ export class Terminal implements ITerminalApi { } } + public get onBell(): IEvent { return this._core.onBell; } + public get onBinary(): IEvent { return this._core.onBinary; } public get onCursorMove(): IEvent { return this._core.onCursorMove; } - public get onLineFeed(): IEvent { return this._core.onLineFeed; } - public get onSelectionChange(): IEvent { return this._core.onSelectionChange; } public get onData(): IEvent { return this._core.onData; } - public get onBinary(): IEvent { return this._core.onBinary; } - public get onTitleChange(): IEvent { return this._core.onTitleChange; } - public get onBell(): IEvent { return this._core.onBell; } - public get onScroll(): IEvent { return this._core.onScroll; } public get onKey(): IEvent<{ key: string, domEvent: KeyboardEvent }> { return this._core.onKey; } + public get onLineFeed(): IEvent { return this._core.onLineFeed; } public get onRender(): IEvent<{ start: number, end: number }> { return this._core.onRender; } public get onResize(): IEvent<{ cols: number, rows: number }> { return this._core.onResize; } + public get onScroll(): IEvent { return this._core.onScroll; } + public get onSelectionChange(): IEvent { return this._core.onSelectionChange; } + public get onTitleChange(): IEvent { return this._core.onTitleChange; } public get element(): HTMLElement | undefined { return this._core.element; } public get parser(): IParser { diff --git a/src/browser/public/AddonManager.test.ts b/src/common/public/AddonManager.test.ts similarity index 100% rename from src/browser/public/AddonManager.test.ts rename to src/common/public/AddonManager.test.ts diff --git a/src/browser/public/AddonManager.ts b/src/common/public/AddonManager.ts similarity index 100% rename from src/browser/public/AddonManager.ts rename to src/common/public/AddonManager.ts diff --git a/src/headless/Terminal.ts b/src/headless/Terminal.ts new file mode 100644 index 0000000000..7f138ce1d8 --- /dev/null +++ b/src/headless/Terminal.ts @@ -0,0 +1,170 @@ +/** + * Copyright (c) 2014 The xterm.js authors. All rights reserved. + * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License) + * @license MIT + * + * Originally forked from (with the author's permission): + * Fabrice Bellard's javascript vt100 for jslinux: + * http://bellard.org/jslinux/ + * Copyright (c) 2011 Fabrice Bellard + * The original design remains. The terminal itself + * has been extended to include xterm CSI codes, among + * other features. + * + * Terminal Emulation References: + * http://vt100.net/ + * http://invisible-island.net/xterm/ctlseqs/ctlseqs.txt + * http://invisible-island.net/xterm/ctlseqs/ctlseqs.html + * http://invisible-island.net/vttest/ + * http://www.inwap.com/pdp10/ansicode.txt + * http://linux.die.net/man/4/console_codes + * http://linux.die.net/man/7/urxvt + */ + +import { DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine'; +import { IBuffer } from 'common/buffer/Types'; +import { CoreTerminal } from 'common/CoreTerminal'; +import { EventEmitter, forwardEvent, IEvent } from 'common/EventEmitter'; +import { ITerminalOptions as IInitializedTerminalOptions } from 'common/services/Services'; +import { IMarker, ITerminalOptions, ScrollSource } from 'common/Types'; + +export class Terminal extends CoreTerminal { + // TODO: We should remove options once components adopt optionsService + public get options(): IInitializedTerminalOptions { return this.optionsService.options; } + + private _onBell = new EventEmitter(); + public get onBell(): IEvent { return this._onBell.event; } + private _onCursorMove = new EventEmitter(); + public get onCursorMove(): IEvent { return this._onCursorMove.event; } + private _onTitleChange = new EventEmitter(); + public get onTitleChange(): IEvent { return this._onTitleChange.event; } + + private _onA11yCharEmitter = new EventEmitter(); + public get onA11yChar(): IEvent { return this._onA11yCharEmitter.event; } + private _onA11yTabEmitter = new EventEmitter(); + public get onA11yTab(): IEvent { return this._onA11yTabEmitter.event; } + + /** + * Creates a new `Terminal` object. + * + * @param options An object containing a set of options, the available options are: + * - `cursorBlink` (boolean): Whether the terminal cursor blinks + * - `cols` (number): The number of columns of the terminal (horizontal size) + * - `rows` (number): The number of rows of the terminal (vertical size) + * + * @public + * @class Xterm Xterm + * @alias module:xterm/src/xterm + */ + constructor( + options: ITerminalOptions = {} + ) { + super(options); + + this._setup(); + + // Setup InputHandler listeners + this.register(this._inputHandler.onRequestBell(() => this.bell())); + this.register(this._inputHandler.onRequestReset(() => this.reset())); + this.register(forwardEvent(this._inputHandler.onCursorMove, this._onCursorMove)); + this.register(forwardEvent(this._inputHandler.onTitleChange, this._onTitleChange)); + this.register(forwardEvent(this._inputHandler.onA11yChar, this._onA11yCharEmitter)); + this.register(forwardEvent(this._inputHandler.onA11yTab, this._onA11yTabEmitter)); + } + + public dispose(): void { + if (this._isDisposed) { + return; + } + super.dispose(); + this.write = () => { }; + } + + /** + * Convenience property to active buffer. + */ + public get buffer(): IBuffer { + return this.buffers.active; + } + + protected _updateOptions(key: string): void { + super._updateOptions(key); + + // TODO: These listeners should be owned by individual components + switch (key) { + case 'tabStopWidth': this.buffers.setupTabStops(); break; + } + } + + // TODO: Support paste here? + + public get markers(): IMarker[] { + return this.buffer.markers; + } + + public addMarker(cursorYOffset: number): IMarker | undefined { + // Disallow markers on the alt buffer + if (this.buffer !== this.buffers.normal) { + return; + } + + return this.buffer.addMarker(this.buffer.ybase + this.buffer.y + cursorYOffset); + } + + public bell(): void { + this._onBell.fire(); + } + + /** + * Resizes the terminal. + * + * @param x The number of columns to resize to. + * @param y The number of rows to resize to. + */ + public resize(x: number, y: number): void { + if (x === this.cols && y === this.rows) { + return; + } + + super.resize(x, y); + } + + /** + * Clear the entire buffer, making the prompt line the new first line. + */ + public clear(): void { + if (this.buffer.ybase === 0 && this.buffer.y === 0) { + // Don't clear if it's already clear + return; + } + this.buffer.lines.set(0, this.buffer.lines.get(this.buffer.ybase + this.buffer.y)!); + this.buffer.lines.length = 1; + this.buffer.ydisp = 0; + this.buffer.ybase = 0; + this.buffer.y = 0; + for (let i = 1; i < this.rows; i++) { + this.buffer.lines.push(this.buffer.getBlankLine(DEFAULT_ATTR_DATA)); + } + this._onScroll.fire({ position: this.buffer.ydisp, source: ScrollSource.TERMINAL }); + } + + /** + * Reset terminal. + * Note: Calling this directly from JS is synchronous but does not clear + * input buffers and does not reset the parser, thus the terminal will + * continue to apply pending input data. + * If you need in band reset (synchronous with input data) consider + * using DECSTR (soft reset, CSI ! p) or RIS instead (hard reset, ESC c). + */ + public reset(): void { + /** + * Since _setup handles a full terminal creation, we have to carry forward + * a few things that should not reset. + */ + this.options.rows = this.rows; + this.options.cols = this.cols; + + this._setup(); + super.reset(); + } +} diff --git a/src/headless/Types.d.ts b/src/headless/Types.d.ts new file mode 100644 index 0000000000..868e5c1783 --- /dev/null +++ b/src/headless/Types.d.ts @@ -0,0 +1,31 @@ +import { IBuffer, IBufferSet } from 'common/buffer/Types'; +import { IEvent } from 'common/EventEmitter'; +import { IFunctionIdentifier, IParams } from 'common/parser/Types'; +import { ICoreTerminal, IDisposable, IMarker, ITerminalOptions } from 'common/Types'; + +export interface ITerminal extends ICoreTerminal { + rows: number; + cols: number; + buffer: IBuffer; + buffers: IBufferSet; + markers: IMarker[]; + // TODO: We should remove options once components adopt optionsService + options: ITerminalOptions; + + onCursorMove: IEvent; + onData: IEvent; + onBinary: IEvent; + onLineFeed: IEvent; + onResize: IEvent<{ cols: number, rows: number }>; + onTitleChange: IEvent; + resize(columns: number, rows: number): void; + addCsiHandler(id: IFunctionIdentifier, callback: (params: IParams) => boolean): IDisposable; + addDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: IParams) => boolean): IDisposable; + addEscHandler(id: IFunctionIdentifier, callback: () => boolean): IDisposable; + addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable; + addMarker(cursorYOffset: number): IMarker | undefined; + dispose(): void; + clear(): void; + write(data: string | Uint8Array, callback?: () => void): void; + reset(): void; +} diff --git a/src/headless/public/Terminal.test.ts b/src/headless/public/Terminal.test.ts new file mode 100644 index 0000000000..15e1efbac5 --- /dev/null +++ b/src/headless/public/Terminal.test.ts @@ -0,0 +1,386 @@ +/** + * Copyright (c) 2019 The xterm.js authors. All rights reserved. + * @license MIT + */ + +import { deepStrictEqual, strictEqual, throws } from 'assert'; +import { Terminal } from 'headless/public/Terminal'; + +let term: Terminal; + +describe('Headless API Tests', function(): void { + beforeEach(() => { + // Create default terminal to be used by most tests + term = new Terminal(); + }); + + it('Default options', async () => { + strictEqual(term.cols, 80); + strictEqual(term.rows, 24); + }); + + it('Proposed API check', async () => { + term = new Terminal({ allowProposedApi: false }); + throws(() => term.buffer, (error) => error.message === 'You must set the allowProposedApi option to true to use proposed API'); + }); + + it('write', async () => { + await writeSync('foo'); + await writeSync('bar'); + await writeSync('文'); + lineEquals(0, 'foobar文'); + }); + + it('write with callback', async () => { + let result: string | undefined; + await new Promise(r => { + term.write('foo', () => { result = 'a'; }); + term.write('bar', () => { result += 'b'; }); + term.write('文', () => { + result += 'c'; + r(); + }); + }); + lineEquals(0, 'foobar文'); + strictEqual(result, 'abc'); + }); + + it('write - bytes (UTF8)', async () => { + await writeSync(new Uint8Array([102, 111, 111])); // foo + await writeSync(new Uint8Array([98, 97, 114])); // bar + await writeSync(new Uint8Array([230, 150, 135])); // 文 + lineEquals(0, 'foobar文'); + }); + + it('write - bytes (UTF8) with callback', async () => { + let result: string | undefined; + await new Promise(r => { + term.write(new Uint8Array([102, 111, 111]), () => { result = 'A'; }); // foo + term.write(new Uint8Array([98, 97, 114]), () => { result += 'B'; }); // bar + term.write(new Uint8Array([230, 150, 135]), () => { // 文 + result += 'C'; + r(); + }); + }); + lineEquals(0, 'foobar文'); + strictEqual(result, 'ABC'); + }); + + it('writeln', async () => { + await writelnSync('foo'); + await writelnSync('bar'); + await writelnSync('文'); + lineEquals(0, 'foo'); + lineEquals(1, 'bar'); + lineEquals(2, '文'); + }); + + it('writeln with callback', async () => { + let result: string | undefined; + await new Promise(r => { + term.writeln('foo', () => { result = '1'; }); + term.writeln('bar', () => { result += '2'; }); + term.writeln('文', () => { + result += '3'; + r(); + }); + }); + lineEquals(0, 'foo'); + lineEquals(1, 'bar'); + lineEquals(2, '文'); + strictEqual(result, '123'); + }); + + it('writeln - bytes (UTF8)', async () => { + await writelnSync(new Uint8Array([102, 111, 111])); + await writelnSync(new Uint8Array([98, 97, 114])); + await writelnSync(new Uint8Array([230, 150, 135])); + lineEquals(0, 'foo'); + lineEquals(1, 'bar'); + lineEquals(2, '文'); + }); + + it('clear', async () => { + term = new Terminal({ rows: 5 }); + for (let i = 0; i < 10; i++) { + await writeSync('\n\rtest' + i); + } + term.clear(); + strictEqual(term.buffer.active.length, 5); + lineEquals(0, 'test9'); + for (let i = 1; i < 5; i++) { + lineEquals(i, ''); + } + }); + + it('getOption, setOption', async () => { + strictEqual(term.getOption('scrollback'), 1000); + term.setOption('scrollback', 50); + strictEqual(term.getOption('scrollback'), 50); + }); + + describe('loadAddon', () => { + it('constructor', async () => { + term = new Terminal({ cols: 5 }); + let cols = 0; + term.loadAddon({ + activate: (t) => cols = t.cols, + dispose: () => {} + }); + strictEqual(cols, 5); + }); + + it('dispose (addon)', async () => { + let disposeCalled = false; + const addon = { + activate: () => {}, + dispose: () => disposeCalled = true + }; + term.loadAddon(addon); + strictEqual(disposeCalled, false); + addon.dispose(); + strictEqual(disposeCalled, true); + }); + + it('dispose (terminal)', async () => { + let disposeCalled = false; + term.loadAddon({ + activate: () => {}, + dispose: () => disposeCalled = true + }); + strictEqual(disposeCalled, false); + term.dispose(); + strictEqual(disposeCalled, true); + }); + }); + + describe('Events', () => { + it('onCursorMove', async () => { + let callCount = 0; + term.onCursorMove(e => callCount++); + await writeSync('foo'); + strictEqual(callCount, 1); + await writeSync('bar'); + strictEqual(callCount, 2); + }); + + it('onData', async () => { + const calls: string[] = []; + term.onData(e => calls.push(e)); + await writeSync('\x1b[5n'); // DSR Status Report + deepStrictEqual(calls, ['\x1b[0n']); + }); + + it('onLineFeed', async () => { + let callCount = 0; + term.onLineFeed(() => callCount++); + await writelnSync('foo'); + strictEqual(callCount, 1); + await writelnSync('bar'); + strictEqual(callCount, 2); + }); + + it('onScroll', async () => { + term = new Terminal({ rows: 5 }); + const calls: number[] = []; + term.onScroll(e => calls.push(e)); + for (let i = 0; i < 4; i++) { + await writelnSync('foo'); + } + deepStrictEqual(calls, []); + await writelnSync('bar'); + deepStrictEqual(calls, [1]); + await writelnSync('baz'); + deepStrictEqual(calls, [1, 2]); + }); + + it('onResize', async () => { + const calls: [number, number][] = []; + term.onResize(e => calls.push([e.cols, e.rows])); + deepStrictEqual(calls, []); + term.resize(10, 5); + deepStrictEqual(calls, [[10, 5]]); + term.resize(20, 15); + deepStrictEqual(calls, [[10, 5], [20, 15]]); + }); + + it('onTitleChange', async () => { + const calls: string[] = []; + term.onTitleChange(e => calls.push(e)); + deepStrictEqual(calls, []); + await writeSync('\x1b]2;foo\x9c'); + deepStrictEqual(calls, ['foo']); + }); + + it('onBell', async () => { + const calls: boolean[] = []; + term.onBell(() => calls.push(true)); + deepStrictEqual(calls, []); + await writeSync('\x07'); + deepStrictEqual(calls, [true]); + }); + }); + + describe('buffer', () => { + it('cursorX, cursorY', async () => { + term = new Terminal({ rows: 5, cols: 5 }); + strictEqual(term.buffer.active.cursorX, 0); + strictEqual(term.buffer.active.cursorY, 0); + await writeSync('foo'); + strictEqual(term.buffer.active.cursorX, 3); + strictEqual(term.buffer.active.cursorY, 0); + await writeSync('\n'); + strictEqual(term.buffer.active.cursorX, 3); + strictEqual(term.buffer.active.cursorY, 1); + await writeSync('\r'); + strictEqual(term.buffer.active.cursorX, 0); + strictEqual(term.buffer.active.cursorY, 1); + await writeSync('abcde'); + strictEqual(term.buffer.active.cursorX, 5); + strictEqual(term.buffer.active.cursorY, 1); + await writeSync('\n\r\n\n\n\n\n'); + strictEqual(term.buffer.active.cursorX, 0); + strictEqual(term.buffer.active.cursorY, 4); + }); + + it('viewportY', async () => { + term = new Terminal({ rows: 5 }); + strictEqual(term.buffer.active.viewportY, 0); + await writeSync('\n\n\n\n'); + strictEqual(term.buffer.active.viewportY, 0); + await writeSync('\n'); + strictEqual(term.buffer.active.viewportY, 1); + await writeSync('\n\n\n\n'); + strictEqual(term.buffer.active.viewportY, 5); + term.scrollLines(-1); + strictEqual(term.buffer.active.viewportY, 4); + term.scrollToTop(); + strictEqual(term.buffer.active.viewportY, 0); + }); + + it('baseY', async () => { + term = new Terminal({ rows: 5 }); + strictEqual(term.buffer.active.baseY, 0); + await writeSync('\n\n\n\n'); + strictEqual(term.buffer.active.baseY, 0); + await writeSync('\n'); + strictEqual(term.buffer.active.baseY, 1); + await writeSync('\n\n\n\n'); + strictEqual(term.buffer.active.baseY, 5); + term.scrollLines(-1); + strictEqual(term.buffer.active.baseY, 5); + term.scrollToTop(); + strictEqual(term.buffer.active.baseY, 5); + }); + + it('length', async () => { + term = new Terminal({ rows: 5 }); + strictEqual(term.buffer.active.length, 5); + await writeSync('\n\n\n\n'); + strictEqual(term.buffer.active.length, 5); + await writeSync('\n'); + strictEqual(term.buffer.active.length, 6); + await writeSync('\n\n\n\n'); + strictEqual(term.buffer.active.length, 10); + }); + + describe('getLine', () => { + it('invalid index', async () => { + term = new Terminal({ rows: 5 }); + strictEqual(term.buffer.active.getLine(-1), undefined); + strictEqual(term.buffer.active.getLine(5), undefined); + }); + + it('isWrapped', async () => { + term = new Terminal({ cols: 5 }); + strictEqual(term.buffer.active.getLine(0)!.isWrapped, false); + strictEqual(term.buffer.active.getLine(1)!.isWrapped, false); + await writeSync('abcde'); + strictEqual(term.buffer.active.getLine(0)!.isWrapped, false); + strictEqual(term.buffer.active.getLine(1)!.isWrapped, false); + await writeSync('f'); + strictEqual(term.buffer.active.getLine(0)!.isWrapped, false); + strictEqual(term.buffer.active.getLine(1)!.isWrapped, true); + }); + + it('translateToString', async () => { + term = new Terminal({ cols: 5 }); + strictEqual(term.buffer.active.getLine(0)!.translateToString(), ' '); + strictEqual(term.buffer.active.getLine(0)!.translateToString(true), ''); + await writeSync('foo'); + strictEqual(term.buffer.active.getLine(0)!.translateToString(), 'foo '); + strictEqual(term.buffer.active.getLine(0)!.translateToString(true), 'foo'); + await writeSync('bar'); + strictEqual(term.buffer.active.getLine(0)!.translateToString(), 'fooba'); + strictEqual(term.buffer.active.getLine(0)!.translateToString(true), 'fooba'); + strictEqual(term.buffer.active.getLine(1)!.translateToString(true), 'r'); + strictEqual(term.buffer.active.getLine(0)!.translateToString(false, 1), 'ooba'); + strictEqual(term.buffer.active.getLine(0)!.translateToString(false, 1, 3), 'oo'); + }); + + it('getCell', async () => { + term = new Terminal({ cols: 5 }); + strictEqual(term.buffer.active.getLine(0)!.getCell(-1), undefined); + strictEqual(term.buffer.active.getLine(0)!.getCell(5), undefined); + strictEqual(term.buffer.active.getLine(0)!.getCell(0)!.getChars(), ''); + strictEqual(term.buffer.active.getLine(0)!.getCell(0)!.getWidth(), 1); + await writeSync('a文'); + strictEqual(term.buffer.active.getLine(0)!.getCell(0)!.getChars(), 'a'); + strictEqual(term.buffer.active.getLine(0)!.getCell(0)!.getWidth(), 1); + strictEqual(term.buffer.active.getLine(0)!.getCell(1)!.getChars(), '文'); + strictEqual(term.buffer.active.getLine(0)!.getCell(1)!.getWidth(), 2); + strictEqual(term.buffer.active.getLine(0)!.getCell(2)!.getChars(), ''); + strictEqual(term.buffer.active.getLine(0)!.getCell(2)!.getWidth(), 0); + }); + }); + + it('active, normal, alternate', async () => { + term = new Terminal({ cols: 5 }); + strictEqual(term.buffer.active.type, 'normal'); + strictEqual(term.buffer.normal.type, 'normal'); + strictEqual(term.buffer.alternate.type, 'alternate'); + + await writeSync('norm '); + strictEqual(term.buffer.active.getLine(0)!.translateToString(), 'norm '); + strictEqual(term.buffer.normal.getLine(0)!.translateToString(), 'norm '); + strictEqual(term.buffer.alternate.getLine(0), undefined); + + await writeSync('\x1b[?47h\r'); // use alternate screen buffer + strictEqual(term.buffer.active.type, 'alternate'); + strictEqual(term.buffer.normal.type, 'normal'); + strictEqual(term.buffer.alternate.type, 'alternate'); + + strictEqual(term.buffer.active.getLine(0)!.translateToString(), ' '); + await writeSync('alt '); + strictEqual(term.buffer.active.getLine(0)!.translateToString(), 'alt '); + strictEqual(term.buffer.normal.getLine(0)!.translateToString(), 'norm '); + strictEqual(term.buffer.alternate.getLine(0)!.translateToString(), 'alt '); + + await writeSync('\x1b[?47l\r'); // use normal screen buffer + strictEqual(term.buffer.active.type, 'normal'); + strictEqual(term.buffer.normal.type, 'normal'); + strictEqual(term.buffer.alternate.type, 'alternate'); + + strictEqual(term.buffer.active.getLine(0)!.translateToString(), 'norm '); + strictEqual(term.buffer.normal.getLine(0)!.translateToString(), 'norm '); + strictEqual(term.buffer.alternate.getLine(0), undefined); + }); + }); + + it('dispose', async () => { + term.dispose(); + strictEqual((term as any)._core._isDisposed, true); + }); +}); + +function writeSync(text: string | Uint8Array): Promise { + return new Promise(r => term.write(text, r)); +} + +function writelnSync(text: string | Uint8Array): Promise { + return new Promise(r => term.writeln(text, r)); +} + +function lineEquals(index: number, text: string): void { + strictEqual(term.buffer.active.getLine(index)!.translateToString(true), text); +} diff --git a/src/headless/public/Terminal.ts b/src/headless/public/Terminal.ts new file mode 100644 index 0000000000..a1de7fdb1c --- /dev/null +++ b/src/headless/public/Terminal.ts @@ -0,0 +1,145 @@ +/** + * Copyright (c) 2018 The xterm.js authors. All rights reserved. + * @license MIT + */ + +import { IEvent } from 'common/EventEmitter'; +import { BufferNamespaceApi } from 'common/public/BufferNamespaceApi'; +import { ParserApi } from 'common/public/ParserApi'; +import { UnicodeApi } from 'common/public/UnicodeApi'; +import { IBufferNamespace as IBufferNamespaceApi, IMarker, IParser, ITerminalAddon, ITerminalOptions, IUnicodeHandling, Terminal as ITerminalApi } from 'xterm-headless'; +import { Terminal as TerminalCore } from 'headless/Terminal'; +import { AddonManager } from 'common/public/AddonManager'; + +export class Terminal implements ITerminalApi { + private _core: TerminalCore; + private _addonManager: AddonManager; + private _parser: IParser | undefined; + private _buffer: BufferNamespaceApi | undefined; + + constructor(options?: ITerminalOptions) { + this._core = new TerminalCore(options); + this._addonManager = new AddonManager(); + } + + private _checkProposedApi(): void { + if (!this._core.optionsService.options.allowProposedApi) { + throw new Error('You must set the allowProposedApi option to true to use proposed API'); + } + } + + public get onBell(): IEvent { return this._core.onBell; } + public get onBinary(): IEvent { return this._core.onBinary; } + public get onCursorMove(): IEvent { return this._core.onCursorMove; } + public get onData(): IEvent { return this._core.onData; } + public get onLineFeed(): IEvent { return this._core.onLineFeed; } + public get onResize(): IEvent<{ cols: number, rows: number }> { return this._core.onResize; } + public get onScroll(): IEvent { return this._core.onScroll; } + public get onTitleChange(): IEvent { return this._core.onTitleChange; } + + public get parser(): IParser { + this._checkProposedApi(); + if (!this._parser) { + this._parser = new ParserApi(this._core); + } + return this._parser; + } + public get unicode(): IUnicodeHandling { + this._checkProposedApi(); + return new UnicodeApi(this._core); + } + public get rows(): number { return this._core.rows; } + public get cols(): number { return this._core.cols; } + public get buffer(): IBufferNamespaceApi { + this._checkProposedApi(); + if (!this._buffer) { + this._buffer = new BufferNamespaceApi(this._core); + } + return this._buffer; + } + public get markers(): ReadonlyArray { + this._checkProposedApi(); + return this._core.markers; + } + public resize(columns: number, rows: number): void { + this._verifyIntegers(columns, rows); + this._core.resize(columns, rows); + } + public registerMarker(cursorYOffset: number): IMarker | undefined { + this._checkProposedApi(); + this._verifyIntegers(cursorYOffset); + return this._core.addMarker(cursorYOffset); + } + public addMarker(cursorYOffset: number): IMarker | undefined { + return this.registerMarker(cursorYOffset); + } + public dispose(): void { + this._addonManager.dispose(); + this._core.dispose(); + } + public scrollLines(amount: number): void { + this._verifyIntegers(amount); + this._core.scrollLines(amount); + } + public scrollPages(pageCount: number): void { + this._verifyIntegers(pageCount); + this._core.scrollPages(pageCount); + } + public scrollToTop(): void { + this._core.scrollToTop(); + } + public scrollToBottom(): void { + this._core.scrollToBottom(); + } + public scrollToLine(line: number): void { + this._verifyIntegers(line); + this._core.scrollToLine(line); + } + public clear(): void { + this._core.clear(); + } + public write(data: string | Uint8Array, callback?: () => void): void { + this._core.write(data, callback); + } + public writeUtf8(data: Uint8Array, callback?: () => void): void { + this._core.write(data, callback); + } + public writeln(data: string | Uint8Array, callback?: () => void): void { + this._core.write(data); + this._core.write('\r\n', callback); + } + public getOption(key: 'bellSound' | 'bellStyle' | 'cursorStyle' | 'fontFamily' | 'logLevel' | 'rendererType' | 'termName' | 'wordSeparator'): string; + public getOption(key: 'allowTransparency' | 'altClickMovesCursor' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'rightClickSelectsWord' | 'popOnBell' | 'visualBell'): boolean; + public getOption(key: 'cols' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'rows' | 'tabStopWidth' | 'scrollback'): number; + public getOption(key: string): any; + public getOption(key: any): any { + return this._core.optionsService.getOption(key); + } + public setOption(key: 'bellSound' | 'fontFamily' | 'termName' | 'wordSeparator', value: string): void; + public setOption(key: 'fontWeight' | 'fontWeightBold', value: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | number): void; + public setOption(key: 'logLevel', value: 'debug' | 'info' | 'warn' | 'error' | 'off'): void; + public setOption(key: 'bellStyle', value: 'none' | 'visual' | 'sound' | 'both'): void; + public setOption(key: 'cursorStyle', value: 'block' | 'underline' | 'bar'): void; + public setOption(key: 'allowTransparency' | 'altClickMovesCursor' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'rightClickSelectsWord' | 'popOnBell' | 'visualBell', value: boolean): void; + public setOption(key: 'fontSize' | 'letterSpacing' | 'lineHeight' | 'tabStopWidth' | 'scrollback', value: number): void; + public setOption(key: 'cols' | 'rows', value: number): void; + public setOption(key: string, value: any): void; + public setOption(key: any, value: any): void { + this._core.optionsService.setOption(key, value); + } + public reset(): void { + this._core.reset(); + } + public loadAddon(addon: ITerminalAddon): void { + // TODO: This could cause issues if the addon calls renderer apis + return this._addonManager.loadAddon(this as any, addon); + } + + private _verifyIntegers(...values: number[]): void { + for (const value of values) { + if (value === Infinity || isNaN(value) || value % 1 !== 0) { + throw new Error('This API only accepts integers'); + } + } + } +} diff --git a/src/headless/tsconfig.json b/src/headless/tsconfig.json new file mode 100644 index 0000000000..b579af97c0 --- /dev/null +++ b/src/headless/tsconfig.json @@ -0,0 +1,26 @@ +{ + "extends": "../tsconfig-library-base", + "compilerOptions": { + "lib": [ + "es2015", + "es2016.Array.Include" + ], + "outDir": "../../out", + "types": [ + "../../node_modules/@types/mocha", + "../../node_modules/@types/node" + ], + "baseUrl": "../", + "paths": { + "common/*": [ "./common/*" ] + } + }, + "include": [ + "./**/*", + "../../typings/xterm.d.ts", // common/Types.d.ts imports from 'xterm' + "../../typings/xterm-headless.d.ts" + ], + "references": [ + { "path": "../common" } + ] +} diff --git a/test/api/Terminal.api.ts b/test/api/Terminal.api.ts index 9e951ffef5..75399b733f 100644 --- a/test/api/Terminal.api.ts +++ b/test/api/Terminal.api.ts @@ -69,12 +69,9 @@ describe('API Integration Tests', function(): void { it('write - bytes (UTF8)', async () => { await openTerminal(page); await page.evaluate(` - // foo - window.term.write(new Uint8Array([102, 111, 111])); - // bar - window.term.write(new Uint8Array([98, 97, 114])); - // 文 - window.term.write(new Uint8Array([230, 150, 135])); + window.term.write(new Uint8Array([102, 111, 111])); // foo + window.term.write(new Uint8Array([98, 97, 114])); // bar + window.term.write(new Uint8Array([230, 150, 135])); // 文 `); await pollFor(page, `window.term.buffer.active.getLine(0).translateToString(true)`, 'foobar文'); }); @@ -82,12 +79,9 @@ describe('API Integration Tests', function(): void { it('write - bytes (UTF8) with callback', async () => { await openTerminal(page); await page.evaluate(` - // foo - window.term.write(new Uint8Array([102, 111, 111]), () => { window.__x = 'A'; }); - // bar - window.term.write(new Uint8Array([98, 97, 114]), () => { window.__x += 'B'; }); - // 文 - window.term.write(new Uint8Array([230, 150, 135]), () => { window.__x += 'C'; }); + window.term.write(new Uint8Array([102, 111, 111]), () => { window.__x = 'A'; }); // foo + window.term.write(new Uint8Array([98, 97, 114]), () => { window.__x += 'B'; }); // bar + window.term.write(new Uint8Array([230, 150, 135]), () => { window.__x += 'C'; }); // 文 `); await pollFor(page, `window.term.buffer.active.getLine(0).translateToString(true)`, 'foobar文'); await pollFor(page, `window.__x`, 'ABC'); diff --git a/tsconfig.all.json b/tsconfig.all.json index 009cd498b8..6fa02446a2 100644 --- a/tsconfig.all.json +++ b/tsconfig.all.json @@ -3,6 +3,7 @@ "include": [], "references": [ { "path": "./src/browser" }, + { "path": "./src/headless" }, { "path": "./test/api" }, { "path": "./test/benchmark" }, { "path": "./addons/xterm-addon-attach" }, diff --git a/typings/xterm-headless.d.ts b/typings/xterm-headless.d.ts new file mode 100644 index 0000000000..03e7567a78 --- /dev/null +++ b/typings/xterm-headless.d.ts @@ -0,0 +1,1253 @@ +/** + * @license MIT + * + * This contains the type declarations for the xterm.js library. Note that + * some interfaces differ between this file and the actual implementation in + * src/, that's because this file declares the *public* API which is intended + * to be stable and consumed by external programs. + */ + +declare module 'xterm-headless' { + /** + * A string representing log level. + */ + export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off'; + + /** + * An object containing start up options for the terminal. + */ + export interface ITerminalOptions { + /** + * Whether to allow the use of proposed API. When false, any usage of APIs + * marked as experimental/proposed will throw an error. This defaults to + * true currently, but will change to false in v5.0. + */ + allowProposedApi?: boolean; + + /** + * Whether background should support non-opaque color. It must be set before + * executing the `Terminal.open()` method and can't be changed later without + * executing it again. Note that enabling this can negatively impact + * performance. + */ + allowTransparency?: boolean; + + /** + * If enabled, alt + click will move the prompt cursor to position + * underneath the mouse. The default is true. + */ + altClickMovesCursor?: boolean; + + /** + * A data uri of the sound to use for the bell when `bellStyle = 'sound'`. + */ + bellSound?: string; + + /** + * The type of the bell notification the terminal will use. + */ + bellStyle?: 'none' | 'sound'; + + /** + * When enabled the cursor will be set to the beginning of the next line + * with every new line. This is equivalent to sending '\r\n' for each '\n'. + * Normally the termios settings of the underlying PTY deals with the + * translation of '\n' to '\r\n' and this setting should not be used. If you + * deal with data from a non-PTY related source, this settings might be + * useful. + */ + convertEol?: boolean; + + /** + * The number of columns in the terminal. + */ + cols?: number; + + /** + * Whether the cursor blinks. + */ + cursorBlink?: boolean; + + /** + * The style of the cursor. + */ + cursorStyle?: 'block' | 'underline' | 'bar'; + + /** + * The width of the cursor in CSS pixels when `cursorStyle` is set to 'bar'. + */ + cursorWidth?: number; + + /** + * Whether input should be disabled. + */ + disableStdin?: boolean; + + /** + * Whether to draw bold text in bright colors. The default is true. + */ + drawBoldTextInBrightColors?: boolean; + + /** + * The modifier key hold to multiply scroll speed. + */ + fastScrollModifier?: 'alt' | 'ctrl' | 'shift' | undefined; + + /** + * The spacing in whole pixels between characters. + */ + letterSpacing?: number; + + /** + * The line height used to render text. + */ + lineHeight?: number; + + /** + * The duration in milliseconds before link tooltip events fire when + * hovering on a link. + * @deprecated This will be removed when the link matcher API is removed. + */ + linkTooltipHoverDuration?: number; + + /** + * What log level to use, this will log for all levels below and including + * what is set: + * + * 1. debug + * 2. info (default) + * 3. warn + * 4. error + * 5. off + */ + logLevel?: LogLevel; + + /** + * Whether to treat option as the meta key. + */ + macOptionIsMeta?: boolean; + + /** + * Whether holding a modifier key will force normal selection behavior, + * regardless of whether the terminal is in mouse events mode. This will + * also prevent mouse events from being emitted by the terminal. For + * example, this allows you to use xterm.js' regular selection inside tmux + * with mouse mode enabled. + */ + macOptionClickForcesSelection?: boolean; + + /** + * The minimum contrast ratio for text in the terminal, setting this will + * change the foreground color dynamically depending on whether the contrast + * ratio is met. Example values: + * + * - 1: The default, do nothing. + * - 4.5: Minimum for WCAG AA compliance. + * - 7: Minimum for WCAG AAA compliance. + * - 21: White on black or black on white. + */ + minimumContrastRatio?: number; + + /** + * Whether to select the word under the cursor on right click, this is + * standard behavior in a lot of macOS applications. + */ + rightClickSelectsWord?: boolean; + + /** + * The number of rows in the terminal. + */ + rows?: number; + + /** + * Whether screen reader support is enabled. When on this will expose + * supporting elements in the DOM to support NVDA on Windows and VoiceOver + * on macOS. + */ + screenReaderMode?: boolean; + + /** + * The amount of scrollback in the terminal. Scrollback is the amount of + * rows that are retained when lines are scrolled beyond the initial + * viewport. + */ + scrollback?: number; + + /** + * The scrolling speed multiplier used for adjusting normal scrolling speed. + */ + scrollSensitivity?: number; + + /** + * The size of tab stops in the terminal. + */ + tabStopWidth?: number; + + /** + * The color theme of the terminal. + */ + theme?: ITheme; + + /** + * Whether "Windows mode" is enabled. Because Windows backends winpty and + * conpty operate by doing line wrapping on their side, xterm.js does not + * have access to wrapped lines. When Windows mode is enabled the following + * changes will be in effect: + * + * - Reflow is disabled. + * - Lines are assumed to be wrapped if the last character of the line is + * not whitespace. + */ + windowsMode?: boolean; + + /** + * A string containing all characters that are considered word separated by the + * double click to select work logic. + */ + wordSeparator?: string; + + /** + * Enable various window manipulation and report features. + * All features are disabled by default for security reasons. + */ + windowOptions?: IWindowOptions; + } + + /** + * Contains colors to theme the terminal with. + */ + export interface ITheme { + /** The default foreground color */ + foreground?: string; + /** The default background color */ + background?: string; + /** The cursor color */ + cursor?: string; + /** The accent color of the cursor (fg color for a block cursor) */ + cursorAccent?: string; + /** The selection background color (can be transparent) */ + selection?: string; + /** ANSI black (eg. `\x1b[30m`) */ + black?: string; + /** ANSI red (eg. `\x1b[31m`) */ + red?: string; + /** ANSI green (eg. `\x1b[32m`) */ + green?: string; + /** ANSI yellow (eg. `\x1b[33m`) */ + yellow?: string; + /** ANSI blue (eg. `\x1b[34m`) */ + blue?: string; + /** ANSI magenta (eg. `\x1b[35m`) */ + magenta?: string; + /** ANSI cyan (eg. `\x1b[36m`) */ + cyan?: string; + /** ANSI white (eg. `\x1b[37m`) */ + white?: string; + /** ANSI bright black (eg. `\x1b[1;30m`) */ + brightBlack?: string; + /** ANSI bright red (eg. `\x1b[1;31m`) */ + brightRed?: string; + /** ANSI bright green (eg. `\x1b[1;32m`) */ + brightGreen?: string; + /** ANSI bright yellow (eg. `\x1b[1;33m`) */ + brightYellow?: string; + /** ANSI bright blue (eg. `\x1b[1;34m`) */ + brightBlue?: string; + /** ANSI bright magenta (eg. `\x1b[1;35m`) */ + brightMagenta?: string; + /** ANSI bright cyan (eg. `\x1b[1;36m`) */ + brightCyan?: string; + /** ANSI bright white (eg. `\x1b[1;37m`) */ + brightWhite?: string; + } + + /** + * An object that can be disposed via a dispose function. + */ + export interface IDisposable { + dispose(): void; + } + + /** + * An event that can be listened to. + * @returns an `IDisposable` to stop listening. + */ + export interface IEvent { + (listener: (arg1: T, arg2: U) => any): IDisposable; + } + + /** + * Represents a specific line in the terminal that is tracked when scrollback + * is trimmed and lines are added or removed. This is a single line that may + * be part of a larger wrapped line. + */ + export interface IMarker extends IDisposable { + /** + * A unique identifier for this marker. + */ + readonly id: number; + + /** + * Whether this marker is disposed. + */ + readonly isDisposed: boolean; + + /** + * The actual line index in the buffer at this point in time. This is set to + * -1 if the marker has been disposed. + */ + readonly line: number; + + /** + * Event listener to get notified when the marker gets disposed. Automatic disposal + * might happen for a marker, that got invalidated by scrolling out or removal of + * a line from the buffer. + */ + onDispose: IEvent; + } + + /** + * The set of localizable strings. + */ + export interface ILocalizableStrings { + /** + * The aria label for the underlying input textarea for the terminal. + */ + promptLabel: string; + + /** + * Announcement for when line reading is suppressed due to too many lines + * being printed to the terminal when `screenReaderMode` is enabled. + */ + tooMuchOutput: string; + } + + /** + * Enable various window manipulation and report features (CSI Ps ; Ps ; Ps t). + * + * Most settings have no default implementation, as they heavily rely on + * the embedding environment. + * + * To implement a feature, create a custom CSI hook like this: + * ```ts + * term.parser.addCsiHandler({final: 't'}, params => { + * const ps = params[0]; + * switch (ps) { + * case XY: + * ... // your implementation for option XY + * return true; // signal Ps=XY was handled + * } + * return false; // any Ps that was not handled + * }); + * ``` + * + * Note on security: + * Most features are meant to deal with some information of the host machine + * where the terminal runs on. This is seen as a security risk possibly leaking + * sensitive data of the host to the program in the terminal. Therefore all options + * (even those without a default implementation) are guarded by the boolean flag + * and disabled by default. + */ + export interface IWindowOptions { + /** + * Ps=1 De-iconify window. + * No default implementation. + */ + restoreWin?: boolean; + /** + * Ps=2 Iconify window. + * No default implementation. + */ + minimizeWin?: boolean; + /** + * Ps=3 ; x ; y + * Move window to [x, y]. + * No default implementation. + */ + setWinPosition?: boolean; + /** + * Ps = 4 ; height ; width + * Resize the window to given `height` and `width` in pixels. + * Omitted parameters should reuse the current height or width. + * Zero parameters should use the display's height or width. + * No default implementation. + */ + setWinSizePixels?: boolean; + /** + * Ps=5 Raise the window to the front of the stacking order. + * No default implementation. + */ + raiseWin?: boolean; + /** + * Ps=6 Lower the xterm window to the bottom of the stacking order. + * No default implementation. + */ + lowerWin?: boolean; + /** Ps=7 Refresh the window. */ + refreshWin?: boolean; + /** + * Ps = 8 ; height ; width + * Resize the text area to given height and width in characters. + * Omitted parameters should reuse the current height or width. + * Zero parameters use the display's height or width. + * No default implementation. + */ + setWinSizeChars?: boolean; + /** + * Ps=9 ; 0 Restore maximized window. + * Ps=9 ; 1 Maximize window (i.e., resize to screen size). + * Ps=9 ; 2 Maximize window vertically. + * Ps=9 ; 3 Maximize window horizontally. + * No default implementation. + */ + maximizeWin?: boolean; + /** + * Ps=10 ; 0 Undo full-screen mode. + * Ps=10 ; 1 Change to full-screen. + * Ps=10 ; 2 Toggle full-screen. + * No default implementation. + */ + fullscreenWin?: boolean; + /** Ps=11 Report xterm window state. + * If the xterm window is non-iconified, it returns "CSI 1 t". + * If the xterm window is iconified, it returns "CSI 2 t". + * No default implementation. + */ + getWinState?: boolean; + /** + * Ps=13 Report xterm window position. Result is "CSI 3 ; x ; y t". + * Ps=13 ; 2 Report xterm text-area position. Result is "CSI 3 ; x ; y t". + * No default implementation. + */ + getWinPosition?: boolean; + /** + * Ps=14 Report xterm text area size in pixels. Result is "CSI 4 ; height ; width t". + * Ps=14 ; 2 Report xterm window size in pixels. Result is "CSI 4 ; height ; width t". + * Has a default implementation. + */ + getWinSizePixels?: boolean; + /** + * Ps=15 Report size of the screen in pixels. Result is "CSI 5 ; height ; width t". + * No default implementation. + */ + getScreenSizePixels?: boolean; + /** + * Ps=16 Report xterm character cell size in pixels. Result is "CSI 6 ; height ; width t". + * Has a default implementation. + */ + getCellSizePixels?: boolean; + /** + * Ps=18 Report the size of the text area in characters. Result is "CSI 8 ; height ; width t". + * Has a default implementation. + */ + getWinSizeChars?: boolean; + /** + * Ps=19 Report the size of the screen in characters. Result is "CSI 9 ; height ; width t". + * No default implementation. + */ + getScreenSizeChars?: boolean; + /** + * Ps=20 Report xterm window's icon label. Result is "OSC L label ST". + * No default implementation. + */ + getIconTitle?: boolean; + /** + * Ps=21 Report xterm window's title. Result is "OSC l label ST". + * No default implementation. + */ + getWinTitle?: boolean; + /** + * Ps=22 ; 0 Save xterm icon and window title on stack. + * Ps=22 ; 1 Save xterm icon title on stack. + * Ps=22 ; 2 Save xterm window title on stack. + * All variants have a default implementation. + */ + pushTitle?: boolean; + /** + * Ps=23 ; 0 Restore xterm icon and window title from stack. + * Ps=23 ; 1 Restore xterm icon title from stack. + * Ps=23 ; 2 Restore xterm window title from stack. + * All variants have a default implementation. + */ + popTitle?: boolean; + /** + * Ps>=24 Resize to Ps lines (DECSLPP). + * DECSLPP is not implemented. This settings is also used to + * enable / disable DECCOLM (earlier variant of DECSLPP). + */ + setWinLines?: boolean; + } + + /** + * The class that represents an xterm.js terminal. + */ + export class Terminal implements IDisposable { + /** + * The number of rows in the terminal's viewport. Use + * `ITerminalOptions.rows` to set this in the constructor and + * `Terminal.resize` for when the terminal exists. + */ + readonly rows: number; + + /** + * The number of columns in the terminal's viewport. Use + * `ITerminalOptions.cols` to set this in the constructor and + * `Terminal.resize` for when the terminal exists. + */ + readonly cols: number; + + /** + * (EXPERIMENTAL) The terminal's current buffer, this might be either the + * normal buffer or the alt buffer depending on what's running in the + * terminal. + */ + readonly buffer: IBufferNamespace; + + /** + * (EXPERIMENTAL) Get all markers registered against the buffer. If the alt + * buffer is active this will always return []. + */ + readonly markers: ReadonlyArray; + + /** + * (EXPERIMENTAL) Get the parser interface to register + * custom escape sequence handlers. + */ + readonly parser: IParser; + + /** + * (EXPERIMENTAL) Get the Unicode handling interface + * to register and switch Unicode version. + */ + readonly unicode: IUnicodeHandling; + + /** + * Natural language strings that can be localized. + */ + static strings: ILocalizableStrings; + + /** + * Creates a new `Terminal` object. + * + * @param options An object containing a set of options. + */ + constructor(options?: ITerminalOptions); + + /** + * Adds an event listener for when the bell is triggered. + * @returns an `IDisposable` to stop listening. + */ + onBell: IEvent; + + /** + * Adds an event listener for when a binary event fires. This is used to + * enable non UTF-8 conformant binary messages to be sent to the backend. + * Currently this is only used for a certain type of mouse reports that + * happen to be not UTF-8 compatible. + * The event value is a JS string, pass it to the underlying pty as + * binary data, e.g. `pty.write(Buffer.from(data, 'binary'))`. + * @returns an `IDisposable` to stop listening. + */ + onBinary: IEvent; + + /** + * Adds an event listener for the cursor moves. + * @returns an `IDisposable` to stop listening. + */ + onCursorMove: IEvent; + + /** + * Adds an event listener for when a data event fires. This happens for + * example when the user types or pastes into the terminal. The event value + * is whatever `string` results, in a typical setup, this should be passed + * on to the backing pty. + * @returns an `IDisposable` to stop listening. + */ + onData: IEvent; + + /** + * Adds an event listener for when a line feed is added. + * @returns an `IDisposable` to stop listening. + */ + onLineFeed: IEvent; + + /** + * Adds an event listener for when the terminal is resized. The event value + * contains the new size. + * @returns an `IDisposable` to stop listening. + */ + onResize: IEvent<{ cols: number, rows: number }>; + + /** + * Adds an event listener for when a scroll occurs. The event value is the + * new position of the viewport. + * @returns an `IDisposable` to stop listening. + */ + onScroll: IEvent; + + /** + * Adds an event listener for when an OSC 0 or OSC 2 title change occurs. + * The event value is the new title. + * @returns an `IDisposable` to stop listening. + */ + onTitleChange: IEvent; + + /** + * Resizes the terminal. It's best practice to debounce calls to resize, + * this will help ensure that the pty can respond to the resize event + * before another one occurs. + * @param x The number of columns to resize to. + * @param y The number of rows to resize to. + */ + resize(columns: number, rows: number): void; + + /** + * (EXPERIMENTAL) Adds a marker to the normal buffer and returns it. If the + * alt buffer is active, undefined is returned. + * @param cursorYOffset The y position offset of the marker from the cursor. + * @returns The new marker or undefined. + */ + registerMarker(cursorYOffset: number): IMarker | undefined; + + /** + * @deprecated use `registerMarker` instead. + */ + addMarker(cursorYOffset: number): IMarker | undefined; + + /* + * Disposes of the terminal, detaching it from the DOM and removing any + * active listeners. + */ + dispose(): void; + + /** + * Scroll the display of the terminal + * @param amount The number of lines to scroll down (negative scroll up). + */ + scrollLines(amount: number): void; + + /** + * Scroll the display of the terminal by a number of pages. + * @param pageCount The number of pages to scroll (negative scrolls up). + */ + scrollPages(pageCount: number): void; + + /** + * Scrolls the display of the terminal to the top. + */ + scrollToTop(): void; + + /** + * Scrolls the display of the terminal to the bottom. + */ + scrollToBottom(): void; + + /** + * Scrolls to a line within the buffer. + * @param line The 0-based line index to scroll to. + */ + scrollToLine(line: number): void; + + /** + * Clear the entire buffer, making the prompt line the new first line. + */ + clear(): void; + + /** + * Write data to the terminal. + * @param data The data to write to the terminal. This can either be raw + * bytes given as Uint8Array from the pty or a string. Raw bytes will always + * be treated as UTF-8 encoded, string data as UTF-16. + * @param callback Optional callback that fires when the data was processed + * by the parser. + */ + write(data: string | Uint8Array, callback?: () => void): void; + + /** + * Writes data to the terminal, followed by a break line character (\n). + * @param data The data to write to the terminal. This can either be raw + * bytes given as Uint8Array from the pty or a string. Raw bytes will always + * be treated as UTF-8 encoded, string data as UTF-16. + * @param callback Optional callback that fires when the data was processed + * by the parser. + */ + writeln(data: string | Uint8Array, callback?: () => void): void; + + /** + * Write UTF8 data to the terminal. + * @param data The data to write to the terminal. + * @param callback Optional callback when data was processed. + * @deprecated use `write` instead + */ + writeUtf8(data: Uint8Array, callback?: () => void): void; + + /** + * Retrieves an option's value from the terminal. + * @param key The option key. + */ + getOption(key: 'bellSound' | 'bellStyle' | 'cursorStyle' | 'fontFamily' | 'logLevel' | 'rendererType' | 'termName' | 'wordSeparator'): string; + /** + * Retrieves an option's value from the terminal. + * @param key The option key. + */ + getOption(key: 'allowTransparency' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'rightClickSelectsWord' | 'popOnBell' | 'visualBell' | 'windowsMode'): boolean; + /** + * Retrieves an option's value from the terminal. + * @param key The option key. + */ + getOption(key: 'cols' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'rows' | 'tabStopWidth' | 'scrollback'): number; + /** + * Retrieves an option's value from the terminal. + * @param key The option key. + */ + getOption(key: string): any; + + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'fontFamily' | 'termName' | 'bellSound' | 'wordSeparator', value: string): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'fontWeight' | 'fontWeightBold', value: null | 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | number): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'logLevel', value: LogLevel): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'bellStyle', value: null | 'none' | 'visual' | 'sound' | 'both'): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'cursorStyle', value: null | 'block' | 'underline' | 'bar'): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'allowTransparency' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'popOnBell' | 'rightClickSelectsWord' | 'visualBell' | 'windowsMode', value: boolean): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'fontSize' | 'letterSpacing' | 'lineHeight' | 'tabStopWidth' | 'scrollback', value: number): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'theme', value: ITheme): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: 'cols' | 'rows', value: number): void; + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: string, value: any): void; + + /** + * Perform a full reset (RIS, aka '\x1bc'). + */ + reset(): void; + + /** + * Loads an addon into this instance of xterm.js. + * @param addon The addon to load. + */ + loadAddon(addon: ITerminalAddon): void; + } + + /** + * An addon that can provide additional functionality to the terminal. + */ + export interface ITerminalAddon extends IDisposable { + /** + * This is called when the addon is activated. + */ + activate(terminal: Terminal): void; + } + + /** + * An object representing a selection within the terminal. + */ + interface ISelectionPosition { + /** + * The start column of the selection. + */ + startColumn: number; + + /** + * The start row of the selection. + */ + startRow: number; + + /** + * The end column of the selection. + */ + endColumn: number; + + /** + * The end row of the selection. + */ + endRow: number; + } + + /** + * An object representing a range within the viewport of the terminal. + */ + export interface IViewportRange { + /** + * The start of the range. + */ + start: IViewportRangePosition; + + /** + * The end of the range. + */ + end: IViewportRangePosition; + } + + /** + * An object representing a cell position within the viewport of the terminal. + */ + interface IViewportRangePosition { + /** + * The x position of the cell. This is a 0-based index that refers to the + * space in between columns, not the column itself. Index 0 refers to the + * left side of the viewport, index `Terminal.cols` refers to the right side + * of the viewport. This can be thought of as how a cursor is positioned in + * a text editor. + */ + x: number; + + /** + * The y position of the cell. This is a 0-based index that refers to a + * specific row. + */ + y: number; + } + + /** + * A range within a buffer. + */ + interface IBufferRange { + /** + * The start position of the range. + */ + start: IBufferCellPosition; + + /** + * The end position of the range. + */ + end: IBufferCellPosition; + } + + /** + * A position within a buffer. + */ + interface IBufferCellPosition { + /** + * The x position within the buffer. + */ + x: number; + + /** + * The y position within the buffer. + */ + y: number; + } + + /** + * Represents a terminal buffer. + */ + interface IBuffer { + /** + * The type of the buffer. + */ + readonly type: 'normal' | 'alternate'; + + /** + * The y position of the cursor. This ranges between `0` (when the + * cursor is at baseY) and `Terminal.rows - 1` (when the cursor is on the + * last row). + */ + readonly cursorY: number; + + /** + * The x position of the cursor. This ranges between `0` (left side) and + * `Terminal.cols` (after last cell of the row). + */ + readonly cursorX: number; + + /** + * The line within the buffer where the top of the viewport is. + */ + readonly viewportY: number; + + /** + * The line within the buffer where the top of the bottom page is (when + * fully scrolled down). + */ + readonly baseY: number; + + /** + * The amount of lines in the buffer. + */ + readonly length: number; + + /** + * Gets a line from the buffer, or undefined if the line index does not + * exist. + * + * Note that the result of this function should be used immediately after + * calling as when the terminal updates it could lead to unexpected + * behavior. + * + * @param y The line index to get. + */ + getLine(y: number): IBufferLine | undefined; + + /** + * Creates an empty cell object suitable as a cell reference in + * `line.getCell(x, cell)`. Use this to avoid costly recreation of + * cell objects when dealing with tons of cells. + */ + getNullCell(): IBufferCell; + } + + /** + * Represents the terminal's set of buffers. + */ + interface IBufferNamespace { + /** + * The active buffer, this will either be the normal or alternate buffers. + */ + readonly active: IBuffer; + + /** + * The normal buffer. + */ + readonly normal: IBuffer; + + /** + * The alternate buffer, this becomes the active buffer when an application + * enters this mode via DECSET (`CSI ? 4 7 h`) + */ + readonly alternate: IBuffer; + + /** + * Adds an event listener for when the active buffer changes. + * @returns an `IDisposable` to stop listening. + */ + onBufferChange: IEvent; + } + + /** + * Represents a line in the terminal's buffer. + */ + interface IBufferLine { + /** + * Whether the line is wrapped from the previous line. + */ + readonly isWrapped: boolean; + + /** + * The length of the line, all call to getCell beyond the length will result + * in `undefined`. + */ + readonly length: number; + + /** + * Gets a cell from the line, or undefined if the line index does not exist. + * + * Note that the result of this function should be used immediately after + * calling as when the terminal updates it could lead to unexpected + * behavior. + * + * @param x The character index to get. + * @param cell Optional cell object to load data into for performance + * reasons. This is mainly useful when every cell in the buffer is being + * looped over to avoid creating new objects for every cell. + */ + getCell(x: number, cell?: IBufferCell): IBufferCell | undefined; + + /** + * Gets the line as a string. Note that this is gets only the string for the + * line, not taking isWrapped into account. + * + * @param trimRight Whether to trim any whitespace at the right of the line. + * @param startColumn The column to start from (inclusive). + * @param endColumn The column to end at (exclusive). + */ + translateToString(trimRight?: boolean, startColumn?: number, endColumn?: number): string; + } + + /** + * Represents a single cell in the terminal's buffer. + */ + interface IBufferCell { + /** + * The width of the character. Some examples: + * + * - `1` for most cells. + * - `2` for wide character like CJK glyphs. + * - `0` for cells immediately following cells with a width of `2`. + */ + getWidth(): number; + + /** + * The character(s) within the cell. Examples of what this can contain: + * + * - A normal width character + * - A wide character (eg. CJK) + * - An emoji + */ + getChars(): string; + + /** + * Gets the UTF32 codepoint of single characters, if content is a combined + * string it returns the codepoint of the last character in the string. + */ + getCode(): number; + + /** + * Gets the number representation of the foreground color mode, this can be + * used to perform quick comparisons of 2 cells to see if they're the same. + * Use `isFgRGB`, `isFgPalette` and `isFgDefault` to check what color mode + * a cell is. + */ + getFgColorMode(): number; + + /** + * Gets the number representation of the background color mode, this can be + * used to perform quick comparisons of 2 cells to see if they're the same. + * Use `isBgRGB`, `isBgPalette` and `isBgDefault` to check what color mode + * a cell is. + */ + getBgColorMode(): number; + + /** + * Gets a cell's foreground color number, this differs depending on what the + * color mode of the cell is: + * + * - Default: This should be 0, representing the default foreground color + * (CSI 39 m). + * - Palette: This is a number from 0 to 255 of ANSI colors (CSI 3(0-7) m, + * CSI 9(0-7) m, CSI 38 ; 5 ; 0-255 m). + * - RGB: A hex value representing a 'true color': 0xRRGGBB. + * (CSI 3 8 ; 2 ; Pi ; Pr ; Pg ; Pb) + */ + getFgColor(): number; + + /** + * Gets a cell's background color number, this differs depending on what the + * color mode of the cell is: + * + * - Default: This should be 0, representing the default background color + * (CSI 49 m). + * - Palette: This is a number from 0 to 255 of ANSI colors + * (CSI 4(0-7) m, CSI 10(0-7) m, CSI 48 ; 5 ; 0-255 m). + * - RGB: A hex value representing a 'true color': 0xRRGGBB + * (CSI 4 8 ; 2 ; Pi ; Pr ; Pg ; Pb) + */ + getBgColor(): number; + + /** Whether the cell has the bold attribute (CSI 1 m). */ + isBold(): number; + /** Whether the cell has the inverse attribute (CSI 3 m). */ + isItalic(): number; + /** Whether the cell has the inverse attribute (CSI 2 m). */ + isDim(): number; + /** Whether the cell has the underline attribute (CSI 4 m). */ + isUnderline(): number; + /** Whether the cell has the inverse attribute (CSI 5 m). */ + isBlink(): number; + /** Whether the cell has the inverse attribute (CSI 7 m). */ + isInverse(): number; + /** Whether the cell has the inverse attribute (CSI 8 m). */ + isInvisible(): number; + + /** Whether the cell is using the RGB foreground color mode. */ + isFgRGB(): boolean; + /** Whether the cell is using the RGB background color mode. */ + isBgRGB(): boolean; + /** Whether the cell is using the palette foreground color mode. */ + isFgPalette(): boolean; + /** Whether the cell is using the palette background color mode. */ + isBgPalette(): boolean; + /** Whether the cell is using the default foreground color mode. */ + isFgDefault(): boolean; + /** Whether the cell is using the default background color mode. */ + isBgDefault(): boolean; + + /** Whether the cell has the default attribute (no color or style). */ + isAttributeDefault(): boolean; + } + + /** + * Data type to register a CSI, DCS or ESC callback in the parser + * in the form: + * ESC I..I F + * CSI Prefix P..P I..I F + * DCS Prefix P..P I..I F data_bytes ST + * + * with these rules/restrictions: + * - prefix can only be used with CSI and DCS + * - only one leading prefix byte is recognized by the parser + * before any other parameter bytes (P..P) + * - intermediate bytes are recognized up to 2 + * + * For custom sequences make sure to read ECMA-48 and the resources at + * vt100.net to not clash with existing sequences or reserved address space. + * General recommendations: + * - use private address space (see ECMA-48) + * - use max one intermediate byte (technically not limited by the spec, + * in practice there are no sequences with more than one intermediate byte, + * thus parsers might get confused with more intermediates) + * - test against other common emulators to check whether they escape/ignore + * the sequence correctly + * + * Notes: OSC command registration is handled differently (see addOscHandler) + * APC, PM or SOS is currently not supported. + */ + export interface IFunctionIdentifier { + /** + * Optional prefix byte, must be in range \x3c .. \x3f. + * Usable in CSI and DCS. + */ + prefix?: string; + /** + * Optional intermediate bytes, must be in range \x20 .. \x2f. + * Usable in CSI, DCS and ESC. + */ + intermediates?: string; + /** + * Final byte, must be in range \x40 .. \x7e for CSI and DCS, + * \x30 .. \x7e for ESC. + */ + final: string; + } + + /** + * Allows hooking into the parser for custom handling of escape sequences. + */ + export interface IParser { + /** + * Adds a handler for CSI escape sequences. + * @param id Specifies the function identifier under which the callback + * gets registered, e.g. {final: 'm'} for SGR. + * @param callback The function to handle the sequence. The callback is + * called with the numerical params. If the sequence has subparams the + * array will contain subarrays with their numercial values. + * Return true if the sequence was handled; false if we should try + * a previous handler (set by addCsiHandler or setCsiHandler). + * The most recently added handler is tried first. + * @return An IDisposable you can call to remove this handler. + */ + registerCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean): IDisposable; + + /** + * Adds a handler for DCS escape sequences. + * @param id Specifies the function identifier under which the callback + * gets registered, e.g. {intermediates: '$' final: 'q'} for DECRQSS. + * @param callback The function to handle the sequence. Note that the + * function will only be called once if the sequence finished sucessfully. + * There is currently no way to intercept smaller data chunks, data chunks + * will be stored up until the sequence is finished. Since DCS sequences + * are not limited by the amount of data this might impose a problem for + * big payloads. Currently xterm.js limits DCS payload to 10 MB + * which should give enough room for most use cases. + * The function gets the payload and numerical parameters as arguments. + * Return true if the sequence was handled; false if we should try + * a previous handler (set by addDcsHandler or setDcsHandler). + * The most recently added handler is tried first. + * @return An IDisposable you can call to remove this handler. + */ + registerDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean): IDisposable; + + /** + * Adds a handler for ESC escape sequences. + * @param id Specifies the function identifier under which the callback + * gets registered, e.g. {intermediates: '%' final: 'G'} for + * default charset selection. + * @param callback The function to handle the sequence. + * Return true if the sequence was handled; false if we should try + * a previous handler (set by addEscHandler or setEscHandler). + * The most recently added handler is tried first. + * @return An IDisposable you can call to remove this handler. + */ + registerEscHandler(id: IFunctionIdentifier, handler: () => boolean): IDisposable; + + /** + * Adds a handler for OSC escape sequences. + * @param ident The number (first parameter) of the sequence. + * @param callback The function to handle the sequence. Note that the + * function will only be called once if the sequence finished sucessfully. + * There is currently no way to intercept smaller data chunks, data chunks + * will be stored up until the sequence is finished. Since OSC sequences + * are not limited by the amount of data this might impose a problem for + * big payloads. Currently xterm.js limits OSC payload to 10 MB + * which should give enough room for most use cases. + * The callback is called with OSC data string. + * Return true if the sequence was handled; false if we should try + * a previous handler (set by addOscHandler or setOscHandler). + * The most recently added handler is tried first. + * @return An IDisposable you can call to remove this handler. + */ + registerOscHandler(ident: number, callback: (data: string) => boolean): IDisposable; + } + + /** + * (EXPERIMENTAL) Unicode version provider. + * Used to register custom Unicode versions with `Terminal.unicode.register`. + */ + export interface IUnicodeVersionProvider { + /** + * String indicating the Unicode version provided. + */ + readonly version: string; + + /** + * Unicode version dependent wcwidth implementation. + */ + wcwidth(codepoint: number): 0 | 1 | 2; + } + + /** + * (EXPERIMENTAL) Unicode handling interface. + */ + export interface IUnicodeHandling { + /** + * Register a custom Unicode version provider. + */ + register(provider: IUnicodeVersionProvider): void; + + /** + * Registered Unicode versions. + */ + readonly versions: ReadonlyArray; + + /** + * Getter/setter for active Unicode version. + */ + activeVersion: string; + } + } diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts index 6bfb71ae06..035748fcbd 100644 --- a/typings/xterm.d.ts +++ b/typings/xterm.d.ts @@ -634,6 +634,12 @@ declare module 'xterm' { */ constructor(options?: ITerminalOptions); + /** + * Adds an event listener for when the bell is triggered. + * @returns an `IDisposable` to stop listening. + */ + onBell: IEvent; + /** * Adds an event listener for when a binary event fires. This is used to * enable non UTF-8 conformant binary messages to be sent to the backend. @@ -674,19 +680,6 @@ declare module 'xterm' { */ onLineFeed: IEvent; - /** - * Adds an event listener for when a scroll occurs. The event value is the - * new position of the viewport. - * @returns an `IDisposable` to stop listening. - */ - onScroll: IEvent; - - /** - * Adds an event listener for when a selection change occurs. - * @returns an `IDisposable` to stop listening. - */ - onSelectionChange: IEvent; - /** * Adds an event listener for when rows are rendered. The event value * contains the start row and end rows of the rendered area (ranges from `0` @@ -703,17 +696,24 @@ declare module 'xterm' { onResize: IEvent<{ cols: number, rows: number }>; /** - * Adds an event listener for when an OSC 0 or OSC 2 title change occurs. - * The event value is the new title. + * Adds an event listener for when a scroll occurs. The event value is the + * new position of the viewport. * @returns an `IDisposable` to stop listening. */ - onTitleChange: IEvent; + onScroll: IEvent; /** - * Adds an event listener for when the bell is triggered. + * Adds an event listener for when a selection change occurs. * @returns an `IDisposable` to stop listening. */ - onBell: IEvent; + onSelectionChange: IEvent; + + /** + * Adds an event listener for when an OSC 0 or OSC 2 title change occurs. + * The event value is the new title. + * @returns an `IDisposable` to stop listening. + */ + onTitleChange: IEvent; /** * Unfocus the terminal. diff --git a/webpack.config.headless.js b/webpack.config.headless.js new file mode 100644 index 0000000000..d5bb97b783 --- /dev/null +++ b/webpack.config.headless.js @@ -0,0 +1,43 @@ +/** + * Copyright (c) 2019 The xterm.js authors. All rights reserved. + * @license MIT + */ + +const path = require('path'); + +/** + * This webpack config does a production build for xterm.js headless. It works by taking the output + * from tsc (via `yarn watch` or `yarn prebuild`) which are put into `out/` and webpacks them into a + * production mode umd library module in `lib-headless/`. The aliases are used fix up the absolute + * paths output by tsc (because of `baseUrl` and `paths` in `tsconfig.json`. + */ +module.exports = { + entry: './out/headless/public/Terminal.js', + devtool: 'source-map', + module: { + rules: [ + { + test: /\.js$/, + use: ["source-map-loader"], + enforce: "pre", + exclude: /node_modules/ + } + ] + }, + resolve: { + modules: ['./node_modules'], + extensions: [ '.js' ], + alias: { + common: path.resolve('./out/common'), + headless: path.resolve('./out/headless') + } + }, + output: { + filename: 'xterm-headless.js', + path: path.resolve('./headless/lib-headless'), + library: { + type: 'commonjs' + } + }, + mode: 'production' +};