postcss 8.4.23 → 8.4.25

package/lib/container.d.ts

@@ -1,20 +1,20 @@
-import Node, { ChildNode, NodeProps, ChildProps } from './node.js'
-import Declaration from './declaration.js'
-import Comment from './comment.js'
 import AtRule from './at-rule.js'
+import Comment from './comment.js'
+import Declaration from './declaration.js'
+import Node, { ChildNode, ChildProps, NodeProps } from './node.js'
 import Rule from './rule.js'
 
 declare namespace Container {
   export interface ValueOptions {
     /**
-     * An array of property names.
+     * String that’s used to narrow down values and speed up the regexp search.
      */
-    props?: string[]
+    fast?: string
 
     /**
-     * String that’s used to narrow down values and speed up the regexp search.
+     * An array of property names.
      */
-    fast?: string
+    props?: string[]
   }
 
   export interface ContainerProps extends NodeProps {
@@ -48,22 +48,28 @@ declare abstract class Container_<
   nodes: Child[]
 
   /**
-   * The container’s first child.
+   * Inserts new nodes to the end of the container.
    *
    * ```js
-   * rule.first === rules.nodes[0]
-   * ```
-   */
-  get first(): Child | undefined
-
-  /**
-   * The container’s last child.
+   * const decl1 = new Declaration({ prop: 'color', value: 'black' })
+   * const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
+   * rule.append(decl1, decl2)
    *
-   * ```js
-   * rule.last === rule.nodes[rule.nodes.length - 1]
+   * root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
+   * root.append({ selector: 'a' })                       // rule
+   * rule.append({ prop: 'color', value: 'black' })       // declaration
+   * rule.append({ text: 'Comment' })                     // comment
+   *
+   * root.append('a {}')
+   * root.first.append('color: black; z-index: 1')
    * ```
+   *
+   * @param nodes New nodes.
+   * @return This node for methods chain.
    */
-  get last(): Child | undefined
+  append(
+    ...nodes: (ChildProps | ChildProps[] | Node | Node[] | string | string[])[]
+  ): this
 
   /**
    * Iterates through the container’s immediate children,
@@ -103,179 +109,75 @@ declare abstract class Container_<
   ): false | undefined
 
   /**
-   * Traverses the container’s descendant nodes, calling callback
-   * for each node.
-   *
-   * Like container.each(), this method is safe to use
-   * if you are mutating arrays during iteration.
-   *
-   * If you only need to iterate through the container’s immediate children,
-   * use `Container#each`.
+   * Returns `true` if callback returns `true`
+   * for all of the container’s children.
    *
    * ```js
-   * root.walk(node => {
-   *   // Traverses all descendant nodes.
-   * })
+   * const noPrefixes = rule.every(i => i.prop[0] !== '-')
    * ```
    *
-   * @param callback Iterator receives each node and index.
-   * @return  Returns `false` if iteration was broke.
+   * @param condition Iterator returns true or false.
+   * @return Is every child pass condition.
    */
-  walk(
-    callback: (node: ChildNode, index: number) => false | void
-  ): false | undefined
+  every(
+    condition: (node: Child, index: number, nodes: Child[]) => boolean
+  ): boolean
 
   /**
-   * Traverses the container’s descendant nodes, calling callback
-   * for each declaration node.
-   *
-   * If you pass a filter, iteration will only happen over declarations
-   * with matching properties.
+   * The container’s first child.
    *
    * ```js
-   * root.walkDecls(decl => {
-   *   checkPropertySupport(decl.prop)
-   * })
-   *
-   * root.walkDecls('border-radius', decl => {
-   *   decl.remove()
-   * })
-   *
-   * root.walkDecls(/^background/, decl => {
-   *   decl.value = takeFirstColorFromGradient(decl.value)
-   * })
+   * rule.first === rules.nodes[0]
    * ```
-   *
-   * Like `Container#each`, this method is safe
-   * to use if you are mutating arrays during iteration.
-   *
-   * @param prop     String or regular expression to filter declarations
-   *                 by property name.
-   * @param callback Iterator receives each node and index.
-   * @return Returns `false` if iteration was broke.
    */
-  walkDecls(
-    propFilter: string | RegExp,
-    callback: (decl: Declaration, index: number) => false | void
-  ): false | undefined
-  walkDecls(
-    callback: (decl: Declaration, index: number) => false | void
-  ): false | undefined
+  get first(): Child | undefined
 
   /**
-   * Traverses the container’s descendant nodes, calling callback
-   * for each rule node.
-   *
-   * If you pass a filter, iteration will only happen over rules
-   * with matching selectors.
-   *
-   * Like `Container#each`, this method is safe
-   * to use if you are mutating arrays during iteration.
+   * Returns a `child`’s index within the `Container#nodes` array.
    *
    * ```js
-   * const selectors = []
-   * root.walkRules(rule => {
-   *   selectors.push(rule.selector)
-   * })
-   * console.log(`Your CSS uses ${ selectors.length } selectors`)
+   * rule.index( rule.nodes[2] ) //=> 2
    * ```
    *
-   * @param selector String or regular expression to filter rules by selector.
-   * @param callback Iterator receives each node and index.
-   * @return Returns `false` if iteration was broke.
+   * @param child Child of the current container.
+   * @return Child index.
    */
-  walkRules(
-    selectorFilter: string | RegExp,
-    callback: (rule: Rule, index: number) => false | void
-  ): false | undefined
-  walkRules(
-    callback: (rule: Rule, index: number) => false | void
-  ): false | undefined
-
+  index(child: Child | number): number
   /**
-   * Traverses the container’s descendant nodes, calling callback
-   * for each at-rule node.
-   *
-   * If you pass a filter, iteration will only happen over at-rules
-   * that have matching names.
-   *
-   * Like `Container#each`, this method is safe
-   * to use if you are mutating arrays during iteration.
-   *
-   * ```js
-   * root.walkAtRules(rule => {
-   *   if (isOld(rule.name)) rule.remove()
-   * })
-   *
-   * let first = false
-   * root.walkAtRules('charset', rule => {
-   *   if (!first) {
-   *     first = true
-   *   } else {
-   *     rule.remove()
-   *   }
-   * })
-   * ```
+   * Insert new node after old node within the container.
    *
-   * @param name     String or regular expression to filter at-rules by name.
-   * @param callback Iterator receives each node and index.
-   * @return Returns `false` if iteration was broke.
+   * @param oldNode Child or child’s index.
+   * @param newNode New node.
+   * @return This node for methods chain.
    */
-  walkAtRules(
-    nameFilter: string | RegExp,
-    callback: (atRule: AtRule, index: number) => false | void
-  ): false | undefined
-  walkAtRules(
-    callback: (atRule: AtRule, index: number) => false | void
-  ): false | undefined
+  insertAfter(
+    oldNode: Child | number,
+    newNode: Child | Child[] | ChildProps | ChildProps[] | string | string[]
+  ): this
 
   /**
-   * Traverses the container’s descendant nodes, calling callback
-   * for each comment node.
-   *
-   * Like `Container#each`, this method is safe
-   * to use if you are mutating arrays during iteration.
+   * Insert new node before old node within the container.
    *
    * ```js
-   * root.walkComments(comment => {
-   *   comment.remove()
-   * })
+   * rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))
    * ```
    *
-   * @param callback Iterator receives each node and index.
-   * @return Returns `false` if iteration was broke.
+   * @param oldNode Child or child’s index.
+   * @param newNode New node.
+   * @return This node for methods chain.
    */
-
-  walkComments(
-    callback: (comment: Comment, indexed: number) => false | void
-  ): false | undefined
-  walkComments(
-    callback: (comment: Comment, indexed: number) => false | void
-  ): false | undefined
-
+  insertBefore(
+    oldNode: Child | number,
+    newNode: Child | Child[] | ChildProps | ChildProps[] | string | string[]
+  ): this
   /**
-   * Inserts new nodes to the end of the container.
+   * The container’s last child.
    *
    * ```js
-   * const decl1 = new Declaration({ prop: 'color', value: 'black' })
-   * const decl2 = new Declaration({ prop: 'background-color', value: 'white' })
-   * rule.append(decl1, decl2)
-   *
-   * root.append({ name: 'charset', params: '"UTF-8"' })  // at-rule
-   * root.append({ selector: 'a' })                       // rule
-   * rule.append({ prop: 'color', value: 'black' })       // declaration
-   * rule.append({ text: 'Comment' })                     // comment
-   *
-   * root.append('a {}')
-   * root.first.append('color: black; z-index: 1')
+   * rule.last === rule.nodes[rule.nodes.length - 1]
    * ```
-   *
-   * @param nodes New nodes.
-   * @return This node for methods chain.
    */
-  append(
-    ...nodes: (Node | Node[] | ChildProps | ChildProps[] | string | string[])[]
-  ): this
+  get last(): Child | undefined
 
   /**
    * Inserts new nodes to the start of the container.
@@ -298,9 +200,8 @@ declare abstract class Container_<
    * @return This node for methods chain.
    */
   prepend(
-    ...nodes: (Node | Node[] | ChildProps | ChildProps[] | string | string[])[]
+    ...nodes: (ChildProps | ChildProps[] | Node | Node[] | string | string[])[]
   ): this
-
   /**
    * Add child to the end of the node.
    *
@@ -314,33 +215,34 @@ declare abstract class Container_<
   push(child: Child): this
 
   /**
-   * Insert new node before old node within the container.
+   * Traverses the container’s descendant nodes, calling callback
+   * for each comment node.
+   *
+   * Like `Container#each`, this method is safe
+   * to use if you are mutating arrays during iteration.
    *
    * ```js
-   * rule.insertBefore(decl, decl.clone({ prop: '-webkit-' + decl.prop }))
+   * root.walkComments(comment => {
+   *   comment.remove()
+   * })
    * ```
    *
-   * @param oldNode Child or child’s index.
-   * @param newNode New node.
-   * @return This node for methods chain.
+   * @param callback Iterator receives each node and index.
+   * @return Returns `false` if iteration was broke.
    */
-  insertBefore(
-    oldNode: Child | number,
-    newNode: Child | ChildProps | string | Child[] | ChildProps[] | string[]
-  ): this
 
   /**
-   * Insert new node after old node within the container.
+   * Removes all children from the container
+   * and cleans their parent properties.
+   *
+   * ```js
+   * rule.removeAll()
+   * rule.nodes.length //=> 0
+   * ```
    *
-   * @param oldNode Child or child’s index.
-   * @param newNode New node.
    * @return This node for methods chain.
    */
-  insertAfter(
-    oldNode: Child | number,
-    newNode: Child | ChildProps | string | Child[] | ChildProps[] | string[]
-  ): this
-
+  removeAll(): this
   /**
    * Removes node from the container and cleans the parent properties
    * from the node and its children.
@@ -357,19 +259,6 @@ declare abstract class Container_<
    */
   removeChild(child: Child | number): this
 
-  /**
-   * Removes all children from the container
-   * and cleans their parent properties.
-   *
-   * ```js
-   * rule.removeAll()
-   * rule.nodes.length //=> 0
-   * ```
-   *
-   * @return This node for methods chain.
-   */
-  removeAll(): this
-
   /**
    * Passes all declaration values within the container that match pattern
    * through callback, replacing those values with the returned result
@@ -394,56 +283,167 @@ declare abstract class Container_<
    * @return This node for methods chain.
    */
   replaceValues(
-    pattern: string | RegExp,
+    pattern: RegExp | string,
     options: Container.ValueOptions,
-    replaced: string | { (substring: string, ...args: any[]): string }
+    replaced: { (substring: string, ...args: any[]): string } | string
   ): this
+
   replaceValues(
-    pattern: string | RegExp,
-    replaced: string | { (substring: string, ...args: any[]): string }
+    pattern: RegExp | string,
+    replaced: { (substring: string, ...args: any[]): string } | string
   ): this
 
   /**
-   * Returns `true` if callback returns `true`
-   * for all of the container’s children.
+   * Returns `true` if callback returns `true` for (at least) one
+   * of the container’s children.
    *
    * ```js
-   * const noPrefixes = rule.every(i => i.prop[0] !== '-')
+   * const hasPrefix = rule.some(i => i.prop[0] === '-')
    * ```
    *
    * @param condition Iterator returns true or false.
-   * @return Is every child pass condition.
+   * @return Is some child pass condition.
    */
-  every(
+  some(
     condition: (node: Child, index: number, nodes: Child[]) => boolean
   ): boolean
 
   /**
-   * Returns `true` if callback returns `true` for (at least) one
-   * of the container’s children.
+   * Traverses the container’s descendant nodes, calling callback
+   * for each node.
+   *
+   * Like container.each(), this method is safe to use
+   * if you are mutating arrays during iteration.
+   *
+   * If you only need to iterate through the container’s immediate children,
+   * use `Container#each`.
    *
    * ```js
-   * const hasPrefix = rule.some(i => i.prop[0] === '-')
+   * root.walk(node => {
+   *   // Traverses all descendant nodes.
+   * })
    * ```
    *
-   * @param condition Iterator returns true or false.
-   * @return Is some child pass condition.
+   * @param callback Iterator receives each node and index.
+   * @return  Returns `false` if iteration was broke.
    */
-  some(
-    condition: (node: Child, index: number, nodes: Child[]) => boolean
-  ): boolean
+  walk(
+    callback: (node: ChildNode, index: number) => false | void
+  ): false | undefined
+
+  walkAtRules(
+    callback: (atRule: AtRule, index: number) => false | void
+  ): false | undefined
 
   /**
-   * Returns a `child`’s index within the `Container#nodes` array.
+   * Traverses the container’s descendant nodes, calling callback
+   * for each at-rule node.
+   *
+   * If you pass a filter, iteration will only happen over at-rules
+   * that have matching names.
+   *
+   * Like `Container#each`, this method is safe
+   * to use if you are mutating arrays during iteration.
    *
    * ```js
-   * rule.index( rule.nodes[2] ) //=> 2
+   * root.walkAtRules(rule => {
+   *   if (isOld(rule.name)) rule.remove()
+   * })
+   *
+   * let first = false
+   * root.walkAtRules('charset', rule => {
+   *   if (!first) {
+   *     first = true
+   *   } else {
+   *     rule.remove()
+   *   }
+   * })
    * ```
    *
-   * @param child Child of the current container.
-   * @return Child index.
+   * @param name     String or regular expression to filter at-rules by name.
+   * @param callback Iterator receives each node and index.
+   * @return Returns `false` if iteration was broke.
    */
-  index(child: Child | number): number
+  walkAtRules(
+    nameFilter: RegExp | string,
+    callback: (atRule: AtRule, index: number) => false | void
+  ): false | undefined
+
+  walkComments(
+    callback: (comment: Comment, indexed: number) => false | void
+  ): false | undefined
+
+  walkComments(
+    callback: (comment: Comment, indexed: number) => false | void
+  ): false | undefined
+  walkDecls(
+    callback: (decl: Declaration, index: number) => false | void
+  ): false | undefined
+
+  /**
+   * Traverses the container’s descendant nodes, calling callback
+   * for each declaration node.
+   *
+   * If you pass a filter, iteration will only happen over declarations
+   * with matching properties.
+   *
+   * ```js
+   * root.walkDecls(decl => {
+   *   checkPropertySupport(decl.prop)
+   * })
+   *
+   * root.walkDecls('border-radius', decl => {
+   *   decl.remove()
+   * })
+   *
+   * root.walkDecls(/^background/, decl => {
+   *   decl.value = takeFirstColorFromGradient(decl.value)
+   * })
+   * ```
+   *
+   * Like `Container#each`, this method is safe
+   * to use if you are mutating arrays during iteration.
+   *
+   * @param prop     String or regular expression to filter declarations
+   *                 by property name.
+   * @param callback Iterator receives each node and index.
+   * @return Returns `false` if iteration was broke.
+   */
+  walkDecls(
+    propFilter: RegExp | string,
+    callback: (decl: Declaration, index: number) => false | void
+  ): false | undefined
+
+  walkRules(
+    callback: (rule: Rule, index: number) => false | void
+  ): false | undefined
+
+  /**
+   * Traverses the container’s descendant nodes, calling callback
+   * for each rule node.
+   *
+   * If you pass a filter, iteration will only happen over rules
+   * with matching selectors.
+   *
+   * Like `Container#each`, this method is safe
+   * to use if you are mutating arrays during iteration.
+   *
+   * ```js
+   * const selectors = []
+   * root.walkRules(rule => {
+   *   selectors.push(rule.selector)
+   * })
+   * console.log(`Your CSS uses ${ selectors.length } selectors`)
+   * ```
+   *
+   * @param selector String or regular expression to filter rules by selector.
+   * @param callback Iterator receives each node and index.
+   * @return Returns `false` if iteration was broke.
+   */
+  walkRules(
+    selectorFilter: RegExp | string,
+    callback: (rule: Rule, index: number) => false | void
+  ): false | undefined
 }
 
 declare class Container<Child extends Node = ChildNode> extends Container_<Child> {}