-
Notifications
You must be signed in to change notification settings - Fork 4.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Menu: migrate Storybook examples to CSF3 #68204
Conversation
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.
To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hiding whitespace changes removes a lot of noise while reviewing
Flaky tests detected in 980c20e. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/12455042305
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good, thanks for the migration @ciampo!
Just left a few questions and things to discuss as I'm getting familiar with the syntax.
args: { | ||
children: ( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The csf-2-to-3
codemod would use render: () => { ... }
instead of args.children
. What's the difference? Seems like it allows you to specify the props type inline when passing it to render
:
export const Default: StoryObj< typeof Menu > = {
render: ( props: MenuProps ) => (
<Menu { ...props }>
/// ...
</Menu>
),
args: {},
};
One difference to note is that the codemod uses render:
but also specifically adds this to all stories that inherit from Default
:
args: {
...Default.args,
},
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When I was working on some of the TypeScript compilation hotspots, I noticed that not having a render
function is better for performance, since it can bypass a lot of work. So we should avoid render
and prefer children
when possible.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As Lena points out, the reason why I used children at the beginning was because I thought it'd be more idiomatic / more performant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This makes sense to me 👍
However, how do we maintain it as other people work on stories and introduce CSF3 ones? Should we add some docs or introduce linting? Any better ideas?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We could document it, and we usually point it out in code review, but that's about as far as I think it needs to be "enforced". No biggie.
This was already a thing in CSF2, where some people would write completely new templates instead of just changing args.children
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From what I know, using args over custom "render" function has always been a best practice, even prior to CSF3.
In case it helps, Storybook docs also point out that using args is preferred: https://storybook.js.org/docs/8.5/writing-stories#working-with-react-hooks:~:text=We%20recommend%20args%20as%20much%20as%20possible%20when%20writing%20your%20own%20stories.
Not sure if we should spend time writing docs or lining Storybook files?
string[] | ||
>( [ 'b' ] ); | ||
export const WithCheckboxes: Story = { | ||
render: function WithCheckboxes( props: MenuProps ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why do we need to provide a named function here? Can't we just do:
render: ( props: MenuProps ) => (
<>
//...
</>
),
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I used named functions to prevent warnings about using hooks outside of a component.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see. The rules of hooks are broken because React doesn't know how to statically treat hooks inside a dynamically assigned function component like this - it just can't possibly guarantee if render()
is not going to be passed around, which would break rules of hooks.
To me that's just another reason not to use this render()
syntax and to use args.children
if possible.
Alternatively, we could move the component declaration outside of render()
and just pass an instance here - would that work better? The hack with tricking the linter bit us back and we had to change it, which is why I'm hesitant to do it once more.
I'm leaving this to your judgment, as I don't have particularly strong feelings.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My understanding was that the hooks linter simply can't know that render: () => {}
is meant to be a React component. render: function UppercaseName() {}
just tells the linter that it's meant to be a component, like any other function with a uppercased name.
What we're doing for render
isn't that different from the way we can define subcomponents, e.g.:
// this is fine
Menu.Submenu = () => { /* something with hooks */ };
// this is not fine because lowercase
Menu.submenu = () => { /* something with hooks */ };
// would've been fine if the `render` field had been uppercase like this 😅
Default.Render = () => { /* something with hooks */ };
So while I can't say that this isn't a "hack", I don't think it's hacky in a way that's unsafe?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've elaborated on it here, and it's definitely not unsafe, and we can move forward with it for Storybook.
args: { | ||
children: ( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When I was working on some of the TypeScript compilation hotspots, I noticed that not having a render
function is better for performance, since it can bypass a lot of work. So we should avoid render
and prefer children
when possible.
string[] | ||
>( [ 'b' ] ); | ||
export const WithCheckboxes: Story = { | ||
render: function WithCheckboxes( props: MenuProps ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These parameter types shouldn't be necessary, since that is already handled through the StoryObj<>
generic.
render: function WithCheckboxes( props: MenuProps ) { | |
render: function WithCheckboxes( props ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did that initially, but then I added back the explicit props because it seems to improve TypeScript performance (TS doesn't need to compute the prop types since they are explicitly declared)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We ran some TS profiling here, and it turned out to make a big difference. Results were similar to here:
As I discussed with @ciampo over DM earlier, I think this has something to do with how Storybook infers component props for stories when working with compound components, and maybe the inference is not optimized to work with subcomponents and does extra cycles, resulting in infinite loop. It's worth debugging with a dev Storybook setup and an isolated story test case, IMO.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Huh, that's unfortunate!
One ideological issue I have with props: MenuProps
is that MyComponentProps
is often not the canonically accurate set of props in our library, because we often mix in element props with WordPressComponentProps<>
. I feel like we should generally prefer React.ComponentProps< typeof MyComponent >
for accuracy. Would that still work here while maintaining the performance benefits? (Not a blocker though, since element props mixed in with WordPressComponentProps<>
are not going to show up as Storybook controls anyway.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's try it out and measure it, but I think it should be fine, as long as we don't let Storybook infer the prop types.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What about React.ComponentProps< Menu >
? It could hit a sweet spot between accuracy and performance?
We can test it out in a separate PR, if needed
</Menu> | ||
); | ||
Default.args = {}; | ||
type Story = StoryObj< MenuProps >; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any reason it's not this?
type Story = StoryObj< MenuProps >; | |
type Story = StoryObj< typeof Menu >; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as #68204 (comment) — performance reasons.
Although I'm happy to revert if we don't think performance is improved with this change.
2514423
to
fd4b118
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good and I'm happy to ship this as it is 👍
The only thing that feels odd is the named render:
functional components, and not because it's wrong, but because it's previously bit us in other places. Still, I'm fine with it here, as the chance for it breaking in an isolated story is low.
Leaving the final review to @mirka since she had some feedback.
I tried going for the approach suggested in the official docs, but the code snippet would stop showing the Here's the change I applied on my local machinediff --git a/packages/components/src/menu/stories/index.story.tsx b/packages/components/src/menu/stories/index.story.tsx
index 37ebb6f905d..2c41b8585c6 100644
--- a/packages/components/src/menu/stories/index.story.tsx
+++ b/packages/components/src/menu/stories/index.story.tsx
@@ -182,151 +182,139 @@ export const WithSubmenu: StoryObj< typeof Menu > = {
},
};
-export const WithCheckboxes: StoryObj< typeof Menu > = {
- render: function WithCheckboxes( props: MenuProps ) {
- const [ isAChecked, setAChecked ] = useState( false );
- const [ isBChecked, setBChecked ] = useState( true );
- const [ multipleCheckboxesValue, setMultipleCheckboxesValue ] =
- useState< string[] >( [ 'b' ] );
-
- const onMultipleCheckboxesCheckedChange: React.ComponentProps<
- typeof Menu.CheckboxItem
- >[ 'onChange' ] = ( e ) => {
- setMultipleCheckboxesValue( ( prevValues ) => {
- if ( prevValues.includes( e.target.value ) ) {
- return prevValues.filter(
- ( val ) => val !== e.target.value
- );
- }
- return [ ...prevValues, e.target.value ];
- } );
- };
+const WithCheckboxesExample = ( props: MenuProps ) => {
+ const [ isAChecked, setAChecked ] = useState( false );
+ const [ isBChecked, setBChecked ] = useState( true );
+ const [ multipleCheckboxesValue, setMultipleCheckboxesValue ] = useState<
+ string[]
+ >( [ 'b' ] );
+
+ const onMultipleCheckboxesCheckedChange: React.ComponentProps<
+ typeof Menu.CheckboxItem
+ >[ 'onChange' ] = ( e ) => {
+ setMultipleCheckboxesValue( ( prevValues ) => {
+ if ( prevValues.includes( e.target.value ) ) {
+ return prevValues.filter( ( val ) => val !== e.target.value );
+ }
+ return [ ...prevValues, e.target.value ];
+ } );
+ };
- return (
- <Menu { ...props }>
- <Menu.TriggerButton
- render={
- <Button __next40pxDefaultSize variant="secondary" />
- }
- >
- Open menu
- </Menu.TriggerButton>
- <Menu.Popover>
- <Menu.Group>
- <Menu.GroupLabel>
- Single selection, uncontrolled
- </Menu.GroupLabel>
- <Menu.CheckboxItem
- name="checkbox-individual-uncontrolled-a"
- value="a"
- suffix="⌥⌘T"
- >
- <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially unchecked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- <Menu.CheckboxItem
- name="checkbox-individual-uncontrolled-b"
- value="b"
- defaultChecked
- >
- <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially checked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- </Menu.Group>
- <Menu.Separator />
- <Menu.Group>
- <Menu.GroupLabel>
- Single selection, controlled
- </Menu.GroupLabel>
- <Menu.CheckboxItem
- name="checkbox-individual-controlled-a"
- value="a"
- checked={ isAChecked }
- onChange={ ( e ) => {
- setAChecked( e.target.checked );
- } }
- >
- <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially unchecked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- <Menu.CheckboxItem
- name="checkbox-individual-controlled-b"
- value="b"
- checked={ isBChecked }
- onChange={ ( e ) =>
- setBChecked( e.target.checked )
- }
- >
- <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially checked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- </Menu.Group>
- <Menu.Separator />
- <Menu.Group>
- <Menu.GroupLabel>
- Multiple selection, uncontrolled
- </Menu.GroupLabel>
- <Menu.CheckboxItem
- name="checkbox-multiple-uncontrolled"
- value="a"
- >
- <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially unchecked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- <Menu.CheckboxItem
- name="checkbox-multiple-uncontrolled"
- value="b"
- defaultChecked
- >
- <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially checked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- </Menu.Group>
- <Menu.Separator />
- <Menu.Group>
- <Menu.GroupLabel>
- Multiple selection, controlled
- </Menu.GroupLabel>
- <Menu.CheckboxItem
- name="checkbox-multiple-controlled"
- value="a"
- checked={ multipleCheckboxesValue.includes( 'a' ) }
- onChange={ onMultipleCheckboxesCheckedChange }
- >
- <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially unchecked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- <Menu.CheckboxItem
- name="checkbox-multiple-controlled"
- value="b"
- checked={ multipleCheckboxesValue.includes( 'b' ) }
- onChange={ onMultipleCheckboxesCheckedChange }
- >
- <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
- <Menu.ItemHelpText>
- Initially checked
- </Menu.ItemHelpText>
- </Menu.CheckboxItem>
- </Menu.Group>
- </Menu.Popover>
- </Menu>
- );
- },
+ return (
+ <Menu { ...props }>
+ <Menu.TriggerButton
+ render={ <Button __next40pxDefaultSize variant="secondary" /> }
+ >
+ Open menu
+ </Menu.TriggerButton>
+ <Menu.Popover>
+ <Menu.Group>
+ <Menu.GroupLabel>
+ Single selection, uncontrolled
+ </Menu.GroupLabel>
+ <Menu.CheckboxItem
+ name="checkbox-individual-uncontrolled-a"
+ value="a"
+ suffix="⌥⌘T"
+ >
+ <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
+ <Menu.ItemHelpText>
+ Initially unchecked
+ </Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ <Menu.CheckboxItem
+ name="checkbox-individual-uncontrolled-b"
+ value="b"
+ defaultChecked
+ >
+ <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
+ <Menu.ItemHelpText>Initially checked</Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ </Menu.Group>
+ <Menu.Separator />
+ <Menu.Group>
+ <Menu.GroupLabel>
+ Single selection, controlled
+ </Menu.GroupLabel>
+ <Menu.CheckboxItem
+ name="checkbox-individual-controlled-a"
+ value="a"
+ checked={ isAChecked }
+ onChange={ ( e ) => {
+ setAChecked( e.target.checked );
+ } }
+ >
+ <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
+ <Menu.ItemHelpText>
+ Initially unchecked
+ </Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ <Menu.CheckboxItem
+ name="checkbox-individual-controlled-b"
+ value="b"
+ checked={ isBChecked }
+ onChange={ ( e ) => setBChecked( e.target.checked ) }
+ >
+ <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
+ <Menu.ItemHelpText>Initially checked</Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ </Menu.Group>
+ <Menu.Separator />
+ <Menu.Group>
+ <Menu.GroupLabel>
+ Multiple selection, uncontrolled
+ </Menu.GroupLabel>
+ <Menu.CheckboxItem
+ name="checkbox-multiple-uncontrolled"
+ value="a"
+ >
+ <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
+ <Menu.ItemHelpText>
+ Initially unchecked
+ </Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ <Menu.CheckboxItem
+ name="checkbox-multiple-uncontrolled"
+ value="b"
+ defaultChecked
+ >
+ <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
+ <Menu.ItemHelpText>Initially checked</Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ </Menu.Group>
+ <Menu.Separator />
+ <Menu.Group>
+ <Menu.GroupLabel>
+ Multiple selection, controlled
+ </Menu.GroupLabel>
+ <Menu.CheckboxItem
+ name="checkbox-multiple-controlled"
+ value="a"
+ checked={ multipleCheckboxesValue.includes( 'a' ) }
+ onChange={ onMultipleCheckboxesCheckedChange }
+ >
+ <Menu.ItemLabel>Checkbox item A</Menu.ItemLabel>
+ <Menu.ItemHelpText>
+ Initially unchecked
+ </Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ <Menu.CheckboxItem
+ name="checkbox-multiple-controlled"
+ value="b"
+ checked={ multipleCheckboxesValue.includes( 'b' ) }
+ onChange={ onMultipleCheckboxesCheckedChange }
+ >
+ <Menu.ItemLabel>Checkbox item B</Menu.ItemLabel>
+ <Menu.ItemHelpText>Initially checked</Menu.ItemHelpText>
+ </Menu.CheckboxItem>
+ </Menu.Group>
+ </Menu.Popover>
+ </Menu>
+ );
+};
+export const WithCheckboxes: StoryObj< typeof Menu > = {
+ render: ( props: MenuProps ) => <WithCheckboxesExample { ...props } />,
args: {
...Default.args,
},
The current approach (named |
I agree 👍 I'd have concerns that we break rules of hooks if this was the app world, but in the isolation of stories, things should be good. |
Why would using a named function allow folks to break the rules of hooks? AFAIK the linter still checks for those, right? |
We're basically tricking the linter here. The problem isn't with the named function necessarily, but rather with how we're passing a component around as an arbitrary object property. React doesn't know and can't guarantee how this property will be used, and it's likely that it will break the rules of hooks, since it doesn't follow the traditional component rendering flow. This is a similar issue to the current |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚀
args: { | ||
children: ( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We could document it, and we usually point it out in code review, but that's about as far as I think it needs to be "enforced". No biggie.
This was already a thing in CSF2, where some people would write completely new templates instead of just changing args.children
.
string[] | ||
>( [ 'b' ] ); | ||
export const WithCheckboxes: Story = { | ||
render: function WithCheckboxes( props: MenuProps ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Huh, that's unfortunate!
One ideological issue I have with props: MenuProps
is that MyComponentProps
is often not the canonically accurate set of props in our library, because we often mix in element props with WordPressComponentProps<>
. I feel like we should generally prefer React.ComponentProps< typeof MyComponent >
for accuracy. Would that still work here while maintaining the performance benefits? (Not a blocker though, since element props mixed in with WordPressComponentProps<>
are not going to show up as Storybook controls anyway.)
string[] | ||
>( [ 'b' ] ); | ||
export const WithCheckboxes: Story = { | ||
render: function WithCheckboxes( props: MenuProps ) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My understanding was that the hooks linter simply can't know that render: () => {}
is meant to be a React component. render: function UppercaseName() {}
just tells the linter that it's meant to be a component, like any other function with a uppercased name.
What we're doing for render
isn't that different from the way we can define subcomponents, e.g.:
// this is fine
Menu.Submenu = () => { /* something with hooks */ };
// this is not fine because lowercase
Menu.submenu = () => { /* something with hooks */ };
// would've been fine if the `render` field had been uppercase like this 😅
Default.Render = () => { /* something with hooks */ };
So while I can't say that this isn't a "hack", I don't think it's hacky in a way that's unsafe?
What?
Migrate
Menu
's storybook examples to the latest story formatWhy?
Keeping aligned with latest Storybook specs and features, potentially better performance
How?
Followed docs at https://storybook.js.org/docs/api/csf
Testing Instructions
Build storybook locally (
npm run storybook:dev
), make sure that allMenu
stories work as ontrunk