Investigate better UX for previewing things

[jrieken]

~~People use previewHtml for building UI which does't work well. We should investigate different options~~~

We will tackle the problem from the other side: #22068 (comment)

[daviwil]

Looking forward to this!

[smelukov]

Maybe the better solution is provided a possibility to build own UI inside a tab through DOM-access (like in Atom).
Something like DOMContentProvider or like that...
Or access to DOM of previewHtml

For example: if I want to insert an iframe inside a tab and get access to its contentWindow-property, then previewHtml is useless for this task. But if I'll have access to DOM of a tab or to DOM of rendered HTML, then this task will have a simple solution.

[smelukov]

Hi! Is there any chance to get a possibility to create an iframe inside a tab? :)

[jrieken]

FYI - I have updated the title of this issue to better reflect what we are shooting for. We know that some people badly wish for customisable and extendable UI. Unfortunately that is still a major challange and we tackle things one at a time.

Today, the previewHtml-command is an ok workaround. It has many gaps and problems and won't be the UX story of the future. To name a few: webview restarts when reparented, webview as many bugs in general, webview can swallow events like drag which we need, key events need to be captured and send "upwards" etc, etc

Initially the previewHtml-command has been added to allow the markdown extension to preview content. Other extensions have implemented the same pattern, e.g preview svg. However, some extensions also have started to implement rich UIs with this, e.g mssql. This brought us into a situation in which evolving the initial preview functionality often breaks the UX-extensibility usage.

The idea is to make better API for previewing markdown or more general for previewing derived resources, like html from markdown, html from svg, or JS from TS. This would allow for some improvements like

• simplified synchronised scrolling
• side-by-side preview inside one tab
• synchronised search
• restoring the editor with a preview-view
• etc

[jrieken]

fyi @mjbvz

[jrieken]

Mockup showing in-editor-peview of something (note that source-view and that preview share the same editor/tab)

Gif how iaWriter sync scrolling from both sides and how it 'zooms' the preview when moving the sash

From the API point to view we need to design a provider that, given a document, can return a preview. The preview is either an URI to another source file, e.g. JS from TS, or html sources that should be rendered. Details are to be defined, but in general something along these lines

interface Preview {
  // allow for scrolling sync, some bidirectional line mapping 
  // allow for preview-kind, e.g. source or html-rendered
  // ...
}

interface PreviewProvider {
  providePreview(document: TextDocument): ProviderResult<Preview>;
}

[mjbvz]

Yes I'm very much in favor of standardizing the preview functionality. A preview provider was one option that we considered when originally looking at implementing markdown scroll synchronization: #5047 (comment)

Besides previewing documents like markdown, the other case I'd be interested in is extension contributed previews of binary/asset files, such as texture files or 3D files

[jrieken]

Besides previewing documents like markdown, the other case I'd be interested in is extension contributed previews of binary/asset files, such as texture files or 3D files

Question is if that would require them to run JS code or if we can build a standard preview without allowing extensions to execute JS. I'd be happy if we can avoid the web view for the new world

[jrieken]

Investigation has finished. We keep this issue around for when we start coding. fyi @egamma

[naillizard]

+1

[zeh]

I wonder if allowing for some common context between the extension scope and the preview scope is part of this investigation. Currently there's no way for the extension to "talk" to the preview container, save for "updating" it via the content provider; for allowing command-style links from its content; and for scrolling.

My rationale is this: I have an extension that allows code editing in one window. When the developer runs the code (via F5), it starts the local debugger and opens a new preview tab with a JS-based emulator inside the tab. Then, whenever the code changes, the preview tab should also change, but keeping its current state rather than refreshing. Likewise, the extension/debugger instance should be able to control the state of the emulator by issuing commands such as pause, play, step, etc or by getting data from it such as watched variables.

The features proposed above sound like nice additions, but I don't see anything that allows this bidirectional communication between the extension code and the preview code. And I could see that being used in many other shapes and forms, not just for fairly static "preview" windows. I wonder if there's any plan in that regard.

Now, to be fair, my use case above isn't entirely impossible: I'm currently solving it with a WebSocket server (ran from the extension context) and client (ran from the preview context). It works, but it's a bit awkward and it adds a few too many moving pieces to the whole endeavor where, ideally, none shall exist. This idea is based on what the LaTeX Preview extension also does for interaction; and mssql uses an iframe pointing to a webserver running from the extension. So I'm probably not the only one who thinks some of this is necessary (or is misinformed enough about some other work around).

