diff --git a/packages/postcss-logical-fallback/README.md b/packages/postcss-logical-fallback/README.md index 35ab9e4..bb32c0f 100644 --- a/packages/postcss-logical-fallback/README.md +++ b/packages/postcss-logical-fallback/README.md @@ -1,32 +1,64 @@ # postcss-logical-fallback -[PostCSS] плагин для поддержки логических свойств в старых браузерах +This is [postcss](https://github.com/postcss/postcss) plugin for logical css props support in legacy browsers. Main idea of the plugin is +an opportunity to write logical styles like in modern browsers in legacy browsers. When all of your +supported browsers will support all modern logical spec you can just delete this plugin and don't rewrite +your styles. Second idea of the plugin is to use logical props where they supported and do fallback only in +non-supported browsers. -[PostCSS]: https://github.com/postcss/postcss -**Рекомендуется использовать вместе -со [stylelint плагином](https://github.com/yandex/i18n-utils/packages/stylelint-use-logical-properties)** +**We highly recommend to use it with +[stylelint plugin](https://github.com/yandex/i18n-utils/packages/stylelint-use-logical-spec)** -Цель данного плагина в том, чтобы создавать фолбеки для плохо поддерживаемых логических -свойств. -Мы выделили: -- Cвойства для абсолютного позиционирования +Main purpose of this plugin is creating fallbacks for bad supported logical props in legacy browsers. +We have distinguished: +- Absolute positioning props like `inset-inline-start`, `inset-inline-end`,`inset-block-start` -и `inset-block-end` из-за плохой поддержки в safari (14.1+ на десктопе, 14.5+ на мобилке), -chrome (87+) и firefox (66+) и большой распространенности данных свойств +and `inset-block-end` due to bad support in safari (14.1+ on desktop, 14.5+ on mobile), +chrome (87+) and firefox (66+) and due to high prevalence of these props. -- Свойства сокращения `inset-inline`, `inset-block`, `margin-inline`, `margin-block`, -`padding-inline`, `padding-block` из-за той же плохой поддержки в старых браузерах +- Shorthand props like `inset-inline`, `inset-block`, `margin-inline`, `margin-block`, +`padding-inline`, `padding-block` due to same bad support in browsers -Подробнее про логические свойства, rtl и зачем нужен этот плагин -можно почитать на [вики](https://wiki.yandex-team.ru/i18n/guide/rtl/) +Full logical props support you can see [here](https://caniuse.com/css-logical-props) -Данный плагин стоит использовать с [autoprefixer](https://github.com/postcss/autoprefixer) -и ставить по порядку до него +We recommend to use this plugin with [autoprefixer](https://github.com/postcss/autoprefixer) +and setup our plugin before autoprefixer -## Примеры -### Фолбек для свойств абсолютного позиционирования -До +**WARNING** +Plugin is based on @supports at rule, so it has to be supported, see on [can i use](https://caniuse.com/css-featurequeries) + +## Usage + +**Step 1:** install plugin and postcss + +```sh +npm install --save-dev postcss postcss-logical-fallback +``` + +**Step 2:** Find config at the root of your project: `postcss.config.js`, +`"postcss"` section in `package.json` +or `postcss` section in your build config. + +If you haven't already use postcss you should setup it according to +[official documentation](https://github.com/postcss/postcss#usage) and add postcss-logical-fallback +after it. + +**Step 3:** Add plugin to the plugin list + +```diff +module.exports = { + plugins: [ ++ require('postcss-logical-fallback'), + require('autoprefixer') + ] +} +``` + +## Examples +### Fallback for absolute positioning props + +Before ```css .class { @@ -35,7 +67,7 @@ chrome (87+) и firefox (66+) и большой распространеннос } ``` -После +After ```css @supports (inset-block-start: 12px) { @@ -58,8 +90,9 @@ chrome (87+) и firefox (66+) и большой распространеннос } ``` -### Фолбек для сокращений -До +### Fallback for shorthands + +Before ```css .class { @@ -68,7 +101,7 @@ chrome (87+) и firefox (66+) и большой распространеннос } ``` -После +After ```css .class { @@ -80,9 +113,9 @@ chrome (87+) и firefox (66+) и большой распространеннос } ``` -### Фолбек для сокращений inset +### Fallback for inset shorthands -До +Before ```css .class { @@ -94,7 +127,7 @@ chrome (87+) и firefox (66+) и большой распространеннос } ``` -После +After ```css @supports (inset-inline: 12px) { @@ -126,32 +159,3 @@ chrome (87+) и firefox (66+) и большой распространеннос ``` -Больше примеров можно найти [здесь](https://wiki.yandex-team.ru/i18n/guide/rtl/#primerytransformacijjplagina) - -## Использование - -**Шаг1:** Установите плагин: - -```sh -npm install --save-dev postcss postcss-logical-fallback -``` - -**Шаг 2:** Найдите конфиг postcss в корне проекта: `postcss.config.js`, -`"postcss"` секцию в `package.json` -иди `postcss` в конфиге вашего сборщика. - -Если вы еще не используете postcss, то установите его в соответствии с -[официальной документацией] и добавьте данный плагин после установки - -**Шаг 3:** Добавьте плагин в список плагинов - -```diff -module.exports = { - plugins: [ -+ require('postcss-logical-fallback'), - require('autoprefixer') - ] -} -``` - -[официальной документацией]: https://github.com/postcss/postcss#usage diff --git a/packages/stylelint-use-logical-properties/README.md b/packages/stylelint-use-logical-properties/README.md index bccfb08..de58273 100644 --- a/packages/stylelint-use-logical-properties/README.md +++ b/packages/stylelint-use-logical-properties/README.md @@ -1,8 +1,8 @@ -# Property Use Logical [stylelint] +# Stylelint Use Logical Spec -### This is fork from https://github.com/dr-itz/stylelint-use-logical-properties/tree/feat/value-split +### This is fork from https://github.com/dr-itz/stylelint-use-logical-spec/tree/feat/value-split -[Property Use Logical] is a [stylelint] rule to enforce the usage of +`Stylelint Use Logical Spec` is a [stylelint] rule to enforce the usage of [Logical Properties and Values] in CSS. Physical dimensions and directions are described _left_ to _right_ and _top_ to @@ -12,26 +12,54 @@ _inline_ or _block_. This plugin modified to support RTL migration, so we **don't support logical sizes** due to uselessness of this at this goal -## Recommendations -### For modern browsers support +## Usage + +Add [stylelint] and stylelint-use-logical-spec to your project. + +```bash +npm install stylelint stylelint-use-logical-spec --save-dev +``` + +Add stylelint-use-logical-spec to your [stylelint configuration]. + +```js +{ + "plugins": [ + "stylelint-use-logical-spec" + ], + "rules": { + "use-logical-spec": ("always" || true) || "allow-shorthands" || ("ignore" || false || null) + } +} +``` + +## Modern browsers support + If you support safari 14.5, chrome 87+, firefox 66+ we recommend to use this plugin standalone with `allow-shorthands` option -### For legacy browser support +## Legacy browser support + For legacy browsers we have developed a postcss plugin - -https://github.com/yandex/i18n-utils/packages/postcss-logical-fallback which you +https://github.com/yandex/i18n-utils/packages/postcss-logical-fallback which you have to add for your project. With this plugin you can use it like in modern browsers -If you want to use this plugin **standalone** - we strongly recommend you to use following -config due to bad support of inset props in browsers +If you want to use this plugin **standalone** - we strongly recommend you to use following +config due to bad support of inset props (logical analog for top, bottom, left and right props) +in browsers ```js { "rules": { - "use-logical-spec": ["always", { "except": [/inset/i] }] + "use-logical-spec": ["always", { "except": ["top", "bottom", "left", "right"] }] } } ``` +### Use plugin with autoprefixer + +Also don't forget to use [autoprefixer](https://github.com/postcss/autoprefixer) +for legacy browser support no matter you use our [postcss plugin](https://github.com/yandex/i18n-utils/packages/postcss-logical-fallback) +or not ## Example @@ -93,27 +121,6 @@ blockquote { } ``` -## Usage - -Add [stylelint] and [Property Use Logical] to your project. - -```bash -npm install stylelint stylelint-use-logical-properties --save-dev -``` - -Add [Property Use Logical] to your [stylelint configuration]. - -```js -{ - "plugins": [ - "stylelint-use-logical-properties" - ], - "rules": { - "stylelint-use-logical-properties": ("always" || true) || "allow-shorthands" || ("ignore" || false || null) - } -} -``` - ## Options ### always @@ -122,125 +129,44 @@ The `"always"` option (alternatively `true`) requires logical properties and values to be used. This option DOESN'T allow use shorthands for logical properties for wider browser support. -The following patterns are _not_ considered violations: - -```pcss -.inset { - inset: 0; -} - -.margin { - margin-inline-start: 0; -} +So the following code -.float { - float: inline-start; -} - -.text-align { - text-align: start; -} - -.text-align-ignored:dir(ltr) { - text-align: left; +```css +.class { + margin-top: 20px; + margin-bottom: 20px; } ``` -While the following patterns _are_ considered violations: - -```pcss -.inset { - top: 0; - right: 0; - bottom: 0; - left: 0; -} - -.padding { - padding-inline: 0; -} - -.maring { - maring-inline: 0; -} - -.margin { - margin-left: 0; -} - -.padding { - padding-left: 0; - padding-right: 0; -} +will be transformed into -.float { - float: left; -} - -.text-align { - text-align: left; +```css +.class { + margin-block-start: 20px; + margin-block-end: 20px; } ``` ### allow-shorthands The `"allow-shorthands"` option requires logical properties and -values to be used. At this option you can use shorthands. It can be used only for new +values to be used. At this option you can use shorthands. It can be used only for new browsers (mostly 2020+) and can't be used on TV platforms. -The following patterns are _not_ considered violations: +So the following code -```pcss -.inset { - inset: 0; -} - -.margin { - margin-inline-start: 0; -} - -.padding { - padding-inline: 0; -} - -.float { - float: inline-start; -} - -.text-align { - text-align: start; -} - -.text-align-ignored:dir(ltr) { - text-align: left; +```css +.class { + margin-top: 20px; + margin-bottom: 20px; } ``` -While the following patterns _are_ considered violations: - -```pcss -.inset { - top: 0; - right: 0; - bottom: 0; - left: 0; -} - -.margin { - margin-left: 0; -} +will be transformed into -.padding { - padding-left: 0; - padding-right: 0; -} - -.float { - float: left; -} - -.text-align { - text-align: left; +```css +.class { + margin-block: 20px; } ``` @@ -282,33 +208,41 @@ Assuming _left to right_ directionality: # Positioning -| Physical Property | Logical Property | -|-------------------|----------------------| -| `top` | `inset-block-start` | -| `right` | `inset-inline-end` | -| `bottom` | `inset-block-end` | -| `left` | `inset-inline-start` | +| Physical Property | Logical Property | Option | +|-------------------|----------------------|---------------------------------| +| `top` | `inset-block-start` | `always` and `allow-shorthands` | +| `right` | `inset-inline-end` | `always` and `allow-shorthands` | +| `bottom` | `inset-block-end` | `always` and `allow-shorthands` | +| `left` | `inset-inline-start` | `always` and `allow-shorthands` | +| `left + right` | `inset-inline` | `allow-shorthands` | +| `bottom + top` | `inset-block` | `allow-shorthands` | ### margin -| Physical Property | Logical Property | -|-------------------|-----------------------| -| `margin-top` | `margin-block-start` | -| `margin-right` | `margin-inline-end` | -| `margin-bottom` | `margin-block-end` | -| `margin-left` | `margin-inline-start` | +| Physical Property | Logical Property | Option | +|------------------------------|-----------------------|---------------------------------| +| `margin-top` | `margin-block-start` | `always` and `allow-shorthands` | +| `margin-right` | `margin-inline-end` | `always` and `allow-shorthands` | +| `margin-bottom` | `margin-block-end` | `always` and `allow-shorthands` | +| `margin-left` | `margin-inline-start` | `always` and `allow-shorthands` | +| `margin-right + margin-left` | `margin-inline` | `allow-shorthands` | +| `margin-bottom + margin-top` | `margin-block` | `allow-shorthands` | ### Padding -| Physical Property | Logical Property | -|-------------------|------------------------| -| `padding-top` | `padding-block-start` | -| `padding-right` | `padding-inline-end` | -| `padding-bottom` | `padding-block-end` | -| `padding-left` | `padding-inline-start` | +| Physical Property | Logical Property | Options | +|--------------------------------|------------------------|---------------------------------| +| `padding-top` | `padding-block-start` | `always` and `allow-shorthands` | +| `padding-right` | `padding-inline-end` | `always` and `allow-shorthands` | +| `padding-bottom` | `padding-block-end` | `always` and `allow-shorthands` | +| `padding-left` | `padding-inline-start` | `always` and `allow-shorthands` | +| `padding-bottom + padding-top` | `padding-block` | `allow-shorthands` | +| `padding-left + padding-right` | `padding-inline` | `allow-shorthands` | ### Border +All works with `allow-shorthands` and `always` + | Physical Property | Logical Property | |------------------------------|-----------------------------| | `border-top` | `border-block-start` | @@ -333,9 +267,11 @@ Assuming _left to right_ directionality: | `border-bottom-right-radius` | `border-end-end-radius` | ## Special thanks + Codebase off https://github.com/csstools/stylelint-use-logical [Logical Properties and Values]: https://www.w3.org/TR/css-logical-1/ + [stylelint]: https://github.com/stylelint/stylelint + [stylelint configuration]: https://github.com/stylelint/stylelint/blob/master/docs/user-guide/configuration.md#readme -[Property Use Logical]: https://github.com/Jordan-Hall/stylelint-use-logical-properties