0
# RTLCSS
1

2
RTLCSS is a framework for converting Left-To-Right (LTR) Cascading Style Sheets to Right-To-Left (RTL) format. It provides both a programmatic API for Node.js applications and a command-line interface for batch processing CSS files, enabling developers to create internationalized web applications that support right-to-left languages like Arabic, Hebrew, and Persian.
3

4
## Package Information
5

6
- **Package Name**: rtlcss
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install rtlcss`
10

11
## Core Imports
12

13
```javascript
14
const rtlcss = require("rtlcss");
15
```
16

17
For PostCSS integration:
18

19
```javascript
20
const postcss = require("postcss");
21
const rtlcss = require("rtlcss");
22
```
23

24
## Basic Usage
25

26
```javascript
27
const rtlcss = require("rtlcss");
28

29
// Simple CSS transformation
30
const css = ".container { float: left; margin-right: 10px; }";
31
const rtlCSS = rtlcss.process(css);
32
console.log(rtlCSS);
33
// Output: ".container { float: right; margin-left: 10px; }"
34

35
// Using with PostCSS
36
const postcss = require("postcss");
37
const result = postcss([rtlcss()])
38
  .process(css)
39
  .css;
40

41
// With custom options
42
const rtlCSSWithOptions = rtlcss.process(css, {
43
  autoRename: true,
44
  stringMap: [
45
    {
46
      name: 'left-right',
47
      search: ['left', 'Left'],
48
      replace: ['right', 'Right']
49
    }
50
  ]
51
});
52
```
53

54
## Architecture
55

56
RTLCSS is built around several key components:
57

58
- **PostCSS Plugin**: Core transformation engine that processes CSS Abstract Syntax Tree (AST)
59
- **Configuration System**: Flexible options, plugins, and hooks for customizing transformations
60
- **Directive System**: Comment-based directives for fine-grained control over transformations
61
- **String Mapping**: Configurable text replacement system for custom transformations
62
- **Utility Functions**: Helper functions for CSS value manipulation and transformation
63
- **CLI Interface**: Command-line tool for batch processing CSS files
64

65
## Capabilities
66

67
### Core API
68

69
Main RTLCSS functions for CSS transformation and PostCSS integration.
70

71
```javascript { .api }
72
/**
73
 * Creates RTLCSS PostCSS plugin instance
74
 * @param options - Configuration options
75
 * @param plugins - Array of RTLCSS plugins
76
 * @param hooks - Pre/post processing hooks
77
 * @returns PostCSS plugin function
78
 */
79
function rtlcss(options?: RTLCSSOptions, plugins?: RTLCSSPlugin[], hooks?: RTLCSSHooks): PostCSSPlugin;
80

81
/**
82
 * Processes CSS string and returns RTL-converted CSS
83
 * @param css - Input CSS string
84
 * @param options - Configuration options
85
 * @param plugins - Array of RTLCSS plugins
86
 * @param hooks - Pre/post processing hooks
87
 * @returns RTL-converted CSS string
88
 */
89
rtlcss.process(css: string, options?: RTLCSSOptions, plugins?: RTLCSSPlugin[], hooks?: RTLCSSHooks): string;
90

91
/**
92
 * Creates configured PostCSS processor instance
93
 * @param config - Configuration object containing options, plugins, and hooks
94
 * @returns PostCSS processor instance
95
 */
