postcss 8.4.24 → 8.4.25

package/lib/node.d.ts

@@ -1,34 +1,36 @@
-import Declaration, { DeclarationProps } from './declaration.js'
-import Comment, { CommentProps } from './comment.js'
-import { Stringifier, Syntax } from './postcss.js'
 import AtRule = require('./at-rule.js')
+
 import { AtRuleProps } from './at-rule.js'
-import Rule, { RuleProps } from './rule.js'
-import Warning, { WarningOptions } from './warning.js'
+import Comment, { CommentProps } from './comment.js'
+import Container from './container.js'
 import CssSyntaxError from './css-syntax-error.js'
-import Result from './result.js'
+import Declaration, { DeclarationProps } from './declaration.js'
+import Document from './document.js'
 import Input from './input.js'
+import { Stringifier, Syntax } from './postcss.js'
+import Result from './result.js'
 import Root from './root.js'
-import Document from './document.js'
-import Container from './container.js'
+import Rule, { RuleProps } from './rule.js'
+import Warning, { WarningOptions } from './warning.js'
 
 declare namespace Node {
-  export type ChildNode = AtRule.default | Rule | Declaration | Comment
+  export type ChildNode = AtRule.default | Comment | Declaration | Rule
 
-  export type AnyNode = AtRule.default | Rule | Declaration | Comment | Root | Document
+  export type AnyNode =
+    | AtRule.default
+    | Comment
+    | Declaration
+    | Document
+    | Root
+    | Rule
 
   export type ChildProps =
     | AtRuleProps
-    | RuleProps
-    | DeclarationProps
     | CommentProps
+    | DeclarationProps
+    | RuleProps
 
   export interface Position {
-    /**
-     * Source offset in file. It starts from 0.
-     */
-    offset: number
-
     /**
      * Source line in file. In contrast to `offset` it starts from 1.
      */
@@ -38,59 +40,75 @@ declare namespace Node {
      * Source column in file.
      */
     line: number
-  }
 
-  export interface Range {
     /**
-     * Start position, inclusive.
+     * Source offset in file. It starts from 0.
      */
-    start: Position
+    offset: number
+  }
 
+  export interface Range {
     /**
      * End position, exclusive.
      */
     end: Position
+
+    /**
+     * Start position, inclusive.
+     */
+    start: Position
   }
 
+  /**
+   * Source represents an interface for the {@link Node.source} property.
+   */
   export interface Source {
     /**
-     * The file source of the node.
+     * The inclusive ending position for the source
+     * code of a node.
      */
-    input: Input
+    end?: Position
+
     /**
-     * The inclusive starting position of the node’s source.
+     * The source file from where a node has originated.
      */
-    start?: Position
+    input: Input
+
     /**
-     * The inclusive ending position of the node's source.
+     * The inclusive starting position for the source
+     * code of a node.
      */
-    end?: Position
+    start?: Position
   }
 
+  /**
+   * Interface represents an interface for an object received
+   * as parameter by Node class constructor.
+   */
   export interface NodeProps {
     source?: Source
   }
 
   export interface NodeErrorOptions {
     /**
-     * Plugin name that created this error. PostCSS will set it automatically.
-     */
-    plugin?: string
-    /**
-     * A word inside a node's string, that should be highlighted as source
-     * of error.
+     * An ending index inside a node's string that should be highlighted as
+     * source of error.
      */
-    word?: string
+    endIndex?: number
     /**
      * An index inside a node's string that should be highlighted as source
      * of error.
      */
     index?: number
     /**
-     * An ending index inside a node's string that should be highlighted as
-     * source of error.
+     * Plugin name that created this error. PostCSS will set it automatically.
      */
-    endIndex?: number
+    plugin?: string
+    /**
+     * A word inside a node's string, that should be highlighted as source
+     * of error.
+     */
+    word?: string
   }
 
   // eslint-disable-next-line @typescript-eslint/no-shadow
@@ -99,200 +117,180 @@ declare namespace Node {
 }
 
 /**
- * All node classes inherit the following common methods.
+ * It represents an abstract class that handles common
+ * methods for other CSS abstract syntax tree nodes.
  *
- * You should not extend this classes to create AST for selector or value
- * parser.
+ * Any node that represents CSS selector or value should
+ * not extend the `Node` class.
  */
 declare abstract class Node_ {
   /**
-   * tring representing the node’s type. Possible values are `root`, `atrule`,
-   * `rule`, `decl`, or `comment`.
+   * It represents parent of the current node.
    *
    * ```js
-   * new Declaration({ prop: 'color', value: 'black' }).type //=> 'decl'
+   * console.log(root.nodes[0].parent === root) //=> true
    * ```
    */
-  type: string
+  parent: Container | Document | undefined
 
   /**
-   * The node’s parent node.
+   * It represents unnecessary whitespace and characters present
+   * in the css source code.
+   *
+   * Information to generate byte-to-byte equal node string as it was
+   * in the origin input.
+   *
+   * The properties of the raws object are decided by parser,
+   * the default parser uses the following properties:
+   *
+   * * `before`: the space symbols before the node. It also stores `*`
+   *   and `_` symbols before the declaration (IE hack).
+   * * `after`: the space symbols after the last child of the node
+   *   to the end of the node.
+   * * `between`: the symbols between the property and value
+   *   for declarations, selector and `{` for rules, or last parameter
+   *   and `{` for at-rules.
+   * * `semicolon`: contains true if the last child has
+   *   an (optional) semicolon.
+   * * `afterName`: the space between the at-rule name and its parameters.
+   * * `left`: the space symbols between `/*` and the comment’s text.
+   * * `right`: the space symbols between the comment’s text
+   *   and <code>*&#47;</code>.
+   * - `important`: the content of the important statement,
+   *   if it is not just `!important`.
+   *
+   * PostCSS filters out the comments inside selectors, declaration values
+   * and at-rule parameters but it stores the origin content in raws.
    *
    * ```js
-   * root.nodes[0].parent === root
+   * const root = postcss.parse('a {\n  color:black\n}')
+   * console.log(root.first.first.raws) //=> { before: '\n  ', between: ':' }
    * ```
    */
-  parent: Document | Container | undefined
+  raws: any
 
   /**
-   * The input source of the node.
+   * It represents information related to origin of a node and is required
+   * for generating source maps.
    *
-   * The property is used in source map generation.
+   * The nodes that are created manually using the public APIs
+   * provided by PostCSS will have `source` undefined and
+   * will be absent in the source map.
    *
-   * If you create a node manually (e.g., with `postcss.decl()`),
-   * that node will not have a `source` property and will be absent
-   * from the source map. For this reason, the plugin developer should
-   * consider cloning nodes to create new ones (in which case the new node’s
-   * source will reference the original, cloned node) or setting
-   * the `source` property manually.
+   * For this reason, the plugin developer should consider
+   * duplicating nodes as the duplicate node will have the
+   * same source as the original node by default or assign
+   * source to a node created manually.
    *
    * ```js
-   * decl.source.input.from //=> '/home/ai/a.sass'
-   * decl.source.start      //=> { line: 10, column: 2 }
-   * decl.source.end        //=> { line: 10, column: 12 }
+   * console.log(decl.source.input.from) //=> '/home/ai/source.css'
+   * console.log(decl.source.start)      //=> { line: 10, column: 2 }
+   * console.log(decl.source.end)        //=> { line: 10, column: 12 }
    * ```
    *
    * ```js
-   * // Bad
+   * // Incorrect method, source not specified!
    * const prefixed = postcss.decl({
    *   prop: '-moz-' + decl.prop,
    *   value: decl.value
    * })
    *
-   * // Good
-   * const prefixed = decl.clone({ prop: '-moz-' + decl.prop })
+   * // Correct method, source is inherited when duplicating.
+   * const prefixed = decl.clone({
+   *   prop: '-moz-' + decl.prop
+   * })
    * ```
    *
    * ```js
    * if (atrule.name === 'add-link') {
-   *   const rule = postcss.rule({ selector: 'a', source: atrule.source })
-   *   atrule.parent.insertBefore(atrule, rule)
+   *   const rule = postcss.rule({
+   *     selector: 'a',
+   *     source: atrule.source
+   *   })
+   *
+   *  atrule.parent.insertBefore(atrule, rule)
    * }
    * ```
    */
   source?: Node.Source
 
   /**
-   * Information to generate byte-to-byte equal node string as it was
-   * in the origin input.
+   * It represents type of a node in
+   * an abstract syntax tree.
    *
-   * Every parser saves its own properties,
-   * but the default CSS parser uses:
-   *
-   * * `before`: the space symbols before the node. It also stores `*`
-   *   and `_` symbols before the declaration (IE hack).
-   * * `after`: the space symbols after the last child of the node
-   *   to the end of the node.
-   * * `between`: the symbols between the property and value
-   *   for declarations, selector and `{` for rules, or last parameter
-   *   and `{` for at-rules.
-   * * `semicolon`: contains true if the last child has
-   *   an (optional) semicolon.
-   * * `afterName`: the space between the at-rule name and its parameters.
-   * * `left`: the space symbols between `/*` and the comment’s text.
-   * * `right`: the space symbols between the comment’s text
-   *   and <code>*&#47;</code>.
-   * * `important`: the content of the important statement,
-   *   if it is not just `!important`.
-   *
-   * PostCSS cleans selectors, declaration values and at-rule parameters
-   * from comments and extra spaces, but it stores origin content in raws
-   * properties. As such, if you don’t change a declaration’s value,
-   * PostCSS will use the raw value with comments.
+   * A type of node helps in identification of a node
+   * and perform operation based on it's type.
    *
    * ```js
-   * const root = postcss.parse('a {\n  color:black\n}')
-   * root.first.first.raws //=> { before: '\n  ', between: ':' }
+   * const declaration = new Declaration({
+   *   prop: 'color',
+   *   value: 'black'
+   * })
+   *
+   * console.log(declaration.type) //=> 'decl'
    * ```
    */
-  raws: any
+  type: string
 
-  /**
-   * @param defaults Value for node properties.
-   */
   constructor(defaults?: object)
 
   /**
-   * Returns a `CssSyntaxError` instance containing the original position
-   * of the node in the source, showing line and column numbers and also
-   * a small excerpt to facilitate debugging.
-   *
-   * If present, an input source map will be used to get the original position
-   * of the source, even from a previous compilation step
-   * (e.g., from Sass compilation).
+   * Insert new node after current node to current node’s parent.
    *
-   * This method produces very useful error messages.
+   * Just alias for `node.parent.insertAfter(node, add)`.
    *
    * ```js
-   * if (!variables[name]) {
-   *   throw decl.error(`Unknown variable ${name}`, { word: name })
-   *   // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
-   *   //   color: $black
-   *   // a
-   *   //          ^
-   *   //   background: white
-   * }
+   * decl.after('color: black')
    * ```
    *
-   * @param message Error description.
-   * @param opts    Options.
-   *
-   * @return Error object to throw it.
+   * @param newNode New node.
+   * @return This node for methods chain.
    */
-  error(message: string, options?: Node.NodeErrorOptions): CssSyntaxError
+  after(newNode: Node | Node.ChildProps | Node[] | string): this
 
   /**
-   * This method is provided as a convenience wrapper for `Result#warn`.
+   * It assigns properties to an existing node instance.
    *
    * ```js
-   *   Declaration: {
-   *     bad: (decl, { result }) => {
-   *       decl.warn(result, 'Deprecated property bad')
-   *     }
-   *   }
+   * decl.assign({ prop: 'word-wrap', value: 'break-word' })
    * ```
    *
-   * @param result The `Result` instance that will receive the warning.
-   * @param text   Warning message.
-   * @param opts   Warning Options.
+   * @param overrides New properties to override the node.
    *
-   * @return Created warning object.
+   * @return `this` for method chaining.
    */
-  warn(result: Result, text: string, opts?: WarningOptions): Warning
+  assign(overrides: object): this
 
   /**
-   * Removes the node from its parent and cleans the parent properties
-   * from the node and its children.
-   *
-   * ```js
-   * if (decl.prop.match(/^-webkit-/)) {
-   *   decl.remove()
-   * }
-   * ```
+   * Insert new node before current node to current node’s parent.
    *
-   * @return Node to make calls chain.
-   */
-  remove(): this
-
-  /**
-   * Returns a CSS string representing the node.
+   * Just alias for `node.parent.insertBefore(node, add)`.
    *
    * ```js
-   * new Rule({ selector: 'a' }).toString() //=> "a {}"
+   * decl.before('content: ""')
    * ```
    *
-   * @param stringifier A syntax to use in string generation.
-   * @return CSS string of this node.
+   * @param newNode New node.
+   * @return This node for methods chain.
    */
-  toString(stringifier?: Stringifier | Syntax): string
+  before(newNode: Node | Node.ChildProps | Node[] | string): this
 
   /**
-   * Assigns properties to the current node.
+   * Clear the code style properties for the node and its children.
    *
    * ```js
-   * decl.assign({ prop: 'word-wrap', value: 'break-word' })
+   * node.raws.before  //=> ' '
+   * node.cleanRaws()
+   * node.raws.before  //=> undefined
    * ```
    *
-   * @param overrides New properties to override the node.
-   * @return Current node to methods chain.
+   * @param keepBetween Keep the `raws.between` symbols.
    */
-  assign(overrides: object): this
+  cleanRaws(keepBetween?: boolean): void
 
   /**
-   * Returns an exact clone of the node.
-   *
-   * The resulting cloned node and its (cloned) children will retain
-   * code style properties.
+   * It creates clone of an existing node, which includes all the properties
+   * and their values, that includes `raws` but not `type`.
    *
    * ```js
    * decl.raws.before    //=> "\n  "
@@ -302,9 +300,19 @@ declare abstract class Node_ {
    * ```
    *
    * @param overrides New properties to override in the clone.
-   * @return Clone of the node.
+   *
+   * @return Duplicate of the node instance.
    */
-  clone(overrides?: object): this
+  clone(overrides?: object): Node_
+
+  /**
+   * Shortcut to clone the node and insert the resulting cloned node
+   * after the current node.
+   *
+   * @param overrides New properties to override in the clone.
+   * @return New node.
+   */
+  cloneAfter(overrides?: object): this
 
   /**
    * Shortcut to clone the node and insert the resulting cloned node
@@ -321,31 +329,40 @@ declare abstract class Node_ {
   cloneBefore(overrides?: object): this
 
   /**
-   * Shortcut to clone the node and insert the resulting cloned node
-   * after the current node.
+   * It creates an instance of the class `CssSyntaxError` and parameters passed
+   * to this method are assigned to the error instance.
    *
-   * @param overrides New properties to override in the clone.
-   * @return New node.
-   */
-  cloneAfter(overrides?: object): this
-
-  /**
-   * Inserts node(s) before the current node and removes the current node.
+   * The error instance will have description for the
+   * error, original position of the node in the
+   * source, showing line and column number.
+   *
+   * If any previous map is present, it would be used
+   * to get original position of the source.
+   *
+   * The Previous Map here is referred to the source map
+   * generated by previous compilation, example: Less,
+   * Stylus and Sass.
+   *
+   * This method returns the error instance instead of
+   * throwing it.
    *
    * ```js
-   * AtRule: {
-   *   mixin: atrule => {
-   *     atrule.replaceWith(mixinRules[atrule.params])
-   *   }
+   * if (!variables[name]) {
+   *   throw decl.error(`Unknown variable ${name}`, { word: name })
+   *   // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black
+   *   //   color: $black
+   *   // a
+   *   //          ^
+   *   //   background: white
    * }
    * ```
    *
-   * @param nodes Mode(s) to replace current one.
-   * @return Current node to methods chain.
+   * @param message Description for the error instance.
+   * @param options Options for the error instance.
+   *
+   * @return Error instance is returned.
    */
-  replaceWith(
-    ...nodes: (Node.ChildNode | Node.ChildProps | Node.ChildNode[] | Node.ChildProps[])[]
-  ): this
+  error(message: string, options?: Node.NodeErrorOptions): CssSyntaxError
 
   /**
    * Returns the next child of the node’s parent.
@@ -364,6 +381,22 @@ declare abstract class Node_ {
    */
   next(): Node.ChildNode | undefined
 
+  /**
+   * Get the position for a word or an index inside the node.
+   *
+   * @param opts Options.
+   * @return Position.
+   */
+  positionBy(opts?: Pick<WarningOptions, 'index' | 'word'>): Node.Position
+
+  /**
+   * Convert string index to line/column.
+   *
+   * @param index The symbol number in the node’s string.
+   * @return Symbol position in file.
+   */
+  positionInside(index: number): Node.Position
+
   /**
    * Returns the previous child of the node’s parent.
    * Returns `undefined` if the current node is the first child.
@@ -380,76 +413,82 @@ declare abstract class Node_ {
   prev(): Node.ChildNode | undefined
 
   /**
-   * Insert new node before current node to current node’s parent.
-   *
-   * Just alias for `node.parent.insertBefore(node, add)`.
-   *
-   * ```js
-   * decl.before('content: ""')
-   * ```
+   * Get the range for a word or start and end index inside the node.
+   * The start index is inclusive; the end index is exclusive.
    *
-   * @param newNode New node.
-   * @return This node for methods chain.
+   * @param opts Options.
+   * @return Range.
    */
-  before(newNode: Node | Node.ChildProps | string | Node[]): this
+  rangeBy(
+    opts?: Pick<WarningOptions, 'endIndex' | 'index' | 'word'>
+  ): Node.Range
 
   /**
-   * Insert new node after current node to current node’s parent.
-   *
-   * Just alias for `node.parent.insertAfter(node, add)`.
+   * Returns a `raws` value. If the node is missing
+   * the code style property (because the node was manually built or cloned),
+   * PostCSS will try to autodetect the code style property by looking
+   * at other nodes in the tree.
    *
    * ```js
-   * decl.after('color: black')
+   * const root = postcss.parse('a { background: white }')
+   * root.nodes[0].append({ prop: 'color', value: 'black' })
+   * root.nodes[0].nodes[1].raws.before   //=> undefined
+   * root.nodes[0].nodes[1].raw('before') //=> ' '
    * ```
    *
-   * @param newNode New node.
-   * @return This node for methods chain.
+   * @param prop        Name of code style property.
+   * @param defaultType Name of default value, it can be missed
+   *                    if the value is the same as prop.
+   * @return {string} Code style value.
    */
-  after(newNode: Node | Node.ChildProps | string | Node[]): this
+  raw(prop: string, defaultType?: string): string
 
   /**
-   * Finds the Root instance of the node’s tree.
+   * It removes the node from its parent and deletes its parent property.
    *
    * ```js
-   * root.nodes[0].nodes[0].root() === root
+   * if (decl.prop.match(/^-webkit-/)) {
+   *   decl.remove()
+   * }
    * ```
    *
-   * @return Root parent.
+   * @return `this` for method chaining.
    */
-  root(): Root
+  remove(): this
 
   /**
-   * Returns a `Node#raws` value. If the node is missing
-   * the code style property (because the node was manually built or cloned),
-   * PostCSS will try to autodetect the code style property by looking
-   * at other nodes in the tree.
+   * Inserts node(s) before the current node and removes the current node.
    *
    * ```js
-   * const root = postcss.parse('a { background: white }')
-   * root.nodes[0].append({ prop: 'color', value: 'black' })
-   * root.nodes[0].nodes[1].raws.before   //=> undefined
-   * root.nodes[0].nodes[1].raw('before') //=> ' '
+   * AtRule: {
+   *   mixin: atrule => {
+   *     atrule.replaceWith(mixinRules[atrule.params])
+   *   }
+   * }
    * ```
    *
-   * @param prop        Name of code style property.
-   * @param defaultType Name of default value, it can be missed
-   *                    if the value is the same as prop.
-   * @return {string} Code style value.
+   * @param nodes Mode(s) to replace current one.
+   * @return Current node to methods chain.
    */
-  raw(prop: string, defaultType?: string): string
+  replaceWith(
+    ...nodes: (
+      | Node.ChildNode
+      | Node.ChildNode[]
+      | Node.ChildProps
+      | Node.ChildProps[]
+    )[]
+  ): this
 
   /**
-   * Clear the code style properties for the node and its children.
+   * Finds the Root instance of the node’s tree.
    *
    * ```js
-   * node.raws.before  //=> ' '
-   * node.cleanRaws()
-   * node.raws.before  //=> undefined
+   * root.nodes[0].nodes[0].root() === root
    * ```
    *
-   * @param keepBetween Keep the `raws.between` symbols.
+   * @return Root parent.
    */
-  cleanRaws(keepBetween?: boolean): void
+  root(): Root
 
   /**
    * Fix circular links on `JSON.stringify()`.
@@ -459,31 +498,39 @@ declare abstract class Node_ {
   toJSON(): object
 
   /**
-   * Convert string index to line/column.
+   * It compiles the node to browser readable cascading style sheets string
+   * depending on it's type.
    *
-   * @param index The symbol number in the node’s string.
-   * @return Symbol position in file.
-   */
-  positionInside(index: number): Node.Position
-
-  /**
-   * Get the position for a word or an index inside the node.
+   * ```js
+   * console.log(new Rule({ selector: 'a' }).toString()) //=> "a {}"
+   * ```
    *
-   * @param opts Options.
-   * @return Position.
+   * @param stringifier A syntax to use in string generation.
+   * @return CSS string of this node.
    */
-  positionBy(opts?: Pick<WarningOptions, 'word' | 'index'>): Node.Position
+  toString(stringifier?: Stringifier | Syntax): string
 
   /**
-   * Get the range for a word or start and end index inside the node.
-   * The start index is inclusive; the end index is exclusive.
+   * It is a wrapper for {@link Result#warn}, providing convenient
+   * way of generating warnings.
    *
-   * @param opts Options.
-   * @return Range.
+   * ```js
+   *   Declaration: {
+   *     bad: (decl, { result }) => {
+   *       decl.warn(result, 'Deprecated property: bad')
+   *     }
+   *   }
+   * ```
+   *
+   * @param result The `Result` instance that will receive the warning.
+   * @param message Description for the warning.
+   * @param options Options for the warning.
+   *
+   * @return `Warning` instance is returned
    */
-  rangeBy(opts?: Pick<WarningOptions, 'word' | 'index' | 'endIndex'>): Node.Range
+  warn(result: Result, message: string, options?: WarningOptions): Warning
 }
 
-declare class Node extends Node_ {}
+declare class Node extends Node_ { }
 
 export = Node