From 4af7f250a222e17398efb053270a8cf99efcb182 Mon Sep 17 00:00:00 2001 From: George Marshall Date: Fri, 7 Jan 2022 12:30:37 -0800 Subject: [PATCH] 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 --- {ui => .storybook}/1.INTRODUCTION.stories.mdx | 0 .../2.DOCUMENTATION.stories.mdx | 23 ++++----- .storybook/main.js | 6 ++- ui/components/ui/button/README.mdx | 36 +++++++++++--- ui/components/ui/button/button.component.js | 22 +++++++++ ui/components/ui/button/button.stories.js | 49 +++++++++++++++---- 6 files changed, 107 insertions(+), 29 deletions(-) rename {ui => .storybook}/1.INTRODUCTION.stories.mdx (100%) rename {ui => .storybook}/2.DOCUMENTATION.stories.mdx (83%) diff --git a/ui/1.INTRODUCTION.stories.mdx b/.storybook/1.INTRODUCTION.stories.mdx similarity index 100% rename from ui/1.INTRODUCTION.stories.mdx rename to .storybook/1.INTRODUCTION.stories.mdx diff --git a/ui/2.DOCUMENTATION.stories.mdx b/.storybook/2.DOCUMENTATION.stories.mdx similarity index 83% rename from ui/2.DOCUMENTATION.stories.mdx rename to .storybook/2.DOCUMENTATION.stories.mdx index 6415f9031..da30c959e 100644 --- a/ui/2.DOCUMENTATION.stories.mdx +++ b/.storybook/2.DOCUMENTATION.stories.mdx @@ -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 storybook issues on github ## 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 `` 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 `` 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) => ( <> +``` + + + + + +## 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 + +``` diff --git a/ui/components/ui/button/button.component.js b/ui/components/ui/button/button.component.js index 1d10b885a..632e230d7 100644 --- a/ui/components/ui/button/button.component.js +++ b/ui/components/ui/button/button.component.js @@ -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, }; diff --git a/ui/components/ui/button/button.stories.js b/ui/components/ui/button/button.stories.js index c1da912ab..051037d21 100644 --- a/ui/components/ui/button/button.stories.js +++ b/ui/components/ui/button/button.stories.js @@ -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: , }, }, + 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) => ( <> +); -LinkType.args = { +TypeLink.args = { + href: 'https://metamask.io/', + type: 'link', children: 'Click me', }; -export const WithIcon = (args) => ( - ; + +Icon.args = { + type: 'primary', + icon: , + children: 'Buy', +}; + +export const Submit = (args) => ( + ); + +Submit.args = { + type: 'primary', + submit: true, + children: 'Submit', +};