Storybook show code fix

[ogjtech]

Close #15.
Adding the following code:

docs: {
    source: {
        type: "code"
    }
}

To the export default {...} as Meta; in each Storybook file shows the component code as they are defined in the file.
For example, the Box component now shows:

(args: any) => (
  <Box {...args}>
    <p>This is a Box component.</p>
  </Box>
)

In the Docs tab.

[DanielvanVliet]

I'm not sure if this is the right approach. Although the displayed code does work now, all information on the arguments for each variant is lost. See button for instance, all variants show the same code now.

Perhaps its best to inspect each component and determine whether
type: 'code' or type: 'dynamic'
Leads to better results.

[bddjong]

I'm not sure if this is the right approach. Although the displayed code does work now, all information on the arguments for each variant is lost. See button for instance, all variants show the same code now.

Agreed. This is going in the right direction, but we should have working code examples for all story templates. Take a look at the NLDS POC for example: http://storybook.nldesignsystem.nl/?path=/docs/components--backlink

[joostvanviegen]

I agree with the comments from @bddjong and @DanielvanVliet and won't be giving an explicit appproval for now.

[DanielvanVliet]

It turns out Storybook has three options for the source code in 'show code'. (storybook docs)

1. Dynamic with type: dynamic option, which is the default
2. Render the source code of the story as a whole with type: code
3. Pass in a custom string to be rendered in the show code.

Stories which require no setup code, such as Button, should generate usable code in the docs with the default type: 'dynamic' option:

The more complicated stories such as DatePicker require some setup code (e.g. a React.useState) to function properly.

The dynamic option does not result in usable code in this case, as all setup code is removed:

Using the second option (rendering the storybook source code) for these more complicated stories is better:

However this code does not respond to changes in the properties, and is thus the same for each variant in the story.
And more importantly, is still missing imports such as DateFnsUtils and might not work.

We can also supply storybook with our own string that should be shown in the 'show code'.
This may be different for each variant, but is still static and will not respond to changes in the properties on the docs page.
This also means that we have to ensure that the code works and this can add alot of work and maintenance when API changes are made.

Still providing custom examples is probably the best way forward for the more 'complicated' components, if we always want to display usable code.
Any thoughts? @Gemeente-DenHaag/mdh-rysst @mjcarsjens

[joostvanviegen]

It turns out Storybook has three options for the source code in 'show code'. (storybook docs)

1. Dynamic with `type: dynamic` option, which is the default

2. Render the source code of the story as a whole with `type: code`

3. Pass in a custom string to be rendered in the show code.

Stories which require no setup code, such as Button, should generate usable code in the docs with the default type: 'dynamic' option:

The more complicated stories such as DatePicker require some setup code (e.g. a React.useState) to function properly.

The dynamic option does not result in usable code in this case, as all setup code is removed:

Using the second option (rendering the storybook source code) for these more complicated stories is better:

However this code does not respond to changes in the properties, and is thus the same for each variant in the story.
And more importantly, is still missing imports such as DateFnsUtils and might not work.

We can also supply storybook with our own string that should be shown in the 'show code'.
This may be different for each variant, but is still static and will not respond to changes in the properties on the docs page.
This also means that we have to ensure that the code works and this can add alot of work and maintenance when API changes are made.

Still providing custom examples is probably the best way forward for the more 'complicated' components, if we always want to display usable code.
Any thoughts? @Gemeente-DenHaag/mdh-rysst @mjcarsjens

I think we should go with a hybrid between 'dynamic', 'code' and 'custom'. Whenever a story is simple enough to use dynamic we'll do so, for the other ones we should decide on a case by case basis if 'code' or 'custom' is better.

[mjcarsjens]

I personally feel like we should try to use dynamic where possible. In cases where this does not work, for example the DatePicker component, my personal preference would go out to writing a custom code block, as follows:

Inline.parameters = {
  docs: {
    source: {
      code:
`
import DateFnsUtils from "@date-io/date-fns";

<PickersUtilsProvider utils={DateFnsUtils}>
  <DatePicker variant="inline" />
</PickersUtilsProvider>
`
    }
  }
}

This does bring along some more maintenance but these are a few rare cases from what I can find, and when API changes are made you would have to update the Story file anyway, so updating 3 code examples for the variants of the component doesn't seem like that much extra work.

I would try to stay away from type: "code" as this does not correctly display how to actually get the variant which is shown.

With regards to components like the Accordion and the AppBar: There seems to be a problem with the @material-ui/icons components in combination with StoryBook, as these all show up as <[Object object] />. I would not put too much effort into fixing this, if the problem still persists once we implemented our own icons this is something we can look at, for now I would simply disregard these issues.

[ogjtech]

@Gemeente-DenHaag/mdh-rysst @mjcarsjens
The Badge component is one such example of showing [object Object] when the code is displayed in the dynamic variant.
To fix this, I have replaced the type of the args parameter to BadgeProps, in order to show the Badge as it is defined in the code and to show more specifically what props can be supplied. Badge is now defined as follows:

const Template: Story<BadgeProps> = (args: BadgeProps) => (
  <Badge {...args}>
    <MailIcon />
  </Badge>
);

[ogjtech]

In cases where this does not work, for example the DatePicker component, my personal preference would go out to writing a custom code block

@mjcarsjens Even though this does show the component as is, it can only be defined once in a Storybook file, not per defined variant. It is not technically impossible, but it would require us to rewrite the way we structure our Storybook files and resort to an outdated way of defining the Templates that are shown. This would mean we need to rewrite all of the storybook files, which in my personal opinion is more trouble than its worth.

Personally I think it better to, for now, just accept that the code is not shown as ideal and trust on the implementer's ability to read documentation and interpret code.

[mjcarsjens]

In cases where this does not work, for example the DatePicker component, my personal preference would go out to writing a custom code block

@mjcarsjens Even though this does show the component as is, it can only be defined once in a Storybook file, not per defined variant. It is not technically impossible, but it would require us to rewrite the way we structure our Storybook files and resort to an outdated way of defining the Templates that are shown. This would mean we need to rewrite all of the storybook files, which in my personal opinion is more trouble than its worth.

Personally I think it better to, for now, just accept that the code is not shown as ideal and trust on the implementer's ability to read documentation and interpret code.

@Gemeente-DenHaag/mdh-rysst @ogjtech
Not exactly true though, you can override the default parameters for each variant:

The code:

The result:

As you can see defining a code template for an individual variant does only change the Show Code feature for that specific variant and it is very much possible to define a own code definition for each variant (see my experimental commit to take a look at the exact code).

I'm not saying your conclusion is wrong in any way, I think this is a decision that should be made with the team as a whole and I'm not trying to veto what we should do. All I'm trying to say is that the option to provide a custom code template for every variant is still possible and can be considered as an option.

[ogjtech]

@mjcarsjens I have tried your approach and, while it does work, it shows very weird indentation. I have tried implementing some of the fixes suggested in this issue, but none of them seem to work.
This issue has existed since September 2019, but to this day has not seen a fix of any kind.

[DanielvanVliet]

Currently there are additional spaces inserted in the code examples.
One way to avoid this would be creating the code variables outside the story config.

Can you do this for all the stories?

[Robbert]

@ogjtech If that multiline string indentation is such an annoying recurring issue, you could consider using this: https://www.npmjs.com/package/ts-dedent

[Robbert]

Also: wouldn't it be convenient to have prettier --check in the CI/CD pipeline? If someone doesn't have the Prettier format-on-save installed it becomes immediately apparent, and you don't have to dweil with de crane open.