[Grid] Add responsive direction and spacing props

docs/pages/api-docs/grid.json

@@ -2,14 +2,25 @@
   "props": {
     "children": { "type": { "name": "node" } },
     "classes": { "type": { "name": "object" } },
-    "columns": { "type": { "name": "number" }, "default": "12" },
-    "columnSpacing": { "type": { "name": "number" } },
+    "columns": {
+      "type": {
+        "name": "union",
+        "description": "Array&lt;number&gt;<br>&#124;&nbsp;number<br>&#124;&nbsp;object"
+      },
+      "default": "12"
+    },
+    "columnSpacing": {
+      "type": {
+        "name": "union",
+        "description": "Array&lt;number<br>&#124;&nbsp;string&gt;<br>&#124;&nbsp;number<br>&#124;&nbsp;object<br>&#124;&nbsp;string"
+      }
+    },
     "component": { "type": { "name": "elementType" } },
     "container": { "type": { "name": "bool" } },
     "direction": {
       "type": {
-        "name": "enum",
-        "description": "'column-reverse'<br>&#124;&nbsp;'column'<br>&#124;&nbsp;'row-reverse'<br>&#124;&nbsp;'row'"
+        "name": "union",
+        "description": "'column-reverse'<br>&#124;&nbsp;'column'<br>&#124;&nbsp;'row-reverse'<br>&#124;&nbsp;'row'<br>&#124;&nbsp;Array&lt;'column-reverse'<br>&#124;&nbsp;'column'<br>&#124;&nbsp;'row-reverse'<br>&#124;&nbsp;'row'&gt;<br>&#124;&nbsp;object"
       },
       "default": "'row'"
     },
@@ -28,7 +39,12 @@
       },
       "default": "false"
     },
