Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[pigment-css][docs] Update the RTL section on the readme #41576

Merged
merged 8 commits into from
Mar 21, 2024
Merged

[pigment-css][docs] Update the RTL section on the readme #41576

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
83e3589
update-rtl-section
danilo-leal Mar 20, 2024
027ab77
Sam's review
danilo-leal Mar 20, 2024
3122e5e
add suggested edits and fix lint
danilo-leal Mar 20, 2024
60afd3d
iterate on the section about both directions
danilo-leal Mar 20, 2024
8e3b070
Marija's review and a few tweaks
danilo-leal Mar 21, 2024
1da85d2
iterate based on comments
danilo-leal Mar 21, 2024
6b900e4
remove Vite-specific syntax from codeblock
danilo-leal Mar 21, 2024
2626b1c
Sam's review
danilo-leal Mar 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 89 additions & 89 deletions packages/pigment-css-react/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -663,6 +663,94 @@ 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 `<html>` element or any other equivalent top level container. Then, update your bundler config as follows to generate styles for both directions:

### 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',
danilo-leal marked this conversation as resolved.
Show resolved Hide resolved
// Generate CSS for the opposite of the `defaultDirection`
// This is set to `false` by default
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',
danilo-leal marked this conversation as resolved.
Show resolved Hide resolved
// Generate CSS for the opposite of the `defaultDirection`
// This is set to `false` by default
generateForBothDir: true,
},
}),
// ... other plugins.
],
});
```

### Generated CSS

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';

const className = css`
margin-left: 10px,
margin-right: 20px,
padding: '0 10px 20px 30px'
`;
```

Then 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;
}
```

### Custom dir selector

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
css: {
getDirSelector(dir: string) {
// return a custom selector you'd like to use
return `:dir(${dir})`;
},
},
```

## How-to guides

### Coming from Emotion or styled-components
Expand Down Expand Up @@ -766,91 +854,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})`;
}
}
```
Loading