Add initial decorations API

[akariv]

Following the discussion in #3274

Here's a simple decorations API which adds the ability to add custom 'decorations' on top of the terminal layers, without interfering with the buffer, selections or the cursor.

API is as follows:

export interface IDecorationService {
  serviceBrand: undefined;

  addDecoration(element: IDecorationElement): IDecorationHandle;
  removeDeoration(handle: IDecorationHandle): boolean;
  forEachDecoration(callback: (decoration: IDecorationElement) => boolean) : void;
  clearDecorations(): number;
}

export type IDecorationHandle = number;
interface IDecorationElement {
  startColumn: number;
  endColumn: number;
  startRow: number;
  endRow: number;
  fillStyle: string | CanvasGradient | CanvasPattern;
  strokeStyle: string | CanvasGradient | CanvasPattern;
}

This is my first contribution to this code base so please review carefully :)

---

Part of #1852

[Tyriar]

Very cool 🙂

[Tyriar]

I was thinking to make this as flexible as possible we would just give correctly positioned DOM elements to the user and the decorations system would be completely separate from the renderers. While we would sacrifice some performance here, we would get a lot of flexibility and ease of development since we don't need to implement it separately for webgl and DOM as well.

[akariv]

So just to make sure I understand you correctly - addDecoration would return an Element (with position: absolute under the Terminal's element), in which the user would be able to add any content they desire. DecorationsService would then manage the top/left/visibility options for each element. Correct?

[Tyriar]

Yep that's right.

visibility options

I imagine it would detach/reattach decorations that have scrolled out/in of the viewport.

[mofux]

IMHO both cases should be considered.

Inline Decoration
I think the decoration should be able to provide an inline cell style via an API (which allows to set / overwrite the background, foreground, italic, bold, underline styles). The renderer should be responsible for rendering this type of cell modification. A use-case for this kind of decoration is the rendering of underlines for Hyperlinks.

Overlay Decoration
In addition to that, a decoration should also allow to attach a custom HTML element to it. In this case the HTML Element will be rendered in a separate HTML Layer that is synchronised with the viewport. The HTML Element will by default resize to the selected range. A use-case for this kind of decoration is the hover overlay (Follow Link) when hovering a Hyperlink. This would also be the preferred choice to solve #3274

[Tyriar]

We could always add inline decorations after if we had the time to invest by adding a type? in a backwards compatible way. I like the idea of eventually being able to change both text and underline color for link hovers like how the editor in VS Code does it. Perhaps going with an IDecorationOptions is more forward thinking:

interface IDecorationOptions {
  range: IBufferRange;
  type?: a | b;
}
registerDecoration(options: IDecorationOptions): IDecoration;

[Tyriar]

Don't think we need a return type here?

[akariv]

Sort of success value for removal - I can remove it.

[Tyriar]

We've started moving towards returning IDisposables for things like this which makes it very convenient to remove the decoration. So something more like this is what I think we should go with:

registerDecoration(range: IBufferRange): IDecoration;
interface IDecoration extends IDisposable {
  // This uses a setter and is implemented by the core so changes can
  // be applied immediately
  range: IBufferRange;
  // This will give ultimate flexibility, perf will probably be fine unless the terminal is covered in decorations
  readonly element: HTMLElement;
}

[akariv]

👍

[Tyriar]

The actual API is declared in xterm.d.ts so the new interface will need to go there.

[Tyriar]

Closing out as this is stale and needs a pretty big rework