README.md
1# Storybook
2
3Our stories are defined alongside our components in `*.stories.js`. They are funnelled down through `stories/stories.js` and `stories/stories-native.js` and are then imported by `stories/index.*.js` which exports the global story loader. See examples in any `*.stories.js` for how to write a story loader. Once you've written a story, adding it to `stories.js` (or `stories-native.js` if it's a native-only story) will be enough to add it to the live storybook.
4
5## Running storybook
6
7### Desktop
8
9The `yarn run storybook` command will spin up a local storybook server on `localhost:6006`
10
11### Native
12
13There's a native storybook UI that controls the selected story. You can also control the current native view by running `yarn run rn-storybook` (with storybook running on a simulator) and navigating to `localhost:7007`.
14
15#### Android
16
17Storybook can be enabled by going to Build > Select Build Variant and selecting 'storyBook'. You can also run `yarn rn-build-storybook-android && yarn rn-push-storybook-android`.
18
19```
20# Enable storybook web UI connection
21adb reverse tcp:7007 tcp:7007
22```
23
24#### iOS
25
26Storybook is controlled by the constants return value in `Storybook.m`. Changing it to `@{@"isStorybook": @true}` enables storybook mode.
27
28## Storyshots
29
30We use an addon to storybook called [Storyshots][1] that adds jest tests on all our defined stories. `yarn test` will run the jest tests and compare the output DOM to the stored snapshots, which are checked into the client repo. This means that updating components with stories can cause jest tests to fail if the snapshots haven't also been updated. Running `yarn test -u` will update the snapshots to the current output.
31
32## useSelector and storybooks
33
34You may want to have a component that accesses state with useSelector. The storybook for this component should use a mock store.
35
36## Connected children (THE OLD WAY)
37
38If a story has a child that is connected to the redux store, that child will still try to its connector in storybook mode, which will fail. To work around this, we patch `connect` in storybook mode to access the store in a different way. `connect` in storybook mode will assume the store is a map that looks like this:
39
40```js
41{
42 [componentDisplayName: string]: ownProps => viewProps
43}
44```
45
46The patched `connect` will ignore anything defined in `(mapStateToProps, mapDispatchToProps, mergeProps)` and try to call the closure (the _prop factory_) in the store. The prop factory will get whatever is in `ownProps` and should return the props that the view expects.
47
48In stories with connected children, a `<Provider />` will need to wrap the top level (via `addDecorator`) and contain this map. For convenience, `createPropProvider` is exported from `./stories` that creates a `<Provider />` from a map. `./prop-providers` contains some common prop factory creators, as well as a `compose` function to combine multiple maps into a single `<Provider />`. See `devices/index.stories.js` for a sample implementation.
49
50### Display names
51
52Making a prop factory requires knowing the display name of the connected component(s), which is generally the variable name of the component. Sometimes the display name fails to get piped through to the connector, in which case a `setDisplayName(n)` will need to be chained _immediately after_ the relevant connect call via recompose. Then the prop factory can be defined under `n`.
53
54### Mocks
55
56Mocks are handled a couple of ways. How storybook and storyshots work is slightly different. Jest has some overrides in the `package.json` file in the 'jest' section. Desktop storybook has some overrides with webpack in the `.storybook/webpack.config.js` file. Native storybook has some overrides through metro in `metro.config.js`.
57
58[1]: https://github.com/storybooks/storybook/tree/master/addons/storyshots
59