0
# Parser and Compilation
1

2
Core CSS parsing functionality that transforms CSS strings into Abstract Syntax Trees (AST) with support for nesting, at-rules, comments, and declarations.
3

4
## Capabilities
5

6
### Compile Function
7

8
The primary entry point for parsing CSS strings into AST structures. Handles CSS nesting, at-rules, comments, and declarations.
9

10
```javascript { .api }
11
/**
12
 * Parse CSS string into Abstract Syntax Tree
13
 * @param value - CSS string to parse
14
 * @returns Array of AST node objects
15
 */
16
function compile(value: string): object[];
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import { compile } from 'stylis';
23

24
// Basic CSS compilation
25
const ast = compile('h1 { color: red; }');
26
console.log(ast);
27
// [{ value: 'h1', type: 'rule', props: ['h1'], children: [...] }]
28

29
// Nested CSS compilation  
30
const nested = compile(`
31
  .container {
32
    padding: 20px;
33
    
34
    h1 {
35
      color: blue;
36
      &:hover {
37
        color: red;
38
      }
39
    }
40
  }
41
`);
42

43
// At-rule compilation
44
const media = compile('@media (max-width: 768px) { .mobile { display: block; } }');
45

46
// Declaration compilation
47
const decl = compile('--custom-property: value;');
48
```
49

50
### Parse Function
51

52
Low-level parsing function with extensive parameter control for advanced use cases and custom parsing workflows.
53

54
```javascript { .api }
55
/**
56
 * Low-level parsing function with extensive parameter control
57
 * @param value - CSS string segment to parse
58
 * @param root - Root AST node
59
 * @param parent - Parent AST node  
60
 * @param rule - Current rule context
61
 * @param rules - Rule stack
62
 * @param rulesets - Ruleset collection
63
 * @param pseudo - Pseudo-selector tracking
64
 * @param points - Parsing position markers
65
 * @param declarations - Declaration collection
66
 * @returns Parsed AST object
67
 */
68
function parse(
69
  value: string, 
70
  root: object, 
71
  parent: object, 
72
  rule: string[], 
73
  rules: string[], 
74
  rulesets: string[], 
75
  pseudo: number[], 
76
  points: number[], 
77
  declarations: string[]
78
): object;
79
```
80

81
### Ruleset Creation
82

83
Creates ruleset AST nodes for CSS rules and selectors.
84

85
```javascript { .api }
86
/**
87
 * Create ruleset AST node for CSS rules and selectors
88
 * @param value - CSS rule text
89
 * @param root - Root AST node
90
 * @param parent - Parent AST node
91
 * @param index - Current index
92
 * @param offset - Parsing offset
93
 * @param rules - Rule context
94
 * @param points - Position markers
95
 * @param type - Node type
96
 * @param props - Properties array
97
 * @param children - Child nodes
98
 * @param length - Character length
99
 * @param siblings - Sibling nodes
100
 * @returns Ruleset AST node
101
 */
102
function ruleset(
103
  value: string, 
104
  root: object, 
105
  parent: object, 
106
  index: number, 
107
  offset: number, 
108
  rules: string[], 
109
  points: number[], 
110
  type: string, 
111
  props: string[], 
112
  children: string[], 
113
  length: number, 
114
  siblings: object[]
115
): object;
116
```
117

118
### Comment Creation
119

120
Creates comment AST nodes for CSS comments.
121

122
```javascript { .api }
123
/**
124
 * Create comment AST node for CSS comments
125
 * @param value - Comment content with delimiters
126
 * @param root - Root AST node
127
 * @param parent - Parent AST node
128
 * @param siblings - Sibling nodes
129
 * @returns Comment AST node
130
 */
131
function comment(value: number, root: object, parent: object, siblings: object[]): object;
132
```
133

134
### Declaration Creation
135

136
Creates declaration AST nodes for CSS property-value pairs.
137

138
```javascript { .api }
139
/**
140
 * Create declaration AST node for CSS property-value pairs
141
 * @param value - Declaration text (property: value;)
142
 * @param root - Root AST node
143
 * @param parent - Parent AST node
144
 * @param length - Property name length
145
 * @param siblings - Sibling nodes
146
 * @returns Declaration AST node
147
 */
148
function declaration(
149
  value: string, 
150
  root: object, 
151
  parent: object, 
152
  length: number, 
153
  siblings: object[]
154
): object;
155
```
156

157
## AST Node Types
158

159
The parser generates different types of AST nodes based on CSS content:
160

161
### Rule Nodes
162
```javascript { .api }
163
interface RuleNode {
164
  value: string;        // 'h1, h2'
165
  type: 'rule';        // Always 'rule' for selectors
166
  props: string[];     // ['h1', 'h2'] - parsed selectors
167
  children: object[];  // Child declaration and rule nodes
168
  // ...standard node properties
169
}
170
```
171

172
### Declaration Nodes
173
```javascript { .api }
174
interface DeclarationNode {
175
  value: string;       // 'color: red;'
176
  type: 'decl';       // Always 'decl' for properties
177
  props: string;      // 'color' - property name
178
  children: string;   // 'red' - property value
179
  // ...standard node properties
180
}
181
```
182

183
### Comment Nodes
184
```javascript { .api }
185
interface CommentNode {
186
  value: string;       // '/* comment text */'
187
  type: 'comm';       // Always 'comm' for comments
188
  props: string;      // '/' - comment delimiter
189
  children: string;   // 'comment text' - comment content
190
  // ...standard node properties
191
}
192
```
193

194
### At-Rule Nodes
195
```javascript { .api }
196
interface AtRuleNode {
197
  value: string;       // '@media (max-width: 768px)'
198
  type: string;       // '@media', '@keyframes', etc.
199
  props: string[];    // ['(max-width: 768px)'] - parsed conditions
200
  children: object[]; // Child nodes within at-rule
201
  // ...standard node properties
202
}
203
```
204

205
## Parsing Features
206

207
### CSS Nesting Support
208
The parser handles CSS nesting with `&` parent selector references:
209

210
```javascript
211
compile(`
212
  .parent {
213
    color: blue;
214
    &:hover { color: red; }
215
    & .child { font-size: 14px; }
216
  }
217
`);
218
```
219

220
### At-Rule Processing
221
Full support for CSS at-rules including media queries, keyframes, imports, and more:
222

223
```javascript
224
compile(`
225
  @import url('styles.css');
226
  @media (min-width: 768px) {
227
    .desktop { display: block; }
228
  }
229
  @keyframes fadeIn {
230
    from { opacity: 0; }
231
    to { opacity: 1; }
232
  }
233
`);
234
```
235

236
### Comment Preservation
237
CSS comments are preserved in the AST and can be processed by middleware:
238

239
```javascript
240
compile(`
241
  /* Main styles */
242
  .component {
243
    /* TODO: add responsive styles */
244
    padding: 20px;
245
  }
246
`);
247
```