[Grid] Document the nested capability (#12313)

docs/src/pages/layout/grid/ComplexGrid.js

@@ -0,0 +1,63 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { withStyles } from '@material-ui/core/styles';
+import Grid from '@material-ui/core/Grid';
+import Paper from '@material-ui/core/Paper';
+import Typography from '@material-ui/core/Typography';
+import ButtonBase from '@material-ui/core/ButtonBase';
+
+const styles = theme => ({
+  root: {
+    flexGrow: 1,
+    maxWidth: 600,
+    padding: theme.spacing.unit * 2,
+  },
+  image: {
+    width: 128,
+    height: 128,
+  },
+  img: {
+    margin: 'auto',
+    display: 'block',
+    maxWidth: '100%',
+    maxHeight: '100%',
+  },
+});
+
+function ComplexGrid(props) {
+  const { classes } = props;
+  return (
+    <Paper className={classes.root}>
+      <Grid container spacing={16}>
+        <Grid item>
+          <ButtonBase className={classes.image}>
+            <img className={classes.img} alt="complex" src="/static/images/grid/complex.jpg" />
+          </ButtonBase>
+        </Grid>
+        <Grid item xs={12} sm container>
+          <Grid item xs container direction="column" spacing={16}>
+            <Grid item xs>
+              <Typography gutterBottom variant="subheading">
+                Standard license
+              </Typography>
+              <Typography gutterBottom>Full resolution 1920x1080 • JPEG</Typography>
+              <Typography color="textSecondary">ID: 1030114</Typography>
+            </Grid>
+            <Grid item>
+              <Typography style={{ cursor: 'pointer' }}>Remove</Typography>
+            </Grid>
+          </Grid>
+          <Grid item>
+            <Typography variant="subheading">$19.00</Typography>
+          </Grid>
+        </Grid>
+      </Grid>
+    </Paper>
+  );
+}
+
+ComplexGrid.propTypes = {
+  classes: PropTypes.object.isRequired,
+};
+
+export default withStyles(styles)(ComplexGrid);

docs/src/pages/layout/grid/InteractiveGrid.js

@@ -67,11 +67,12 @@ class InteractiveGrid extends React.Component {
         </Grid>
         <Grid item xs={12}>
           <Paper className={classes.control}>
-            <Grid container>
-              <Grid item xs={6} sm={4}>
+            <Grid container spacing={24}>
+              <Grid item xs={12}>
                 <FormControl component="fieldset">
                   <FormLabel>direction</FormLabel>
                   <RadioGroup
+                    row
                     name="direction"
                     aria-label="Direction"
                     value={direction}
@@ -88,10 +89,11 @@ class InteractiveGrid extends React.Component {
                   </RadioGroup>
                 </FormControl>
               </Grid>
-              <Grid item xs={6} sm={4}>
+              <Grid item xs={12}>
                 <FormControl component="fieldset">
                   <FormLabel>justify</FormLabel>
                   <RadioGroup
+                    row
                     name="justify"
                     aria-label="Justify"
                     value={justify}
@@ -110,13 +112,19 @@ class InteractiveGrid extends React.Component {
                       control={<Radio />}
                       label="space-around"
                     />
+                    <FormControlLabel
+                      value="space-evenly"
+                      control={<Radio />}
+                      label="space-evenly"
+                    />
                   </RadioGroup>
                 </FormControl>
               </Grid>
-              <Grid item xs={6} sm={4}>
+              <Grid item xs={12}>
                 <FormControl component="fieldset">
                   <FormLabel>alignItems</FormLabel>
                   <RadioGroup
+                    row
                     name="alignItems"
                     aria-label="Align items"
                     value={alignItems}

docs/src/pages/layout/grid/NestedGrid.js

@@ -0,0 +1,64 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { withStyles } from '@material-ui/core/styles';
+import Paper from '@material-ui/core/Paper';
+import Grid from '@material-ui/core/Grid';
+
+const styles = theme => ({
+  root: {
+    flexGrow: 1,
+  },
+  paper: {
+    padding: theme.spacing.unit,
+    textAlign: 'center',
+    color: theme.palette.text.secondary,
+  },
+});
+
+function FormRow(props) {
+  const { classes } = props;
+
+  return (
+    <React.Fragment>
+      <Grid item xs={4}>
+        <Paper className={classes.paper}>item</Paper>
+      </Grid>
+      <Grid item xs={4}>
+        <Paper className={classes.paper}>item</Paper>
+      </Grid>
+      <Grid item xs={4}>
+        <Paper className={classes.paper}>item</Paper>
+      </Grid>
+    </React.Fragment>
+  );
+}
+
+FormRow.propTypes = {
+  classes: PropTypes.object.isRequired,
+};
+
+function NestedGrid(props) {
+  const { classes } = props;
+
+  return (
+    <div className={classes.root}>
+      <Grid container spacing={8}>
+        <Grid item xs={12} container spacing={24}>
+          <FormRow classes={classes} />
+        </Grid>
+        <Grid item xs={12} container spacing={24}>
+          <FormRow classes={classes} />
+        </Grid>
+        <Grid item xs={12} container spacing={24}>
+          <FormRow classes={classes} />
+        </Grid>
+      </Grid>
+    </div>
+  );
+}
+
+NestedGrid.propTypes = {
+  classes: PropTypes.object.isRequired,
+};
+
+export default withStyles(styles)(NestedGrid);

docs/src/pages/layout/grid/grid.md

@@ -63,6 +63,22 @@ Unfortunately, CSS grid is only supported by the most recent browsers.
 
 {{"demo": "pages/layout/grid/CSSGrid.js"}}
 
+## Nested Grid
+
+The `container` and `item` properties are two independant boolean. They can be combined.
+
+> A flex **container** is the box generated by an element with a computed display of `flex` or `inline-flex`. In-flow children of a flex container are called flex **items** and are laid out using the flex layout model.
+
+https://www.w3.org/TR/css-flexbox-1/#box-model
+
+{{"demo": "pages/layout/grid/NestedGrid.js"}}
+
+## Complex Grid
+
+The following demo doesn't follow the Material Design specification, but illustrates how the grid can be used to build complex layouts.
+
+{{"demo": "pages/layout/grid/ComplexGrid.js"}}
+
 ## Limitations
 
 ### Negative margin

pages/layout/grid.js

@@ -48,6 +48,20 @@ module.exports = require('fs')
           raw: preval`
 module.exports = require('fs')
   .readFileSync(require.resolve('docs/src/pages/layout/grid/CSSGrid'), 'utf8')
+`,
+        },
+        'pages/layout/grid/NestedGrid.js': {
+          js: require('docs/src/pages/layout/grid/NestedGrid').default,
+          raw: preval`
+module.exports = require('fs')
+  .readFileSync(require.resolve('docs/src/pages/layout/grid/NestedGrid'), 'utf8')
+`,
+        },
+        'pages/layout/grid/ComplexGrid.js': {
+          js: require('docs/src/pages/layout/grid/ComplexGrid').default,
+          raw: preval`
+module.exports = require('fs')
+  .readFileSync(require.resolve('docs/src/pages/layout/grid/ComplexGrid'), 'utf8')
 `,
         },
         'pages/layout/grid/AutoGridNoWrap.js': {