UI: refactor Canvas component so we can improve types for PREVIEW addons and TAB addons

code/lib/manager-api/src/modules/stories.ts

@@ -18,6 +18,7 @@ import type {
   StoryPreparedPayload,
   DocsPreparedPayload,
   API_DocsEntry,
+  API_ViewMode,
 } from '@storybook/types';
 import {
   PRELOAD_ENTRIES,
@@ -59,7 +60,6 @@ const STORY_INDEX_PATH = './index.json';
 type Direction = -1 | 1;
 type ParameterName = string;
 
-type ViewMode = 'story' | 'info' | 'settings' | string | undefined;
 type StoryUpdate = Partial<
   Pick<API_StoryEntry, 'prepared' | 'parameters' | 'initialArgs' | 'argTypes' | 'args'>
 >;
@@ -77,7 +77,7 @@ type DocsUpdate = Partial<Pick<API_DocsEntry, 'prepared' | 'parameters'>>;
 
 export interface SubState extends API_LoadedRefData {
   storyId: StoryId;
-  viewMode: ViewMode;
+  viewMode: API_ViewMode;
   status: StatusState;
 }
 
@@ -110,13 +110,13 @@ export interface SubAPI {
    * @param {StoryId} [story] - The ID of the story to select.
    * @param {Object} [obj] - An optional object containing additional options.
    * @param {string} [obj.ref] - The ref ID of the story to select.
-   * @param {ViewMode} [obj.viewMode] - The view mode to display the story in.
+   * @param {API_ViewMode} [obj.viewMode] - The view mode to display the story in.
    * @returns {void}
    */
   selectStory: (
     kindOrId?: string,
     story?: StoryId,
-    obj?: { ref?: string; viewMode?: ViewMode }
+    obj?: { ref?: string; viewMode?: API_ViewMode }
   ) => void;
   /**
    * Returns the current story's data, including its ID, kind, name, and parameters.
@@ -595,7 +595,7 @@ export const init: ModuleFn<SubAPI, SubState, true> = ({
         viewMode,
       }: {
         storyId: string;
-        viewMode: ViewMode;
+        viewMode: API_ViewMode;
         [k: string]: any;
       }) {
         const { sourceType } = getEventMetadata(this, fullAPI);
@@ -720,7 +720,7 @@ export const init: ModuleFn<SubAPI, SubState, true> = ({
         story?: StoryName;
         name?: StoryName;
         storyId: string;
-        viewMode: ViewMode;
+        viewMode: API_ViewMode;
       }) {
         const { ref } = getEventMetadata(this, fullAPI);
 

code/lib/types/src/modules/addons.ts

@@ -299,8 +299,8 @@ export type BaseStory<TArgs, StoryFnReturnType> =
   | Addon_BaseStoryObject<TArgs, StoryFnReturnType>;
 
 export interface Addon_RenderOptions {
-  active?: boolean;
-  key?: string;
+  active: boolean;
+  key: string;
 }
 
 /**
@@ -314,14 +314,57 @@ export type ReactJSXElement = {
 
 export type Addon_Type = Addon_BaseType | Addon_PageType;
 export interface Addon_BaseType {
+  /**
+   * The title of the addon.
+   * This can be a simple string, but it can also be a React.FunctionComponent or a React.ReactElement.
+   */
   title: FCWithoutChildren | string | ReactElement | ReactNode;
+  /**
+   * The type of the addon.
+   * @example Addon_TypesEnum.PANEL
+   */
   type: Addon_Types;
+  /**
+   * The unique id of the addon.
+   * @warn This will become non-optional in 8.0
+   *
+   * This needs to be globally unique, so we recommend prefixing it with your org name or npm package name.
+   *
+   * Do not prefix with `storybook`, this is reserved for core storybook feature and core addons.
+   *
+   * @example 'my-org-name/my-addon-name'
+   */
   id?: string;
+  /**
+   * This component will wrap your `render` function.
+   *
+   * With it you can determine if you want your addon to be rendered or not.
+   *
+   * This is to facilitate addons keeping state, and keep listening for events even when they are not currently on screen/rendered.
+   */
   route?: (routeOptions: RouterData) => string;
+  /**
+   * This will determine the value of `active` prop of your render function.
+   */
   match?: (matchOptions: RouterData) => boolean;
-  render: (renderOptions: Addon_RenderOptions) => any | null;
+  /**
+   * The actual contents of your addon.
+   *
+   * This is called as a function, so if you want to use hooks,
+   * your function needs to return a JSX.Element within which components are rendered
+   */
+  render: (renderOptions: Addon_RenderOptions) => ReactElement<any, any> | null;
+  /**
+   * @unstable
+   */
   paramKey?: string;
+  /**
+   * @unstable
+   */
   disabled?: boolean;
+  /**
+   * @unstable
+   */
   hidden?: boolean;
 }
 
@@ -405,7 +448,7 @@ export enum Addon_TypesEnum {
    */
   PANEL = 'panel',
   /**
-   * This adds items in the toolbar above the canvas - on the right side.
+   * This adds items in the toolbar above the canvas - on the left side.
    */
   TOOL = 'tool',
   /**
@@ -414,7 +457,7 @@ export enum Addon_TypesEnum {
   TOOLEXTRA = 'toolextra',
   /**
    * This adds wrapper components around the canvas/iframe component storybook renders.
-   * @unstable
+   * @unstable this API is not stable yet, and is likely to change in 8.0.
    */
   PREVIEW = 'preview',
   /**
@@ -428,9 +471,3 @@ export enum Addon_TypesEnum {
    */
   NOTES_ELEMENT = 'notes-element',
 }
-
-// type A = OrString<'bla' | 'foo'>;
-
-// type OrString<T extends string> = T | (string & {});
-
-// const x: A = 'ffffff';

code/lib/types/src/modules/api.ts

@@ -3,19 +3,17 @@
 import type { RenderData } from '../../../router/src/types';
 import type { Channel } from '../../../channels/src';
 import type { ThemeVars } from '../../../theming/src/types';
-import type { ViewMode } from './csf';
 import type { DocsOptions } from './core-common';
 import type { API_HashEntry, API_IndexHash } from './api-stories';
 import type { SetStoriesStory, SetStoriesStoryData } from './channelApi';
-import type { Addon_Collection, Addon_Type } from './addons';
+import type { Addon_Collection, Addon_RenderOptions, Addon_Type } from './addons';
 import type { StoryIndex } from './storyIndex';
 
-export type API_ViewMode = 'story' | 'info' | 'settings' | 'page' | undefined | string;
+type OrString<T extends string> = T | (string & {});
 
-export interface API_RenderOptions {
-  active: boolean;
-  key: string;
-}
+export type API_ViewMode = OrString<'story' | 'docs' | 'settings'> | undefined;
+
+export type API_RenderOptions = Addon_RenderOptions;
 
 export interface API_RouteOptions {
   storyId: string;
@@ -62,7 +60,7 @@ export interface API_Provider<API> {
 
 export type API_IframeRenderer = (
   storyId: string,
-  viewMode: ViewMode,
+  viewMode: API_ViewMode,
   id: string,
   baseUrl: string,
   scale: number,

code/lib/types/src/modules/channelApi.ts

@@ -1,11 +1,11 @@
+import type { API_ViewMode } from './api';
 import type {
   Args,
   ArgTypes,
   ComponentId,
   Parameters,
   StoryId,
   StoryKind,
-  ViewMode,
   Globals,
   GlobalTypes,
 } from './csf';
@@ -23,7 +23,7 @@ export interface SetStoriesStory {
       [optionName: string]: any;
     };
     docsOnly?: boolean;
-    viewMode?: ViewMode;
+    viewMode?: API_ViewMode;
     [parameterName: string]: any;
   };
   argTypes?: ArgTypes;

code/lib/types/src/modules/csf.ts

@@ -60,13 +60,19 @@ export type {
   Tag,
 } from '@storybook/csf';
 
-export type ViewMode = ViewModeBase | 'story' | 'info' | 'settings' | string | undefined;
+type OrString<T extends string> = T | (string & {});
+
+export type ViewMode = OrString<ViewModeBase | 'settings'> | undefined;
 
 type Layout = 'centered' | 'fullscreen' | 'padded' | 'none';
 
 export interface StorybookParameters {
   options?: Addon_OptionsParameter;
-  /** The layout property defines basic styles added to the preview body where the story is rendered. If you pass 'none', no styles are applied. */
+  /**
+   * The layout property defines basic styles added to the preview body where the story is rendered.
+   *
+   * If you pass `none`, no styles are applied.
+   */
   layout?: Layout;
 }
 

code/ui/manager/src/components/preview/preview.tsx

@@ -15,13 +15,12 @@ import { defaultWrappers, ApplyWrappers } from './wrappers';
 import { ToolbarComp } from './toolbar';
 import { FramesRenderer } from './FramesRenderer';
 
-import type { PreviewProps } from './utils/types';
+import type { PreviewProps, Wrapper } from './utils/types';
 
 const { FEATURES } = global;
 
-const getWrappers = (getFn: API['getElements']) =>
-  Object.values(getFn<Addon_BaseType>(types.PREVIEW));
-const getTabs = (getFn: API['getElements']) => Object.values(getFn<Addon_BaseType>(types.TAB));
+const getWrappers = (getFn: API['getElements']) => Object.values(getFn(types.PREVIEW));
+const getTabs = (getFn: API['getElements']) => Object.values(getFn(types.TAB));
 
 const canvasMapper = ({ state, api }: Combo) => ({
   storyId: state.storyId,
@@ -58,7 +57,7 @@ const createCanvas = (id: string, baseUrl = 'iframe.html', withLoader = true): A
           active,
         }) => {
           const wrappers = useMemo(
-            () => [...defaultWrappers, ...getWrappers(getElements)],
+            () => [...defaultWrappers, ...getWrappers(getElements)] as Wrapper[],
             [getElements, ...defaultWrappers]
           );
 
@@ -211,7 +210,7 @@ const Preview = React.memo<PreviewProps>(function Preview(props) {
             const key = t.id || t.key || i;
             return (
               <Fragment key={key}>
-                <Location>{(lp) => <Render active={match(lp)} />}</Location>
+                <Location>{(lp) => <Render key={key} active={match(lp)} />}</Location>
               </Fragment>
             );
           })}

code/ui/manager/src/components/preview/utils/types.tsx

@@ -1,12 +1,10 @@
 import type { FunctionComponent, ReactNode } from 'react';
 import type { State, API, LeafEntry } from '@storybook/manager-api';
-import type { StoryId } from '@storybook/types';
-
-export type ViewMode = State['viewMode'];
+import type { API_ViewMode, StoryId } from '@storybook/types';
 
 export interface PreviewProps {
   api: API;
-  viewMode: ViewMode;
+  viewMode: API_ViewMode;
   refs: State['refs'];
   storyId: StoryId;
   entry: LeafEntry;
@@ -60,7 +58,7 @@ export interface FramesRendererProps {
   refId: string;
   baseUrl: string;
   scale: number;
-  viewMode: ViewMode;
+  viewMode: API_ViewMode;
   queryParams: State['customQueryParams'];
   refs: State['refs'];
 }

code/ui/manager/src/components/preview/wrappers.tsx

@@ -20,12 +20,12 @@ export const ApplyWrappers: FC<ApplyWrappersProps> = ({
   );
 };
 
-export const defaultWrappers = [
+export const defaultWrappers: Wrapper[] = [
   {
     render: (p) => (
       <IframeWrapper id="storybook-preview-wrapper" hidden={!p.active}>
         {p.children}
       </IframeWrapper>
     ),
-  } as Wrapper,
+  },
 ];