[Feature Request] Document z-index usage and add some logic to it

[Prinzhorn]

Context

• [X] This issue is not a bug report. (please use a different template for reporting a bug)
• [X] This issue is not a duplicate of an existing issue. (please use the search to find existing issues)

Description

z-index across Monaco appears to not follow any logic. I'm putting a full-screen overlay over the editor and just realized you can still drag the handle between the two halfs of the diff editor. Looking at the CSS it has a z-index of 35:

.monaco-sash {
    z-index: 35;
}

I'm sure I will eventually run into more issue, e.g. with modal overlays or my fixed positioned autocomplete results.

Searching through the Monaco CSS shows z-indexes ranging from 1 to 10000 with no apparent logic (e.g. 5, 10, 40, 41, 50, 100, 2500, 10000).

In the app I'm currently working on I have cleanly structured z-index like this:

:root {
  --z-index-grid-header-footer: 1;
  --z-index-main-menu: 2;
  --z-index-spinner-overlay: 3;
  --z-index-resize-handle: 4;
  --z-index-suggestions: 5;
  --z-index-dialog: 6;
  --z-index-help: 7;
  --z-index-toasts: 8;
}

Now I could go ahead and change them from 10001 to 10008 to make sure they are always on top of Monaco (that's exactly the benefit of having them in a central place). But what if tomorrow Monaco adds an element with a z-index of 20000? Or why not 999999?

Any thoughts on how to make embedding Monaco more predictable? I assume the current state has grown historically and is depth from VS Code. This has caused problems in the past https://github.com/microsoft/monaco-editor/issues/2203

[mike-luabase]

@Prinzhorn did you figure out a solution for this?

[Prinzhorn]

@mike-luabase I've ignored it for now, so no I didn't

[hediet]

What solution do you propose, @Prinzhorn? I think we'd be open for a PR for this!

[Prinzhorn]

I have no idea what others are doing with their z-indexes and monaco is also in a unique position that it's not a library itself but extracted from vscode and vscode likely has z-indexes on its own that interact with monaco. Other libraries allow changing z-index either on a JS API level or via CSS variables, e.g. https://github.com/zerodevx/svelte-toast/pull/40

Here's how this could work for monaco. All -default- CSS variables are defined my monaco itself, those without -default- can be used to override.

1. Migrate all existing z-index to a variable with a default value, e.g.

:root {
    --monaco-default-z-index-sash: 35;
    --monaco-default-z-index-sash-handle: 100;
    --monaco-default-z-index-diff-editor-overview-diff-overview: 9;
    --monaco-default-z-index-diff-editor-overview-diff-viewport: 10;
   /* All other z-indexes that monaco has, between 1 to 10000 */
}

2. Now we can normalize them without breaking ordering.

:root {
    --monaco-default-z-index-diff-editor-overview-diff-overview: 1;
    --monaco-default-z-index-diff-editor-overview-diff-viewport: 2;
    --monaco-default-z-index-sash: 3;
    --monaco-default-z-index-sash-handle: 4;
}

3. Looks like a counter to me, let's use a counter base value:

:root {
    --monaco-default-z-index-base: var(--monaco-z-index-base, 1);
    --monaco-default-z-index-diff-editor-overview-diff-overview: calc(var(--monaco-default-z-index-base) + 1);
    --monaco-default-z-index-diff-editor-overview-diff-viewport: calc(var(--monaco-default-z-index-base) + 2);
    --monaco-default-z-index-sash: calc(var(--monaco-default-z-index-base) + 3);
    --monaco-default-z-index-sash-handle: calc(var(--monaco-default-z-index-base) + 4);
}

4. Actually use the variables in their original magic number place:

.monaco-diff-editor .diffOverview {
	z-index: var(--monaco-z-index-diff-editor-overview-diff-overview, var(--monaco-default-z-index-diff-editor-overview-diff-overview));
}

What did we win?

1. For the most common use case (e.g. you treat the embedded monaco editor as a single unit that should be consistent in itself but you want to be able to put things behind or in front): You just define --monaco-z-index-base (which monaco doesn't define). So you can have monaco start at any index, e.g. 100 and it'll just occupy the next dozen or so.
2. If you need more control for individual elements you can opt into defining individual vars such as --monaco-z-index-diff-editor-overview-diff-overview to override the default.

I think the counter on its own would not be enough. There are elements that monaco positions fixed and you might want to have your own elements between the base editor and those elements. If that's not the case then a simplified version of the above with just a counter would be enough and consumers of monaco can define their own --monaco-z-index-base and be good. In my case I could move my z-index around to make room for monaco between --z-index-main-menu and --z-index-spinner-overlay.

Maybe we can get away with two counters (for the base editor and fixed elements) and get rid of overriding individual indexes, which sounds super fragile anyway. In the best case a single counter is enough and consumers of monaco don't have to worry about anything else. But the second counter could also easily depend on the first so that we're back at having only to worry about one for most use cases.

[dlech]

The solution/workaround I came up with was to assign a z-index like this:

.monaco-editor .overflow-guard  {
    z-index: 1;
}

.my-content-that-overlays-editor {
    z-index: 2;
}

.monaco-editor .overflowingContentWidget  {
    z-index: 3;
}

.my-modal-dialogs {
    z-index: 4;
}

Basically, this flattens all of monaco editor into two layers that can be incorporated into an external layer scheme instead of having to deal with all of the various layers defined in vscode/monaco.