docs(box): Adjust examples and props descriptions

telus · Nov 13, 2017 · f4a4d37 · f4a4d37
1 parent e308466
commit f4a4d37
Show file tree

Hide file tree

Showing 8 changed files with 56 additions and 73 deletions.
diff --git a/docs/components/MarkdownHeading/__tests__/__snapshots__/MarkdownHeading.spec.jsx.snap b/docs/components/MarkdownHeading/__tests__/__snapshots__/MarkdownHeading.spec.jsx.snap
@@ -4,6 +4,7 @@ exports[`MarkdownHeading renders 1`] = `
 <Box
   below={3}
   inline={false}
+  tag="div"
 >
   <Heading
     invert={false}

diff --git a/docs/components/SectionHeading/__tests__/__snapshots__/SectionHeading.spec.jsx.snap b/docs/components/SectionHeading/__tests__/__snapshots__/SectionHeading.spec.jsx.snap
@@ -4,6 +4,7 @@ exports[`SectionHeadingRenderer renders 1`] = `
 <Box
   below={3}
   inline={false}
+  tag="div"
 >
   <Heading
     id="a-section"

diff --git a/docs/scss/_examples.scss b/docs/scss/_examples.scss
@@ -61,7 +61,3 @@
 .docs_divider-height {
   height: 150px;
 }
