Core: Allow overriding WebView and UrlStore

code/lib/preview-web/src/Preview.tsx

@@ -42,7 +42,7 @@ const STORY_INDEX_PATH = './index.json';
 
 export type MaybePromise<T> = Promise<T> | T;
 
-export class Preview<TFramework extends AnyFramework> {
+export class Preview<TFramework extends AnyFramework, TRootElement = HTMLElement> {
   serverChannel?: Channel;
 
   storyStore: StoryStore<TFramework>;
@@ -51,9 +51,9 @@ export class Preview<TFramework extends AnyFramework> {
 
   importFn?: Store_ModuleImportFn;
 
-  renderToDOM?: Store_RenderToDOM<TFramework>;
+  renderToDOM?: Store_RenderToDOM<TFramework, TRootElement>;
 
-  storyRenders: StoryRender<TFramework>[] = [];
+  storyRenders: StoryRender<TFramework, TRootElement>[] = [];
 
   previewEntryError?: Error;
 
@@ -81,7 +81,9 @@ export class Preview<TFramework extends AnyFramework> {
     // getProjectAnnotations has been run, thus this slightly awkward approach
     getStoryIndex?: () => Store_StoryIndex;
     importFn: Store_ModuleImportFn;
-    getProjectAnnotations: () => MaybePromise<Store_WebProjectAnnotations<TFramework>>;
+    getProjectAnnotations: () => MaybePromise<
+      Store_WebProjectAnnotations<TFramework, TRootElement>
+    >;
   }) {
     // We save these two on initialization in case `getProjectAnnotations` errors,
     // in which case we may need them later when we recover.
@@ -106,7 +108,7 @@ export class Preview<TFramework extends AnyFramework> {
   }
 
   getProjectAnnotationsOrRenderError(
-    getProjectAnnotations: () => MaybePromise<Store_WebProjectAnnotations<TFramework>>
+    getProjectAnnotations: () => MaybePromise<Store_WebProjectAnnotations<TFramework, TRootElement>>
   ): Store_PromiseLike<ProjectAnnotations<TFramework>> {
     return SynchronousPromise.resolve()
       .then(getProjectAnnotations)
@@ -132,7 +134,9 @@ export class Preview<TFramework extends AnyFramework> {
   }
 
   // If initialization gets as far as project annotations, this function runs.
-  initializeWithProjectAnnotations(projectAnnotations: Store_WebProjectAnnotations<TFramework>) {
+  initializeWithProjectAnnotations(
+    projectAnnotations: Store_WebProjectAnnotations<TFramework, TRootElement>
+  ) {
     this.storyStore.setProjectAnnotations(projectAnnotations);
 
     this.setInitialGlobals();
@@ -305,11 +309,11 @@ export class Preview<TFramework extends AnyFramework> {
   // main to be consistent with the previous behaviour. In the future,
   // we will change it to go ahead and load the story, which will end up being
   // "instant", although async.
-  renderStoryToElement(story: Store_Story<TFramework>, element: HTMLElement) {
+  renderStoryToElement(story: Store_Story<TFramework>, element: TRootElement) {
     if (!this.renderToDOM)
       throw new Error(`Cannot call renderStoryToElement before initialization`);
 
-    const render = new StoryRender<TFramework>(
+    const render = new StoryRender<TFramework, TRootElement>(
       this.channel,
       this.storyStore,
       this.renderToDOM,
@@ -329,9 +333,9 @@ export class Preview<TFramework extends AnyFramework> {
 
   async teardownRender(
     render:
-      | StoryRender<TFramework>
-      | TemplateDocsRender<TFramework>
-      | StandaloneDocsRender<TFramework>,
+      | StoryRender<TFramework, TRootElement>
+      | TemplateDocsRender<TFramework, TRootElement>
+      | StandaloneDocsRender<TFramework, TRootElement>,
     { viewModeChanged }: { viewModeChanged?: boolean } = {}
   ) {
     this.storyRenders = this.storyRenders.filter((r) => r !== render);

code/lib/preview-web/src/PreviewWeb.tsx

@@ -41,6 +41,8 @@ import { PREPARE_ABORTED } from './render/Render';
 import { StoryRender } from './render/StoryRender';
 import { TemplateDocsRender } from './render/TemplateDocsRender';
 import { StandaloneDocsRender } from './render/StandaloneDocsRender';
+import { SelectionStore } from './SelectionStore';
+import { View } from './View';
 
 const { window: globalWindow } = global;
 
@@ -49,33 +51,45 @@ function focusInInput(event: Event) {
   return /input|textarea/i.test(target.tagName) || target.getAttribute('contenteditable') !== null;
 }
 
-type PossibleRender<TFramework extends AnyFramework> =
-  | StoryRender<TFramework>
-  | TemplateDocsRender<TFramework>
-  | StandaloneDocsRender<TFramework>;
+type PossibleRender<TFramework extends AnyFramework, TRootElement = HTMLElement> =
+  | StoryRender<TFramework, TRootElement>
+  | TemplateDocsRender<TFramework, TRootElement>
+  | StandaloneDocsRender<TFramework, TRootElement>;
 
-function isStoryRender<TFramework extends AnyFramework>(
-  r: PossibleRender<TFramework>
-): r is StoryRender<TFramework> {
+function isStoryRender<TFramework extends AnyFramework, TRootElement>(
+  r: PossibleRender<TFramework, TRootElement>
+): r is StoryRender<TFramework, TRootElement> {
   return r.type === 'story';
 }
 
-export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramework> {
-  urlStore: UrlStore;
+export class PreviewWeb<
+  TFramework extends AnyFramework,
+  TRootElement = HTMLElement
+> extends Preview<TFramework, TRootElement> {
+  selectionStore: SelectionStore;
 
-  view: WebView;
+  view: View<TRootElement>;
 
   previewEntryError?: Error;
 
   currentSelection?: Store_Selection;
 
-  currentRender?: PossibleRender<TFramework>;
+  currentRender?: PossibleRender<TFramework, TRootElement>;
 
-  constructor() {
+  constructor({
+    // I'm not quite sure how to express this -- if you don't pass a view, you need to ensure
+    // this is a PreviewWeb<..., HTMLElement>. If you pass one, it can be parameterized however you want,
+    // as long as it is consistent.
+    view = new WebView() as any,
+    selectionStore = new UrlStore(),
+  }: {
+    view: View<TRootElement>;
+    selectionStore: SelectionStore;
+  }) {
     super();
 
-    this.view = new WebView();
-    this.urlStore = new UrlStore();
+    this.view = view;
+    this.selectionStore = selectionStore;
   }
 
   setupListeners() {
@@ -88,7 +102,9 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
     this.channel.on(PRELOAD_ENTRIES, this.onPreloadStories.bind(this));
   }
 
-  initializeWithProjectAnnotations(projectAnnotations: Store_WebProjectAnnotations<TFramework>) {
+  initializeWithProjectAnnotations(
+    projectAnnotations: Store_WebProjectAnnotations<TFramework, TRootElement>
+  ) {
     return super
       .initializeWithProjectAnnotations(projectAnnotations)
       .then(() => this.setInitialGlobals());
@@ -98,7 +114,7 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
     if (!this.storyStore.globals)
       throw new Error(`Cannot call setInitialGlobals before initialization`);
 
-    const { globals } = this.urlStore.selectionSpecifier || {};
+    const { globals } = this.selectionStore.selectionSpecifier || {};
     if (globals) {
       this.storyStore.globals.updateFromPersisted(globals);
     }
@@ -121,12 +137,12 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
     if (!this.storyStore.storyIndex)
       throw new Error(`Cannot call selectSpecifiedStory before initialization`);
 
-    if (!this.urlStore.selectionSpecifier) {
+    if (!this.selectionStore.selectionSpecifier) {
       this.renderMissingStory();
       return;
     }
 
-    const { storySpecifier, args } = this.urlStore.selectionSpecifier;
+    const { storySpecifier, args } = this.selectionStore.selectionSpecifier;
     const entry = this.storyStore.storyIndex.entryFromSpecifier(storySpecifier);
 
     if (!entry) {
@@ -155,10 +171,10 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
     }
 
     const { id: storyId, type: viewMode } = entry;
-    this.urlStore.setSelection({ storyId, viewMode });
-    this.channel.emit(STORY_SPECIFIED, this.urlStore.selection);
+    this.selectionStore.setSelection({ storyId, viewMode });
+    this.channel.emit(STORY_SPECIFIED, this.selectionStore.selection);
 
-    this.channel.emit(CURRENT_STORY_WAS_SET, this.urlStore.selection);
+    this.channel.emit(CURRENT_STORY_WAS_SET, this.selectionStore.selection);
 
     await this.renderSelection({ persistedArgs: args });
   }
@@ -173,7 +189,7 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
   }) {
     await super.onGetProjectAnnotationsChanged({ getProjectAnnotations });
 
-    if (this.urlStore.selection) {
+    if (this.selectionStore.selection) {
       this.renderSelection();
     }
   }
@@ -192,7 +208,7 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
       this.channel.emit(SET_INDEX, await this.storyStore.getSetIndexPayload());
     }
 
-    if (this.urlStore.selection) {
+    if (this.selectionStore.selection) {
       await this.renderSelection();
     } else {
       // Our selection has never applied before, but maybe it does now, let's try!
@@ -213,13 +229,13 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
   async onSetCurrentStory(selection: { storyId: StoryId; viewMode?: ViewMode }) {
     await this.storyStore.initializationPromise;
 
-    this.urlStore.setSelection({ viewMode: 'story', ...selection });
-    this.channel.emit(CURRENT_STORY_WAS_SET, this.urlStore.selection);
+    this.selectionStore.setSelection({ viewMode: 'story', ...selection });
+    this.channel.emit(CURRENT_STORY_WAS_SET, this.selectionStore.selection);
     this.renderSelection();
   }
 
   onUpdateQueryParams(queryParams: any) {
-    this.urlStore.setQueryParams(queryParams);
+    this.selectionStore.setQueryParams(queryParams);
   }
 
   async onUpdateGlobals({ globals }: { globals: Globals }) {
@@ -256,7 +272,7 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
   async renderSelection({ persistedArgs }: { persistedArgs?: Args } = {}) {
     const { renderToDOM } = this;
     if (!renderToDOM) throw new Error('Cannot call renderSelection before initialization');
-    const { selection } = this.urlStore;
+    const { selection } = this.selectionStore;
     if (!selection) throw new Error('Cannot call renderSelection as no selection was made');
 
     const { storyId } = selection;
@@ -289,12 +305,12 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
       await this.teardownRender(this.currentRender);
     }
 
-    let render: PossibleRender<TFramework>;
+    let render: PossibleRender<TFramework, TRootElement>;
     if (entry.type === 'story') {
-      render = new StoryRender<TFramework>(
+      render = new StoryRender<TFramework, TRootElement>(
         this.channel,
         this.storyStore,
-        (...args) => {
+        (...args: Parameters<typeof renderToDOM>) => {
           // At the start of renderToDOM we make the story visible (see note in WebView)
           this.view.showStoryDuringRender();
           return renderToDOM(...args);
@@ -304,9 +320,17 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
         'story'
       );
     } else if (entry.standalone) {
-      render = new StandaloneDocsRender<TFramework>(this.channel, this.storyStore, entry);
+      render = new StandaloneDocsRender<TFramework, TRootElement>(
+        this.channel,
+        this.storyStore,
+        entry
+      );
     } else {
-      render = new TemplateDocsRender<TFramework>(this.channel, this.storyStore, entry);
+      render = new TemplateDocsRender<TFramework, TRootElement>(
+        this.channel,
+        this.storyStore,
+        entry
+      );
     }
 
     // We need to store this right away, so if the story changes during
@@ -385,20 +409,24 @@ export class PreviewWeb<TFramework extends AnyFramework> extends Preview<TFramew
 
     if (isStoryRender(render)) {
       if (!render.story) throw new Error('Render has not been prepared!');
-      this.storyRenders.push(render as StoryRender<TFramework>);
-      (this.currentRender as StoryRender<TFramework>).renderToElement(
+      this.storyRenders.push(render as StoryRender<TFramework, TRootElement>);
+      (this.currentRender as StoryRender<TFramework, TRootElement>).renderToElement(
         this.view.prepareForStory(render.story)
       );
     } else {
       this.currentRender.renderToElement(
         this.view.prepareForDocs(),
-        this.renderStoryToElement.bind(this)
+        // This argument is used for docs, which is currently only compatible with HTMLElements
+        this.renderStoryToElement.bind(this) as PreviewWeb<
+          TFramework,
+          HTMLElement
+        >['renderStoryToElement']
       );
     }
   }
 
   async teardownRender(
-    render: PossibleRender<TFramework>,
+    render: PossibleRender<TFramework, TRootElement>,
     { viewModeChanged = false }: { viewModeChanged?: boolean } = {}
   ) {
     this.storyRenders = this.storyRenders.filter((r) => r !== render);

code/lib/preview-web/src/SelectionStore.ts

@@ -0,0 +1,12 @@
+/* eslint-disable camelcase */
+import type { Store_SelectionSpecifier, Store_Selection } from '@storybook/types';
+
+export abstract class SelectionStore {
+  public selectionSpecifier: Store_SelectionSpecifier | null;
+
+  public selection?: Store_Selection;
+
+  abstract setSelection(selection: Store_Selection): void;
+
+  abstract setQueryParams(queryParams: qs.ParsedQs): void;
+}

code/lib/preview-web/src/UrlStore.ts

@@ -4,6 +4,7 @@ import qs from 'qs';
 import type { ViewMode, Store_SelectionSpecifier, Store_Selection } from '@storybook/types';
 
 import { parseArgsParam } from './parseArgsParam';
+import { SelectionStore } from './SelectionStore';
 
 const { history, document } = global;
 
@@ -84,12 +85,13 @@ export const getSelectionSpecifierFromPath: () => Store_SelectionSpecifier | nul
   return null;
 };
 
-export class UrlStore {
+export class UrlStore extends SelectionStore {
   selectionSpecifier: Store_SelectionSpecifier | null;
 
   selection?: Store_Selection;
 
   constructor() {
+    super();
     this.selectionSpecifier = getSelectionSpecifierFromPath();
   }
 

code/lib/preview-web/src/View.ts

@@ -0,0 +1,25 @@
+/* eslint-disable camelcase */
+import type { Store_Story } from '@storybook/types';
+
+export abstract class View<TRootElement> {
+  // Get ready to render a story, returning the element to render to
+  abstract prepareForStory(story: Store_Story<any>): TRootElement;
+
+  abstract prepareForDocs(): TRootElement;
+
+  abstract showErrorDisplay({ message = '', stack = '' }): void;
+
+  abstract showNoPreview(): void;
+
+  abstract showPreparingStory({ immediate = false }): void;
+
+  abstract showPreparingDocs(): void;
+
+  abstract showMain(): void;
+
+  abstract showDocs(): void;
+
+  abstract showStory(): void;
+
+  abstract showStoryDuringRender(): void;
+}