applications/storybook/CONTRIBUTING.md

   1 # Contributing
   2
   3 -   [React component stories](#react-component-stories)
   4 -   [React component props](#react-component-props)
   5 -   [Storybook Canvas block](#storybook-canvas-block)
   6
   7 ## React component stories
   8
   9 The main way we intend to convey documentation about React Components in this Storybook is via Storybook's [MDX Docs Support](https://storybook.js.org/docs/react/writing-docs/mdx).
  10
  11 For that we employ the pattern of writing a couple of stories in a `Component.stories.tsx` file and linking them to an mdx documentation page through the `<Story />` Storybook Block by referencing the story's id like so:
  12
  13 ```jsx
  14 import { Canvas, Story } from '@storybook/addon-docs/blocks';
  15
  16 <Story id="story-id" />;
  17 ```
  18
  19 The name you call your mdx file does not matter as it has to be linked manually to the respective component stories file like so (however `Component.mdx` seems like a convenient pattern for mdx pages that are directly linked to a stories file of the same component):
  20
  21 ```jsx
  22 import mdx from './Component.mdx';
  23 import Component from './Component.tsx';
  24
  25 export default {
  26     component: Component,
  27     title: 'Component',
  28     parameters: {
  29         docs: {
  30             page: mdx,
  31         },
  32     },
  33 };
  34 ```
  35
  36 The easiest way to find a story-id is by going to a running storybook instance and checking the url when on a story in the canvas:
  37
  38 <img src="./src/assets/storybook-story-id.png" width="400" alt="" />
  39
  40 However the story-id is computed from your story's title and its name, soit is also possible to predict it.
  41
  42 This pattern is documented in the following storybook 'recipe': [CSF Stories with arbitrary MDX](https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#csf-stories-with-arbitrary-mdx)
  43
  44 ## React component props
  45
  46 To show the arguments (props) for a certain component in the documentation page use the ArgsTable Storybook Block
  47
  48 ```jsx
  49 import { Alert } from 'react-components';
  50
  51 import { ArgsTable } from '@storybook/addon-docs/blocks';
  52
  53 <ArgsTable of={Alert} />;
  54 ```
  55
  56 <img src="./src/assets/storybook-argstable.png" alt="" />
  57
  58 Note: If you comment your props this way in your component in `react-components`:
  59
  60 ```
  61 interface Props extends React.HTMLProps<HTMLSpanElement> {
  62     text: string;
  63         /**
  64          * Here is a super useful comment.
  65          */
  66     charsToDisplayEnd?: number;
  67 ```
  68
  69 This comment will be present in StoryBook:
  70
  71 <img src="./src/assets/storybook-props-comments.png" alt="Comment available" />
  72
  73 There have been issues with typescript-docgen not being able to correctly extract the args/props for the ArgsTable. The following scenarios cause problems with that.
  74
  75 Importing a component under a different name than it was exported as
  76
  77 ```js
  78 /* bar.js */
  79 import Baz from './foo';
  80
  81 /* foo.js */
  82 export default Foo;
  83 ```
  84
  85 Exporting the component as an anonymous value, for example when wrapped in higher order functions and directly exported.
  86
  87 ```js
  88 const A = () => {
  89     /* ... */
  90 };
  91
  92 export default forwardRef(A);
  93 ```
  94
  95 One option to deal with this is to wrap the component definition itself so that the wrapped component is named by a variable.
  96
  97 ```js
  98 const A = forwardRef(() => {
  99     /* ... */
 100 });
 101
 102 export default A;
 103 ```
 104
 105 ## Storybook Canvas block
 106
 107 Usually you'll see a `<Story />` wrapped inside the `<Canvas />` Storybook Block. This is done to show the source code alongside the inline story:
 108
 109 ```jsx
 110 import { Canvas, Story } from '@storybook/addon-docs/blocks';
 111
 112 <Canvas>
 113     <Story id="story-id" />
 114 </Canvas>;
 115 ```
 116
 117 <img src="./src/assets/storybook-canvas-block.png" alt="" />