[docs] Improve the theme nesting documentation

docs/src/pages/css-in-js/advanced/advanced.md

@@ -25,8 +25,29 @@ You might need to access the theme variables inside your React components.
 You can nest multiple theme providers.
 This can be really useful when dealing with different area of your application that have distinct appearance from each other.
 
+```jsx
+<ThemeProvider theme={outerTheme}>
+  <Child1 />
+  <ThemeProvider theme={innerTheme}>
+    <Child2 />
+  </ThemeProvider>
+</ThemeProvider>
+```
+
 {{"demo": "pages/css-in-js/advanced/ThemeNesting.js", "react": "next"}}
 
+The inner theme will **override** the outer theme.
+You can extend the outer theme by providing a function:
+
+```jsx
+<ThemeProvider theme={…} >
+  <Child1 />
+  <ThemeProvider theme={outerTheme => ({ darkMode: true, ...outerTheme })}>
+    <Child2 />
+  </ThemeProvider>
+</ThemeProvider>
+```
+
 ## JSS plugins
 
 JSS uses the concept of plugins to extend its core, allowing people to cherry-pick the features they need.

docs/src/pages/customization/themes/CustomStyles.js

@@ -35,6 +35,7 @@ const theme = createMuiTheme({
     // My business variables
     danger: orange[500],
   },
+  typography: { useNextVariants: true },
 });
 
 function CustomStyles() {

docs/src/pages/customization/themes/DarkTheme.js

@@ -6,9 +6,7 @@ const theme = createMuiTheme({
   palette: {
     type: 'dark', // Switching the dark mode on is a single property value change.
   },
-  typography: {
-    useNextVariants: true,
-  },
+  typography: { useNextVariants: true },
 });
 
 function DarkTheme() {

docs/src/pages/customization/themes/OverridesCss.js

@@ -19,6 +19,7 @@ const theme = createMuiTheme({
       },
     },
   },
+  typography: { useNextVariants: true },
 });
 
 function OverridesCss() {

docs/src/pages/customization/themes/OverridesProperties.js

@@ -10,6 +10,7 @@ const theme = createMuiTheme({
       disableRipple: true, // No more ripple, on the whole application 💣!
     },
   },
+  typography: { useNextVariants: true },
 });
 
 function OverridesProperties() {

docs/src/pages/customization/themes/Palette.js

@@ -8,6 +8,7 @@ const theme = createMuiTheme({
     primary: { main: purple[500] }, // Purple and green play nicely together.
     secondary: { main: '#11cb5f' }, // This is just green.A700 as hex.
   },
+  typography: { useNextVariants: true },
 });
 
 function Palette() {

docs/src/pages/customization/themes/ThemeNesting.js

@@ -0,0 +1,36 @@
+import React from 'react';
+import { createMuiTheme, MuiThemeProvider } from '@material-ui/core/styles';
+import Checkbox from '@material-ui/core/Checkbox';
+import orange from '@material-ui/core/colors/orange';
+import green from '@material-ui/core/colors/green';
+
+const outerTheme = createMuiTheme({
+  palette: {
+    secondary: {
+      main: orange[500],
+    },
+  },
+  typography: { useNextVariants: true },
+});
+
+const innerTheme = createMuiTheme({
+  palette: {
+    secondary: {
+      main: green[500],
+    },
+  },
+  typography: { useNextVariants: true },
+});
+
+function ThemeNesting() {
+  return (
+    <MuiThemeProvider theme={outerTheme}>
+      <Checkbox defaultChecked />
+      <MuiThemeProvider theme={innerTheme}>
+        <Checkbox defaultChecked />
+      </MuiThemeProvider>
+    </MuiThemeProvider>
+  );
+}
+
+export default ThemeNesting;

docs/src/pages/customization/themes/ThemeNestingExtend.js

@@ -0,0 +1,40 @@
+import React from 'react';
+import { createMuiTheme, MuiThemeProvider } from '@material-ui/core/styles';
+import Checkbox from '@material-ui/core/Checkbox';
+import orange from '@material-ui/core/colors/orange';
+import green from '@material-ui/core/colors/green';
+
+const outerTheme = createMuiTheme({
+  palette: {
+    secondary: {
+      main: orange[500],
+    },
+  },
+  typography: { useNextVariants: true },
+});
+
+function ThemeNestingExtend() {
+  return (
+    <MuiThemeProvider theme={outerTheme}>
+      <Checkbox defaultChecked />
+      <MuiThemeProvider
+        theme={theme =>
+          createMuiTheme({
+            ...theme,
+            palette: {
+              ...theme.palette,
+              primary: {
+                main: green[500],
+              },
+            },
+          })
+        }
+      >
+        <Checkbox defaultChecked color="primary" />
+        <Checkbox defaultChecked color="secondary" />
+      </MuiThemeProvider>
+    </MuiThemeProvider>
+  );
+}
+
+export default ThemeNestingExtend;

docs/src/pages/customization/themes/themes.md

@@ -356,10 +356,15 @@ Let's say you want to display the value of the primary color, you can use the `w
 
 ## Nesting the theme
 
-The theming solution is very flexible, as you can nest multiple theme providers.
+The theming solution is very flexible, as [you can nest](/css-in-js/advanced/#theme-nesting) multiple theme providers.
 This can be really useful when dealing with different area of your application that have distinct appearance from each other.
 
-{{"demo": "pages/customization/themes/Nested.js"}}
+{{"demo": "pages/customization/themes/ThemeNesting.js"}}
+
+The inner theme will **override** the outer theme.
+You can extend the outer theme by providing a function:
+
+{{"demo": "pages/customization/themes/ThemeNestingExtend.js"}}
 
 #### A note on performance
 

pages/customization/themes.js

@@ -65,11 +65,18 @@ module.exports = require('fs')
   .readFileSync(require.resolve('docs/src/pages/customization/themes/WithTheme'), 'utf8')
 `,
         },
-        'pages/customization/themes/Nested.js': {
-          js: require('docs/src/pages/customization/themes/Nested').default,
+        'pages/customization/themes/ThemeNesting.js': {
+          js: require('docs/src/pages/customization/themes/ThemeNesting').default,
           raw: preval`
 module.exports = require('fs')
-  .readFileSync(require.resolve('docs/src/pages/customization/themes/Nested'), 'utf8')
+  .readFileSync(require.resolve('docs/src/pages/customization/themes/ThemeNesting'), 'utf8')
+`,
+        },
+        'pages/customization/themes/ThemeNestingExtend.js': {
+          js: require('docs/src/pages/customization/themes/ThemeNestingExtend').default,
+          raw: preval`
+module.exports = require('fs')
+  .readFileSync(require.resolve('docs/src/pages/customization/themes/ThemeNestingExtend'), 'utf8')
 `,
         },
       }}