Support specifying processors during processing CSS declarations

Author: aleen42

README.md

@@ -382,6 +382,7 @@ All the options are optional, and a default value will be used if any of them is
 | stringMap          | `PluginStringMap[]`       | Check below     | An array of strings maps that will be used to make the replacements of the declarations' URLs and to match the names of the rules if `processRuleNames` is `true` |
 | greedy             | `boolean`                 | `false`         | When greedy is `true`, the matches of `stringMap` will not take into account word boundaries |
 | aliases            | `Record<string, string>`  | `{}`            | A strings map to treat some declarations as others |
+| processDeclarationPlugins | `Array<{name: string, priority: number, processors: []}>` | `[]` | Plugins applied when processing CSS declarations |
 
 ---
 
@@ -1447,6 +1448,62 @@ const options = {
 
 ---
 
+#### processDeclarationPlugins
+
+<details><summary>Expand</summary>
+<p>
+
+Sometimes, we can register some plugins when processing CSS declarations via the `processDeclarationPlugins` options, which is helpful when we need to avoid unexpected flipping situations like `background-position`.
+
+##### input
+
+```css
+.test {
+    background-position: 0 100%;
+}
+```
+
+##### Convert `0` to `100%` (default)
+
+##### output
+
+```css
+.test {
+    background-position: 100% 100%;
+}
+```
+
+##### Set a plugin to avoid flipping
+
+```javascript
+const options = {
+	processDeclarationPlugins: [
+        {
+            name: 'avoid-flipping-background',
+            priority: 99, // above the core RTLCSS plugin which has a priority value of 100
+            processors: [{
+                expr: /(background|object)(-position(-x)?|-image)?$/i,
+                action: (prop, value) => ({prop, value})}
+            ]
+        }
+    ]
+};
+```
+
+##### output
+
+```css
+.test {
+    background-position: 0 100%;
+}
+```
+
+</p>
+
+</details>
+
+---
+
 Control Directives
 ---
 

src/@types/index.ts

@@ -39,6 +39,11 @@ export interface PluginStringMap {
     replace: strings;
 }
 
+export interface PluginProcessor {
+    expr: RegExp;
+    action: (prop: string, value: string, context: object) => object;
+}
+
 export type PrefixSelectorTransformer = (prefix: string, selector: string) => string | void;
 
 export interface PluginOptions {
@@ -58,6 +63,7 @@ export interface PluginOptions {
     stringMap?: PluginStringMap[];
     greedy?: boolean;
     aliases?: Record<string, string>;
+    processDeclarationPlugins?: Array<{ name: string, priority: number, processors: PluginProcessor[] }>;
 }
 
 export interface PluginOptionsNormalized extends Omit<Required<PluginOptions>, 'stringMap' | 'prefixSelectorTransformer'> {

src/data/store.ts

@@ -143,7 +143,8 @@ const defaultOptions = (): PluginOptionsNormalized => ({
     useCalc: false,
     stringMap: getRTLCSSStringMap(defaultStringMap),
     greedy: false,
-    aliases: {}
+    aliases: {},
+    processDeclarationPlugins: []
 });
 
 const store: Store = {
@@ -217,7 +218,10 @@ const normalizeOptions = (options: PluginOptions): PluginOptionsNormalized => {
     if (options.aliases && isObjectWithStringKeys(options.aliases)) {
         returnOptions.aliases = options.aliases;
     }
-    return returnOptions;
+    return {
+        ...returnOptions,
+        processDeclarationPlugins: (options.processDeclarationPlugins || []).map(plugin => ({...plugin, directives: {control: {}, value: []}}))
+    };
 };
 
 const initStore = (options: PluginOptions): void => {

src/parsers/declarations.ts

@@ -59,7 +59,8 @@ export const parseDeclarations = (
         useCalc,
         stringMap,
         greedy,
-        aliases
+        aliases,
+        processDeclarationPlugins
     } = store.options;
 
     const deleteDeclarations: Declaration[] = [];
@@ -160,7 +161,7 @@ export const parseDeclarations = (
                 stringMap,
                 greedy,
                 aliases
-            });
+            }, processDeclarationPlugins);
 
             /* the source could be undefined in certain cases but not during the tests */
             /* istanbul ignore next */