96
rtlcss.configure(config: RTLCSSConfiguration): PostCSSProcessor;
97
```
98

99
[Core API](./core-api.md)
100

101
### Configuration
102

103
Configuration system for customizing RTLCSS behavior, including options, plugins, and hooks.
104

105
```javascript { .api }
106
interface RTLCSSOptions {
107
  /** Enable automatic CSS class renaming */
108
  autoRename?: boolean;
109
  /** Strict mode for auto-renaming */
110
  autoRenameStrict?: boolean;
111
  /** Plugin/directive blacklist */
112
  blacklist?: { [pluginName: string]: { [directiveName: string]: boolean } };
113
  /** Remove directive comments after processing */
114
  clean?: boolean;
115
  /** Greedy string matching mode */
116
  greedy?: boolean;
117
  /** Process URLs in CSS */
118
  processUrls?: boolean | { atrule?: boolean };
119
  /** Custom string replacement mappings */
120
  stringMap?: StringMapEntry[];
121
  /** Use calc() for flipping values */
122
  useCalc?: boolean;
123
  /** Property name aliases */
124
  aliases?: { [property: string]: string };
125
  /** Process environment-specific values */
126
  processEnv?: boolean;
127
}
128
```
129

130
[Configuration](./configuration.md)
131

132
### Directives
133

134
Comment-based directives for fine-grained control over CSS transformations.
135

136
```javascript { .api }
137
// Control directives that modify processing flow
138
/* rtl:ignore */
139
/* rtl:begin:ignore */
140
/* rtl:end:ignore */
141
/* rtl:rename */
142
/* rtl:raw: .custom { direction: rtl; } */
143
/* rtl:remove */
144
/* rtl:begin:options: {"autoRename": true} */
145
/* rtl:end:options */
146
```
147

148
[Directives](./directives.md)
149

150
### Command Line Interface
151

152
Command-line tool for batch processing CSS files with various options.
153

154
```bash { .api }
155
# Basic usage
156
rtlcss input.css output.css
157

158
# Process directory recursively
159
rtlcss -d input-dir output-dir
160

161
# Read from stdin
162
cat input.css | rtlcss -
163

164
# With custom config
165
rtlcss -c .rtlcssrc input.css output.css
166
```
167

168
[CLI](./cli.md)
169

170
## Types
171

172
```javascript { .api }
173
interface StringMapEntry {
174
  /** String map identifier */
175
  name: string;
176
  /** Processing priority */
177
  priority: number;
178
  /** String(s) to search for */
179
  search: string | string[];
180
  /** Replacement string(s) */
181
  replace: string | string[];
182
  /** Stop processing other maps if this matches */
183
  exclusive?: boolean;
184
  /** Scope and case sensitivity options */
185
  options?: {
186
    scope?: '*' | 'url' | 'selector';
187
    ignoreCase?: boolean;
188
    greedy?: boolean;
189
  };
190
}
191

192
interface RTLCSSPlugin {
193
  /** Plugin identifier */
194
  name: string;
195
  /** Processing priority */
196
  priority: number;
197
  /** Control and value directives */
198
  directives: {
199
    control?: { [name: string]: DirectiveHandler };
200
    value?: DirectiveHandler[];
201
  };
202
  /** CSS property processors */
203
  processors?: PropertyProcessor[];
204
}
205

206
interface RTLCSSHooks {
207
  /** Called before CSS processing */
208
  pre?: (root: PostCSS.Root, postcss: PostCSS) => void;
209
  /** Called after CSS processing */
210
  post?: (root: PostCSS.Root, postcss: PostCSS) => void;
211
}
212

213
interface RTLCSSConfiguration {
214
  /** Configuration options */
215
  options?: RTLCSSOptions;
216
  /** Array of plugins */
217
  plugins?: RTLCSSPlugin[];
218
  /** Pre/post processing hooks */
219
  hooks?: RTLCSSHooks;
220
}
221

222
// PostCSS integration types
223
type PostCSSPlugin = (options?: any) => PostCSS.Processor;
224
namespace PostCSS {
225
  interface Processor {
226
    process(css: string, options?: ProcessOptions): Result;
227
  }
228
  interface ProcessOptions {
229
    from?: string;
230
    to?: string;
231
    map?: boolean | { inline?: boolean };
232
  }
233
  interface Result {
234
    css: string;
235
    map?: string;
236
    warnings(): Warning[];
237
  }
238
  interface Warning {
239
    toString(): string;
240
  }
241
  interface Root {
242
    walkRules(callback: (rule: Rule) => void): void;
243
    append(node: string): void;
244
  }
245
  interface Rule {
246
    selector: string;
247
    remove(): void;
248
  }
249
}
250
```