[Splike]

+1

[zeh]

For reference, this now seems to be possible with the new webview API. A sample extension already exists.

So I believe this issue can be closed as this functionality is now available. cc @jrieken @egamma

[telamonian]

I saw the coder cat sample extension, and I also looked over the webview and custom editor API. I'm still a bit confused, though. Is there now enough extension points in vscode to make it practical for someone to build the kind of one-tab side-by-side markdown editor/preview that @jrieken mentioned:

or that intellij has:

or is this still a pipe dream?

[telamonian]

Lately I've been trying to migrate from intellij to vscode. For the most part it's been great, but I'm finding the way that vscode opens previews for markdown, svg, etc in a new editor group to be kind of hard to deal with. In vscode after I open, say, a markdown preview, the next code file I open then ends up in the new editor group that was created for the markdown preview. This creates a UX problem when my intent was only to preview some markdown and then go back to editing code. intellij's approach of having editor and preview encapsulated into one tab is much nicer

[keshann93]

anyone still looking for a markdown preview/editor for vscode, tryout this extension

[mjbvz]

This should be covered by the custom editor api that was shipped in VS Code 1.46

Please file new issues if you find that any features/api is missing from custom editors

[jrieken]

Please file new issues if you find that any features/api is missing from custom editors

This is all about a text editor with a webview to its side (but still being a single logical workbench editor). Custom editors cannot really do that because there is no way they can drive a Monaco editor the way we do

[mjbvz]

@jrieken It may make sense to split this out into separate proposals. We've discussed allowing custom editors to mark themselves as "beside" so that they automatically open in a split view next to the text editor

[DanTup]

Would these have to be custom editors? Or could it also support TextDocumentContentProvider?

I was playing with an idea to show the current code file with generated code expanded as a preview to the side (since there aren't any APIs for us to show read-only generated code "inline" in the editor, and get full navigation/semantic token support). It seems like @mjbvz's comment above with support for TextDocumentContentProvider might do it (and if done right, might even allow debugging stepping through the generated code while keeping the two together?).

[bpasero]

With #132651 it is possible to split an editor into 2 in the same group:

While what is pushed now is limiting to opening the same editor side by side, #36700 would allow this for any 2 editors.

There is nothing technical blocking us from simply putting a text file to the left and a preview editor to the right as this hack shows:

But there are some questions:

• how would an extension API look like for markdown to open a preview like that
• the preview editor is not syncing with the text document, so whatever magic we do there needs to expand to side-by-side-editors which probably needs extension API too
• how would a user be able to trigger this UI, should it be another action in the editor toolbar for previewing or even be the default?

[mjbvz]

@bpasero Trying to support webviews is tough since webviews aren't tied directly to a resource (at least not at the vscode api layer). Maybe we can make that functionality specific to custom editors

To start, can we create a command that opens the current resource in a split view with the text editor on the left and default custom editor on the right? That seems possible with the work you've been doing

Longer term, we should also likely allow users to configure if a resource opens in this split view by default, and potentially let extensions create editors in split mode by default as well

[DanTup]

Maybe we can make that functionality specific to custom editors

Could TextDocumentContentProvider be supported too? I'd like to show a preview of code with generated code included, and this would work great (it's readonly, and has other functionality like hovers, navigation, etc.). Building a custom editor just to show another code view would be pretty clunky.

[bpasero]

@mjbvz to clarify how the side by side editor works: you can literally put any editor (anything that extends EditorPane) into either sides. The side by side editor is essentially a host of 2 full editors that can be independent from each other.

There is a bit of a challenge how this editor is being accessed from other components because components have to be aware that there is a left and a right side, so this would probably need a bit of adoption going forward. In other words, any code that does IEditorService.activeEditor and Co will need to check for side by side editor.

To start, can we create a command that opens the current resource in a split view with the text editor on the left and default custom editor on the right? That seems possible with the work you've been doing

Yeah possible. Any kind of editor can be opened to the side. An alternative idea I had was to add a command that would allow you to pick an editor from quick open to put to the side of the active editor. But that requires that you have opened a markdown preview before.