sdk: export more types, add showSidebar option and vm.editor.setCurrentFile #1837

fvsch · 2022-04-17T11:22:00Z

Grab-bag of improvements for the upcoming 1.7.0 SDK release.

Fix the vm.editor.getUrl return value (we used Promise<string | null> but were returning Promise<{ url: string } | null>).
Add support for a new showSidebar: boolean option, translating to the URL parameter showSidebar=1 and showSidebar=0.
- (That would be our first boolean URL parameter to actually accept a negative value. This matches the existing vm.editor.showSidebar(boolean) method that we already support.
Add support for a new vm.editor.setCurrentFile method.
- This is not fully implemented yet (let alone deployed) on the editor side! Which is fine as long as we're in alpha.
- Marked as experimental for now, and the method or its description may change as we refine the actual implementation.
Slight refactoring of the RDC class to add more precise typing.
Export all the types defined in src/interfaces.ts instead only a select few.
- Main motivation was from user feedback that using e.g. EmbedOptions['view'] didn't return the type they wanted, since it returns UiViewOption | undefined instead of UiViewOption, and you have to use TypeScript shenanigans on top of that to remove the undefined part.
- Renamed a few types to slightly longer names with common patterns, e.g. UiView and UiTheme to UiViewOption and UiThemeOption. Since exporting those types makes them a public API, so that any change to those types would be a BREAKING change, I wanted to get the names explicit enough, even if that means a bit more verbosity.
- Before that I moved a few implementation-specific types used by the RDC and VM classes into src/rdc.ts and src/vm.ts.

…from array

fvsch

Some context for a few changes.

fvsch · 2022-04-17T11:23:36Z

sdk/src/connection.ts

@@ -1,4 +1,4 @@
-import { VM } from './VM';
+import { VM } from './vm';


Maybe that's obsessive of me, but I was twitching every time I saw VM.tsand RDC.ts in all caps alongside all our other lowercase modules. 😛

fvsch · 2022-04-17T12:24:35Z

sdk/src/constants.ts

+  'polymer',
+  'typescript',
+  'vue',
+] as const;


This array is used to warn users when they use an unsupported template type (with a console.warn), and is also used as the source of truth for the ProjectTemplate type:

type ProjectTemplate = typeof projectTemplates[number]; // 'angular-cli' | 'create-react-app' | 'html' | …

fvsch · 2022-04-17T12:27:40Z

sdk/src/index.ts

+  OpenFileOption,
+  UiThemeOption,
+  UiViewOption,
+} from './interfaces';


New typing feature: exporting more types from src/interfaces.ts

fvsch · 2022-04-17T12:29:43Z

sdk/src/index.ts

+  embedProjectId,
+  openGithubProject,
+  openProject,
+  openProjectId,


This is technically the same as what we had before with

import * as StackBlitzSDK from './lib'; export default StackBlitzSDK;

EXCEPT that if we add a new export to src/lib.ts, it won't automatically end up as part of our public API.
This forces us to be more explicit and import-then-export it from src/index.ts. Maybe a bit verbose, but more intentional and thus safer.

fvsch · 2022-04-17T12:32:32Z

sdk/src/interfaces.ts

-   * Hide the sidebar on page load.
-   *
-   * Users will still be able to open the sidebar by clicking one of the sidebar icons.
+   * Hide the ActivityBar (sidebar icons).


Tentatively fixed the description for the hideExplorer option.

It's hard to describe in non-jargony terms, and I'm guessing we added this arcane feature for some customer at one point that didn't want the sidebar or ActivityBar to show at all. This may become obsolete if we change the embed layout to use a drawer menu like the main layout does on small screen (either all the time in embeds, or only on small screens).

fvsch · 2022-04-17T12:35:07Z

sdk/src/interfaces.ts

   */
-  hideNavigation?: boolean;
+  showSidebar?: boolean;


This one is a bit hard to describe because it signals an intent BUT we may not respect it in some cases.

Especially on small screen widths (<1000px), we would hide the sidebar by default even if receiving showSidebar=1. I didn't describe the full implementation (which we're also tweaking right now), but used a comment that suggests we might do something different on small screens.

fvsch · 2022-04-17T12:42:03Z

sdk/src/params.ts

+  openFile: (value: Options['openFile']) => stringParams('file', value).join('&'),
+  theme: (value: Options['theme']) => enumParam('theme', ['light', 'dark'], value),
+  view: (value: Options['view']) => enumParam('view', ['preview', 'editor'], value),
+};


Refactored how we generate the URL query string.

This is a bit more indirect than what we had before (a single function going through each option with code like if (options.someOption) params.push('someOption='+options.someOption)), but it has two upsides:

We can reuse code used to validate parameter values depending on their type.

Using the Record<keyof Options, …> type, we make sure that we are handling all supported options and not forgetting one. When we add an option, TS forces us to add a generator or exclude that option name in type Options = Omit<…>.

fvsch · 2022-04-17T12:43:22Z

sdk/src/vm.ts

+          type: 'SDK_GET_PREVIEW_URL',
+          payload: {},
+        })
+        .then((data) => data?.url ?? null);


Fix for the issue where we were returning { url: string } | null and not string | null.

fvsch · 2022-04-17T12:47:50Z

sdk/src/vm.ts

