content revisions

danilo-leal · Oct 12, 2023 · 79ea825 · 79ea825
1 parent 1e30d20
commit 79ea825
Show file tree

Hide file tree

Showing 7 changed files with 62 additions and 147 deletions.
diff --git a/docs/data/joy/customization/right-to-left/right-to-left.md b/docs/data/joy/customization/right-to-left/right-to-left.md
@@ -1,32 +1,30 @@
-# Right-to-left
+# Right-to-left language support
 
-<p class="description">Learn how to make Joy UI components support right-to-left languages such as Arabic, Persian, Hebrew, and others.</p>
+<p class="description">Learn how to implement right-to-left (RTL) text with Material UI to support languages such as Arabic, Persian, and Hebrew.</p>
 
-## Introduction
-
-Following the guide below, you'll learn how to turn text-based components in Joy UI to right-to-left.
+This guide outlines the three steps necessary to change the direction of text-based components in Joy UI to support RTL languages, as shown in the demo below:
 
 <!-- {{"demo": "Direction.js"}} -->
 
-## Basic setup
+## 1. Set the HTML direction
 
-### Global approach
+### Globally
 
-Set the `dir` attribute on the `html` tag to `rtl` as the first step to support right-to-left languages.
+Add `dir="rtl"` to the app's root `<html>` to set the global text direction:
 
 ```html
 <html dir="rtl"></html>
 ```
 
-If your React app doesn't control the root HTML element and you want to change the text direction at runtime, use the JavaScript API.
+If your React app doesn't control the root `<html>` and you need to change the text direction at runtime, use the JavaScript API instead:
 
 ```js
 document.dir = 'rtl';
 ```
 
-### Local approach
+### Locally
 
-To only make part of your app support right-to-left, use the `dir` attribute in that part's specific wrapper as an alternative to the global approach above.
+Add the `dir="rtl"` attribute to any other HTML element or React component if you need limit the scope of the text direction to that element and its children.
 
 :::warning
 This won't work with portaled elements, such as Dialogs, as they render outside of the element with the `dir` attribute.
@@ -41,14 +39,21 @@ To fix it, make sure to add the `dir` attribute directly to them:
 
 :::
 
-## Third-party plugin
+## 2. Set the theme direction
 
