Merge pull request #25974 from storybookjs/yann/improve-play-fn-porta…

…ble-stories-2

Portable stories: Only provide a play function wrapper if it exists

MIGRATION.md

@@ -1,6 +1,7 @@
 <h1>Migration</h1>
 
 - [From version 7.x to 8.0.0](#from-version-7x-to-800)
+  - [Type change in `composeStories` API](#type-change-in-composestories-api)
   - [Tab addons are now routed to a query parameter](#tab-addons-are-now-routed-to-a-query-parameter)
   - [Default keyboard shortcuts changed](#default-keyboard-shortcuts-changed)
   - [Manager addons are now rendered with React 18](#manager-addons-are-now-rendered-with-react-18)
@@ -392,6 +393,23 @@
 
 ## From version 7.x to 8.0.0
 
+### Type change in `composeStories` API
+
+There is a TypeScript type change in the `play` function returned from `composeStories` or `composeStory` in `@storybook/react` or `@storybook/vue3`, where before it was always defined, now it is potentially undefined. This means that you might have to make a small change in your code, such as:
+
+```ts
+const { Primary } = composeStories(stories)
+
+// before
+await Primary.play(...)
+
+// after
+await Primary.play?.(...) // if you don't care whether the play function exists
+await Primary.play!(...) // if you want a runtime error when the play function does not exist
+```
+
+There are plans to make the type of the play function be inferred based on your imported story's play function in a near future, so the types will be 100% accurate.
+
 ### Tab addons are now routed to a query parameter
 
 The URL of a tab used to be: `http://localhost:6006/?path=/my-addon-tab/my-story`.

code/lib/preview-api/src/modules/store/csf/portable-stories.test.ts

@@ -41,7 +41,7 @@ describe('composeStory', () => {
     };
 
     const composedStory = composeStory(Story, meta);
-    await composedStory.play({ canvasElement: null });
+    await composedStory.play!({ canvasElement: null });
     expect(spy).toHaveBeenCalledWith(
       expect.objectContaining({
         args: {
@@ -52,16 +52,6 @@ describe('composeStory', () => {
     );
   });
 
-  it('should throw when executing the play function but the story does not have one', async () => {
-    const Story = () => {};
-    Story.args = {
-      primary: true,
-    };
-
-    const composedStory = composeStory(Story, meta);
-    expect(composedStory.play({ canvasElement: null })).rejects.toThrow();
-  });
-
   it('should throw an error if Story is undefined', () => {
     expect(() => {
       // @ts-expect-error (invalid input)

code/lib/preview-api/src/modules/store/csf/portable-stories.ts

@@ -101,16 +101,13 @@ export function composeStory<TRenderer extends Renderer = Renderer, TArgs extend
       parameters: story.parameters as Parameters,
       argTypes: story.argTypes as StrictArgTypes<TArgs>,
       id: story.id,
-      play: (async (extraContext: ComposedStoryPlayContext<TRenderer, TArgs>) => {
-        if (story.playFunction === undefined) {
-          throw new Error('The story does not have a play function. Make sure to add one.');
-        }
-
-        await story.playFunction({
-          ...context,
-          ...extraContext,
-        });
-      }) as unknown as ComposedStoryPlayFn<TRenderer, Partial<TArgs>>,
+      play: story.playFunction
+        ? ((async (extraContext: ComposedStoryPlayContext<TRenderer, TArgs>) =>
+            story.playFunction!({
+              ...context,
+              ...extraContext,
+            })) as unknown as ComposedStoryPlayFn<TRenderer, Partial<TArgs>>)
+        : undefined,
     }
   );
 

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

@@ -55,7 +55,7 @@ export type ComposedStoryFn<
   TRenderer extends Renderer = Renderer,
   TArgs = Args,
 > = PartialArgsStoryFn<TRenderer, TArgs> & {
-  play: ComposedStoryPlayFn<TRenderer, TArgs>;
+  play: ComposedStoryPlayFn<TRenderer, TArgs> | undefined;
   args: TArgs;
   id: StoryId;
   storyName: string;

code/renderers/react/src/__test__/portable-stories.test.tsx

@@ -99,7 +99,7 @@ describe('CSF3', () => {
 
     const { container } = render(<CSF3InputFieldFilled />);
 
-    await CSF3InputFieldFilled.play({ canvasElement: container });
+    await CSF3InputFieldFilled.play!({ canvasElement: container });
 
     const input = screen.getByTestId('input') as HTMLInputElement;
     expect(input.value).toEqual('Hello world!');

code/renderers/vue3/src/__tests__/composeStories/portable-stories.test.ts

@@ -86,7 +86,7 @@ describe('CSF3', () => {
 
     const { container } = render(CSF3InputFieldFilled());
 
-    await CSF3InputFieldFilled.play({ canvasElement: container as HTMLElement });
+    await CSF3InputFieldFilled.play!({ canvasElement: container as HTMLElement });
 
     const input = screen.getByTestId('input') as HTMLInputElement;
     expect(input.value).toEqual('Hello world!');