-
-.docs_flex-button {
-  align-items: flex-start;
-}
diff --git a/src/components/Box/Box.jsx b/src/components/Box/Box.jsx
@@ -28,18 +28,18 @@ const getBetweenClasses = (betweenSize, inline) => {
 }
 
 /**
- * Apply spacing within or around components
+ * Apply spacing within or around components.
  *
  * <span class="docs--badge__new">new!</span> <span class="docs--badge__version">v0.29.0</span>
  */
 const Box = ({
-  inline,
   tag,
   vertical,
   horizontal,
   inset,
   below,
   between,
+  inline,
   dangerouslyAddClassName,
   children,
   ...rest
@@ -55,42 +55,52 @@ const Box = ({
     dangerouslyAddClassName
   )
 
-  return React.createElement(tag || 'div', { ...safeRest(rest), className: classes }, children)
+  return React.createElement(tag, { ...safeRest(rest), className: classes }, children)
 }
 
 Box.propTypes = {
   /**
-   * If `true`, sets `flex-direction: row` to Box, arranging direct children as a row. This is used in conjunction with the `between` prop.
-   */
-  inline: PropTypes.bool,
-  /**
-   * Specifies which HTML element to render Box as. Example: `"section"`.
+   * Specify an HTML element to render, such as `section`.
    */
   tag: PropTypes.string,
   /**
-   * Sets a `padding-top` and `padding-bottom`.
+   * Indent content from the container's top and bottom edge by applying padding.
    */
   vertical: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
   /**
-   * Sets a `padding-left` and `padding-right`.
+   * Indent content from the container's left and right edge by applying padding.
    */
   horizontal: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
   /**
-   * Sets `padding` on all four sides.
+   * Indent content from all of the container's edges by applying padding.
    */
   inset: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
   /**
    * @ignore
    *
+   * We are keeping this hidden for now as we are not sold on the necessity. We use it internally still to apply
+   * spacing to Markdown components, but would like to use between instead if the library allows it.
+   *
    * Sets a `margin-bottom`.
    */
   below: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
   /**
-   * Sets a `margin-bottom` to all direct children except the last. If the `inline` prop is set to `true`, this sets a `margin-right` to all direct children except the last. When the `inline` prop is not used, the Box will have `flex-direction: column` set.
+   * Create either a block or an inline stack, applying margin in between every direct child. Margin will not be
+   * applied to the last component in the stack.
+   *
+   * By default, `between` will arrange the Box's children as a flex column. Combine with `inline` to arrange them
+   * as a flex row.
    */
   between: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
   /**
-   * Append custom classes to `className`.
+   * Arrange children in a row. Combine with `between` to apply margins in between the row's elements.
+   */
+  inline: PropTypes.bool,
+  /**
+   * Append custom classes to `className`. Use sparingly, and do not attempt to override Box style properties as that
+   * may cause unexpected behaviour.
+   *
+   * You would typically use this feature to apply flex alignment properties in combination with `between`.
    */
   dangerouslyAddClassName: PropTypes.string,
   /**
@@ -101,7 +111,7 @@ Box.propTypes = {
 
 Box.defaultProps = {
   inline: false,
-  tag: undefined,
+  tag: 'div',
   vertical: undefined,
   horizontal: undefined,
   inset: undefined,

diff --git a/src/components/Box/Box.md b/src/components/Box/Box.md
@@ -1,20 +1,8 @@
-```jsx
-<Card>
-  <Box between={4} dangerouslyAddClassName="docs_flex-button">
-    <Box between={3}>
-      <Heading level="h1">Our latest and greatest</Heading>
-      <Paragraph>Everything you would expect, without conditions.</Paragraph>
-    </Box>
-    <ButtonLink href="//telus.com">Learn more</ButtonLink>
-  </Box>
-</Card>
-```
+### Spacing levels
 
-## Spacing matrix
+The spacing system defines 8 levels of spacing. Levels `4` and above are responsive, as detailed in this table:
 
-The Box component contains props that accept values from `1` to `8`. These numbered values correspond to our spacing system. Numbers `4` and above feature responsive spacing, as detailed in this table:
-
-| Number | Default value | Value in viewports greater or equal to `768px` | 
+| Level | Default value | Value in viewports greater or equal to `768px` |
 | ------ | ------------: | -------------------------------------------: |
 | 1 | 0.25rem (4px) | _unchanged_ |
 | 2 | 0.5rem (8px) | _unchanged_ |
@@ -25,13 +13,15 @@ The Box component contains props that accept values from `1` to `8`. These numbe
 | 7 | 3rem (48px) | 4.5rem (72px) |
 | 8 | 4rem (64px) | 6rem (96px) |
 
-### Usage tips
+### Recommended usage
+
+- Use levels `1` - `3` to space inline content, such as [Typography](#typography), [Buttons](#button), or [Icons](#icons)
+- Use levels `4` - `8` to space block content, such as [Cards](#card) or [Dividers](#dividers)
+- Use levels `5`, `7`, and `8` to vertically stack full-width Blocks
 
-- Numbers `1` to `3` are suitable for spacing inline content such as [Typography](#typography), [Button](#button), and [ButtonLink](#buttonlink) components
-- Numbers `4` to `8` are suitable for spacing major types of content such as [Cards](#card) and [Dividers](#dividers)
-- Numbers `5`, `7`, and `8` are used to space blocks vertically
 
-### Example separating blocks
+These examples showcase all of the `Box` properties working together to control both inset (padding) and stacking (margin).
+Note the compositional nature of `Box`. Use multiple Boxes to achieve complex layouts.  
 
 ```jsx
 <Box between={5}>
@@ -49,44 +39,14 @@ The Box component contains props that accept values from `1` to `8`. These numbe
 </Box>
 ```
 
-## Spacing in between elements
-
-When wrapping a Box element around a series of elements, use the `between` prop to add either `margin-right` for inline elements or `margin-bottom` for stacked elements. Spacing will be applied to all directly-descending children except the last in the series.
-
-### Stacked
-
-```jsx 
-<Box between={3}>
-  <Box between={2}>
-    <Heading level="h4">Wi-Fi Enabled</Heading>
-
-    <Paragraph>Control any device connected to your SmartPlug from any location with internet access.</Paragraph>
-  </Box>
-
-  <Box between={2}>
-    <Heading level="h4">Create ‘Scenes’</Heading>
-
-    <Paragraph>Create your own scenes and rooms such as 'Kitchen' and manage all SmartPlugs in that scene.</Paragraph>
-  </Box>
-
-  <Box between={2}>
-    <Heading level="h4">Compatibility</Heading>
-
-    <Paragraph>Works with Google Assistant, Amazon Alexa, Apple HomeKit, and Nest.</Paragraph>
-  </Box>
-</Box>
-```
-
-### Inline
-
 ```jsx
 <Box inline between={3}>
-  <Link href="//telus.com">Phones</Link>
+  <Link href="#">Phones</Link>
   <span>|</span>
-  <Link href="//telus.com">Pre-Owned</Link>
+  <Link href="#">Pre-Owned</Link>
   <span>|</span>
-  <Link href="//telus.com">Prepaid</Link>
+  <Link href="#">Prepaid</Link>
   <span>|</span>
-  <Link href="//telus.com">Sale</Link>
+  <Link href="#">Sale</Link>
 </Box>
 ```
diff --git a/src/components/Box/Box.modules.scss b/src/components/Box/Box.modules.scss
@@ -35,7 +35,6 @@ $responsive-spacings: (
   flex-direction: column;
 }
 
-// Todo remove unneeded classes related to margin
 @mixin spacingClasses ($level, $value) {
   .verticalPadding-#{$level} {
     padding-top: $value;

diff --git a/src/components/ExpandCollapse/Accordion/__tests__/__snapshots__/Accordion.spec.jsx.snap b/src/components/ExpandCollapse/Accordion/__tests__/__snapshots__/Accordion.spec.jsx.snap
@@ -49,6 +49,7 @@ exports[`Accordion renders a closed accordion 1`] = `
             >
               <Box
                 inline={false}
+                tag="div"
                 vertical={3}
               >
                 <div
@@ -57,6 +58,7 @@ exports[`Accordion renders a closed accordion 1`] = `
                   <Box
                     between={3}
                     inline={true}
+                    tag="div"
                   >
                     <div
                       className="betweenRightMargin-3 betweenRight"
@@ -120,6 +122,7 @@ exports[`Accordion renders a closed accordion 1`] = `
                             between={2}
                             dangerouslyAddClassName="headerAlign"
                             inline={false}
+                            tag="div"
                           >
                             <div
                               className="betweenBottomMargin-2 betweenBottom headerAlign"
@@ -188,6 +191,7 @@ exports[`Accordion renders a closed accordion 1`] = `
                   </DimpleDivider>
                   <Box
                     inline={false}
+                    tag="div"
                     vertical={3}
                   >
                     <div
@@ -286,6 +290,7 @@ exports[`Accordion renders an open accordion 1`] = `
             >
               <Box
                 inline={false}
+                tag="div"
                 vertical={3}
               >
                 <div
@@ -294,6 +299,7 @@ exports[`Accordion renders an open accordion 1`] = `
                   <Box
                     between={3}
                     inline={true}
+                    tag="div"
                   >
                     <div
                       className="betweenRightMargin-3 betweenRight"
@@ -357,6 +363,7 @@ exports[`Accordion renders an open accordion 1`] = `
                             between={2}
                             dangerouslyAddClassName="headerAlign"
                             inline={false}
+                            tag="div"
                           >
                             <div
                               className="betweenBottomMargin-2 betweenBottom headerAlign"
@@ -425,6 +432,7 @@ exports[`Accordion renders an open accordion 1`] = `
                   </DimpleDivider>
                   <Box
                     inline={false}
+                    tag="div"
                     vertical={3}
                   >
                     <div

diff --git a/src/components/ExpandCollapse/__tests__/__snapshots__/ExpandCollapse.spec.jsx.snap b/src/components/ExpandCollapse/__tests__/__snapshots__/ExpandCollapse.spec.jsx.snap
@@ -52,6 +52,7 @@ exports[`ExpandCollapse renders a closed panel 1`] = `
             >
               <Box
                 inline={false}
+                tag="div"
                 vertical={3}
               >
                 <div
@@ -60,6 +61,7 @@ exports[`ExpandCollapse renders a closed panel 1`] = `
                   <Box
                     between={3}
                     inline={true}
+                    tag="div"
                   >
                     <div
                       className="betweenRightMargin-3 betweenRight"
@@ -123,6 +125,7 @@ exports[`ExpandCollapse renders a closed panel 1`] = `
                             between={2}
                             dangerouslyAddClassName="headerAlign"
                             inline={false}
+                            tag="div"
                           >
                             <div
                               className="betweenBottomMargin-2 betweenBottom headerAlign"
@@ -191,6 +194,7 @@ exports[`ExpandCollapse renders a closed panel 1`] = `
                   </DimpleDivider>
                   <Box
                     inline={false}
+                    tag="div"
                     vertical={3}
                   >
                     <div
@@ -301,6 +305,7 @@ exports[`ExpandCollapse renders an open panel 1`] = `
             >
               <Box
                 inline={false}
+                tag="div"
                 vertical={3}
               >
                 <div
@@ -309,6 +314,7 @@ exports[`ExpandCollapse renders an open panel 1`] = `
                   <Box
                     between={3}
                     inline={true}
+                    tag="div"
                   >
                     <div
                       className="betweenRightMargin-3 betweenRight"
@@ -372,6 +378,7 @@ exports[`ExpandCollapse renders an open panel 1`] = `
                             between={2}
                             dangerouslyAddClassName="headerAlign"
                             inline={false}
+                            tag="div"
                           >
                             <div
                               className="betweenBottomMargin-2 betweenBottom headerAlign"
@@ -440,6 +447,7 @@ exports[`ExpandCollapse renders an open panel 1`] = `
                   </DimpleDivider>
                   <Box
                     inline={false}
+                    tag="div"
                     vertical={3}
                   >
                     <div