0
# Core API
1

2
The core RTLCSS API provides three main functions for CSS transformation and PostCSS integration.
3

4
## Capabilities
5

6
### RTLCSS Plugin Factory
7

8
Creates a PostCSS plugin instance configured for RTL transformation.
9

10
```javascript { .api }
11
/**
12
 * Creates RTLCSS PostCSS plugin instance
13
 * @param options - Configuration options for transformation behavior
14
 * @param plugins - Array of RTLCSS plugins for extending functionality
15
 * @param hooks - Pre/post processing hooks for custom logic
16
 * @returns PostCSS plugin function
17
 */
18
function rtlcss(options?: RTLCSSOptions, plugins?: RTLCSSPlugin[], hooks?: RTLCSSHooks): PostCSSPlugin;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const postcss = require("postcss");
25
const rtlcss = require("rtlcss");
26

27
// Basic usage with default options
28
const processor = postcss([rtlcss()]);
29
const result = processor.process(css).css;
30

31
// With custom options
32
const processor = postcss([rtlcss({
33
  autoRename: true,
34
  clean: false,
35
  stringMap: [
36
    {
37
      name: 'custom-map',
38
      search: 'theme-light',
39
      replace: 'theme-dark',
40
      priority: 50
41
    }
42
  ]
43
})]);
44

45
// With custom plugin
46
const customPlugin = {
47
  name: 'my-plugin',
48
  priority: 50,
49
  processors: [
50
    {
51
      expr: /^custom-prop$/,
52
      action: (prop, value, context) => ({
53
        prop: prop,
54
        value: value.replace('left', 'right')
55
      })
56
    }
57
  ]
58
};
59

60
const processor = postcss([rtlcss({}, [customPlugin])]);
61
```
62

63
### Process Function
64

65
Processes CSS string directly and returns RTL-converted CSS.
66

67
```javascript { .api }
68
/**
69
 * Processes CSS string and returns RTL-converted CSS
70
 * @param css - Input CSS string to transform
71
 * @param options - Configuration options
72
 * @param plugins - Array of RTLCSS plugins
73
 * @param hooks - Pre/post processing hooks
74
 * @returns RTL-converted CSS string
75
 */
76
rtlcss.process(css: string, options?: RTLCSSOptions, plugins?: RTLCSSPlugin[], hooks?: RTLCSSHooks): string;
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
const rtlcss = require("rtlcss");
83

84
// Simple transformation
85
const css = `
86
  .header {
87
    float: left;
88
    margin-right: 20px;
89
    text-align: left;
90
  }
91
`;
92

93
const rtlCSS = rtlcss.process(css);
94
console.log(rtlCSS);
95
// Output:
96
// .header {
97
//   float: right;
98
//   margin-left: 20px;
99
//   text-align: right;
100
// }
101

102
// With options
103
const rtlCSSWithOptions = rtlcss.process(css, {
104
  autoRename: true,
105
  stringMap: [
106
    {
107
      name: 'header-footer',
108
      search: 'header',
109
      replace: 'راس_الصفحة',
110
      priority: 100
111
    }
112
  ]
113
});
114

115
// With hooks
116
const rtlCSSWithHooks = rtlcss.process(css, {}, [], {
117
  pre: (root, postcss) => {
118
    console.log('Processing started');
119
  },
120
  post: (root, postcss) => {
121
    console.log('Processing completed');
122
  }
123
});
124
```
125

126
### Configure Function
127

128
Creates a configured PostCSS processor instance.
129

130
```javascript { .api }
131
/**
132
 * Creates configured PostCSS processor instance
133
 * @param config - Configuration object containing options, plugins, and hooks
134
 * @returns PostCSS processor instance with RTLCSS plugin configured
135
 */
136
rtlcss.configure(config: RTLCSSConfiguration): PostCSS.Processor;
137
```
138

139
**Usage Examples:**
140

141
```javascript
142
const rtlcss = require("rtlcss");
143

144
// Create configured processor
145
const processor = rtlcss.configure({
146
  options: {
147
    autoRename: true,
148
    clean: false,
149
    processUrls: true
150
  },
151
  plugins: [
152
    {
153
      name: 'custom-plugin',
154
      priority: 100,
155
      processors: [
156
        {
157
          expr: /^border-(left|right)$/,
158
          action: (prop, value, context) => {
159
            const newProp = prop.replace('left', 'right').replace('right', 'left');
160
            return { prop: newProp, value: value };
161
          }
162
        }
163
      ]
164
    }
165
  ],
166
  hooks: {
167
    pre: (root, postcss) => {
168
      // Add custom pre-processing logic
169
      root.walkRules(rule => {
170
        if (rule.selector.includes('.rtl-only')) {
171
          rule.remove();
172
        }
173
      });
174
    },
175
    post: (root, postcss) => {
176
      // Add custom post-processing logic
177
      root.append('/* RTL conversion completed */');
178
    }
179
  }
180
});
181

182
// Use the configured processor
183
const result = processor.process(css).css;
184
```
185

186
## PostCSS Integration
187

188
RTLCSS is designed as a PostCSS plugin and integrates seamlessly with PostCSS workflows.
189

190
```javascript { .api }
191
// PostCSS plugin compatibility flag
192
rtlcss.postcss = true;
193
```
194

195
**Integration Examples:**
196

197
```javascript
198
const postcss = require("postcss");
199
const rtlcss = require("rtlcss");
200
const autoprefixer = require("autoprefixer");
201

202
// Chain with other PostCSS plugins
203
const processor = postcss([
204
  autoprefixer(),
205
  rtlcss({
206
    autoRename: true,
207
    processUrls: true
208
  })
209
]);
210

211
const result = processor.process(css, {
212
  from: 'src/styles.css',
213
  to: 'dist/styles.rtl.css'
214
});
215

216
// With source maps
217
const result = processor.process(css, {
218
  from: 'src/styles.css',
219
  to: 'dist/styles.rtl.css',
220
  map: { inline: false }
221
});
222

223
console.log(result.css); // RTL CSS
224
console.log(result.map); // Source map
225
```