0
# Node Constructors
1

2
Factory functions for creating all types of CSS selector AST nodes. These constructors are essential for programmatically building selector structures.
3

4
## Capabilities
5

6
### Attribute Constructor
7

8
Creates attribute selector nodes for CSS attribute selectors like `[href]`, `[class="btn"]`, `[data-*]`.
9

10
```javascript { .api }
11
/**
12
 * Creates a new attribute selector node
13
 * @param props - Attribute node properties
14
 * @returns Attribute node
15
 */
16
function attribute(props?: AttributeOptions): Attribute;
17

18
interface AttributeOptions extends NamespaceOptions {
19
  /** The attribute name */
20
  attribute: string;
21
  /** Comparison operator (=, ~=, |=, ^=, $=, *=) */
22
  operator?: AttributeOperator;
23
  /** Case insensitive flag */
24
  insensitive?: boolean;
25
  /** Quote mark for the value */
26
  quoteMark?: QuoteMark;
27
  /** Whether the value is quoted (deprecated, use quoteMark) */
28
  quoted?: boolean;
29
  /** Spacing configuration */
30
  spaces?: AttributeSpaces;
31
  /** Raw values for precise output control */
32
  raws?: AttributeRaws;
33
}
34

35
type AttributeOperator = "=" | "~=" | "|=" | "^=" | "$=" | "*=";
36
type QuoteMark = '"' | "'" | null;
37

38
interface AttributeSpaces {
39
  before?: string;
40
  after?: string;
41
  attribute?: Partial<SpaceAround>;
42
  operator?: Partial<SpaceAround>;
43
  value?: Partial<SpaceAround>;
44
  insensitive?: Partial<SpaceAround>;
45
}
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
const parser = require('postcss-selector-parser');
52

53
// Simple attribute selector
54
const attr1 = parser.attribute({ attribute: 'href' });
55
// Result: [href]
56

57
// Attribute with value
58
const attr2 = parser.attribute({
59
  attribute: 'class',
60
  operator: '=',
61
  value: 'button',
62
  quoteMark: '"'
63
});
64
// Result: [class="button"]
65

66
// Case insensitive attribute
67
const attr3 = parser.attribute({
68
  attribute: 'data-value',
69
  operator: '*=',
70
  value: 'test',
71
  insensitive: true
72
});
73
// Result: [data-value*="test" i]
74
```
75

76
### Attribute Interface
77

78
The Attribute class provides additional methods for advanced attribute manipulation.
79

80
```javascript { .api }
81
interface Attribute extends Base {
82
  attribute: string;
83
  operator?: AttributeOperator;
84
  value?: string;
85
  insensitive?: boolean;
86
  quoteMark?: QuoteMark;
87
  namespace?: string | true;
88
  
89
  /** Get the attribute value with proper quoting */
90
  getQuotedValue(options?: { quoteMark?: QuoteMark }): string;
91
  
92
  /** Set the attribute value with quote options */
93
  setValue(value: string, options?: { quoteMark?: QuoteMark; smart?: boolean }): this;
94
  
95
  /** Get intelligently selected quote mark */
96
  smartQuoteMark(options?: { preferredQuote?: QuoteMark }): QuoteMark;
97
  
98
  /** Get preferred quote mark based on content */
99
  preferredQuoteMark(options?: { preferredQuote?: QuoteMark }): QuoteMark;
100
  
101
  /** Read-only property returning 'i' or empty string */
102
  readonly insensitiveFlag: string;
103
  
104
  /** Read-only property for namespaced attribute name */
105
  readonly qualifiedAttribute: string;
106
}
107

108
// Static constants
109
Attribute.NO_QUOTE = null;
110
Attribute.SINGLE_QUOTE = "'";
111
Attribute.DOUBLE_QUOTE = '"';
112
```
113

114
### Class Name Constructor
115

116
Creates class selector nodes for CSS class selectors like `.button`, `.nav-item`.
117

118
```javascript { .api }
119
/**
120
 * Creates a new class selector node
121
 * @param props - Class node properties
122
 * @returns ClassName node
123
 */
124
function className(props?: NamespaceOptions): ClassName;
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
// Simple class selector
131
const cls1 = parser.className({ value: 'button' });
132
// Result: .button
133

134
// Namespaced class
135
const cls2 = parser.className({
136
  value: 'component',
137
  namespace: 'ui'
138
});
139
// Result: ui|.component
140
```
141

142
### Combinator Constructor
143

144
Creates combinator nodes for CSS selector combinators like `>`, `+`, `~`, ` ` (space).
145

