feat(sdk): add vm methods for controlling the editor ui

[fvsch]

⚠️ This is a draft for @stackblitz/[email protected] and things might change.

Adds a number of methods to the SDK's VM interface, enabling some control of embedded projects at runtime.

All the VM methods return promises that may resolve to null or to a specific payload, or reject with an error message.

UI controls

• vm.editor.openFile: extend to accept multiple file paths
• vm.editor.setTheme: change the color scheme of the embed (light or dark)
• vm.editor.setView: change the primary UI view mode (default, editor or preview)
• vm.editor.showSidebar: show or hide the sidebar

Preview controls

• vm.preview.origin: changed type to indicate that it will be null for WebContainers-based projects. I'm also considering marking it as @deprecated, because it's only usable in EngineBlock projects, but we might have users of the SDK who actively rely on it and I’m not sure we want to spook them. Depends on if we want to remove it in v2.0?
• vm.preview.getUrl: allows retrieving the current preview URL. For EngineBlock projects, this is imprecise because it doesn't include the current path if modified by the user or the preview page. For WebContainer projects, it should be more precise (you get the correct path) but will reject when there is no previewed URL.
• vm.preview.setUrl: allows setting a new path for the current URL. The URL origin cannot be modified, so this cannot be used to show arbitrary web pages in the preview area. Some questions:
  • Naming: should we call it setPath instead, if it only accepts a path? I like having matching getUrl and setUrl, but the setUrl(path: string) signature might be confusing.
  • For WebContainers projects, we might want to relax this rule and allow providing a path and a port, which could be used to switch between two web servers.

Because the preview methods have different behavior in EngineBlock and WebContainers-based projects, and because we are not sure how stable they would be in practice and in the future (our implementation of setting, modifying or even getting the actual iframe location at runtime can easily bump into browser restrictions), I am marking them as @experimental. They would be marked experimental at least in 1.7.x, and probably until 2.0.

[sylwiavargas]

Naming: should we call it setPath instead, if it only accepts a path? I like having matching getUrl and setUrl, but the setUrl(path: string) signature might be confusing.

I agree with you - I'm much more in favor of setUrl because it feels predictable with getUrl.