@@ -153,6 +161,9 @@ export class VM {
     * @experimental
     */
    setUrl: (path: string = '/'): Promise<null> => {
+      if (typeof path !== 'string' || !path.startsWith('/')) {
+        throw new Error(`Invalid argument: expected a path starting with '/', got '${path}'`);
+      }


Having this method called setUrl when you can only pass a path and not a full URL is a bit misleading. The argument being called path was not enough to avoid one beta tester from trying to pass a full URL.

There are two possible fixes:

Change the method name to setPath or setUrlPath. (But we kinda like having matching getUrl and setUrl methods. I'd be open to setUrlPath, if we think that's a better choice.)

Or keep the method name as setUrl, and validate the input.

I went with the second option right now, but we can reconsider.

fvsch · 2022-04-17T13:20:48Z

sdk/src/vm.ts

+     * @since 1.7.0
+     * @experimental
+     */
+    setCurrentFile: (path: string): Promise<null> => {


New feature that is useful for multi-step demos with more than one file open at a time (e.g. 2 files in 2 side-by-side panes).

In a multi-step demo, it can be useful to explicitly set the currently focused file out of all the files that are open in tabs, so that:

That file gets revealed in the file explorer sidebar (e.g. expanding the folder hierarchy to reveal that file).

And to make sure that the file's tab gets the "open" state, if it's one of several tabs in a pane.

Right now I'm erring on the side of not opening an editor tab for the file if there isn't one already. Why? Because that would raise complex questions that we could only answer with questionable defaults.

Let's say there are open tabs (and maybe several panes) already:

Do we keep the existing tabs and just open a new one? Hmm probably.

Okay but what if at least one of the existing tabs is in "preview" mode (which will happen when using openFile to open one or several files initially): do we replace one of the tabs then? (Technically we should, but that might be an unexpected result!)

And if we have several panes, where do we add the new tab? First pane? The pane which hosts the currently focused editor tab (if any)? Will that make the result unpredictable, depending on user actions?

In a multi-step demo, it's probably better for embedders to explicitly call:

// Reset the open tabs, even if that was the state used in the previous demo step, // because the user may have interacted with the editor and closed some tabs! await vm.editor.openFile(['src/foo.js', 'src/bar.js']); // Select the right-side file await vm.editor.setCurrentFile('src/bar.js');

ggdaltoso

Thanks for implementing these features and helping with all types ✨

ggdaltoso · 2022-04-18T19:55:10Z

sdk/src/helpers.ts

@@ -22,62 +21,14 @@ export function embedUrl(route: string, options?: EmbedOptions) {
  if (options && typeof options === 'object') {
    Object.assign(config, options);
  }
-  return `${getOrigin(config)}${route}${buildProjectQuery(config)}`;
+  return `${getOrigin(config)}${route}${buildParams(config)}`;


Thanks for refactoring this!

…ntFile (#1837) * fix vm.editor.getUrl returning an object and not a string * improve types of the RDC class * export all types from src/interfaces.ts * refactor URL param generation * add showSidebar option * sdk: add experimental vm.editor.setCurrentFile * bump version to 1.7.0-alpha.3

Florens Verschelde added 5 commits April 14, 2022 23:43

sdk: fix vm.editor.getUrl returning an object and not a string

823420a

sdk: improve types of the RDC class

f099742

sdk: export all types from src/interfaces.ts

a810a83

sdk: refactor URL param generation, and add showSidebar option

ed3e0f6

sdk: bump version to 1.7.0-alpha.3

604569b

fvsch requested review from sulco and ggdaltoso April 17, 2022 11:22

Florens Verschelde added 2 commits April 17, 2022 13:33

sdk: list exported types and methods explicitly

93d74ae

sdk: move constants to their own module, derive ProjectTemplate type …

08ff58a

…from array

fvsch commented Apr 17, 2022

View reviewed changes

sdk: add experimental vm.editor.setCurrentFile

0e28409

fvsch force-pushed the fvsch/sdk-1-7-typings-and-show-sidebar branch from 3ef777a to 0e28409 Compare April 17, 2022 13:15

fvsch commented Apr 17, 2022

View reviewed changes

fvsch changed the title ~~sdk: export more types, fix a couple typing issues, add showSidebar option~~ sdk: export more types, add showSidebar option and vm.editor.setCurrentFile Apr 17, 2022

ggdaltoso approved these changes Apr 18, 2022

View reviewed changes

sdk: style: use UPPER_SNAKE_CASE for constants

ec2b26e

fvsch merged commit 07604d2 into sdk-1-7 Apr 18, 2022

fvsch mentioned this pull request May 7, 2022

Release @stackblitz/[email protected] #1860

Merged

fvsch deleted the fvsch/sdk-1-7-typings-and-show-sidebar branch June 9, 2022 13:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

sdk: export more types, add showSidebar option and vm.editor.setCurrentFile #1837

sdk: export more types, add showSidebar option and vm.editor.setCurrentFile #1837

fvsch commented Apr 17, 2022 •

edited

Loading

fvsch left a comment

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022

fvsch Apr 17, 2022 •

edited

Loading

ggdaltoso left a comment

ggdaltoso Apr 18, 2022

		@@ -1,4 +1,4 @@
		import { VM } from './VM';
		import { VM } from './vm';

sdk: export more types, add showSidebar option and vm.editor.setCurrentFile #1837

sdk: export more types, add showSidebar option and vm.editor.setCurrentFile #1837

Conversation

fvsch commented Apr 17, 2022 • edited Loading

fvsch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fvsch Apr 17, 2022 • edited Loading

Choose a reason for hiding this comment

ggdaltoso left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fvsch commented Apr 17, 2022 •

edited

Loading

fvsch Apr 17, 2022 •

edited

Loading