Documentation: Updated TS documentation for re-using play functions

[Foxhoundn]

The current documentation introduces typescript errors when the rest of the context object is not passed to the re-used play functions. Hi @IanVS & @jonniebigodes.

What I did

Added rest of the context object to the play functions

How to test

Follow the current documentation on TypeScript 4.9, you should see the following error (or a variation of it)

With this fix, the error should be gone.

Checklist

• [ x] Make sure your changes are tested (stories and/or unit, integration, or end-to-end tests)
• [ x] Make sure to add/update documentation regarding your changes
• [ x] If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Maintainers

• If this PR should be tested against many or all sandboxes,
  make sure to add the ci:merged or ci:daily GH label to it.
• Make sure this PR contains one of the labels below.

["cleanup", "BREAKING CHANGE", "feature request", "bug", "documentation", "maintenance", "dependencies", "other"]

[kylegach]

These are great improvements! Thanks, and congratulations on your first contribution, @Foxhoundn! 🥳

If you don't mind, could you do a Find in the /docs directory for play: async ({ canvasElement })? I'm guessing there's a bunch more snippets around with this anti-pattern present.

[Foxhoundn]

These are great improvements! Thanks, and congratulations on your first contribution, @Foxhoundn! 🥳

If you don't mind, could you do a Find in the /docs directory for play: async ({ canvasElement })? I'm guessing there's a bunch more snippets around with this anti-pattern present.

Hi, there are yes, but those are not causing any issues since they only use the canvasElement prop from the context object and the context does not need to be passed further. Would you still like those to be changed? For example:

export const Example = {
  play: async ({ canvasElement }) => {
    // Starts querying the component from its root element
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByTestId('email'), '[email protected]', {
      delay: 100,
    });
    await userEvent.type(canvas.getByTestId('password'), 'a-random-password'{
      delay: 100,
    });

    // See https://storybook.js.org/docs/7.0/react/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));
  },
};

to:

export const Example = {
  play: async (context) => {
    // Starts querying the component from its root element
    const canvas = within(context.canvasElement);

    await userEvent.type(canvas.getByTestId('email'), '[email protected]', {
      delay: 100,
    });
    await userEvent.type(canvas.getByTestId('password'), 'a-random-password'{
      delay: 100,
    });

    // See https://storybook.js.org/docs/7.0/react/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
    await userEvent.click(canvas.getByRole('button'));
  },
};

?

[jonniebigodes]

@Foxhoundn, thanks for taking the time and effort into this pull request and helping improve the documentation with this great find. Appreciate it 🙏 ! I left one small item that requires your attention before merging this. And I'm with you on this comment, as we shouldn't enforce passing down the entire context unless absolutely needed. Which is the reason you've pushed this pull request.

Let me know once you've addressed the changes so we can merge this.

Hope you have a great day.

Stay safe

[jonniebigodes]

@Foxhoundn can you add a small comment in the example explaining why the user would use context instead of the destructured canvasElement, so that we can clarify to the readers? Also if you're able, can you also apply this pattern to this file, so that folks don't see one example with canvasElement and another with context

[kylegach]

Hi, there are yes, but those are not causing any issues since they only use the canvasElement prop from the context object and the context does not need to be passed further. Would you still like those to be changed?

Oh, that's a great point. No, I agree with you that they do not need changed. Thanks for the back-and-forth!

[Foxhoundn]

@Foxhoundn can you add a small comment in the example explaining why the user would use context instead of the destructured canvasElement, so that we can clarify to the readers? Also if you're able, can you also apply this pattern to this file, so that folks don't see one example with canvasElement and another with context

Well to be honest - I do not know why the whole context is required, it's how the play function is typed. Thinking about it more and seeing that if you @ts-ignore and just pass { canvasElement}, everything seems to work fine - so maybe a better solution would be to either make the other props optional, or create a new interface for the play function that has optional / partial props of the context.

One reason for this would be when you want to reuse play functions in unit test as one user did here - https://discord.com/channels/486522875931656193/1083439468658299011 - you have no way of providing the whole context to the play function, but you can specify the canvasElement (usually it's going to be document or something like that in a jest scenario). Atm if I as a user tried to reuse the play function in a test, I'd be very confused as to what exactly do I need to pass as the arguments.

So @jonniebigodes, @kylegach, @yannbf and @IanVS - please let me know what you think :)

[jonniebigodes]

@Foxhoundn, thanks for the follow-up and for bringing this to our attention. Once again, we're thankful for it 🙇 . And indeed, that's a rather interesting case we'll need to look into so that we don't lose track of this. Would you be ok with opening up an issue and mentioning this pull request, the last comment, and the Discord conversation? Please let me know when you've done it, and we'll go from there.

[Foxhoundn]

@Foxhoundn, thanks for the follow-up and for bringing this to our attention. Once again, we're thankful for it 🙇 . And indeed, that's a rather interesting case we'll need to look into so that we don't lose track of this. Would you be ok with opening up an issue and mentioning this pull request, the last comment, and the Discord conversation? Please let me know when you've done it, and we'll go from there.

Done! - #21573