-To pull right-to-left entirely, you need to use the [`stylis-plugin-rtl`](https://github.com/styled-components/stylis-plugin-rtl), to help flip the text direction.
-Its usage varies slightly depending if you're using Emotion or styled-components as your styled engine.
+Use the `createTheme` API to set the theme direction to `'rtl'`:
 
-### Installation
+```js
+import { createTheme } from '@mui/material/styles';
 
-Run one of the following commands to add `stylis-plugin-rtl` to your project:
+const theme = createTheme({
+  direction: 'rtl',
+});
+```
+
+## 3. Configure RTL style plugin
+
+Install the [`stylis-plugin-rtl`](https://github.com/styled-components/stylis-plugin-rtl) using one of the commands below:
 
 <codeblock storageKey="package-manager">
 
@@ -69,38 +74,33 @@ pnpm add stylis stylis-plugin-rtl
 :::warning
 Only Emotion is compatible with version 2 of the plugin.
 styled-components requires version 1.
-If you're using [styled-components instead of Emotion](/joy-ui/customization/styled-components-setup/), make sure to install the correct version.
+If you're using [styled-components instead of Emotion](/material-ui/guides/styled-components/), make sure to install the correct version.
 :::
 
-### Emotion setup
+### With Emotion
 
-If you're using Emotion, use the [CacheProvider](https://emotion.sh/docs/cache-provider) to create a new cache instance that uses the `stylis-plugin-rtl` (also include the default `prefixer` plugin to retain vendor prefixing) and add that to the top of your application tree.
+If you're using Emotion, use the [CacheProvider](https://emotion.sh/docs/cache-provider) to create a new cache instance that uses `rtlPlugin` from `stylis-plugin-rtl` and add that to the top of your application tree:
 
 ```jsx
 import rtlPlugin from 'stylis-plugin-rtl';
 import { CacheProvider } from '@emotion/react';
 import createCache from '@emotion/cache';
 import { prefixer } from 'stylis';
-import { CssVarsProvider } from "@mui/joy/styles";
 
 // Create rtl cache
 const cacheRtl = createCache({
-  key: "joy-ui-rtl",
+  key: 'muirtl',
   stylisPlugins: [prefixer, rtlPlugin],
 });
 
 function RTL(props) {
-    return (
-    <CssVarsProvider>
-      <CacheProvider value={cacheRtl}>{props.children}</CacheProvider>;
-    </StyleSheetManager>
-  );
+  return <CacheProvider value={cacheRtl}>{props.children}</CacheProvider>;
 }
 ```
 
-### styled-components setup
+### With styled-components
 
-If you're using styled-components, use the [StyleSheetManager](https://styled-components.com/docs/api#stylesheetmanager) and provide the stylis-plugin-rtl as an item to the `stylisPlugins` property.
+If you're using styled-components, use the [StyleSheetManager](https://styled-components.com/docs/api#stylesheetmanager) and provide `rtlPlugin` to the `stylisPlugins` property:
 
 ```jsx
 import { StyleSheetManager } from 'styled-components';
@@ -115,19 +115,13 @@ function RTL(props) {
 }
 ```
 
-## Locally opting out of rtl
+### Opting out of RTL locally
 
-Use the template literal syntax and add the `/* @noflip */` directive before the rule or property for which you want to turn off the right-to-left styles.
+To turn off RTL on specific components, use the template literal syntax and add the `/* @noflip */` directive:
 
-```jsx
-const AffectedText = styled('div')`
-  text-align: left;
-`;
-
-const UnaffectedText = styled('div')`
+```js
+const LeftToRightTextInRtlApp = styled('div')`
   /* @noflip */
   text-align: left;
 `;
 ```
-
-<!-- {{"demo": "RtlOptOutStylis.js", "hideToolbar": true}} -->
diff --git a/docs/data/joy/pages.ts b/docs/data/joy/pages.ts
@@ -143,7 +143,7 @@ const pages: readonly MuiPage[] = [
           },
           {
             pathname: '/joy-ui/customization/right-to-left',
-            title: 'Right-to-left',
+            title: 'Right-to-left language support',
           },
         ],
       },

diff --git a/docs/data/material/guides/right-to-left/Direction.js b/docs/data/material/guides/right-to-left/Direction.js
@@ -7,9 +7,9 @@ import { CacheProvider } from '@emotion/react';
 import createCache from '@emotion/cache';
 
 const theme = createTheme({
-  direction: 'rtl', // Both here and <body dir="rtl">
+  direction: 'rtl',
 });
