mirror of
https://github.com/kremalicious/metamask-extension.git
synced 2024-11-22 01:47:00 +01:00
Updating storybook docs (#13055)
* Updating and moving docs to .storybook/ folder and updating Button to be the standard of docs we want to strive for * Capitalizing API
This commit is contained in:
George Marshall
GitHub
parent
49343d08c1
commit
4af7f250a2
@ -4,7 +4,7 @@ import { Meta } from '@storybook/addon-docs';
|
||||
|
||||
# Documentation Guidelines
|
||||
|
||||
> 💡 To improve the quality of our component documentation we are currently in the process of updating our storybook to use Storyboook's [controls](https://storybook.js.org/addons/@storybook/addon-controls/), [a11y](https://storybook.js.org/addons/@storybook/addon-a11y/) and [docs](https://storybook.js.org/addons/@storybook/addon-docs/) plugins. You will find most components currently without documentation and use knobs for their primary interactivity. These will eventually be updated.
|
||||
> 💡 To improve the quality of our component documentation we are currently in the process of updating our storybook to use Storyboook's [controls](https://storybook.js.org/addons/@storybook/addon-controls/), [a11y](https://storybook.js.org/addons/@storybook/addon-a11y/) and [docs](https://storybook.js.org/addons/@storybook/addon-docs/) plugins. You will find most components currently without documentation and use [knobs](https://storybook.js.org/addons/@storybook/addon-knobs)(deprecated) for their primary interactivity. These will eventually be updated. Want to contribute? Check out the <a href="https://github.com/MetaMask/metamask-extension/issues?q=is%3Aopen+is%3Aissue+label%3Atype-story" targe="_blank">storybook issues on github</a>
|
||||
|
||||
## General Guidelines
|
||||
|
||||
@ -14,10 +14,9 @@ Some general documentation best practices to follow:
|
||||
|
||||
- Put yourself in the shoes of another developer trying to use the component you just created for the first time
|
||||
- Write a brief description of the component and what it's used for in the `README.mdx` file
|
||||
- Display the component's api using the `<ArgsTable of={YourComponent} />` component from storybook docs
|
||||
- Use the [controls](https://storybook.js.org/addons/@storybook/addon-controls/) api over knobs
|
||||
- Use the updated `argType` [actions](https://storybook.js.org/docs/react/essentials/actions) api over importing the actions plugin directly
|
||||
- Check the accessibility of the component using the **Accessibility** tab
|
||||
- Display the component's API using the `<ArgsTable of={YourComponent} />` component from storybook docs. Add descriptions of each prop by using jsDoc style comments in the `propTypes`.
|
||||
- Use the [controls](https://storybook.js.org/addons/@storybook/addon-controls/) over [knobs](https://storybook.js.org/addons/@storybook/addon-knobs)(deprecated)
|
||||
- Use the [action argType annotation](https://storybook.js.org/docs/react/essentials/actions#action-argtype-annotation) over importing the actions plugin directly
|
||||
|
||||
See the [Button](https://metamask.github.io/metamask-storybook/index.html?path=/story/ui-components-ui-button-button-stories-js--default-story)(`ui/components/ui/button/button.stories.js`) component for reference
|
||||
|
||||
@ -25,7 +24,7 @@ See the [Button](https://metamask.github.io/metamask-storybook/index.html?path=/
|
||||
|
||||
[Component Story Format (CSF)](https://storybook.js.org/docs/react/api/csf) is the recommended way to write stories. It's an open standard based on ES6 modules.
|
||||
|
||||
A story can be as simple as:
|
||||
A story **without MDX** documentation can be as simple as:
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
@ -42,7 +41,7 @@ DefaultStory.storyName = 'Default';
|
||||
```
|
||||
|
||||
For a more in-depth and higher quality form of story and documentation, you can use controls and MDX docs.
|
||||
The example below displays the Button component and it explains how we should write our stories:
|
||||
The example below displays the `Button` component and it explains how we should write our stories:
|
||||
|
||||
```jsx
|
||||
// Button component example story
|
||||
@ -51,7 +50,7 @@ import React from 'react';
|
||||
|
||||
import BuyIcon from '../icon/overview-buy-icon.component';
|
||||
|
||||
// The mdx file to document component api and usage
|
||||
// The mdx file to document component API and usage
|
||||
import README from './README.mdx';
|
||||
import Button from '.';
|
||||
|
||||
@ -71,7 +70,7 @@ export default {
|
||||
argTypes: {
|
||||
children: { control: 'text' },
|
||||
disabled: { control: 'boolean' },
|
||||
// use the updated action api to log actions in the actions tab
|
||||
// use the updated action API to log actions in the actions tab
|
||||
onClick: { action: 'clicked' },
|
||||
type: {
|
||||
control: {
|
||||
@ -113,7 +112,8 @@ DefaultStory.storyName = 'Default';
|
||||
|
||||
// More stories should be added for different usage examples
|
||||
// You can add as many stories as you think appropriate to comprehensively document the component
|
||||
export const Types = (args) => (
|
||||
// A good convention is to name the story component after the prop you are highlighting
|
||||
export const Type = (args) => (
|
||||
<>
|
||||
<Button {...args} type="default">
|
||||
{args.children || 'Default'}
|
||||
@ -169,7 +169,8 @@ Buttons communicate actions that users can take.
|
||||
|
||||
## Component API
|
||||
|
||||
<!-- Display the component api using the ArgsTable. Use JSDoc style comments in the PropTypes of your component to add descriptions for props -->
|
||||
<!-- Display the component API using the ArgsTable. Use JSDoc style comments in the PropTypes of your component to add descriptions for props. See button.component.js Button.propTypes for an example of jsDoc style comments
|
||||
-->
|
||||
|
||||
<ArgsTable of={Button} />
|
||||
|
||||
@ -3,7 +3,11 @@ const path = require('path');
|
||||
const CopyWebpackPlugin = require('copy-webpack-plugin');
|
||||
|
||||
module.exports = {
|
||||
stories: ['../ui/**/*.stories.js', '../ui/**/*.stories.mdx'],
|
||||
stories: [
|
||||
'../ui/**/*.stories.js',
|
||||
'../ui/**/*.stories.mdx',
|
||||
'./*.stories.mdx',
|
||||
],
|
||||
addons: [
|
||||
'@storybook/addon-essentials',
|
||||
'@storybook/addon-actions',
|
||||
|
||||
@ -33,27 +33,49 @@ By changing the `type` prop you can use different styles of the button.
|
||||
| `link` | an optional action or navigation action out of the app changes root html tag from `<button>` to `<a>` |
|
||||
|
||||
<Canvas>
|
||||
<Story id="ui-components-ui-button-button-stories-js--types" />
|
||||
<Story id="ui-components-ui-button-button-stories-js--type" />
|
||||
</Canvas>
|
||||
|
||||
### Link Type
|
||||
### Type Link
|
||||
|
||||
By changing the `type` to `"link"` the root html element of the button changes from `<button>` to `<a>`.
|
||||
|
||||
Rendered html
|
||||
|
||||
```html
|
||||
<a class="button btn-link" role="button" tabindex="0">Click me</a>
|
||||
<a class="button btn-link">Click me</a>
|
||||
```
|
||||
|
||||
<Canvas>
|
||||
<Story id="ui-components-ui-button-button-stories-js--link-type" />
|
||||
<Story id="ui-components-ui-button-button-stories-js--type-link" />
|
||||
</Canvas>
|
||||
|
||||
### With Icon
|
||||
### Icon
|
||||
|
||||
Pass an icon component to `icon` prop to add an icon.
|
||||
Pass an icon component to `icon` prop to add an icon to the left side of the Button.
|
||||
|
||||
<Canvas>
|
||||
<Story id="ui-components-ui-button-button-stories-js--with-icon" />
|
||||
<Story id="ui-components-ui-button-button-stories-js--icon" />
|
||||
</Canvas>
|
||||
|
||||
## Submit
|
||||
|
||||
If the `submit` prop is set to `true` the html type attribute will be set to `type="submit"`
|
||||
|
||||
```html
|
||||
<button class="button btn--rounded btn-primary" type="submit">Submit</button>
|
||||
```
|
||||
|
||||
<Canvas>
|
||||
<Story id="ui-components-ui-button-button-stories-js--submit" />
|
||||
</Canvas>
|
||||
|
||||
## OnClick
|
||||
|
||||
If the `onClick` prop is provided and is of type `function` the button html will render with `role="button"` and `tabIndex="0"` attributes. It also provides keyboard functionality on press of the "Enter" key.
|
||||
|
||||
```html
|
||||
<button class="button btn--rounded btn-default" role="button" tabindex="0">
|
||||
Click me
|
||||
</button>
|
||||
```
|
||||
|
||||
@ -73,12 +73,34 @@ const Button = ({
|
||||
};
|
||||
|
||||
Button.propTypes = {
|
||||
/**
|
||||
* The type of variation a button can be.
|
||||
* Can be one of 'default','primary','secondary','warning','danger','danger-primary' or 'link'
|
||||
*/
|
||||
type: PropTypes.string,
|
||||
/**
|
||||
* If true sets the html 'type' attribute to type="submit"
|
||||
*/
|
||||
submit: PropTypes.bool,
|
||||
/**
|
||||
* Increase the height of the button to 54px
|
||||
*/
|
||||
large: PropTypes.bool,
|
||||
/**
|
||||
* Additional className to provide on the root element of the button
|
||||
*/
|
||||
className: PropTypes.string,
|
||||
/**
|
||||
* The children of the button component
|
||||
*/
|
||||
children: PropTypes.node,
|
||||
/**
|
||||
* Provide an icon component for an icon to appear on the left side of the button
|
||||
*/
|
||||
icon: PropTypes.node,
|
||||
/**
|
||||
* Buttons are rounded by default.
|
||||
*/
|
||||
rounded: PropTypes.bool,
|
||||
};
|
||||
|
||||
|
||||
@ -16,8 +16,6 @@ export default {
|
||||
},
|
||||
argTypes: {
|
||||
children: { control: 'text' },
|
||||
disabled: { control: 'boolean' },
|
||||
onClick: { action: 'clicked' },
|
||||
type: {
|
||||
control: {
|
||||
type: 'select',
|
||||
@ -32,9 +30,7 @@ export default {
|
||||
'link',
|
||||
],
|
||||
},
|
||||
submit: { control: 'boolean' },
|
||||
large: { control: 'boolean' },
|
||||
className: { control: 'text' },
|
||||
icon: {
|
||||
control: {
|
||||
type: 'select',
|
||||
@ -44,6 +40,17 @@ export default {
|
||||
BuyIcon: <BuyIcon />,
|
||||
},
|
||||
},
|
||||
submit: { control: 'boolean' },
|
||||
disabled: { control: 'boolean' },
|
||||
className: { control: 'text' },
|
||||
onClick: { action: 'clicked' },
|
||||
},
|
||||
args: {
|
||||
disabled: false,
|
||||
large: false,
|
||||
submit: false,
|
||||
className: '',
|
||||
rounded: true,
|
||||
},
|
||||
};
|
||||
|
||||
@ -57,7 +64,7 @@ DefaultStory.args = {
|
||||
children: 'Default',
|
||||
};
|
||||
|
||||
export const Types = (args) => (
|
||||
export const Type = (args) => (
|
||||
<>
|
||||
<Button {...args} type="default">
|
||||
{args.children || 'Default'}
|
||||
@ -83,14 +90,36 @@ export const Types = (args) => (
|
||||
</>
|
||||
);
|
||||
|
||||
export const LinkType = (args) => <Button {...args} type="link" />;
|
||||
Type.args = {
|
||||
children: '',
|
||||
};
|
||||
|
||||
LinkType.args = {
|
||||
export const TypeLink = (args) => (
|
||||
<Button type={args.type}>{args.children}</Button>
|
||||
);
|
||||
|
||||
TypeLink.args = {
|
||||
href: 'https://metamask.io/',
|
||||
type: 'link',
|
||||
children: 'Click me',
|
||||
};
|
||||
|
||||
export const WithIcon = (args) => (
|
||||
<Button {...args} type="primary" icon={<BuyIcon />}>
|
||||
{args.children || 'Buy'}
|
||||
export const Icon = (args) => <Button {...args}>{args.children}</Button>;
|
||||
|
||||
Icon.args = {
|
||||
type: 'primary',
|
||||
icon: <BuyIcon />,
|
||||
children: 'Buy',
|
||||
};
|
||||
|
||||
export const Submit = (args) => (
|
||||
<Button type={args.type} submit={args.submit}>
|
||||
{args.children}
|
||||
</Button>
|
||||
);
|
||||
|
||||
Submit.args = {
|
||||
type: 'primary',
|
||||
submit: true,
|
||||
children: 'Submit',
|
||||
};
|
||||
|
||||
Loading…
Reference in New Issue
Block a user