[docs] Improve right to left guide

docs/src/pages/guides/right-to-left/RtlOptOutStylis.js

@@ -1,12 +1,14 @@
 import * as React from 'react';
-import { createTheme } from '@material-ui/core/styles';
-import styled from '@emotion/styled';
-import { ThemeProvider } from '@emotion/react';
+import rtlPlugin from 'stylis-plugin-rtl';
+import { CacheProvider } from '@emotion/react';
+import createCache from '@emotion/cache';
+import { styled } from '@material-ui/core/styles';
+import FormControlLabel from '@material-ui/core/FormControlLabel';
+import Switch from '@material-ui/core/Switch';
 
 const Root = styled('div')((props) => ({
   width: '100%',
-  marginTop: props.theme?.spacing(4),
-  marginRight: props.theme?.spacing(2),
+  marginTop: props.theme?.spacing(6),
 }));
 
 const AffectedText = styled('div')`
@@ -18,15 +20,37 @@ const UnaffectedText = styled('div')`
   text-align: left;
 `;
 
-const theme = createTheme();
+const rtlCache = createCache({
+  key: 'muirtl',
+  // @ts-ignore external dependency
+  stylisPlugins: [rtlPlugin],
+});
+
+const ltrCache = createCache({
+  key: 'mui',
+});
 
 export default function RtlOptOut() {
+  const [rtl, setRtl] = React.useState(false);
+
+  const handleChage = () => {
+    setRtl(!rtl);
+  };
+
   return (
-    <ThemeProvider theme={theme}>
-      <Root>
-        <AffectedText>Affected</AffectedText>
-        <UnaffectedText>Unaffected</UnaffectedText>
-      </Root>
-    </ThemeProvider>
+    <React.Fragment>
+      <div>
+        <FormControlLabel
+          control={<Switch checked={rtl} onChange={handleChage} />}
+          label="RTL"
+        />
+      </div>
+      <CacheProvider value={rtl ? rtlCache : ltrCache}>
+        <Root {...(rtl ? { dir: 'rtl' } : {})}>
+          <AffectedText>Affected</AffectedText>
+          <UnaffectedText>Unaffected</UnaffectedText>
+        </Root>
+      </CacheProvider>
+    </React.Fragment>
   );
 }

docs/src/pages/guides/right-to-left/RtlOptOutStylis.tsx

@@ -1,12 +1,14 @@
 import * as React from 'react';
-import { createTheme, Theme } from '@material-ui/core/styles';
-import styled from '@emotion/styled';
-import { ThemeProvider } from '@emotion/react';
+import rtlPlugin from 'stylis-plugin-rtl';
+import { CacheProvider } from '@emotion/react';
+import createCache from '@emotion/cache';
+import { styled } from '@material-ui/core/styles';
+import FormControlLabel from '@material-ui/core/FormControlLabel';
+import Switch from '@material-ui/core/Switch';
 
-const Root = styled('div')((props: { theme?: Theme }) => ({
+const Root = styled('div')((props) => ({
   width: '100%',
-  marginTop: props.theme?.spacing(4),
-  marginRight: props.theme?.spacing(2),
+  marginTop: props.theme?.spacing(6),
 }));
 
 const AffectedText = styled('div')`
@@ -18,15 +20,37 @@ const UnaffectedText = styled('div')`
   text-align: left;
 `;
 
-const theme = createTheme();
+const rtlCache = createCache({
+  key: 'muirtl',
+  // @ts-ignore external dependency
+  stylisPlugins: [rtlPlugin],
+});
+
+const ltrCache = createCache({
+  key: 'mui',
+});
 
 export default function RtlOptOut() {
+  const [rtl, setRtl] = React.useState(false);
+
+  const handleChage = () => {
+    setRtl(!rtl);
+  };
+
   return (
-    <ThemeProvider theme={theme}>
-      <Root>
-        <AffectedText>Affected</AffectedText>
-        <UnaffectedText>Unaffected</UnaffectedText>
-      </Root>
-    </ThemeProvider>
+    <React.Fragment>
+      <div>
+        <FormControlLabel
+          control={<Switch checked={rtl} onChange={handleChage} />}
+          label="RTL"
+        />
+      </div>
+      <CacheProvider value={rtl ? rtlCache : ltrCache}>
+        <Root {...(rtl ? { dir: 'rtl' } : {})}>
+          <AffectedText>Affected</AffectedText>
+          <UnaffectedText>Unaffected</UnaffectedText>
+        </Root>
+      </CacheProvider>
+    </React.Fragment>
   );
 }

docs/src/pages/guides/right-to-left/right-to-left.md

