Skip to content
This repository was archived by the owner on Jan 13, 2025. It is now read-only.

Commit e145e37

Browse files
lynnmercierlynnmercier
authored
docs(rtl): Simplify README to follow best practices (#917)
1 parent b001aec commit e145e37

File tree

2 files changed

+18
-199
lines changed

2 files changed

+18
-199
lines changed

‎packages/mdc-rtl/README.md

Lines changed: 13 additions & 194 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,7 @@ path: /catalog/rtl/
88

99
# RTL
1010

11-
MDC RTL provides sass mixins to assist with RTL / bi-directional layouts within MDC-Web components.
12-
Because we would like to achieve a standard approach to RTL throughout MDC-Web, we highly recommend
13-
that any MDC-Web component that needs RTL support leverage this package.
11+
UIs for languages that are read from right-to-left (RTL), such as Arabic and Hebrew, should be mirrored to ensure content is easy to understand.
1412

1513
## Design & API Documentation
1614

@@ -28,76 +26,22 @@ npm install --save @material/rtl
2826

2927
## Usage
3028

31-
Simply `@import "@material/rtl/mixins";` and start using the mixins. Each mixin is described below.
29+
### Sass Mixins
3230

33-
### mdc-rtl
31+
`mdc-rtl` is the most flexible mixin, because it can work with multiple CSS properties. All other RTL mixins logic could be engineered by only using `mdc-rtl`, but we provide these mixins for convenience.
3432

35-
```scss
36-
@mixin mdc-rtl($root-selector: null)
37-
```
38-
39-
Creates a rule that will be applied when an MDC-Web component is within the context of an RTL layout.
40-
41-
Usage Example:
42-
43-
```scss
44-
.mdc-foo {
45-
position: absolute;
46-
left: 0;
33+
Both `mdc-rtl-reflexive-property` and `mdc-rtl-reflexive-box` work with one base box-model property, e.g. margin, border, padding. But `mdc-rtl-reflexive-property` is more flexible because it accepts different left and right values. `mdc-rtl-reflexive-box` assumes the left and right values are the same, and therefore that the box-model is symmetrical.
4734

48-
@include mdc-rtl {
49-
left: auto;
50-
right: 0;
51-
}
35+
`mdc-rtl-reflexive-position` is the least flexible mixin. It only works with one horizontal position property, "left" or "right". It also assumes the left and right values are the same.
5236

53-
&__bar {
54-
margin-left: 4px;
55-
@include mdc-rtl(".mdc-foo") {
56-
margin-left: auto;
57-
margin-right: 4px;
58-
}
59-
}
60-
}
61-
62-
.mdc-foo--mod {
63-
padding-left: 4px;
64-
65-
@include mdc-rtl {
66-
padding-left: auto;
67-
padding-right: 4px;
68-
}
69-
}
70-
```
37+
| Mixin | Description |
38+
| ----------------------------------------------- | - |
39+
| `mdc-rtl($root-selector)` | Creates a rule that is applied when the root element is within an RTL context |
40+
| `mdc-rtl-reflexive-box($base-property, $default-direction, $value, $root-selector)` | Applies the value to the `#{$base-property}-#{$default-direction}` property in a LTR context, and flips the direction in an RTL context. **This mixin zeros out the original value in an RTL context.** |
41+
| `mdc-rtl-reflexive-property($base-property, $left-value, $right-value, $root-selector)` | Emits rules that assign `#{$base-property}`-left to `#{left-value}` and `#{base-property}`-right to `#{right-value}` in a LTR context, and vice versa in a RTL context. **Basically it flips values between a LTR and RTL context.** |
42+
| `mdc-rtl-reflexive-position($position-property, $value, $root-selector)` | Applies the value to the specified position in a LTR context, and flips the direction in an RTL context. `$position-property` is a horizontal position, either "left" or "right". |
7143

72-
will emit the following css:
73-
74-
```css
75-
.mdc-foo {
76-
position: absolute;
77-
left: 0;
78-
}
79-
[dir="rtl"] .mdc-foo, .mdc-foo[dir="rtl"] {
80-
left: auto;
81-
right: 0;
82-
}
83-
.mdc-foo__bar {
84-
margin-left: 4px;
85-
}
86-
[dir="rtl"] .mdc-foo .mdc-foo__bar, .mdc-foo[dir="rtl"] .mdc-foo__bar {
87-
margin-left: auto;
88-
margin-right: 4px;
89-
}
90-
91-
.mdc-foo--mod {
92-
padding-left: 4px;
93-
}
94-
[dir="rtl"] .mdc-foo--mod, .mdc-foo--mod[dir="rtl"] {
95-
padding-left: auto;
96-
padding-right: 4px;
97-
}
98-
```
99-
**N.B.**: checking for `[dir="rtl"]` on an ancestor element works in most cases, it will sometimes
100-
lead to false negatives for more complex layouts, e.g.
44+
**A note about [dir="rtl"]**: `mdc-rtl($root-selector)` checks for `[dir="rtl"]` on the ancestor element. This works in most cases, it will sometimes lead to false negatives for more complex layouts, e.g.
10145

10246
```html
10347
<html dir="rtl">
@@ -108,129 +52,4 @@ lead to false negatives for more complex layouts, e.g.
10852
</html>
10953
```
11054

111-
Unfortunately, we've found that this is the best we can do for now. In the future, selectors such
112-
as [:dir](http://mdn.io/:dir) will help us mitigate this.
113-
114-
### mdc-rtl-reflexive-box
115-
116-
```scss
117-
@mixin mdc-rtl-reflexive-box($base-property, $default-direction, $value, $root-selector: null)
118-
```
119-
120-
Takes a base box-model property - e.g. margin / border / padding - along with a default
121-
direction and value, and emits rules which apply the value to the
122-
`#{$base-property}-#{$default-direction}` property by default, but flips the direction
123-
when within an RTL context.
124-
125-
For example:
126-
127-
```scss
128-
.mdc-foo {
129-
@include mdc-rtl-reflexive-box(margin, left, 8px);
130-
}
131-
```
132-
is equivalent to:
133-
134-
```scss
135-
.mdc-foo {
136-
margin-left: 8px;
137-
138-
@include mdc-rtl {
139-
margin-right: 8px;
140-
margin-left: 0;
141-
}
142-
}
143-
```
144-
145-
Whereas:
146-
147-
```scss
148-
.mdc-foo {
149-
@include mdc-rtl-reflexive-box(margin, right, 8px);
150-
}
151-
```
152-
is equivalent to:
153-
154-
```scss
155-
.mdc-foo {
156-
margin-right: 8px;
157-
158-
@include mdc-rtl {
159-
margin-right: 0;
160-
margin-left: 8px;
161-
}
162-
}
163-
```
164-
165-
You can also pass a 4th optional $root-selector argument which will be forwarded to `mdc-rtl`,
166-
e.g. `@include mdc-rtl-reflexive-box-property(margin, left, 8px, ".mdc-component")`.
167-
168-
Note that this function will always zero out the original value in an RTL context. If you're
169-
trying to flip the values, use `mdc-rtl-reflexive-property`.
170-
171-
### mdc-rtl-reflexive-property
172-
173-
```scss
174-
@mixin mdc-rtl-reflexive-property($base-property, $left-value, $right-value, $root-selector: null)
175-
```
176-
177-
Takes a base property and emits rules that assign `#{$base-property}`-left to `#{left-value}` and
178-
`#{base-property}`-right to `#{right-value}` in a LTR context, and vice versa in a RTL context.
179-
180-
For example:
181-
182-
```scss
183-
.mdc-foo {
184-
@include mdc-rtl-reflexive-property(margin, auto, 12px);
185-
}
186-
```
187-
is equivalent to:
188-
189-
```scss
190-
.mdc-foo {
191-
margin-left: auto;
192-
margin-right: 12px;
193-
194-
@include mdc-rtl {
195-
margin-left: 12px;
196-
margin-right: auto;
197-
}
198-
}
199-
```
200-
201-
A 4th optional $root-selector argument can be given, which will be passed to `mdc-rtl`.
202-
203-
### mdc-rtl-reflexive-position
204-
205-
```scss
206-
@mixin mdc-rtl-reflexive-position($pos, $value, $root-selector: null)
207-
```
208-
209-
Takes an argument specifying a horizontal position property (either "left" or "right") as well
210-
as a value, and applies that value to the specified position in a LTR context, and flips it in a
211-
RTL context.
212-
213-
For example:
214-
215-
```scss
216-
.mdc-foo {
217-
@include mdc-rtl-reflexive-position(left, 0);
218-
position: absolute;
219-
}
220-
```
221-
is equivalent to:
222-
223-
```scss
224-
.mdc-foo {
225-
position: absolute;
226-
left: 0;
227-
right: initial;
228-
229-
@include mdc-rtl {
230-
right: 0;
231-
left: initial;
232-
}
233-
}
234-
```
235-
236-
An optional third `$root-selector` argument may also be given, which is passed to `mdc-rtl`.
55+
Unfortunately, we've found that this is the best we can do for now. In the future, selectors such as [:dir](http://mdn.io/:dir) will help us mitigate this.

‎packages/mdc-rtl/_mixins.scss

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@
125125
* ```
126126
*
127127
* You can also pass a 4th optional $root-selector argument which will be forwarded to `mdc-rtl`,
128-
* e.g. `@include mdc-rtl-reflexive-box-property(margin, left, 8px, ".mdc-component")`.
128+
* e.g. `@include mdc-rtl-reflexive-box(margin, left, 8px, ".mdc-component")`.
129129
*
130130
* Note that this function will always zero out the original value in an RTL context. If you're
131131
* trying to flip the values, use mdc-rtl-reflexive-property().
@@ -206,15 +206,15 @@
206206
* ```
207207
* An optional third $root-selector argument may also be given, which is passed to `mdc-rtl`.
208208
*/
209-
@mixin mdc-rtl-reflexive-position($pos, $value, $root-selector: null) {
210-
@if (index((right, left), $pos) == null) {
211-
@error "Invalid position #{pos}. Please specifiy either right or left";
209+
@mixin mdc-rtl-reflexive-position($position-property, $value, $root-selector: null) {
210+
@if (index((right, left), $position-property) == null) {
211+
@error "Invalid position #{position-property}. Please specifiy either right or left";
212212
}
213213

214214
$left-value: $value;
215215
$right-value: initial;
216216

217-
@if ($pos == right) {
217+
@if ($position-property == right) {
218218
$right-value: $value;
219219
$left-value: initial;
220220
}

0 commit comments

Comments
 (0)