Merge pull request #4844 from Tyriar/doc_override

Expose a documentOverride setting
xtermjs · Oct 13, 2023 · 4245283 · 4245283
2 parents 34017f3 + 41c6228
commit 4245283
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 0 deletions.
diff --git a/src/browser/Terminal.ts b/src/browser/Terminal.ts
@@ -398,6 +398,9 @@ export class Terminal extends CoreTerminal implements ITerminal {
     }
 
     this._document = parent.ownerDocument!;
+    if (this.options.documentOverride && this.options.documentOverride instanceof Document) {
+      this._document = this.optionsService.rawOptions.documentOverride as Document;
+    }
 
     // Create main element container
     this.element = this._document.createElement('div');

diff --git a/src/common/services/OptionsService.ts b/src/common/services/OptionsService.ts
@@ -18,6 +18,7 @@ export const DEFAULT_OPTIONS: Readonly<Required<ITerminalOptions>> = {
   cursorInactiveStyle: 'outline',
   customGlyphs: true,
   drawBoldTextInBrightColors: true,
+  documentOverride: null,
   fastScrollModifier: 'alt',
   fastScrollSensitivity: 5,
   fontFamily: 'courier-new, courier, monospace',

diff --git a/src/common/services/Services.ts b/src/common/services/Services.ts
@@ -217,6 +217,7 @@ export interface ITerminalOptions {
   cursorInactiveStyle?: CursorInactiveStyle;
   customGlyphs?: boolean;
   disableStdin?: boolean;
+  documentOverride?: any | null;
   drawBoldTextInBrightColors?: boolean;
   fastScrollModifier?: 'none' | 'alt' | 'ctrl' | 'shift';
   fastScrollSensitivity?: number;

diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts
@@ -89,6 +89,17 @@ declare module 'xterm' {
      */
     disableStdin?: boolean;
 
+    /**
+     * A {@link Document} to use instead of the one that xterm.js was attached
+     * to. The purpose of this is to improve support in multi-window
+     * applications where HTML elements may be references across multiple
+     * windows which can cause problems with `instanceof`.
+     *
+     * The type is `any` because using `Document` can cause TS to have
+     * performance/compiler problems.
+     */
+    documentOverride?: any | null;
+
     /**
      * Whether to draw bold text in bright colors. The default is true.
      */