@@ -38,49 +38,25 @@ const theme = createTheme({
 
 ### 3. Install the rtl plugin
 
-In case you are using `jss` (up to v4), you need this JSS plugin to flip the styles: [jss-rtl](https://github.com/alitaheri/jss-rtl).
+When using either `emotion` or `styled-components`, you need [`stylis-plugin-rtl`](https://github.com/styled-components/stylis-plugin-rtl) to flip the styles.
 
 ```sh
-npm install jss-rtl
+npm install stylis stylis-plugin-rtl
 ```
 
-If you are using `emotion` or `styled-components`, you need this stylis plugin to flip the styles: [stylis-plugin-rtl](https://github.com/styled-components/stylis-plugin-rtl).
+> **Note**: Only `emotion` is compatible with version 2 of the plugin. `styled-components` requires version 1. If you are using `styled-components` as a [styled engine](/guides/styled-engine/), make sure to install the correct version.
+
+In case you are using `jss` (up to v4) or with the legacy `@material-ui/styles` package, you need [`jss-rtl`](https://github.com/alitaheri/jss-rtl) to flip the styles.
 
 ```sh
-npm install stylis-plugin-rtl
+npm install jss-rtl
 ```
 
-**Note**: Only `emotion` is compatible with version 2 of the plugin. `styled-components` requires version 1. If you are using `styled-components` as styled engine, make sure to install the correct version.
-
 Having installed the plugin in your project, Material-UI components still require it to be loaded by the style engine instance that you use. Find bellow guides on how you can load it.
 
 ### 4. Load the rtl plugin
 
-#### 4.1 JSS
-
-Having installed the plugin in your project, Material-UI components still require it to be loaded by the jss instance, as described below.
-Internally, withStyles is using this JSS plugin when `direction: 'rtl'` is set on the theme.
-Head to the [plugin README](https://github.com/alitaheri/jss-rtl) to learn more about it.
-
-Once you have created a new JSS instance with the plugin, you need to make it available to all the components in the component tree.
-The [`StylesProvider`](/styles/api/#stylesprovider) component enables this:
-
-```jsx
-import { create } from 'jss';
-import rtl from 'jss-rtl';
-import { StylesProvider, jssPreset } from '@material-ui/styles';
-
-// Configure JSS
-const jss = create({
-  plugins: [...jssPreset().plugins, rtl()],
-});
-
-function RTL(props) {
-  return <StylesProvider jss={jss}>{props.children}</StylesProvider>;
-}
-```
-
-#### 4.2 emotion
+#### 4.1 emotion
 
 If you use emotion as your style engine, you should create new cache instance that uses the `stylis-plugin-rtl` and provide that on the top of your application tree. The [CacheProvider](https://emotion.sh/docs/cache-provider) component enables this:
 
@@ -100,7 +76,7 @@ function RTL(props) {
 }
 ```
 
-#### 4.3 styled-components
+#### 4.2 styled-components
 
 If you use `styled-components` as your style engine, you can use the [StyleSheetManager](https://styled-components.com/docs/api#stylesheetmanager) and provide the stylis-plugin-rtl as an item in the `stylisPlugins` property:
 
@@ -117,6 +93,30 @@ function RTL(props) {
 }
 ```
 
+#### 4.3 JSS
+
+After installing the plugin in your project, you need to configure the JSS instance to load it.
+The next step is to make the new JSS instance available to all the components in the component tree.
+The [`StylesProvider`](/styles/api/#stylesprovider) component enables this:
+
+```jsx
+import { create } from 'jss';
+import rtl from 'jss-rtl';
+import { StylesProvider, jssPreset } from '@material-ui/styles';
+
+// Configure JSS
+const jss = create({
+  plugins: [...jssPreset().plugins, rtl()],
+});
+
+function RTL(props) {
+  return <StylesProvider jss={jss}>{props.children}</StylesProvider>;
+}
+```
+
+For more information on the plugin, head to the [plugin README](https://github.com/alitaheri/jss-rtl).
+**Note**: Internally, withStyles is using this JSS plugin when `direction: 'rtl'` is set on the theme.
+
 ## Demo
 
 _Use the direction toggle button on the top right corner to flip the whole documentation_
@@ -125,18 +125,38 @@ _Use the direction toggle button on the top right corner to flip the whole docum
 
 ## Opting out of rtl transformation
 
-### JSS
+### emotion & styled-components
 
-If you want to prevent a specific rule-set from being affected by the `rtl` transformation you can add `flip: false` at the beginning.
+You have to use the template literal syntax and add the `/* @noflip */` directive before the rule or property for which you want to disable right-to-left styles.
 
-_Use the direction toggle button on the top right corner to see the effect._
+```jsx
+const AffectedText = styled('div')`
+  text-align: left;
+`;
+
+const UnaffectedText = styled('div')`
+  /* @noflip */
+  text-align: left;
+`;
+```
 
-{{"demo": "pages/guides/right-to-left/RtlOptOut.js", "hideEditButton": true}}
+{{"demo": "pages/guides/right-to-left/RtlOptOutStylis.js", "hideToolbar": true}}
 
-### emotion & styled-components
-
-You have to use the template literal syntax and add the `/* @noflip */` directive before the rule or property for which you want to disable right-to-left styles.
+### JSS
 
-_Use the direction toggle button on the top right corner to see the effect._
+If you want to prevent a specific rule-set from being affected by the `rtl` transformation you can add `flip: false` at the beginning.
 
-{{"demo": "pages/guides/right-to-left/RtlOptOutStylis.js", "hideEditButton": true}}
+```jsx
+const useStyles = makeStyles(
+  (theme) => ({
+    affected: {
+      textAlign: 'right',
+    },
+    unaffected: {
+      flip: false,
+      textAlign: 'right',
+    },
+  }),
+  { defaultTheme },
+);
+```