1 | import Node, { ChildNode, NodeProps, ChildProps } from './node.js'
|
2 | import Declaration from './declaration.js'
|
3 | import Comment from './comment.js'
|
4 | import AtRule from './at-rule.js'
|
5 | import Rule from './rule.js'
|
6 |
|
7 | interface ValueOptions {
|
8 | /**
|
9 | * An array of property names.
|
10 | */
|
11 | props?: string[]
|
12 |
|
13 | /**
|
14 | * String that’s used to narrow down values and speed up the regexp search.
|
15 | */
|
16 | fast?: string
|
17 | }
|
18 |
|
19 | export interface ContainerProps extends NodeProps {
|
20 | nodes?: (ChildNode | ChildProps)[]
|
21 | }
|
22 |
|
23 | /**
|
24 | * The `Root`, `AtRule`, and `Rule` container nodes
|
25 | * inherit some common methods to help work with their children.
|
26 | *
|
27 | * Note that all containers can store any content. If you write a rule inside
|
28 | * a rule, PostCSS will parse it.
|
29 | */
|
30 | export default abstract class Container extends Node {
|
31 | /**
|
32 | * An array containing the container’s children.
|
33 | *
|
34 | * ```js
|
35 | * const root = postcss.parse('a { color: black }')
|
36 | * root.nodes.length //=> 1
|
37 | * root.nodes[0].selector //=> 'a'
|
38 | * root.nodes[0].nodes[0].prop //=> 'color'
|
39 | * ```
|
40 | */
|
41 | nodes: ChildNode[]
|
42 |
|
43 | /**
|
44 | * The container’s first child.
|
45 | *
|
46 | * ```js
|
47 | * rule.first === rules.nodes[0]
|
48 | * ```
|
49 | */
|
50 | get first (): ChildNode | undefined
|
51 |
|
52 | /**
|
53 | * The container’s last child.
|
54 | *
|
55 | * ```js
|
56 | * rule.last === rule.nodes[rule.nodes.length - 1]
|
57 | * ```
|
58 | */
|
59 | get last (): ChildNode | undefined
|
60 |
|
61 | /**
|
62 | * Iterates through the container’s immediate children,
|
63 | * calling `callback` for each child.
|
64 | *
|
65 | * Returning `false` in the callback will break iteration.
|
66 | *
|
67 | * This method only iterates through the container’s immediate children.
|
68 | * If you need to recursively iterate through all the container’s descendant
|
69 | * nodes, use `Container#walk`.
|
70 | *
|
71 | * Unlike the for `{}`-cycle or `Array#forEach` this iterator is safe
|
72 | * if you are mutating the array of child nodes during iteration.
|
73 | * PostCSS will adjust the current index to match the mutations.
|
74 | *
|
75 | * ```js
|
76 | * const root = postcss.parse('a { color: black; z-index: 1 }')
|
77 | * const rule = root.first
|
78 | *
|
79 | * for (const decl of rule.nodes) {
|
80 | * decl.cloneBefore({ prop: '-webkit-' + decl.prop })
|
81 | * // Cycle will be infinite, because cloneBefore moves the current node
|
82 | * // to the next index
|
83 | * }
|
84 | *
|
85 | * rule.each(decl => {
|
86 | * decl.cloneBefore({ prop: '-webkit-' + decl.prop })
|
87 | * // Will be executed only for color and z-index
|
88 | * })
|
89 | * ```
|
90 | *
|
91 | * @param callback Iterator receives each node and index.
|
92 | * @return Returns `false` if iteration was broke.
|
93 | */
|
94 | each (callback: (node: ChildNode, index: number) => void): void
|
95 | each (callback: (node: ChildNode, index: number) => false): false
|
96 |
|
97 | /**
|
98 | * Traverses the container’s descendant nodes, calling callback
|
99 | * for each node.
|
100 | *
|
101 | * Like container.each(), this method is safe to use
|
102 | * if you are mutating arrays during iteration.
|
103 | *
|
104 | * If you only need to iterate through the container’s immediate children,
|
105 | * use `Container#each`.
|
106 | *
|
107 | * ```js
|
108 | * root.walk(node => {
|
109 | * // Traverses all descendant nodes.
|
110 | * })
|
111 | * ```
|
112 | *
|
113 | * @param callback Iterator receives each node and index.
|
114 | * @return Returns `false` if iteration was broke.
|
115 | */
|
116 | walk (callback: (node: ChildNode, index: number) => void): void
|
117 | walk (callback: (node: ChildNode, index: number) => false): false
|
118 |
|
119 | /**
|
120 | * Traverses the container’s descendant nodes, calling callback
|
121 | * for each declaration node.
|
122 | *
|
123 | * If you pass a filter, iteration will only happen over declarations
|
124 | * with matching properties.
|
125 | *
|
126 | * ```js
|
127 | * root.walkDecls(decl => {
|
128 | * checkPropertySupport(decl.prop)
|
129 | * })
|
130 | *
|
131 | * root.walkDecls('border-radius', decl => {
|
132 | * decl.remove()
|
133 | * })
|
134 | *
|
135 | * root.walkDecls(/^background/, decl => {
|
136 | * decl.value = takeFirstColorFromGradient(decl.value)
|
137 | * })
|
138 | * ```
|
139 | *
|
140 | * Like `Container#each`, this method is safe
|
141 | * to use if you are mutating arrays during iteration.
|
142 | *
|
143 | * @param prop String or regular expression to filter declarations
|
144 | * by property name.
|
145 | * @param callback Iterator receives each node and index.
|
146 | * @return Returns `false` if iteration was broke.
|
147 | */
|
148 | walkDecls (
|
149 | propFilter: string | RegExp,
|
150 | callback: (decl: Declaration, index: number) => void
|
151 | ): void
|
152 | walkDecls (callback: (decl: Declaration, index: number) => void): void
|
153 | walkDecls (
|
154 | propFilter: string | RegExp,
|
155 | callback: (decl: Declaration, index: number) => false
|
156 | ): false
|
157 | walkDecls (callback: (decl: Declaration, index: number) => false): false
|
158 |
|
159 | /**
|
160 | * Traverses the container’s descendant nodes, calling callback
|
161 | * for each rule node.
|
162 | *
|
163 | * If you pass a filter, iteration will only happen over rules
|
164 | * with matching selectors.
|
165 | *
|
166 | * Like `Container#each`, this method is safe
|
167 | * to use if you are mutating arrays during iteration.
|
168 | *
|
169 | * ```js
|
170 | * const selectors = []
|
171 | * root.walkRules(rule => {
|
172 | * selectors.push(rule.selector)
|
173 | * })
|
174 | * console.log(`Your CSS uses ${ selectors.length } selectors`)
|
175 | * ```
|
176 | *
|
177 | * @param selector String or regular expression to filter rules by selector.
|
178 | * @param callback Iterator receives each node and index.
|
179 | * @return Returns `false` if iteration was broke.
|
180 | */
|
181 | walkRules (
|
182 | selectorFilter: string | RegExp,
|
183 | callback: (atRule: Rule, index: number) => void
|
184 | ): void
|
185 | walkRules (callback: (atRule: Rule, index: number) => void): void
|
186 | walkRules (
|
187 | selectorFilter: string | RegExp,
|
188 | callback: (atRule: Rule, index: number) => false
|
189 | ): false
|
190 | walkRules (callback: (atRule: Rule, index: number) => false): false
|
191 |
|
192 | /**
|
193 | * Traverses the container’s descendant nodes, calling callback
|
194 | * for each at-rule node.
|
195 | *
|
196 | * If you pass a filter, iteration will only happen over at-rules
|
197 | * that have matching names.
|
198 | *
|
199 | * Like `Container#each`, this method is safe
|
200 | * to use if you are mutating arrays during iteration.
|
201 | *
|
202 | * ```js
|
203 | * root.walkAtRules(rule => {
|
204 | * if (isOld(rule.name)) rule.remove()
|
205 | * })
|
206 | *
|
207 | * let first = false
|
208 | * root.walkAtRules('charset', rule => {
|
209 | * if (!first) {
|
210 | * first = true
|
211 | * } else {
|
212 | * rule.remove()
|
213 | * }
|
214 | * })
|
215 | * ```
|
216 | *
|
217 | * @param name String or regular expression to filter at-rules by name.
|
218 | * @param callback Iterator receives each node and index.
|
219 | * @return Returns `false` if iteration was broke.
|
220 | */
|
221 | walkAtRules (
|
222 | nameFilter: string | RegExp,
|
223 | callback: (atRule: AtRule, index: number) => void
|
224 | ): void
|
225 | walkAtRules (callback: (atRule: AtRule, index: number) => void): void
|
226 | walkAtRules (
|
227 | nameFilter: string | RegExp,
|
228 | callback: (atRule: AtRule, index: number) => false
|
229 | ): false
|
230 | walkAtRules (callback: (atRule: AtRule, index: number) => false): false
|
231 |
|
232 | /**
|
233 | * Traverses the container’s descendant nodes, calling callback
|
234 | * for each comment node.
|
235 | *
|
236 | * Like `Container#each`, this method is safe
|
237 | * to use if you are mutating arrays during iteration.
|
238 | *
|
239 | * ```js
|
240 | * root.walkComments(comment => {
|
241 | * comment.remove()
|
242 | * })
|
243 | * ```
|
244 | *
|
245 | * @param callback Iterator receives each node and index.
|
246 | * @return Returns `false` if iteration was broke.
|
247 | */
|
248 |
|
249 | walkComments (callback: (comment: Comment, indexed: number) => void): void
|
250 | walkComments (
|
251 | callback: (comment: Comment, indexed: number) => boolean
|
252 | ): boolean
|
253 |
|
254 | /**
|
255 | * Inserts new nodes to the end of the container.
|
256 | *
|
257 | * ```js
|
258 | * const decl1 = new Declaration({ prop: 'color', value: 'black' })
|
259 | * const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
|
260 | * rule.append(decl1, decl2)
|
261 | *
|
262 | * root.append({ name: 'charset', params: '"UTF-8"' }) // at-rule
|
263 | * root.append({ selector: 'a' }) // rule
|
264 | * rule.append({ prop: 'color', value: 'black' }) // declaration
|
265 | * rule.append({ text: 'Comment' }) // comment
|
266 | *
|
267 | * root.append('a {}')
|
268 | * root.first.append('color: black; z-index: 1')
|
269 | * ```
|
270 | *
|
271 | * @param nodes New nodes.
|
272 | * @return This node for methods chain.
|
273 | */
|
274 | append (
|
275 | ...nodes: (Node | Node[] | ChildProps | ChildProps[] | string | string[])[]
|
276 | ): this
|
277 |
|
278 | /**
|
279 | * Inserts new nodes to the start of the container.
|
280 | *
|
281 | * ```js
|
282 | * const decl1 = new Declaration({ prop: 'color', value: 'black' })
|
283 | * const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
|
284 | * rule.prepend(decl1, decl2)
|
285 | *
|
286 | * root.append({ name: 'charset', params: '"UTF-8"' }) // at-rule
|
287 | * root.append({ selector: 'a' }) // rule
|
288 | * rule.append({ prop: 'color', value: 'black' }) // declaration
|
289 | * rule.append({ text: 'Comment' }) // comment
|
290 | *
|
291 | * root.append('a {}')
|
292 | * root.first.append('color: black; z-index: 1')
|
293 | * ```
|
294 | *
|
295 | * @param nodes New nodes.
|
296 | * @return This node for methods chain.
|
297 | */
|
298 | prepend (
|
299 | ...nodes: (Node | Node[] | ChildProps | ChildProps[] | string | string[])[]
|
300 | ): this
|
301 |
|
302 | /**
|
303 | * Add child to the end of the node.
|
304 | *
|
305 | * ```js
|
306 | * rule.push(new Declaration({ prop: 'color', value: 'black' }}))
|
307 | * ```
|
308 | *
|
309 | * @param child New node.
|
310 | * @return This node for methods chain.
|
311 | */
|
312 | push (child: ChildNode): this
|
313 |
|
314 | /**
|
315 | * Insert new node before old node within the container.
|
316 | *
|
317 | * ```js
|
318 | * rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))
|
319 | * ```
|
320 | *
|
321 | * @param oldNode Child or child’s index.
|
322 | * @param newNode New node.
|
323 | * @return This node for methods chain.
|
324 | */
|
325 | insertBefore (
|
326 | oldNode: ChildNode | number,
|
327 | newNode:
|
328 | | ChildNode
|
329 | | ChildProps
|
330 | | string
|
331 | | ChildNode[]
|
332 | | ChildProps[]
|
333 | | string[]
|
334 | ): this
|
335 |
|
336 | /**
|
337 | * Insert new node after old node within the container.
|
338 | *
|
339 | * @param oldNode Child or child’s index.
|
340 | * @param newNode New node.
|
341 | * @return This node for methods chain.
|
342 | */
|
343 | insertAfter (
|
344 | oldNode: ChildNode | number,
|
345 | newNode:
|
346 | | ChildNode
|
347 | | ChildProps
|
348 | | string
|
349 | | ChildNode[]
|
350 | | ChildProps[]
|
351 | | string[]
|
352 | ): this
|
353 |
|
354 | /**
|
355 | * Removes node from the container and cleans the parent properties
|
356 | * from the node and its children.
|
357 | *
|
358 | * ```js
|
359 | * rule.nodes.length //=> 5
|
360 | * rule.removeChild(decl)
|
361 | * rule.nodes.length //=> 4
|
362 | * decl.parent //=> undefined
|
363 | * ```
|
364 | *
|
365 | * @param child Child or child’s index.
|
366 | * @return This node for methods chain.
|
367 | */
|
368 | removeChild (child: ChildNode | number): this
|
369 |
|
370 | /**
|
371 | * Removes all children from the container
|
372 | * and cleans their parent properties.
|
373 | *
|
374 | * ```js
|
375 | * rule.removeAll()
|
376 | * rule.nodes.length //=> 0
|
377 | * ```
|
378 | *
|
379 | * @return This node for methods chain.
|
380 | */
|
381 | removeAll (): this
|
382 |
|
383 | /**
|
384 | * Passes all declaration values within the container that match pattern
|
385 | * through callback, replacing those values with the returned result
|
386 | * of callback.
|
387 | *
|
388 | * This method is useful if you are using a custom unit or function
|
389 | * and need to iterate through all values.
|
390 | *
|
391 | * ```js
|
392 | * root.replaceValues(/\d+rem/, { fast: 'rem' }, string => {
|
393 | * return 15 * parseInt(string) + 'px'
|
394 | * })
|
395 | * ```
|
396 | *
|
397 | * @param pattern Replace pattern.
|
398 | * @param {object} opts Options to speed up the search.
|
399 | * @param callback String to replace pattern or callback
|
400 | * that returns a new value. The callback
|
401 | * will receive the same arguments
|
402 | * as those passed to a function parameter
|
403 | * of `String#replace`.
|
404 | * @return This node for methods chain.
|
405 | */
|
406 | replaceValues (
|
407 | pattern: string | RegExp,
|
408 | options: ValueOptions,
|
409 | replaced: string | { (substring: string, ...args: any[]): string }
|
410 | ): this
|
411 | replaceValues (
|
412 | pattern: string | RegExp,
|
413 | replaced: string | { (substring: string, ...args: any[]): string }
|
414 | ): this
|
415 |
|
416 | /**
|
417 | * Returns `true` if callback returns `true`
|
418 | * for all of the container’s children.
|
419 | *
|
420 | * ```js
|
421 | * const noPrefixes = rule.every(i => i.prop[0] !== '-')
|
422 | * ```
|
423 | *
|
424 | * @param condition Iterator returns true or false.
|
425 | * @return Is every child pass condition.
|
426 | */
|
427 | every (
|
428 | condition: (node: ChildNode, index: number, nodes: ChildNode[]) => boolean
|
429 | ): boolean
|
430 |
|
431 | /**
|
432 | * Returns `true` if callback returns `true` for (at least) one
|
433 | * of the container’s children.
|
434 | *
|
435 | * ```js
|
436 | * const hasPrefix = rule.some(i => i.prop[0] === '-')
|
437 | * ```
|
438 | *
|
439 | * @param condition Iterator returns true or false.
|
440 | * @return Is some child pass condition.
|
441 | */
|
442 | some (
|
443 | condition: (node: ChildNode, index: number, nodes: ChildNode[]) => boolean
|
444 | ): boolean
|
445 |
|
446 | /**
|
447 | * Returns a `child`’s index within the `Container#nodes` array.
|
448 | *
|
449 | * ```js
|
450 | * rule.index( rule.nodes[2] ) //=> 2
|
451 | * ```
|
452 | *
|
453 | * @param child Child of the current container.
|
454 | * @return Child index.
|
455 | */
|
456 | index (child: ChildNode | number): number
|
457 | }
|