-
Notifications
You must be signed in to change notification settings - Fork 5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Adding
Box component in TS to component-library (#19363)
* Adding TS version of Box to component-library * Updates to types and comments
- Loading branch information
1 parent
fa70aec
commit 35ae06d
Showing
9 changed files
with
4,448 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,368 @@ | ||
| import { Story, Canvas, ArgsTable } from '@storybook/addon-docs'; | ||
|
|
||
| import { Box } from './box'; | ||
|
|
||
| # Box | ||
|
|
||
| The `Box` is a utility component that accepts many helper props to make styling easier. | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--box-default-story" /> | ||
| </Canvas> | ||
|
|
||
| ## Props | ||
|
|
||
| <ArgsTable of={Box} /> | ||
|
|
||
| ## Usage | ||
|
|
||
| The following describes the props and example usage for this component. | ||
|
|
||
| ### Margin | ||
|
|
||
| The margin props `margin`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, `marginInline`, `marginInlineStart`, and `marginInlineEnd` can be used to set the margins of the `Box` component. All of the margin props accept [responsive props](#responsive-props) in the form of array props | ||
|
|
||
| Accepted props are: `0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto` or array of these values | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--margin" /> | ||
| </Canvas> | ||
|
|
||
| ```jsx | ||
| <Box margin={4} /> | ||
| <Box marginTop={4} /> | ||
| <Box marginRight={4} /> | ||
| <Box marginBottom={4} /> | ||
| <Box marginLeft={'auto'} /> | ||
| <Box marginInline={4} /> | ||
| <Box marginInlineStart={4} /> | ||
| <Box marginInlineEnd={4} /> | ||
|
|
||
| // Responsive props | ||
| <Box margin={[4, 8]} /> | ||
| <Box marginTop={[4, 8]} /> | ||
| <Box marginRight={[4, 8]} /> | ||
| <Box marginBottom={[4, 8]} /> | ||
| <Box marginLeft={['auto', 8]} /> | ||
| <Box marginInline={['auto', 8]} /> | ||
| <Box marginInlineStart={['auto', 8]} /> | ||
| <Box marginInlineEnd={['auto', 8]} /> | ||
| ``` | ||
|
|
||
| ### Padding | ||
|
|
||
| The padding props work very similarly to margin. The padding props `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `paddingInline`, `paddingInlineStart`, and `paddingInlineEnd` can be used to set the paddings of the `Box` component. All of the padding props accept [responsive props](#responsive-props) in the form of array props | ||
|
|
||
| Accepted props are: `0, 1, 2, 4, 6, 8, 9, 10, 12` or array of these values | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--padding" /> | ||
| </Canvas> | ||
|
|
||
| ```jsx | ||
| <Box padding={4} /> | ||
| <Box paddingTop={4} /> | ||
| <Box paddingRight={4} /> | ||
| <Box paddingBottom={4} /> | ||
| <Box paddingLeft={4} /> | ||
|
|
||
| // Responsive props | ||
| <Box padding={[4, 8]} /> | ||
| <Box paddingTop={[4, 8]} /> | ||
| <Box paddingRight={[4, 8]} /> | ||
| <Box paddingBottom={[4, 8]} /> | ||
| <Box paddingLeft={[4, 8]} /> | ||
| ``` | ||
|
|
||
| ### Display | ||
|
|
||
| The `display` prop can be used to set the display of the `Box` component. All of the display props accept [responsive props](#responsive-props) in the form of array props. | ||
|
|
||
| Accepted props imported from the design system `Display` const are: | ||
|
|
||
| - `Display.Block` | ||
| - `Display.Flex` | ||
| - `Display.Grid` | ||
| - `Display.InlineBlock` | ||
| - `Display.InlineFlex` | ||
| - `Display.InlineGrid` | ||
| - `Display.Inline` | ||
| - `Display.ListItem` | ||
| - `Display.None` | ||
|
|
||
| or array of these values. | ||
|
|
||
| ```jsx | ||
| import { Display } from '../../../helpers/constants/design-system'; | ||
| import Box from '../ui/box'; | ||
|
|
||
| <Box display={Display.Block} /> | ||
| <Box display={Display.Flex} /> | ||
| <Box display={Display.Grid} /> | ||
| <Box display={Display.InlineBlock} /> | ||
| <Box display={Display.InlineFlex} /> | ||
| <Box display={Display.Inline} /> | ||
| <Box display={Display.None} /> | ||
| ``` | ||
|
|
||
| ### Color | ||
|
|
||
| The `color` prop can be used to set the color of the content in Box component. The `color` prop accepts [responsive props](#responsive-props) in the form of array props. Defaults to `Color.textDefault`. | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--color-story" /> | ||
| </Canvas> | ||
|
|
||
| Example of importing `TextColor` object with `Box` component | ||
|
|
||
| ```jsx | ||
| import { TextColor } from '../../../helpers/constants/design-system'; | ||
| import Box from '../ui/box'; | ||
|
|
||
| <Box color={TextColor.textDefault}>Text goes here</Box>; | ||
| ``` | ||
|
|
||
| ### Background Color | ||
|
|
||
| Use the `backgroundColor` prop along with the `Color` or `BackgroundColor` object from `ui/helpers/constants/design-system.js` to change background color. The `backgroundColor` prop accepts [responsive props](#responsive-props) in the form of array props. | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--background-color-story" /> | ||
| </Canvas> | ||
|
|
||
| Example of importing `BackgroundColor` object with `Box` component | ||
|
|
||
| ```jsx | ||
| import { | ||
| BackgroundColor, | ||
| TextColor, | ||
| } from '../../../helpers/constants/design-system'; | ||
| import Box from '../ui/box'; | ||
|
|
||
| <Box backgroundColor={BackgroundColor.backgroundDefault}> | ||
| <Typography color={TextColor.textDefault}> | ||
| BackgroundColor.backgroundDefault | ||
| </Typography> | ||
| </Box>; | ||
| ``` | ||
|
|
||
| ### Border Color | ||
|
|
||
| Use the `borderColor` prop along with the `Color` or `BorderColor` object from `ui/helpers/constants/design-system.js` to change border color. The `borderColor` prop accepts [responsive props](#responsive-props) in the form of array props. | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--border-color-story" /> | ||
| </Canvas> | ||
|
|
||
| Example of importing `BorderColor` object with `Box` component | ||
|
|
||
| ```jsx | ||
| import { | ||
| BackgroundColor, | ||
| BorderColor, | ||
| TextColor, | ||
| } from '../../../helpers/constants/design-system'; | ||
| import Box from '../ui/box'; | ||
|
|
||
| <Box | ||
| backgroundColor={BackgroundColor.backgroundDefault} | ||
| borderColor={BorderColor.borderDefault} | ||
| > | ||
| <Typography color={TextColor.textDefault}> | ||
| BorderColor.borderDefault | ||
| </Typography> | ||
| </Box>; | ||
| ``` | ||
|
|
||
| ### Border Radius | ||
|
|
||
| Use the `borderRadius` prop along with the `BorderRadius` object from `ui/helpers/constants/design-system.js` to change border radius. The `borderRadius` prop accepts [responsive props](#responsive-props) in the form of array props. | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--border-radius-story" /> | ||
| </Canvas> | ||
|
|
||
| Example of importing `BorderRadius` object with `Box` component | ||
|
|
||
| ```jsx | ||
| import { BorderRadius } from '../../../helpers/constants/design-system'; | ||
| import Box from '../ui/box'; | ||
|
|
||
| <Box borderRadius={BorderRadius.none}>BorderRadius.none 0px</Box> | ||
| <Box borderRadius={BorderRadius.XS}>BorderRadius.XS 2px</Box> | ||
| <Box borderRadius={BorderRadius.SM}>BorderRadius.SM 4px</Box> | ||
| <Box borderRadius={BorderRadius.MD}>BorderRadius.MD 6px</Box> | ||
| <Box borderRadius={BorderRadius.LG}>BorderRadius.LG 8px</Box> | ||
| <Box borderRadius={BorderRadius.XL}>BorderRadius.XL 12px</Box> | ||
| <Box borderRadius={BorderRadius.pill}>BorderRadius.pill 9999px</Box> | ||
| <Box borderRadius={BorderRadius.full}>BorderRadius.full 50%</Box> | ||
| ``` | ||
|
|
||
| ### Responsive Props | ||
|
|
||
| The box component provides a responsive props api in the form of array props. Array props are inspired by [styled-systems array props](https://styled-system.com/guides/array-props). The responsive props follow a mobile first methodology with the first item in the array applying the style to the base level size e.g. `0px` and up. The second item overwrites the first items styles at the next breakpoint. | ||
|
|
||
| - All Box props accept the responsive props format | ||
| - To skip a breakpoint use `null` as the skipped item's value e.g. `<Box display={['display', null, ;flex']} />` | ||
|
|
||
| ``` | ||
| // the responsive props | ||
| <Box display={['block', 'flex']} /> | ||
| // is equivalent to the css | ||
| .box { | ||
| display: block; | ||
| @media screen and (max-width: $breakpoint-sm) { | ||
| display: flex; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--responsive-props" /> | ||
| </Canvas> | ||
|
|
||
| ```jsx | ||
| import { | ||
| BorderColor, | ||
| BackgroundColor, | ||
| } from '../../../helpers/constants/design-system'; | ||
| import Box from '../ui/box'; | ||
|
|
||
| <Box | ||
| padding={[2, 4]} | ||
| gap={[2, 4]} | ||
| display={['flex']} | ||
| flexDirection={['column', 'row']} | ||
| borderColor={BorderColor.borderDefault} | ||
| > | ||
| <Box | ||
| padding={[4, 8]} | ||
| backgroundColor={BackgroundColor.backgroundAlternative} | ||
| borderColor={BorderColor.borderMuted} | ||
| > | ||
| responsive | ||
| </Box> | ||
| <Box | ||
| padding={[4, 8]} | ||
| backgroundColor={BackgroundColor.backgroundAlternative} | ||
| borderColor={BorderColor.borderMuted} | ||
| > | ||
| props | ||
| </Box> | ||
| <Box | ||
| padding={[4, 8]} | ||
| backgroundColor={BackgroundColor.backgroundAlternative} | ||
| borderColor={BorderColor.borderMuted} | ||
| > | ||
| example | ||
| </Box> | ||
| </Box>; | ||
| ``` | ||
|
|
||
| ### As | ||
|
|
||
| The polymorphic `as` prop allows you to change the root HTML element of the Box component. Defaults to `'div'` | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--as" /> | ||
| </Canvas> | ||
|
|
||
| ```jsx | ||
| import Box from '../../ui/box'; | ||
|
|
||
| <Box>div(default)</Box> | ||
| <Box as="ul">ul</Box> | ||
| <Box as="li">li</Box> | ||
| <Box as="button">button</Box> | ||
| <Box as="header">header</Box> | ||
| ``` | ||
|
|
||
| ### Width | ||
|
|
||
| Use the `width` prop to pass a singular `BlockSize` or for a responsive width pass an array up to 4 `BlockSize` | ||
|
|
||
| Responsive widths go from smallest to largest screen sizes | ||
|
|
||
| Example: [BlockSize.Half, BlockSize.ThreeFourths, BlockSize.OneFifth, BlockSize.ThreeSixths] | ||
|
|
||
| - BlockSize.Half is the default width for `base screen size (0px)` and up | ||
| - BlockSize.ThreeFourths is the width for `small screen size (576px) ` and up | ||
| - BlockSize.OneFifth is the width for `medium screen size (768px)` and up | ||
| - BlockSize.ThreeSixths is the width for `large screen size (1280px)` and up | ||
|
|
||
| <Canvas> | ||
| <Story id="components-componentlibrary-box--width" /> | ||
| </Canvas> | ||
|
|
||
| ```jsx | ||
| import { | ||
| BlockSize, | ||
| Display, | ||
| FlexWrap, | ||
| } from '../../../helpers/constants/design-system'; | ||
| import Box from '../../ui/box'; | ||
|
|
||
| <> | ||
| <p>Static widths</p> | ||
|
|
||
| <Box display={Display.Flex}> | ||
| <Box width={BlockSize.Full}>BlockSize.Full</Box> | ||
| <Box width={BlockSize.Half}>BlockSize.Half</Box> | ||
| <Box width={BlockSize.Half}>BlockSize.Half</Box> | ||
| <Box width={BlockSize.OneThird}>BlockSize.OneThird</Box> | ||
| <Box width={BlockSize.OneThird}>BlockSize.OneThird</Box> | ||
| <Box width={BlockSize.OneThird}>BlockSize.OneThird</Box> | ||
| <Box width={BlockSize.OneFourth}>BlockSize.OneFourth</Box> | ||
| <Box width={BlockSize.OneFourth}>BlockSize.OneFourth</Box> | ||
| <Box width={BlockSize.OneFourth}>BlockSize.OneFourth</Box> | ||
| <Box width={BlockSize.OneFourth}>BlockSize.OneFourth</Box> | ||
| </Box> | ||
|
|
||
| <p>Responsive widths</p> | ||
|
|
||
| <Box display={Display.Flex} flexWrap={FlexWrap.Wrap}> | ||
| <Box | ||
| width={[ | ||
| BlockSize.Full, | ||
| BlockSize.Half, | ||
| BlockSize.OneThird, | ||
| BlockSize.OneFourth, | ||
| ]} | ||
| > | ||
| BlockSize.Full, BlockSize.Half, BlockSize.OneThird, BlockSize.OneFourth, | ||
| </Box> | ||
| <Box | ||
| width={[ | ||
| BlockSize.Full, | ||
| BlockSize.Half, | ||
| BlockSize.OneThird, | ||
| BlockSize.OneFourth, | ||
| ]} | ||
| > | ||
| BlockSize.Full, BlockSize.Half, BlockSize.OneThird, BlockSize.OneFourth, | ||
| </Box> | ||
| <Box | ||
| width={[ | ||
| BlockSize.Full, | ||
| BlockSize.Half, | ||
| BlockSize.OneThird, | ||
| BlockSize.OneFourth, | ||
| ]} | ||
| > | ||
| BlockSize.Full, BlockSize.Half, BlockSize.OneThird, BlockSize.OneFourth, | ||
| </Box> | ||
| <Box | ||
| width={[ | ||
| BlockSize.Full, | ||
| BlockSize.Half, | ||
| BlockSize.OneThird, | ||
| BlockSize.OneFourth, | ||
| ]} | ||
| > | ||
| BlockSize.Full, BlockSize.Half, BlockSize.OneThird, BlockSize.OneFourth, | ||
| </Box> | ||
| </Box> | ||
| </>; | ||
| ``` |
Oops, something went wrong.