-    "rowSpacing": { "type": { "name": "number" } },
+    "rowSpacing": {
+      "type": {
+        "name": "union",
+        "description": "Array&lt;number<br>&#124;&nbsp;string&gt;<br>&#124;&nbsp;number<br>&#124;&nbsp;object<br>&#124;&nbsp;string"
+      }
+    },
     "sm": {
       "type": {
         "name": "union",
@@ -37,7 +53,10 @@
       "default": "false"
     },
     "spacing": {
-      "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },
+      "type": {
+        "name": "union",
+        "description": "Array&lt;number<br>&#124;&nbsp;string&gt;<br>&#124;&nbsp;number<br>&#124;&nbsp;object<br>&#124;&nbsp;string"
+      },
       "default": "0"
     },
     "sx": { "type": { "name": "object" } },

docs/src/pages/components/grid/ResponsiveGrid.js

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { experimentalStyled as styled } from '@material-ui/core/styles';
+import Box from '@material-ui/core/Box';
+import Paper from '@material-ui/core/Paper';
+import Grid from '@material-ui/core/Grid';
+
+const Item = styled(Paper)(({ theme }) => ({
+  ...theme.typography.body2,
+  padding: theme.spacing(2),
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+}));
+
+export default function ResponsiveGrid() {
+  return (
+    <Box sx={{ flexGrow: 1 }}>
+      <Grid container spacing={{ xs: 2, md: 3 }} columns={{ xs: 4, sm: 8, md: 12 }}>
+        {Array.from(Array(6)).map((_, index) => (
+          <Grid item xs={2} sm={4} md={4} key={index}>
+            <Item>xs=2</Item>
+          </Grid>
+        ))}
+      </Grid>
+    </Box>
+  );
+}

docs/src/pages/components/grid/ResponsiveGrid.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { experimentalStyled as styled } from '@material-ui/core/styles';
+import Box from '@material-ui/core/Box';
+import Paper from '@material-ui/core/Paper';
+import Grid from '@material-ui/core/Grid';
+
+const Item = styled(Paper)(({ theme }) => ({
+  ...theme.typography.body2,
+  padding: theme.spacing(2),
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+}));
+
+export default function ResponsiveGrid() {
+  return (
+    <Box sx={{ flexGrow: 1 }}>
+      <Grid container spacing={{ xs: 2, md: 3 }} columns={{ xs: 4, sm: 8, md: 12 }}>
+        {Array.from(Array(6)).map((_, index) => (
+          <Grid item xs={2} sm={4} md={4} key={index}>
+            <Item>xs=2</Item>
+          </Grid>
+        ))}
+      </Grid>
+    </Box>
+  );
+}

docs/src/pages/components/grid/RowAndColumnSpacing.js

@@ -14,7 +14,7 @@ const Item = styled(Paper)(({ theme }) => ({
 export default function RowAndColumnSpacing() {
   return (
     <Box sx={{ width: '100%' }}>
-      <Grid container rowSpacing={1} columnSpacing={3}>
+      <Grid container rowSpacing={1} columnSpacing={{ xs: 1, sm: 2, md: 3 }}>
         <Grid item xs={6}>
           <Item>1</Item>
         </Grid>

docs/src/pages/components/grid/RowAndColumnSpacing.tsx

@@ -14,7 +14,7 @@ const Item = styled(Paper)(({ theme }) => ({
 export default function RowAndColumnSpacing() {
   return (
     <Box sx={{ width: '100%' }}>
-      <Grid container rowSpacing={1} columnSpacing={3}>
+      <Grid container rowSpacing={1} columnSpacing={{ xs: 1, sm: 2, md: 3 }}>
         <Grid item xs={6}>
           <Item>1</Item>
         </Grid>

docs/src/pages/components/grid/grid.md

@@ -57,6 +57,29 @@ The prop is converted into a CSS property using the [`theme.spacing()`](/customi
 
 {{"demo": "pages/components/grid/SpacingGrid.js", "bg": true}}
 
+## Responsive values
+
+You can switch the props' value based on the active breakpoint.
+For instance, we can implement the ["recommended"](https://material.io/design/layout/responsive-layout-grid.html) responsive layout grid of Material Design.
+
+{{"demo": "pages/components/grid/ResponsiveGrid.js", "bg": true}}
+
+Responsive values is supported by:
+
+- `spacing`
+- `direction`
+- `columns`
+- all the [other props](#system-props) of the system
+
+> ⚠️ When using a responsive `columns` prop, each grid item needs its corresponding breakpoint.
+> For instance, this is not working. The grid item misses the value for `md`:
+>
+> ```jsx
+> <Grid container columns={{ xs: 4, md: 12 }}>
+>   <Grid item xs={2} />
+> </Grid>
+> ```
+
 ### Row & column spacing
 
 The `rowSpacing` and `columnSpacing` props allow for specifying the row and column gaps independently.

docs/src/pages/components/stack/stack.md

@@ -34,7 +34,7 @@ Use the `divider` prop to insert an element between each child. This works parti
 
 ## Responsive values
 
-Easily switch `direction` or `spacing` based on the active breakpoint.
+You can switch the `direction` or `spacing` values based on the active breakpoint.
 
 {{"demo": "pages/components/stack/ResponsiveStack.js", "bg": true}}
 

packages/material-ui/src/Grid/Grid.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { SxProps, SystemProps } from '@material-ui/system';
+import { ResponsiveStyleValue, SxProps, SystemProps } from '@material-ui/system';
 import { Theme } from '../styles';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
 import { GridClasses } from './gridClasses';
@@ -27,12 +27,12 @@ export interface GridTypeMap<P = {}, D extends React.ElementType = 'div'> {
        * The number of columns.
        * @default 12
        */
-      columns?: number;
+      columns?: ResponsiveStyleValue<number>;
       /**
        * Defines the horizontal space between the type `item` components.
        * It overrides the value of the `spacing` prop.
        */
-      columnSpacing?: number;
+      columnSpacing?: ResponsiveStyleValue<GridSpacing>;
       /**
        * If `true`, the component will have the flex *container* behavior.
        * You should be wrapping *items* with a *container*.
@@ -44,7 +44,7 @@ export interface GridTypeMap<P = {}, D extends React.ElementType = 'div'> {
        * It is applied for all screen sizes.
        * @default 'row'
        */
-      direction?: GridDirection;
+      direction?: ResponsiveStyleValue<GridDirection>;
       /**
        * If `true`, the component will have the flex *item* behavior.
        * You should be wrapping *items* with a *container*.
@@ -67,7 +67,7 @@ export interface GridTypeMap<P = {}, D extends React.ElementType = 'div'> {
        * Defines the vertical space between the type `item` components.
        * It overrides the value of the `spacing` prop.
        */
-      rowSpacing?: number;
+      rowSpacing?: ResponsiveStyleValue<GridSpacing>;
       /**
        * Defines the number of grids the component is going to use.
        * It's applied for the `sm` breakpoint and wider screens if not overridden.
@@ -79,7 +79,7 @@ export interface GridTypeMap<P = {}, D extends React.ElementType = 'div'> {
        * It can only be used on a type `container` component.
        * @default 0
        */
-      spacing?: GridSpacing;
+      spacing?: ResponsiveStyleValue<GridSpacing>;
       /**
        * The system prop that allows defining system overrides as well as additional CSS styles.
        */