@xterm/xterm 5.4.0-beta.9 → 5.4.0

package/src/common/buffer/BufferLine.ts

@@ -4,7 +4,7 @@
  */
 
 import { CharData, IAttributeData, IBufferLine, ICellData, IExtendedAttrs } from 'common/Types';
-import { AttributeData, ExtendedAttrs } from 'common/buffer/AttributeData';
+import { AttributeData } from 'common/buffer/AttributeData';
 import { CellData } from 'common/buffer/CellData';
 import { Attributes, BgFlags, CHAR_DATA_ATTR_INDEX, CHAR_DATA_CHAR_INDEX, CHAR_DATA_WIDTH_INDEX, Content, NULL_CELL_CHAR, NULL_CELL_CODE, NULL_CELL_WIDTH, WHITESPACE_CELL_CHAR } from 'common/buffer/Constants';
 import { stringFromCodePoint } from 'common/input/TextDecoder';
@@ -212,13 +212,13 @@ export class BufferLine implements IBufferLine {
    * Since the input handler see the incoming chars as UTF32 codepoints,
    * it gets an optimized access method.
    */
-  public setCellFromCodePoint(index: number, codePoint: number, width: number, fg: number, bg: number, eAttrs: IExtendedAttrs): void {
-    if (bg & BgFlags.HAS_EXTENDED) {
-      this._extendedAttrs[index] = eAttrs;
+  public setCellFromCodepoint(index: number, codePoint: number, width: number, attrs: IAttributeData): void {
+    if (attrs.bg & BgFlags.HAS_EXTENDED) {
+      this._extendedAttrs[index] = attrs.extended;
     }
     this._data[index * CELL_SIZE + Cell.CONTENT] = codePoint | (width << Content.WIDTH_SHIFT);
-    this._data[index * CELL_SIZE + Cell.FG] = fg;
-    this._data[index * CELL_SIZE + Cell.BG] = bg;
+    this._data[index * CELL_SIZE + Cell.FG] = attrs.fg;
+    this._data[index * CELL_SIZE + Cell.BG] = attrs.bg;
   }
 
   /**
@@ -253,12 +253,12 @@ export class BufferLine implements IBufferLine {
     this._data[index * CELL_SIZE + Cell.CONTENT] = content;
   }
 
-  public insertCells(pos: number, n: number, fillCellData: ICellData, eraseAttr?: IAttributeData): void {
+  public insertCells(pos: number, n: number, fillCellData: ICellData): void {
     pos %= this.length;
 
     // handle fullwidth at pos: reset cell one to the left if pos is second cell of a wide char
     if (pos && this.getWidth(pos - 1) === 2) {
-      this.setCellFromCodePoint(pos - 1, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+      this.setCellFromCodepoint(pos - 1, 0, 1, fillCellData);
     }
 
     if (n < this.length - pos) {
@@ -277,11 +277,11 @@ export class BufferLine implements IBufferLine {
 
     // handle fullwidth at line end: reset last cell if it is first cell of a wide char
     if (this.getWidth(this.length - 1) === 2) {
-      this.setCellFromCodePoint(this.length - 1, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+      this.setCellFromCodepoint(this.length - 1, 0, 1, fillCellData);
     }
   }
 
-  public deleteCells(pos: number, n: number, fillCellData: ICellData, eraseAttr?: IAttributeData): void {
+  public deleteCells(pos: number, n: number, fillCellData: ICellData): void {
     pos %= this.length;
     if (n < this.length - pos) {
       const cell = new CellData();
@@ -301,21 +301,21 @@ export class BufferLine implements IBufferLine {
     // - reset pos-1 if wide char
     // - reset pos if width==0 (previous second cell of a wide char)
     if (pos && this.getWidth(pos - 1) === 2) {
-      this.setCellFromCodePoint(pos - 1, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+      this.setCellFromCodepoint(pos - 1, 0, 1, fillCellData);
     }
     if (this.getWidth(pos) === 0 && !this.hasContent(pos)) {
-      this.setCellFromCodePoint(pos, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+      this.setCellFromCodepoint(pos, 0, 1, fillCellData);
     }
   }
 
-  public replaceCells(start: number, end: number, fillCellData: ICellData, eraseAttr?: IAttributeData, respectProtect: boolean = false): void {
+  public replaceCells(start: number, end: number, fillCellData: ICellData, respectProtect: boolean = false): void {
     // full branching on respectProtect==true, hopefully getting fast JIT for standard case
     if (respectProtect) {
       if (start && this.getWidth(start - 1) === 2 && !this.isProtected(start - 1)) {
-        this.setCellFromCodePoint(start - 1, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+        this.setCellFromCodepoint(start - 1, 0, 1, fillCellData);
       }
       if (end < this.length && this.getWidth(end - 1) === 2 && !this.isProtected(end)) {
-        this.setCellFromCodePoint(end, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+        this.setCellFromCodepoint(end, 0, 1, fillCellData);
       }
       while (start < end  && start < this.length) {
         if (!this.isProtected(start)) {
@@ -328,11 +328,11 @@ export class BufferLine implements IBufferLine {
 
     // handle fullwidth at start: reset cell one to the left if start is second cell of a wide char
     if (start && this.getWidth(start - 1) === 2) {
-      this.setCellFromCodePoint(start - 1, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+      this.setCellFromCodepoint(start - 1, 0, 1, fillCellData);
     }
     // handle fullwidth at last cell + 1: reset to empty cell if it is second part of a wide char
     if (end < this.length && this.getWidth(end - 1) === 2) {
-      this.setCellFromCodePoint(end, 0, 1, eraseAttr?.fg || 0, eraseAttr?.bg || 0, eraseAttr?.extended || new ExtendedAttrs());
+      this.setCellFromCodepoint(end, 0, 1, fillCellData);
     }
 
     while (start < end  && start < this.length) {
@@ -508,16 +508,43 @@ export class BufferLine implements IBufferLine {
     }
   }
 
-  public translateToString(trimRight: boolean = false, startCol: number = 0, endCol: number = this.length): string {
+  /**
+   * Translates the buffer line to a string.
+   *
+   * @param trimRight Whether to trim any empty cells on the right.
+   * @param startCol The column to start the string (0-based inclusive).
+   * @param endCol The column to end the string (0-based exclusive).
+   * @param outColumns if specified, this array will be filled with column numbers such that
+   * `returnedString[i]` is displayed at `outColumns[i]` column. `outColumns[returnedString.length]`
+   * is where the character following `returnedString` will be displayed.
+   *
+   * When a single cell is translated to multiple UTF-16 code units (e.g. surrogate pair) in the
+   * returned string, the corresponding entries in `outColumns` will have the same column number.
+   */
+  public translateToString(trimRight?: boolean, startCol?: number, endCol?: number, outColumns?: number[]): string {
+    startCol = startCol ?? 0;
+    endCol = endCol ?? this.length;
     if (trimRight) {
       endCol = Math.min(endCol, this.getTrimmedLength());
     }
+    if (outColumns) {
+      outColumns.length = 0;
+    }
     let result = '';
     while (startCol < endCol) {
       const content = this._data[startCol * CELL_SIZE + Cell.CONTENT];
       const cp = content & Content.CODEPOINT_MASK;
-      result += (content & Content.IS_COMBINED_MASK) ? this._combined[startCol] : (cp) ? stringFromCodePoint(cp) : WHITESPACE_CELL_CHAR;
-      startCol += (content >> Content.WIDTH_SHIFT) || 1; // always advance by 1
+      const chars = (content & Content.IS_COMBINED_MASK) ? this._combined[startCol] : (cp) ? stringFromCodePoint(cp) : WHITESPACE_CELL_CHAR;
+      result += chars;
+      if (outColumns) {
+        for (let i = 0; i < chars.length; ++i) {
+          outColumns.push(startCol);
+        }
+      }
+      startCol += (content >> Content.WIDTH_SHIFT) || 1; // always advance by at least 1
+    }
+    if (outColumns) {
+      outColumns.push(startCol);
     }
     return result;
   }

package/src/common/services/OptionsService.ts

@@ -4,7 +4,7 @@
  */
 
 import { EventEmitter } from 'common/EventEmitter';
-import { Disposable } from 'common/Lifecycle';
+import { Disposable, toDisposable } from 'common/Lifecycle';
 import { isMac } from 'common/Platform';
 import { CursorStyle, IDisposable } from 'common/Types';
 import { FontWeight, IOptionsService, ITerminalOptions } from 'common/services/Services';
@@ -86,6 +86,13 @@ export class OptionsService extends Disposable implements IOptionsService {
     this.rawOptions = defaultOptions;
     this.options = { ... defaultOptions };
     this._setupOptions();
+
+    // Clear out options that could link outside xterm.js as they could easily cause an embedder
+    // memory leak
+    this.register(toDisposable(() => {
+      this.rawOptions.linkHandler = null;
+      this.rawOptions.documentOverride = null;
+    }));
   }
 
   // eslint-disable-next-line @typescript-eslint/naming-convention

package/src/headless/Terminal.ts

@@ -81,6 +81,10 @@ export class Terminal extends CoreTerminal {
     this._onBell.fire();
   }
 
+  public input(data: string, wasUserInput: boolean = true): void {
+    this.coreService.triggerDataEvent(data, wasUserInput);
+  }
+
   /**
    * Resizes the terminal.
    *

package/src/headless/public/Terminal.ts

@@ -134,6 +134,9 @@ export class Terminal extends Disposable implements ITerminalApi {
       this._publicOptions[propName] = options[propName];
     }
   }
+  public input(data: string, wasUserInput: boolean = true): void {
+    this._core.input(data, wasUserInput);
+  }
   public resize(columns: number, rows: number): void {
     this._verifyIntegers(columns, rows);
     this._core.resize(columns, rows);

package/typings/xterm.d.ts

@@ -963,6 +963,18 @@ declare module '@xterm/xterm' {
      */
     focus(): void;
 
+    /**
+     * Input data to application side. The data is treated the same way input
+     * typed into the terminal would (ie. the {@link onData} event will fire).
+     * @param data The data to forward to the application.
+     * @param wasUserInput Whether the input is genuine user input. This is true
+     * by default and triggers additionalbehavior like focus or selection
+     * clearing. Set this to false if the data sent should not be treated like
+     * user input would, for example passing an escape sequence to the
+     * application.
+     */
+    input(data: string, wasUserInput?: boolean): void;
+
     /**
      * 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
@@ -1010,6 +1022,28 @@ declare module '@xterm/xterm' {
      */
     attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;
 
+    /**
+     * Attaches a custom wheel event handler which is run before keys are
+     * processed, giving consumers of xterm.js control over whether to proceed
+     * or cancel terminal wheel events.
+     * @param customWheelEventHandler The custom WheelEvent handler to attach.
+     * This is a function that takes a WheelEvent, allowing consumers to stop
+     * propagation and/or prevent the default action. The function returns
+     * whether the event should be processed by xterm.js.
+     *
+     * @example A handler that prevents all wheel events while ctrl is held from
+     * being processed.
+     * ```ts
+     * term.attachCustomWheelEventHandler(ev => {
+     *   if (ev.ctrlKey) {
+     *     return false;
+     *   }
+     *   return true;
+     * });
+     * ```
+     */
+    attachCustomWheelEventHandler(customWheelEventHandler: (event: WheelEvent) => boolean): void;
+
     /**
      * Registers a link provider, allowing a custom parser to be used to match
      * and handle links. Multiple link providers can be used, they will be asked