-// Create rtl cache
+
 const cacheRtl = createCache({
   key: 'muirtl',
   stylisPlugins: [prefixer, rtlPlugin],
@@ -20,7 +20,7 @@ export default function Direction() {
     <CacheProvider value={cacheRtl}>
       <ThemeProvider theme={theme}>
         <div dir="rtl">
-          <TextField label="Name" variant="outlined" />
+          <TextField label="بطاطا" variant="outlined" />
         </div>
       </ThemeProvider>
     </CacheProvider>

diff --git a/docs/data/material/guides/right-to-left/Direction.tsx b/docs/data/material/guides/right-to-left/Direction.tsx
@@ -7,9 +7,9 @@ import { CacheProvider } from '@emotion/react';
 import createCache from '@emotion/cache';
 
 const theme = createTheme({
-  direction: 'rtl', // Both here and <body dir="rtl">
+  direction: 'rtl',
 });
-// Create rtl cache
+
 const cacheRtl = createCache({
   key: 'muirtl',
   stylisPlugins: [prefixer, rtlPlugin],
@@ -20,7 +20,7 @@ export default function Direction() {
     <CacheProvider value={cacheRtl}>
       <ThemeProvider theme={theme}>
         <div dir="rtl">
-          <TextField label="Name" variant="outlined" />
+          <TextField label="بطاطا" variant="outlined" />
         </div>
       </ThemeProvider>
     </CacheProvider>

diff --git a/docs/data/material/guides/right-to-left/Direction.tsx.preview b/docs/data/material/guides/right-to-left/Direction.tsx.preview
@@ -1,7 +1,7 @@
 <CacheProvider value={cacheRtl}>
   <ThemeProvider theme={theme}>
     <div dir="rtl">
-      <TextField label="Name" variant="outlined" />
+      <TextField label="بطاطا" variant="outlined" />
     </div>
   </ThemeProvider>
 </CacheProvider>
diff --git a/docs/data/material/guides/right-to-left/right-to-left.md b/docs/data/material/guides/right-to-left/right-to-left.md
@@ -1,32 +1,30 @@
-# Right-to-left
+# Right-to-left language support
 
-<p class="description">Learn how to make Material UI components support right-to-left languages such as Arabic, Persian, Hebrew, and others.</p>
+<p class="description">Learn how to implement right-to-left (RTL) text with Material UI to support languages such as Arabic, Persian, and Hebrew.</p>
 
-## Introduction
-
-Following the guide below, you'll learn how to turn text-based components in Material UI to right-to-left.
+This guide outlines the three steps necessary to change the direction of text-based components in Material UI to support RTL languages, as shown in the demo below:
 
 {{"demo": "Direction.js"}}
 
-## Basic setup
+## 1. Set the HTML direction
 
-### Global approach
+### Globally
 
-Set the `dir` attribute on the `html` tag to `rtl` as the first step to support right-to-left languages.
+Add `dir="rtl"` to the app's root `<html>` to set the global text direction:
 
 ```html
 <html dir="rtl"></html>
 ```
 
-If your React app doesn't control the root HTML element and you want to change the text direction at runtime, use the JavaScript API.
+If your React app doesn't control the root `<html>` and you need to change the text direction at runtime, use the JavaScript API instead:
 
 ```js
 document.dir = 'rtl';
 ```
 
-### Local approach
+### Locally
 
-To only make part of your app support right-to-left, use the `dir` attribute in that part's specific wrapper as an alternative to the global approach above.
+Add the `dir="rtl"` attribute to any other HTML element or React component if you need limit the scope of the text direction to that element and its children.
 
 :::warning
 This won't work with portaled elements, such as Dialogs, as they render outside of the element with the `dir` attribute.
@@ -41,9 +39,9 @@ To fix it, make sure to add the `dir` attribute directly to them:
 
 :::
 
-### Theme setup
+## 2. Set the theme direction
 
-Set the text direction in your theme with the `createTheme` API.
+Use the `createTheme` API to set the theme direction to `'rtl'`:
 
 ```js
 import { createTheme } from '@mui/material/styles';
@@ -53,13 +51,9 @@ const theme = createTheme({
 });
 ```
 
-## Third-party plugins
-
-Depending on the style engine you're using with Material UI, you'll need the support of different plugins to pull right-to-left off entirely.
-
-### stylis-plugin-rtl
+## 3. Configure RTL style plugin
 
-If you're using Emotion, Material UI's default style engine, or styled-component, install the [`stylis-plugin-rtl`](https://github.com/styled-components/stylis-plugin-rtl) to help flip the text direction.
+Install the [`stylis-plugin-rtl`](https://github.com/styled-components/stylis-plugin-rtl) using one of the commands below:
 
 <codeblock storageKey="package-manager">
 
@@ -83,9 +77,9 @@ styled-components requires version 1.
 If you're using [styled-components instead of Emotion](/material-ui/guides/styled-components/), make sure to install the correct version.
 :::
 
-#### Emotion setup
+### With Emotion
 
-If you're using Emotion, use the [CacheProvider](https://emotion.sh/docs/cache-provider) to create a new cache instance that uses the `stylis-plugin-rtl` (also include the default `prefixer` plugin to retain vendor prefixing) and add that to the top of your application tree.
+If you're using Emotion, use the [CacheProvider](https://emotion.sh/docs/cache-provider) to create a new cache instance that uses `rtlPlugin` from `stylis-plugin-rtl` and add that to the top of your application tree:
 
 ```jsx
 import rtlPlugin from 'stylis-plugin-rtl';
@@ -104,9 +98,9 @@ function RTL(props) {
 }
 ```
 
-#### styled-components setup
+### With styled-components
 
-If you're using styled-components, use the [StyleSheetManager](https://styled-components.com/docs/api#stylesheetmanager) and provide the stylis-plugin-rtl as an item to the `stylisPlugins` property.
+If you're using styled-components, use the [StyleSheetManager](https://styled-components.com/docs/api#stylesheetmanager) and provide `rtlPlugin` to the `stylisPlugins` property:
 
 ```jsx
 import { StyleSheetManager } from 'styled-components';
@@ -121,86 +115,13 @@ function RTL(props) {
 }
 ```
 
-### jss-rtl
-
-In case you are using `jss` (up to v4) or with the legacy `@mui/styles` package, you need [`jss-rtl`](https://github.com/alitaheri/jss-rtl) to flip the styles.
-
-<codeblock storageKey="package-manager">
-
-```bash npm
-npm install jss-rtl
-```
-
-```bash yarn
-yarn add jss-rtl
-```
-
-```bash pnpm
-pnpm add jss-rtl
-```
-
-</codeblock>
+### Opting out of RTL locally
 
-:::info
-The `withStyles` API is internally using this plugin whtn `direction: rtl` is set on the theme.
-:::
-
-#### JSS setup
-
-Start by configuring a JSS instance to load the plugin.
-Then, make it available to all components by using the [`StylesProvider`](/system/styles/api/#stylesprovider) component.
-
-```jsx
-import { create } from 'jss';
-import rtl from 'jss-rtl';
-import { StylesProvider, jssPreset } from '@mui/styles';
+To turn off RTL on specific components, use the template literal syntax and add the `/* @noflip */` directive:
 
-// Configure JSS
-const jss = create({
-  plugins: [...jssPreset().plugins, rtl()],
-});
-
-function RTL(props) {
-  return <StylesProvider jss={jss}>{props.children}</StylesProvider>;
-}
-```
-
-## Locally opting out of rtl
-
-To opt out of right-to-left text in specific and local instances, follow the guides below for your styled engine.
-
-### Emotion & styled-components
-
-Use the template literal syntax and add the `/* @noflip */` directive before the rule or property for which you want to turn off the right-to-left styles.
-
-```jsx
-const AffectedText = styled('div')`
-  text-align: left;
-`;
-
-const UnaffectedText = styled('div')`
+```js
+const LeftToRightTextInRtlApp = styled('div')`
   /* @noflip */
   text-align: left;
 `;
 ```
-
-{{"demo": "RtlOptOutStylis.js", "hideToolbar": true}}
-
-### JSS
-
-Use the `flip: false` at the beginning of a rule set.
-
-```jsx
-const useStyles = makeStyles(
-  (theme) => ({
-    affected: {
-      textAlign: 'right',
-    },
-    unaffected: {
-      flip: false,
-      textAlign: 'right',
-    },
-  }),
-  { defaultTheme },
-);
-```
diff --git a/docs/data/material/pages.ts b/docs/data/material/pages.ts
@@ -199,7 +199,7 @@ const pages: MuiPage[] = [
       { pathname: '/material-ui/guides/testing' },
       { pathname: '/material-ui/guides/localization' },
       { pathname: '/material-ui/guides/content-security-policy', title: 'Content Security Policy' },
-      { pathname: '/material-ui/guides/right-to-left', title: 'Right-to-left' },
+      { pathname: '/material-ui/guides/right-to-left', title: 'Right-to-left language support' },
       { pathname: '/material-ui/guides/shadow-dom', title: 'Shadow DOM' },
       {
         pathname: '/material-ui/guides/next-js-app-router',
-Original file line number
+Diff line change
@@ Expand Up / @@ -143,7 +143,7 @@ const pages: readonly MuiPage[] = [ @@
               },
               {
                 pathname: '/joy-ui/customization/right-to-left',
-                title: 'Right-to-left',
+                title: 'Right-to-left language support',
               },
             ],
           },
@@ Expand Down @@