From be373d639a8bf57022c59378d9e134af9d61b606 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 31 Aug 2020 10:53:56 -0500 Subject: [PATCH] docs(react): update grid docs (#6733) * docs(react): update grid docs * docs(react): update toc of grid docs * Update packages/react/src/components/Grid/Grid.mdx Co-authored-by: Alison Joseph * chore(react): remove console.log * chore(grid): run prettier Co-authored-by: Alison Joseph Co-authored-by: TJ Egan Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> --- packages/react/src/components/Grid/Column.js | 2 +- .../react/src/components/Grid/Grid-story.js | 100 +++++-- .../react/src/components/Grid/Grid-story.scss | 4 +- packages/react/src/components/Grid/Grid.js | 4 +- packages/react/src/components/Grid/Grid.mdx | 258 ++++++++++++++++++ 5 files changed, 344 insertions(+), 24 deletions(-) create mode 100644 packages/react/src/components/Grid/Grid.mdx diff --git a/packages/react/src/components/Grid/Column.js b/packages/react/src/components/Grid/Column.js index 3cb191eaa478..e89c007bc6c7 100644 --- a/packages/react/src/components/Grid/Column.js +++ b/packages/react/src/components/Grid/Column.js @@ -119,7 +119,7 @@ function getClassNameForBreakpoints(breakpoints) { for (let i = 0; i < breakpoints.length; i++) { const breakpoint = breakpoints[i]; - if (!breakpoint) { + if (breakpoint === undefined || breakpoint === null) { continue; } diff --git a/packages/react/src/components/Grid/Grid-story.js b/packages/react/src/components/Grid/Grid-story.js index 21496e871fce..d5be8199e5d2 100644 --- a/packages/react/src/components/Grid/Grid-story.js +++ b/packages/react/src/components/Grid/Grid-story.js @@ -1,6 +1,7 @@ import './Grid-story.scss'; import React from 'react'; import { Grid, Row, Column } from './'; +import mdx from './Grid.mdx'; export default { title: 'Grid', @@ -10,6 +11,11 @@ export default { Column, }, decorators: [(storyFn) =>
{storyFn()}
], + parameters: { + docs: { + page: mdx, + }, + }, }; function DemoContent({ children }) { @@ -24,16 +30,16 @@ export const autoColumns = () => ( - 1/4 + Span 25% - 1/4 + Span 25% - 1/4 + Span 25% - 1/4 + Span 25% @@ -42,17 +48,26 @@ export const autoColumns = () => ( export const responsiveGrid = () => ( - - sm: 1/4, md: 1/2, lg: 2/3 - - - sm: 1/4, md: 1/4, lg: 1/6 - - - sm: 1/4, md: 1/8, lg: 1/12 - - - sm: 1/4, md: 1/8, lg: 1/12 + + +

Small: Span 2 of 4

+

Medium: Span 4 of 8

+

Large: Span 6 of 12

+ + + + +

Small: Span 2 of 4

+

Medium: Span 2 of 8

+

Large: Span 3 of 12

+ + + + +

Small: Span 0 of 4

+

Medium: Span 2 of 8

+

Large: Span 3 of 12

+ @@ -62,16 +77,16 @@ export const offset = () => ( - Small Screen Offset 3 + Small: offset 3 - Small Screen Offset 2 + Small: offset 2 - Small Screen Offset 1 + Small: offset 1 - Small Screen Offset 0 + Small: offset 0 @@ -227,3 +242,50 @@ export const fullWidth = () => ( ); + +export const mixedGridModes = () => ( + + + + Wide + + + 1/4 + + + 1/4 + + + 1/4 + + + + + Narrow + + + 1/4 + + + 1/4 + + + 1/4 + + + + + Condensed + + + 1/4 + + + 1/4 + + + 1/4 + + + +); diff --git a/packages/react/src/components/Grid/Grid-story.scss b/packages/react/src/components/Grid/Grid-story.scss index 2dd6595c617f..01731fe13d60 100644 --- a/packages/react/src/components/Grid/Grid-story.scss +++ b/packages/react/src/components/Grid/Grid-story.scss @@ -6,12 +6,12 @@ } // grid styles -#root .outside { +.bx--grid .outside { min-height: 80px; height: 100%; } -#root .inside { +.bx--grid .inside { min-height: 80px; height: 100%; } diff --git a/packages/react/src/components/Grid/Grid.js b/packages/react/src/components/Grid/Grid.js index 5e04f5ffe926..ddfd50eee500 100644 --- a/packages/react/src/components/Grid/Grid.js +++ b/packages/react/src/components/Grid/Grid.js @@ -52,8 +52,8 @@ Grid.propTypes = { className: PropTypes.string, /** - * Collapse the gutter to 2px. Useful for fluid layouts. - * Rows have 2px of margin between them to match gutter. + * Collapse the gutter to 1px. Useful for fluid layouts. + * Rows have 1px of margin between them to match gutter. */ condensed: PropTypes.bool, diff --git a/packages/react/src/components/Grid/Grid.mdx b/packages/react/src/components/Grid/Grid.mdx new file mode 100644 index 000000000000..30e2585df452 --- /dev/null +++ b/packages/react/src/components/Grid/Grid.mdx @@ -0,0 +1,258 @@ +import { Story, Preview, Props } from '@storybook/addon-docs/blocks'; + +# Grid + + + + +## Table of Contents + +- [Overview](#overview) +- [Grid modes](#grid-modes) + - [Wide grid](#wide-grid) + - [Narrow grid](#narrow-grid) + - [Condensed grid](#condensed-grid) + - [Mix-and-match](#mix-and-match) +- [Auto columns](#auto-columns) +- [Offset columns](#offset-columns) +- [Component API](#component-api) + - [Using the `as` prop](#using-the-as-prop) +- [FAQ](#faq) + - [How can I hide columns at a certain breakpoint?](#how-can-i-hide-columns-at-a-certain-breakpoint) + - [Can I nest grid components?](#can-i-nest-grid-components) +- [Feedback](#feedback) + + + + +Carbon's grid components help developers use the +[2x Grid](https://www.carbondesignsystem.com/guidelines/2x-grid/overview). The +project provides `Grid`, `Row`, and `Column` components which can be used to +build a variety of layouts. You can import these components from +`carbon-components-react`: + +```js +import { Grid, Row, Column } from 'carbon-components-react'; +``` + + + + + +## Overview + +Every layout starts with the `Grid` component. You can specify a `Grid` at the +top-level of your project, or at different depths provided that it can span +100% width of its container. + +Next, you will use a combination of `Row` and `Column`. You can have multiple +`Row` components in a `Grid`, and multiple `Column` components in a `Row`. Each +`Row` will contain all the `Column` components provided to it, as long as they +don't span more columns than the total number of columns in the grid. + +To specify how many columns the `Column` component should span, you can use the +`sm`, `md`, `lg`, `xlg`, or `max` props. These props are shorthand versions of +the names given to each of the breakpoints defined by the +[2x Grid](https://www.carbondesignsystem.com/guidelines/2x-grid/implementation/#responsive-options). +In the example below, we will use the `lg` prop for the large breakpoint and the +number `4` to specify that each `Column` component should span 4 columns at that +breakpoint. + +```js +import { Grid, Row, Column } from 'carbon-components-react'; + +function MyComponent() { + return ( + + + Span 4 of 12 + Span 4 of 12 + Span 4 of 12 + Span 4 of 12 + + + ); +} +``` + +_Note: by default, `carbon-components` ships with a 12 column grid. You can +enable a 16 column grid, which will be the default grid in the next major +version, by using our +[feature flags in Sass](https://github.com/carbon-design-system/carbon/blob/master/docs/guides/sass.md#feature-flags)._ + +You can pair up multiple breakpoint props to specify how many columns the +`Column` component should span at different break points. In the example below, +we will use the `sm`, `md`, and `lg` prop to specify how many columns the +`Column` components should span at the small, medium, and large breakpoints. + + + + + +## Grid modes + +There are several +[grid modes](https://www.carbondesignsystem.com/guidelines/2x-grid/implementation/#grid-modes) +that you can use depending on the layout effect you're looking to achieve. By +default, `Grid` uses the wide grid mode with a 32px gutter. However, you can use +the `narrow` or `condensed` props to enable the narrow and condensed grid modes, +respectively. + +The same way that you can pass in `narrow` or `condensed` to the `Grid` +component, you can also pass in `narrow` or `condensed` to a `Row` component to +enable a certain grid mode but only for a row. This can be useful when you need +to mix-and-match certain grid modes to achieve a particular layout. + +### Wide grid + + + + + +### Narrow grid + + + + + +### Condensed grid + + + + + +### Mix-and-match + + + + + +## Auto columns + +In some situations, you may want your content to span a specific proportion of +the grid without having to calculate it across every breakpoint. A common +use-case for this is if you have a row of four cards and want each to span 25% +width each. + +In these situations, you can make use of the auto columns feature of the +`Column` component. Auto columns is enabled when you do not provide any +breakpoint props, and it will automatically set each column to a percentage of +the total available width. + +For example, if you have on `Column` component it would span 100%, two `Column` +components would span 50% each, four `Column` components would span 25% each, +and so on. + + + + + +## Offset columns + +You can offset your `Column` components by a specific amount of columns using +the object form for each breakpoint prop. This specific prop type allows you to +pass in an object to each breakpoint prop and this object has two keys, `span` +and `offset`, which allow you to specify the total numbers of columns the +`Column` component spans, and how many columns to offset it by. + +You can specify either prop in this object form, and can mix-and-match across +breakpoints. For example, the following snippet will have the `Column` component +span two columns at the small breakpoint and then four columns at the medium +breakpoint. At the medium breakpoint, it will be offset by two columns. + +```jsx + +``` + + + + + +## Component API + + + +### Using the `as` prop + +By default, `Grid`, `Row`, and `Column` will render as a `div`. However, you can +use the `as` prop to change this to another HTML element, or a custom component +from your project. + +In the example below, we use the `as` prop on `Row` to change it from a `div` to +a `section`. Simililarly, we use the `as` prop on `Column` to change it from a +`div` to an `article`. + +```jsx +import { Grid, Row, Column } from 'carbon-components'react; + +function MyComponent() { + return ( + + + Example content + Example content + Example content + Example content + + + ); +} +``` + +You can also provide a custom component to the `as` prop. This custom component +should accept all props passed to it, like a class name for the column. + +```jsx +import { Grid, Row, Column } from 'carbon-components'react; + +function Article({ children, ...rest }) { + return
{children}
; +} + +function CustomColumn({ children, ...rest }) { + return {children} + + Example content + Example content + Example content + Example content + + + ); +} +``` + +## FAQ + +### How can I hide columns at a certain breakpoint? + +To hide a column at a specific breakpoint, you should specify 0 for the span of +the column at that particular breakpoint. For example, you can use the following +two forms for specifying column span and pass in 0 to either to hide the column +at the small breakpoint. + +```jsx + + +``` + +### Can I nest grid components? + +At the moment, there is no ability to nest grid components. In the future, we +may take advantage of CSS Grid and +[subgrid](https://caniuse.com/#feat=css-subgrid) alongside but at the moment we +are limited in terms of what we can support for nesting. + +If you would like to contribute nesting for the grid components available, we +would love for you to get in touch! + +## Feedback + +Help us improve these components by providing feedback, reaching out tot he +team, or updating this file on +[GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/Grid/Grid.mdx).