146
```javascript { .api }
147
/**
148
 * Creates a new combinator node
149
 * @param props - Combinator node properties
150
 * @returns Combinator node
151
 */
152
function combinator(props?: NodeOptions): Combinator;
153

154
interface CombinatorRaws {
155
  value?: string;
156
  spaces?: {
157
    before?: string;
158
    after?: string;
159
  };
160
}
161
```
162

163
**Usage Examples:**
164

165
```javascript
166
// Child combinator
167
const comb1 = parser.combinator({ value: '>' });
168
// Result: >
169

170
// Adjacent sibling combinator
171
const comb2 = parser.combinator({ value: '+' });
172
// Result: +
173

174
// General sibling combinator
175
const comb3 = parser.combinator({ value: '~' });
176
// Result: ~
177

178
// Descendant combinator (space)
179
const comb4 = parser.combinator({ value: ' ' });
180
// Result: (space)
181
```
182

183
### Comment Constructor
184

185
Creates comment nodes for CSS comments within selectors.
186

187
```javascript { .api }
188
/**
189
 * Creates a new comment node
190
 * @param props - Comment node properties
191
 * @returns Comment node
192
 */
193
function comment(props?: NodeOptions): Comment;
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
// CSS comment
200
const comm = parser.comment({ value: '/* comment */' });
201
// Result: /* comment */
202
```
203

204
### ID Constructor
205

206
Creates ID selector nodes for CSS ID selectors like `#header`, `#nav-menu`.
207

208
```javascript { .api }
209
/**
210
 * Creates a new ID selector node
211
 * @param props - ID node properties
212
 * @returns Identifier node
213
 */
214
function id(props?: NamespaceOptions): Identifier;
215
```
216

217
**Usage Examples:**
218

219
```javascript
220
// Simple ID selector
221
const id1 = parser.id({ value: 'header' });
222
// Result: #header
223

224
// Namespaced ID
225
const id2 = parser.id({
226
  value: 'nav',
227
  namespace: 'main'
228
});
229
// Result: main|#nav
230
```
231

232
### Nesting Constructor
233

234
Creates nesting selector nodes for CSS nesting selectors like `&`.
235

236
```javascript { .api }
237
/**
238
 * Creates a new nesting selector node
239
 * @param props - Nesting node properties
240
 * @returns Nesting node
241
 */
242
function nesting(props?: NodeOptions): Nesting;
243
```
244

245
**Usage Examples:**
246

247
```javascript
248
// Nesting selector
249
const nest = parser.nesting({ value: '&' });
250
// Result: &
251
```
252

253
### Pseudo Constructor
254

255
Creates pseudo-class and pseudo-element nodes like `:hover`, `::before`, `:nth-child()`.
256

257
```javascript { .api }
258
/**
259
 * Creates a new pseudo selector node
260
 * @param props - Pseudo node properties
261
 * @returns Pseudo node
262
 */
263
function pseudo(props?: ContainerOptions): Pseudo;
264
```
265

266
**Usage Examples:**
267

268
```javascript
269
// Simple pseudo-class
270
const pseudo1 = parser.pseudo({ value: ':hover' });
271
// Result: :hover
272

273
// Pseudo-element
274
const pseudo2 = parser.pseudo({ value: '::before' });
275
// Result: ::before
276

277
// Functional pseudo with content
278
const pseudo3 = parser.pseudo({ 
279
  value: ':nth-child',
280
  nodes: [parser.string({ value: '2n+1' })]
281
});
282
// Result: :nth-child(2n+1)
283
```
284

285
### Root Constructor
286

287
Creates root container nodes that hold all selectors in a selector list.
288

289
```javascript { .api }
290
/**
291
 * Creates a new root container node
292
 * @param props - Root node properties
293
 * @returns Root node
294
 */
295
function root(props?: ContainerOptions): Root;
296
```
297

298
**Usage Examples:**
299

300
```javascript
301
// Empty root
302
const root1 = parser.root();
303

304
// Root with selectors
305
const root2 = parser.root({
306
  nodes: [
307
    parser.selector({ nodes: [parser.className({ value: 'btn' })] }),
308
    parser.selector({ nodes: [parser.id({ value: 'header' })] })
309
  ]
310
});
311
// Result: .btn, #header
312
```
313

314
### Root Interface
315

316
The Root class provides additional methods and properties for root container nodes.
317

