From 83e3589a3b3e9b182ce114c4d5de12fa23f3476e Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Wed, 20 Mar 2024 10:52:10 -0300 Subject: [PATCH 1/8] update-rtl-section --- packages/pigment-css-react/README.md | 177 +++++++++++++-------------- 1 file changed, 88 insertions(+), 89 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index 3b82b05855d1f1..c3d2fa3fcf6f25 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -19,9 +19,9 @@ Pigment CSS is a zero-runtime CSS-in-JS library that extracts the colocated sty - [Color schemes](#color-schemes) - [Switching color schemes](#switching-color-schemes) - [TypeScript](#typescript) +- [Right-to-left support](#right-to-left-support) - [How-to guides](#how-to-guides) - [Coming from Emotion or styled-components](#coming-from-emotion-or-styled-components) -- [RTL Support](#rtl-support) ## Getting started @@ -663,6 +663,93 @@ declare module '@pigment-css/react/theme' { } ``` +## Right-to-left support + +Pigment CSS offers a built-in mechanism to support right-to-left (RTL) or left-to-right (LTR) CSS automatically. To turn it on, start by updating your bundler config: + +### Next.js + +```js +const { withPigment } = require('@pigment-css/nextjs-plugin'); + +// ... +module.exports = withPigment(nextConfig, { + theme: yourCustomTheme, + // CSS output option + css: { + // Specify your default direction + defaultDirection: 'ltr', + // Use this prop if you want to output CSS for both directions. Default is `false`. + generateForBothDir: true, + }, +}); +``` + +### Vite + +```js +import { pigment } from '@pigment-css/vite-plugin'; + +export default defineConfig({ + plugins: [ + pigment({ + theme: yourTheme, + css: { + // Specify your default direction + defaultDirection: 'ltr', + // Use this prop if you want to output CSS for both directions. Default is `false`. + generateForBothDir: true, + }, + }), + // ... Your other plugins. + ], +}); +``` + +So, with RTL turned on, if your authored CSS is: + +```js +import { css } from '@pigment-css/react'; + +const className = css` + margin-left: 10px, + margin-right: 20px, + padding: '0 10px 20px 30px' +`; +``` + +The actual CSS output would be: + +```css +.cmip3v5 { + margin-left: 10px; + margin-right: 20px; + padding: 0 10px 20px 30px; +} + +[dir='rtl'] .cmip3v5 { + margin-right: 10px; + margin-left: 20px; + padding: 0 30px 20px 10px; +} +``` + +Make sure to add the `dir` attribute on either the `html` element or any other equivalent parent element per your application logic or user preference. + +#### Custom dir selector + +The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize this selector by passing an optional `getDirSelector` method in the `css` property above: + +```js + // ... + css: { + getDirSelector(dir: string) { + // return your own selector that you'd like to use. + return `:dir(${dir})`; + } + } +``` + ## How-to guides ### Coming from Emotion or styled-components @@ -766,91 +853,3 @@ function App() { ) } ``` - -## RTL Support - -Pigment CSS offers built-in mechanism to automatically output corresponding rtl or ltr CSS. If your app by default caters to ltr direction, you also have an option to configure the plugin to output the CSS for the other direction automatically. To configure Pigment CSS for this, update the bundler config. - -### Next.js - -```js -const { withPigment } = require('@pigment-css/nextjs-plugin'); - -// ... -module.exports = withPigment(nextConfig, { - theme: yourCustomTheme, - // CSS output option - css: { - // Specify your default CSS authoring direction - defaultDirection: 'ltr', - // If you want to output CSS for the direction other than - // the `defaultDirection`. Default is `false`. - generateForBothDir: true, - }, -}); -``` - -### Vite - -```js -import { pigment } from '@pigment-css/vite-plugin'; - -export default defineConfig({ - plugins: [ - pigment({ - theme: yourTheme, - css: { - // Specify your default CSS authoring direction - defaultDirection: 'ltr', - // If you want to output CSS for the direction other than - // the `defaultDirection`. Default is `false`. - generateForBothDir: true, - }, - }), - // ... Your other plugins. - ], -}); -``` - -Coming back to the app code, if one of the authored CSS is: - -```js -import { css } from '@pigment-css/react'; - -const className = css` - margin-left: 10px, - margin-right: 20px, - padding: '0 10px 20px 30px' -`; -``` - -The output CSS would be: - -```css -.cmip3v5 { - margin-left: 10px; - margin-right: 20px; - padding: 0 10px 20px 30px; -} -[dir='rtl'] .cmip3v5 { - margin-right: 10px; - margin-left: 20px; - padding: 0 30px 20px 10px; -} -``` - -Remember to also add the `dir` attribute on the `html` element or any relevant parent element as per your application logic or user preference. - -#### Custom dir selector - -The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize this selector by passing an optional `getDirSelector` method in the `css` property above: - -```js - // ... - css: { - getDirSelector(dir: string) { - // return your own selector that you'd like to use. - return `:dir(${dir})`; - } - } -``` From 027ab776c7e16697f8ee759d744dc64f47a80b09 Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Wed, 20 Mar 2024 11:35:05 -0300 Subject: [PATCH 2/8] Sam's review --- packages/pigment-css-react/README.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index c3d2fa3fcf6f25..21149d8d8251f0 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -665,7 +665,7 @@ declare module '@pigment-css/react/theme' { ## Right-to-left support -Pigment CSS offers a built-in mechanism to support right-to-left (RTL) or left-to-right (LTR) CSS automatically. To turn it on, start by updating your bundler config: +Pigment CSS is designed for left-to-right (LTR) languages by default. To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows: ### Next.js @@ -706,7 +706,7 @@ export default defineConfig({ }); ``` -So, with RTL turned on, if your authored CSS is: +For example, if you've specified `'rtl'` as the direction and your authored CSS looks like this: ```js import { css } from '@pigment-css/react'; @@ -718,7 +718,7 @@ const className = css` `; ``` -The actual CSS output would be: +Then the actual CSS output would be: ```css .cmip3v5 { @@ -734,20 +734,22 @@ The actual CSS output would be: } ``` -Make sure to add the `dir` attribute on either the `html` element or any other equivalent parent element per your application logic or user preference. - #### Custom dir selector -The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize this selector by passing an optional `getDirSelector` method in the `css` property above: +The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize this selector by passing an optional `getDirSelector` method to the `css` property in your bundler config: ```js - // ... - css: { - getDirSelector(dir: string) { - // return your own selector that you'd like to use. - return `:dir(${dir})`; - } - } + plugins: [ + pigment({ + theme: yourTheme, + css: { + getDirSelector(dir: string) { + // return a custom selector that you'd like to use + return `:dir(${dir})`; + }, + }, + }), + ] ``` ## How-to guides From 3122e5eb8733cb783f3fe3d702e7a8b7d94d1bde Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Wed, 20 Mar 2024 12:30:08 -0300 Subject: [PATCH 3/8] add suggested edits and fix lint --- packages/pigment-css-react/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index 21149d8d8251f0..527a43737d26ee 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -665,7 +665,7 @@ declare module '@pigment-css/react/theme' { ## Right-to-left support -Pigment CSS is designed for left-to-right (LTR) languages by default. To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows: +Pigment CSS is designed for left-to-right (LTR) languages by default. To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows: ### Next.js @@ -706,7 +706,7 @@ export default defineConfig({ }); ``` -For example, if you've specified `'rtl'` as the direction and your authored CSS looks like this: +For example, if you've specified `defaultDirection: 'ltr'` and `dir="rtl"`, and your authored CSS looks like this: ```js import { css } from '@pigment-css/react'; From 60afd3d967af96fc7e71236fff8a0e46332a21c6 Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Wed, 20 Mar 2024 13:33:47 -0300 Subject: [PATCH 4/8] iterate on the section about both directions --- packages/pigment-css-react/README.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index 527a43737d26ee..82ed4c75911153 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -678,9 +678,7 @@ module.exports = withPigment(nextConfig, { // CSS output option css: { // Specify your default direction - defaultDirection: 'ltr', - // Use this prop if you want to output CSS for both directions. Default is `false`. - generateForBothDir: true, + defaultDirection: 'rtl', }, }); ``` @@ -696,16 +694,27 @@ export default defineConfig({ theme: yourTheme, css: { // Specify your default direction - defaultDirection: 'ltr', - // Use this prop if you want to output CSS for both directions. Default is `false`. - generateForBothDir: true, + defaultDirection: 'rtl', }, }), - // ... Your other plugins. + // ... other plugins ], }); ``` +### Generate CSS for both directions + +Turn the `generateForBothDir` prop to true if you want to generate CSS for both directions. This would allow, for example, your user to toggle the app's direction, which would happen instantly, given the CSS is already available. + +```js + css: { + // Specify your default direction + defaultDirection: 'ltr', + // Default is `false` + generateForBothDir: true, + }, +``` + For example, if you've specified `defaultDirection: 'ltr'` and `dir="rtl"`, and your authored CSS looks like this: ```js From 8e3b070c31dc0452eca8676ce2538f7d85456755 Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Thu, 21 Mar 2024 07:03:44 -0300 Subject: [PATCH 5/8] Marija's review and a few tweaks --- packages/pigment-css-react/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index 82ed4c75911153..dbd0ff6303e023 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -665,7 +665,7 @@ declare module '@pigment-css/react/theme' { ## Right-to-left support -Pigment CSS is designed for left-to-right (LTR) languages by default. To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows: +To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows: ### Next.js @@ -704,7 +704,7 @@ export default defineConfig({ ### Generate CSS for both directions -Turn the `generateForBothDir` prop to true if you want to generate CSS for both directions. This would allow, for example, your user to toggle the app's direction, which would happen instantly, given the CSS is already available. +Turn the `generateForBothDir` prop to true to generate CSS for both directions. This enables you to add a direction toggle on your app that would change it instantly given the CSS is already available. ```js css: { @@ -743,9 +743,9 @@ Then the actual CSS output would be: } ``` -#### Custom dir selector +### Custom dir selector -The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize this selector by passing an optional `getDirSelector` method to the `css` property in your bundler config: +The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize it by passing an optional `getDirSelector` method to the `css` property in your bundler config: ```js plugins: [ @@ -753,7 +753,7 @@ The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can cu theme: yourTheme, css: { getDirSelector(dir: string) { - // return a custom selector that you'd like to use + // return a custom selector you'd like to use return `:dir(${dir})`; }, }, From 1da85d272a1d50f9e913f34e6bd8fa6155fd32ef Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Thu, 21 Mar 2024 09:12:26 -0300 Subject: [PATCH 6/8] iterate based on comments --- packages/pigment-css-react/README.md | 29 ++++++++++++---------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index dbd0ff6303e023..494b41e8d62291 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -677,8 +677,11 @@ module.exports = withPigment(nextConfig, { theme: yourCustomTheme, // CSS output option css: { - // Specify your default direction - defaultDirection: 'rtl', + // Specify your default CSS authoring direction + defaultDirection: 'ltr', + // To output CSS for the opposite direction to `defaultDirection` + // Default is `false`. + generateForBothDir: true, }, }); ``` @@ -693,27 +696,19 @@ export default defineConfig({ pigment({ theme: yourTheme, css: { - // Specify your default direction - defaultDirection: 'rtl', + // Specify your default CSS authoring direction + defaultDirection: 'ltr', + // To output CSS for the opposite direction to `defaultDirection` + // Default is `false`. + generateForBothDir: true, }, }), - // ... other plugins + // ... other plugins. ], }); ``` -### Generate CSS for both directions - -Turn the `generateForBothDir` prop to true to generate CSS for both directions. This enables you to add a direction toggle on your app that would change it instantly given the CSS is already available. - -```js - css: { - // Specify your default direction - defaultDirection: 'ltr', - // Default is `false` - generateForBothDir: true, - }, -``` +### Generated CSS For example, if you've specified `defaultDirection: 'ltr'` and `dir="rtl"`, and your authored CSS looks like this: From 6b900e4ac4e71256cb15f86589d484731fbd2387 Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Thu, 21 Mar 2024 09:42:21 -0300 Subject: [PATCH 7/8] remove Vite-specific syntax from codeblock --- packages/pigment-css-react/README.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index 494b41e8d62291..1dc428d6d4094a 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -743,17 +743,12 @@ Then the actual CSS output would be: The default selector in the output CSS is `[dir=rtl]` or `[dir=ltr]`. You can customize it by passing an optional `getDirSelector` method to the `css` property in your bundler config: ```js - plugins: [ - pigment({ - theme: yourTheme, - css: { - getDirSelector(dir: string) { - // return a custom selector you'd like to use - return `:dir(${dir})`; - }, + css: { + getDirSelector(dir: string) { + // return a custom selector you'd like to use + return `:dir(${dir})`; }, - }), - ] + }, ``` ## How-to guides From 2626b1c2491f8bac22ad8a5eb906188bab927e17 Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Thu, 21 Mar 2024 15:31:22 -0300 Subject: [PATCH 8/8] Sam's review --- packages/pigment-css-react/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/pigment-css-react/README.md b/packages/pigment-css-react/README.md index 1dc428d6d4094a..270970cdafd747 100644 --- a/packages/pigment-css-react/README.md +++ b/packages/pigment-css-react/README.md @@ -665,7 +665,7 @@ declare module '@pigment-css/react/theme' { ## Right-to-left support -To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows: +To support right-to-left (RTL) languages, add the `dir="rtl"` attribute to your app's `` element or any other equivalent top level container. Then, update your bundler config as follows to generate styles for both directions: ### Next.js @@ -679,8 +679,8 @@ module.exports = withPigment(nextConfig, { css: { // Specify your default CSS authoring direction defaultDirection: 'ltr', - // To output CSS for the opposite direction to `defaultDirection` - // Default is `false`. + // Generate CSS for the opposite of the `defaultDirection` + // This is set to `false` by default generateForBothDir: true, }, }); @@ -698,8 +698,8 @@ export default defineConfig({ css: { // Specify your default CSS authoring direction defaultDirection: 'ltr', - // To output CSS for the opposite direction to `defaultDirection` - // Default is `false`. + // Generate CSS for the opposite of the `defaultDirection` + // This is set to `false` by default generateForBothDir: true, }, }),