Refactor props of Story block

code/ui/blocks/src/blocks/Story.stories.tsx

@@ -108,6 +108,17 @@ export const WithDefaultInteractions: Story = {
     chromatic: { delay: 500 },
   },
 };
+
+export const WithInteractionsAutoplay: Story = {
+  args: {
+    of: ButtonStories.Clicking,
+    autoplay: true,
+  },
+  parameters: {
+    chromatic: { delay: 500 },
+  },
+};
+
 export const WithInteractionsAutoplayInStory: Story = {
   args: {
     of: ButtonStories.ClickingInDocs,
@@ -116,3 +127,12 @@ export const WithInteractionsAutoplayInStory: Story = {
     chromatic: { delay: 500 },
   },
 };
+
+export const WithInteractionsAutoplayInStoryDeprecated: Story = {
+  args: {
+    of: ButtonStories.ClickingInDocsDeprecated,
+  },
+  parameters: {
+    chromatic: { delay: 500 },
+  },
+};

code/ui/blocks/src/blocks/Story.tsx

@@ -1,10 +1,10 @@
 import type { FC, ComponentProps } from 'react';
-import React, { useContext, useRef, useEffect, useState } from 'react';
+import React, { useContext } from 'react';
 import type {
   Renderer,
   ModuleExport,
   ModuleExports,
-  PreparedStory as StoryType,
+  PreparedStory,
   StoryAnnotations,
   StoryId,
 } from '@storybook/types';
@@ -18,26 +18,62 @@ export const storyBlockIdFromId = (storyId: string) => `story--${storyId}`;
 
 type PureStoryProps = ComponentProps<typeof PureStory>;
 
-type CommonProps = StoryAnnotations & {
-  height?: string;
-  inline?: boolean;
-};
-
-type StoryDefProps = {
-  name: string;
-};
+/**
+ * Props to define a story
+ *
+ * @deprecated Define stories in CSF files
+ */
+type StoryDefProps = StoryAnnotations;
 
+/**
+ * Props to reference another story
+ */
 type StoryRefProps = {
+  /**
+   * @deprecated Use of={storyExport} instead
+   */
   id?: string;
+  /**
+   * Pass the export defining a story to render that story
+   *
+   * ```jsx
+   * import { Meta, Story } from '@storybook/blocks';
+   * import * as ButtonStories from './Button.stories';
+   *
+   * <Meta of={ButtonStories} />
+   * <Story of={ButtonStories.Primary} />
+   * ```
+   */
   of?: ModuleExport;
+  /**
+   * Pass all exports of the CSF file if this MDX file is unattached
+   *
+   * ```jsx
+   * import { Story } from '@storybook/blocks';
+   * import * as ButtonStories from './Button.stories';
+   *
+   * <Story of={ButtonStories.Primary} meta={ButtonStories} />
+   * ```
+   */
   meta?: ModuleExports;
 };
 
-type StoryImportProps = {
-  name: string;
+type StoryParameters = {
+  /**
+   * Render the story inline or in an iframe
+   */
+  inline?: boolean;
+  /**
+   * When rendering in an iframe (`inline={false}`), set the story height
+   */
+  height?: string;
+  /**
+   * Whether to run the story's play function
+   */
+  autoplay?: boolean;
 };
 
-export type StoryProps = (StoryDefProps | StoryRefProps | StoryImportProps) & CommonProps;
+export type StoryProps = (StoryDefProps | StoryRefProps) & StoryParameters;
 
 export const getStoryId = (props: StoryProps, context: DocsContextProps): StoryId => {
   const { id, of, meta } = props as StoryRefProps;
@@ -50,84 +86,73 @@ export const getStoryId = (props: StoryProps, context: DocsContextProps): StoryI
   return id || context.storyIdByName(name);
 };
 
+// Find the first option that isn't undefined
+function getProp<T>(...options: (T | undefined)[]) {
+  return options.find((option) => typeof option !== 'undefined');
+}
+
 export const getStoryProps = <TFramework extends Renderer>(
-  { height, inline }: StoryProps,
-  story: StoryType<TFramework>
+  props: StoryParameters,
+  story: PreparedStory<TFramework>,
+  context: DocsContextProps<TFramework>
 ): PureStoryProps => {
-  const { name: storyName, parameters = {} } = story || {};
+  const { parameters = {} } = story || {};
   const { docs = {} } = parameters;
+  const storyParameters = (docs.story || {}) as StoryParameters;
 
   if (docs.disable) {
     return null;
   }
 
-  // prefer block props, then story parameters defined by the framework-specific settings and optionally overridden by users
-  const { inlineStories = false, iframeHeight = 100 } = docs;
-  const storyIsInline = typeof inline === 'boolean' ? inline : inlineStories;
+  // prefer block props, then story parameters defined by the framework-specific settings
+  // and optionally overridden by users
 
+  // Deprecated parameters
+  const {
+    inlineStories,
+    iframeHeight,
+    autoplay: docsAutoplay,
+  } = docs as {
+    inlineStories?: boolean;
+    iframeHeight?: string;
+    autoplay?: boolean;
+  };
+  const inline = getProp(props.inline, storyParameters.inline, inlineStories) || false;
+
+  const height = getProp(props.height, storyParameters.height, iframeHeight) || '100px';
+  if (inline) {
+    const autoplay = getProp(props.autoplay, storyParameters.autoplay, docsAutoplay) || false;
+    return {
+      story,
+      inline: true,
+      height,
+      autoplay,
+      renderStoryToElement: context.renderStoryToElement,
+    };
+  }
   return {
-    inline: storyIsInline,
-    id: story?.id,
-    height: height || (storyIsInline ? undefined : iframeHeight),
-    title: storyName,
-    ...(storyIsInline && {
-      parameters,
-    }),
+    story,
+    inline: false,
+    height,
   };
 };
 
 const Story: FC<StoryProps> = (props) => {
   const context = useContext(DocsContext);
-  const storyRef = useRef();
   const storyId = getStoryId(props, context);
   const story = useStory(storyId, context);
-  const [showLoader, setShowLoader] = useState(true);
-
-  useEffect(() => {
-    if (!(story && storyRef.current)) {
-      return () => {};
-    }
-    const element = storyRef.current as HTMLElement;
-    const { autoplay } = story.parameters.docs || {};
-    const cleanup = context.renderStoryToElement(story, element, { autoplay });
-    setShowLoader(false);
-    return () => {
-      cleanup();
-    };
-  }, [context, story]);
 
   if (!story) {
     return <StorySkeleton />;
   }
 
-  const storyProps = getStoryProps(props, story);
+  const storyProps = getStoryProps(props, story, context);
   if (!storyProps) {
     return null;
   }
 
-  if (storyProps.inline) {
-    // We do this so React doesn't complain when we replace the span in a secondary render
-    const htmlContents = `<span></span>`;
-
-    // FIXME: height/style/etc. lifted from PureStory
-    const { height } = storyProps;
-    return (
-      <div id={storyBlockIdFromId(story.id)} className="sb-story">
-        {height ? (
-          <style>{`#story--${story.id} { min-height: ${height}; transform: translateZ(0); overflow: auto }`}</style>
-        ) : null}
-        {showLoader && <StorySkeleton />}
-        <div
-          ref={storyRef}
-          data-name={story.name}
-          dangerouslySetInnerHTML={{ __html: htmlContents }}
-        />
-      </div>
-    );
-  }
-
   return (
-    <div id={storyBlockIdFromId(story.id)}>
+    <div id={storyBlockIdFromId(story.id)} className="sb-story">
       <PureStory {...storyProps} />
     </div>
   );

code/ui/blocks/src/components/Story.tsx

@@ -1,10 +1,8 @@
 import { global } from '@storybook/global';
-import type { ElementType, FunctionComponent } from 'react';
-import React, { createElement, Fragment } from 'react';
-import type { Parameters } from '@storybook/types';
+import type { FunctionComponent } from 'react';
+import React, { useRef, useEffect, useState } from 'react';
+import type { DocsContextProps, PreparedStory } from '@storybook/types';
 import { Loader, getStoryHref } from '@storybook/components';
-// eslint-disable-next-line import/no-cycle
-import { EmptyBlock } from '.';
 import { IFrame } from './IFrame';
 import { ZoomContext } from './ZoomContext';
 
@@ -15,48 +13,74 @@ export enum StoryError {
   NO_STORY = 'No component or story to display',
 }
 
-/** error message for Story with null storyFn
- * if the story id exists, it must be pointing to a non-existing story
- *  if there is assigned story id, the story must be empty
- */
-const MISSING_STORY = (id?: string) => (id ? `Story "${id}" doesn't exist.` : StoryError.NO_STORY);
-
 interface CommonProps {
-  title?: string;
-  height?: string;
-  id: string;
+  story: PreparedStory;
+  inline: boolean;
+  height: string;
 }
 
 interface InlineStoryProps extends CommonProps {
-  parameters: Parameters;
-  storyFn: ElementType;
+  inline: true;
+  autoplay: boolean;
+  renderStoryToElement: DocsContextProps['renderStoryToElement'];
 }
 
-type IFrameStoryProps = CommonProps;
+interface IFrameStoryProps extends CommonProps {
+  inline: false;
+}
 
 type StoryProps = InlineStoryProps | IFrameStoryProps;
 
-const InlineStory: FunctionComponent<InlineStoryProps> = ({ storyFn, height, id }) => (
-  <Fragment>
-    {height ? (
-      <style>{`#story--${id} { min-height: ${height}; transform: translateZ(0); overflow: auto }`}</style>
-    ) : null}
-    <Fragment>
-      {storyFn ? createElement(storyFn) : <EmptyBlock>{MISSING_STORY(id)}</EmptyBlock>}
-    </Fragment>
-  </Fragment>
-);
+const InlineStory: FunctionComponent<InlineStoryProps> = ({
+  story,
+  height,
+  autoplay,
+  renderStoryToElement,
+}) => {
+  const storyRef = useRef();
+  const [showLoader, setShowLoader] = useState(true);
 
-const IFrameStory: FunctionComponent<IFrameStoryProps> = ({ id, title, height = '500px' }) => (
+  useEffect(() => {
+    if (!(story && storyRef.current)) {
+      return () => {};
+    }
+    const element = storyRef.current as HTMLElement;
+    const cleanup = renderStoryToElement(story, element, { autoplay });
+    setShowLoader(false);
+    return () => {
+      cleanup();
+    };
+  }, [autoplay, renderStoryToElement, story]);
+
+  // We do this so React doesn't complain when we replace the span in a secondary render
+  const htmlContents = `<span></span>`;
+
+  return (
+    <>
+      {height ? (
+        <style>{`#story--${story.id} { min-height: ${height}; transform: translateZ(0); overflow: auto }`}</style>
+      ) : null}
+      {showLoader && <StorySkeleton />}
+      <div
+        ref={storyRef}
+        data-name={story.name}
+        // eslint-disable-next-line react/no-danger
+        dangerouslySetInnerHTML={{ __html: htmlContents }}
+      />
+    </>
+  );
+};
+
+const IFrameStory: FunctionComponent<IFrameStoryProps> = ({ story, height = '500px' }) => (
   <div style={{ width: '100%', height }}>
     <ZoomContext.Consumer>
       {({ scale }) => {
         return (
           <IFrame
             key="iframe"
-            id={`iframe--${id}`}
-            title={title}
-            src={getStoryHref(BASE_URL, id, { viewMode: 'story' })}
+            id={`iframe--${story.id}`}
+            title={story.name}
+            src={getStoryHref(BASE_URL, story.id, { viewMode: 'story' })}
             allowFullScreen
             scale={scale}
             style={{
@@ -75,18 +99,12 @@ const IFrameStory: FunctionComponent<IFrameStoryProps> = ({ id, title, height =
  * A story element, either rendered inline or in an iframe,
  * with configurable height.
  */
-const Story: FunctionComponent<
-  StoryProps & { inline?: boolean; error?: StoryError; children?: React.ReactNode }
-> = ({ children, error, inline, ...props }) => {
-  const { id, title, height } = props;
-
-  if (error) {
-    return <EmptyBlock>{error}</EmptyBlock>;
-  }
+const Story: FunctionComponent<StoryProps> = (props) => {
+  const { inline } = props;
   return inline ? (
     <InlineStory {...(props as InlineStoryProps)} />
   ) : (
-    <IFrameStory id={id} title={title} height={height} />
+    <IFrameStory {...(props as IFrameStoryProps)} />
   );
 };
 

code/ui/blocks/src/examples/Button.stories.tsx

@@ -84,7 +84,7 @@ export const Clicking: Story = {
   },
 };
 
-export const ClickingInDocs: Story = {
+export const ClickingInDocsDeprecated: Story = {
   ...Clicking,
   parameters: {
     docs: {
@@ -92,3 +92,14 @@ export const ClickingInDocs: Story = {
     },
   },
 };
+
+export const ClickingInDocs: Story = {
+  ...Clicking,
+  parameters: {
+    docs: {
+      story: {
+        autoplay: true,
+      },
+    },
+  },
+};