318
```javascript { .api }
319
interface Root extends Container {
320
  /** Indicates if the input selector had a trailing comma */
321
  trailingComma: boolean;
322
  
323
  /** 
324
   * Create an error with better context information
325
   * @param message - Error message
326
   * @param options - Error options including word and index
327
   * @returns Error with source location context
328
   */
329
  error(message: string, options?: ErrorOptions): Error;
330
  
331
  /**
332
   * Find node at specific line and column
333
   * @param line - Line number (1-based)
334
   * @param column - Column number (1-based)
335
   * @returns Node at specified location
336
   */
337
  nodeAt(line: number, column: number): Node | undefined;
338
}
339
```
340

341
### Selector Constructor
342

343
Creates selector nodes that contain the components of individual CSS selectors.
344

345
```javascript { .api }
346
/**
347
 * Creates a new selector node
348
 * @param props - Selector node properties
349
 * @returns Selector node
350
 */
351
function selector(props?: ContainerOptions): Selector;
352
```
353

354
**Usage Examples:**
355

356
```javascript
357
// Simple selector
358
const sel1 = parser.selector({
359
  nodes: [
360
    parser.tag({ value: 'div' }),
361
    parser.className({ value: 'container' })
362
  ]
363
});
364
// Result: div.container
365

366
// Complex selector
367
const sel2 = parser.selector({
368
  nodes: [
369
    parser.id({ value: 'main' }),
370
    parser.combinator({ value: '>' }),
371
    parser.className({ value: 'content' })
372
  ]
373
});
374
// Result: #main > .content
375
```
376

377
### String Constructor
378

379
Creates string literal nodes for values within functional pseudo-selectors or other contexts.
380

381
```javascript { .api }
382
/**
383
 * Creates a new string literal node
384
 * @param props - String node properties
385
 * @returns String node
386
 */
387
function string(props?: NodeOptions): String;
388
```
389

390
**Usage Examples:**
391

392
```javascript
393
// String literal
394
const str = parser.string({ value: '2n+1' });
395
// Used in contexts like :nth-child(2n+1)
396
```
397

398
### Tag Constructor
399

400
Creates tag/element selector nodes for HTML elements like `div`, `span`, `h1`.
401

402
```javascript { .api }
403
/**
404
 * Creates a new tag selector node
405
 * @param props - Tag node properties
406
 * @returns Tag node
407
 */
408
function tag(props?: NamespaceOptions): Tag;
409
```
410

411
**Usage Examples:**
412

413
```javascript
414
// Simple tag selector
415
const tag1 = parser.tag({ value: 'div' });
416
// Result: div
417

418
// Namespaced tag
419
const tag2 = parser.tag({
420
  value: 'svg',
421
  namespace: 'http://www.w3.org/2000/svg'
422
});
423
// Result: svg (with namespace context)
424
```
425

426
### Namespace Interface
427

428
Node types that support namespaces (Tag and Attribute) provide additional namespace-related methods.
429

430
```javascript { .api }
431
interface Namespace extends Base {
432
  namespace?: string | true;
433
  
434
  /**
435
   * Get qualified name with namespace prefix
436
   * @param value - Name to qualify
437
   * @returns Qualified name with namespace
438
   */
439
  qualifiedName(value?: string): string;
440
  
441
  /** Read-only namespace string property */
442
  readonly namespaceString: string | undefined;
443
  
444
  /** Alias for namespace property */
445
  ns: string | true | undefined;
446
}
447
```
448

449
### Universal Constructor
450

451
Creates universal selector nodes for the CSS universal selector `*`.
452

453
```javascript { .api }
454
/**
455
 * Creates a new universal selector node
456
 * @param props - Universal node properties
457
 * @returns Universal node
458
 */
459
function universal(props?: NamespaceOptions): Universal;
460
```
461

462
**Usage Examples:**
463

464
```javascript
465
// Universal selector
466
const univ1 = parser.universal({ value: '*' });
467
// Result: *
468

469
// Namespaced universal
470
const univ2 = parser.universal({
471
  value: '*',
472
  namespace: 'ui'
473
});
474
// Result: ui|*
475
```
476

477
## Common Types
478

479
```javascript { .api }
480
interface NodeOptions {
481
  value?: string;
482
  spaces?: Spaces;
483
  source?: NodeSource;
484
  sourceIndex?: number;
485
}
486

487
interface ContainerOptions extends NodeOptions {
488
  nodes?: Node[];
489
}
490

491
interface NamespaceOptions extends NodeOptions {
492
  namespace?: string | true;
493
}
494

495
interface Spaces {
496
  before: string;
497
  after: string;
498
}
499

500
interface SpaceAround {
501
  before: string;
502
  after: string;
503
}
504

505
interface NodeSource {
506
  start?: { line: number; column: number };
507
  end?: { line: number; column: number };
508
}
509
```