postcss 8.4.24 → 8.4.25

package/lib/css-syntax-error.d.ts

@@ -6,14 +6,14 @@ declare namespace CssSyntaxError {
    */
   export interface RangePosition {
     /**
-     * The line number in the input.
+     * The column number in the input.
      */
-    line: number
+    column: number
 
     /**
-     * The column number in the input.
+     * The line number in the input.
      */
-    column: number
+    line: number
   }
 
   // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -51,60 +51,45 @@ declare namespace CssSyntaxError {
  */
 declare class CssSyntaxError_ {
   /**
-   * Instantiates a CSS syntax error. Can be instantiated for a single position
-   * or for a range.
-   * @param message        Error message.
-   * @param lineOrStartPos If for a single position, the line number, or if for
-   *                       a range, the inclusive start position of the error.
-   * @param columnOrEndPos If for a single position, the column number, or if for
-   *                       a range, the exclusive end position of the error.
-   * @param source         Source code of the broken file.
-   * @param file           Absolute path to the broken file.
-   * @param plugin         PostCSS plugin name, if error came from plugin.
-   */
-  constructor(
-    message: string,
-    lineOrStartPos?: number | CssSyntaxError.RangePosition,
-    columnOrEndPos?: number | CssSyntaxError.RangePosition,
-    source?: string,
-    file?: string,
-    plugin?: string
-  )
-
-  stack: string
-
-  /**
-   * Always equal to `'CssSyntaxError'`. You should always check error type
-   * by `error.name === 'CssSyntaxError'`
-   * instead of `error instanceof CssSyntaxError`,
-   * because npm could have several PostCSS versions.
+   * Source column of the error.
    *
    * ```js
-   * if (error.name === 'CssSyntaxError') {
-   *   error //=> CssSyntaxError
-   * }
+   * error.column       //=> 1
+   * error.input.column //=> 4
    * ```
+   *
+   * PostCSS will use the input source map to detect the original location.
+   * If you need the position in the PostCSS input, use `error.input.column`.
    */
-  name: 'CssSyntaxError'
+  column?: number
 
   /**
-   * Error message.
+   * Source column of the error's end, exclusive. Provided if the error pertains
+   * to a range.
    *
    * ```js
-   * error.message //=> 'Unclosed block'
+   * error.endColumn       //=> 1
+   * error.input.endColumn //=> 4
    * ```
+   *
+   * PostCSS will use the input source map to detect the original location.
+   * If you need the position in the PostCSS input, use `error.input.endColumn`.
    */
-  reason: string
+  endColumn?: number
 
   /**
-   * Full error text in the GNU error format
-   * with plugin, file, line and column.
+   * Source line of the error's end, exclusive. Provided if the error pertains
+   * to a range.
    *
    * ```js
-   * error.message //=> 'a.css:1:1: Unclosed block'
+   * error.endLine       //=> 3
+   * error.input.endLine //=> 4
    * ```
+   *
+   * PostCSS will use the input source map to detect the original location.
+   * If you need the position in the PostCSS input, use `error.input.endLine`.
    */
-  message: string
+  endLine?: number
 
   /**
    * Absolute path to the broken file.
@@ -120,68 +105,55 @@ declare class CssSyntaxError_ {
   file?: string
 
   /**
-   * Source line of the error.
-   *
-   * ```js
-   * error.line       //=> 2
-   * error.input.line //=> 4
-   * ```
-   *
-   * PostCSS will use the input source map to detect the original location.
-   * If you need the position in the PostCSS input, use `error.input.line`.
-   */
-  line?: number
-
-  /**
-   * Source column of the error.
+   * Input object with PostCSS internal information
+   * about input file. If input has source map
+   * from previous tool, PostCSS will use origin
+   * (for example, Sass) source. You can use this
+   * object to get PostCSS input source.
    *
    * ```js
-   * error.column       //=> 1
-   * error.input.column //=> 4
+   * error.input.file //=> 'a.css'
+   * error.file       //=> 'a.sass'
    * ```
-   *
-   * PostCSS will use the input source map to detect the original location.
-   * If you need the position in the PostCSS input, use `error.input.column`.
    */
-  column?: number
+  input?: FilePosition
 
   /**
-   * Source line of the error's end, exclusive. Provided if the error pertains
-   * to a range.
+   * Source line of the error.
    *
    * ```js
-   * error.endLine       //=> 3
-   * error.input.endLine //=> 4
+   * error.line       //=> 2
+   * error.input.line //=> 4
    * ```
    *
    * PostCSS will use the input source map to detect the original location.
-   * If you need the position in the PostCSS input, use `error.input.endLine`.
+   * If you need the position in the PostCSS input, use `error.input.line`.
    */
-  endLine?: number
+  line?: number
 
   /**
-   * Source column of the error's end, exclusive. Provided if the error pertains
-   * to a range.
+   * Full error text in the GNU error format
+   * with plugin, file, line and column.
    *
    * ```js
-   * error.endColumn       //=> 1
-   * error.input.endColumn //=> 4
+   * error.message //=> 'a.css:1:1: Unclosed block'
    * ```
-   *
-   * PostCSS will use the input source map to detect the original location.
-   * If you need the position in the PostCSS input, use `error.input.endColumn`.
    */
-  endColumn?: number
+  message: string
 
   /**
-   * Source code of the broken file.
+   * Always equal to `'CssSyntaxError'`. You should always check error type
+   * by `error.name === 'CssSyntaxError'`
+   * instead of `error instanceof CssSyntaxError`,
+   * because npm could have several PostCSS versions.
    *
    * ```js
-   * error.source       //=> 'a { b {} }'
-   * error.input.source //=> 'a b { }'
+   * if (error.name === 'CssSyntaxError') {
+   *   error //=> CssSyntaxError
+   * }
    * ```
    */
-  source?: string
+  name: 'CssSyntaxError'
 
   /**
    * Plugin name, if error came from plugin.
@@ -193,31 +165,46 @@ declare class CssSyntaxError_ {
   plugin?: string
 
   /**
-   * Input object with PostCSS internal information
-   * about input file. If input has source map
-   * from previous tool, PostCSS will use origin
-   * (for example, Sass) source. You can use this
-   * object to get PostCSS input source.
+   * Error message.
    *
    * ```js
-   * error.input.file //=> 'a.css'
-   * error.file       //=> 'a.sass'
+   * error.message //=> 'Unclosed block'
    * ```
    */
-  input?: FilePosition
+  reason: string
 
   /**
-   * Returns error position, message and source code of the broken part.
+   * Source code of the broken file.
    *
    * ```js
-   * error.toString() //=> "CssSyntaxError: app.css:1:1: Unclosed block
-   *                  //    > 1 | a {
-   *                  //        | ^"
+   * error.source       //=> 'a { b {} }'
+   * error.input.source //=> 'a b { }'
    * ```
-   *
-   * @return Error position, message and source code.
    */
-  toString(): string
+  source?: string
+
+  stack: string
+
+  /**
+   * Instantiates a CSS syntax error. Can be instantiated for a single position
+   * or for a range.
+   * @param message        Error message.
+   * @param lineOrStartPos If for a single position, the line number, or if for
+   *                       a range, the inclusive start position of the error.
+   * @param columnOrEndPos If for a single position, the column number, or if for
+   *                       a range, the exclusive end position of the error.
+   * @param source         Source code of the broken file.
+   * @param file           Absolute path to the broken file.
+   * @param plugin         PostCSS plugin name, if error came from plugin.
+   */
+  constructor(
+    message: string,
+    lineOrStartPos?: CssSyntaxError.RangePosition | number,
+    columnOrEndPos?: CssSyntaxError.RangePosition | number,
+    source?: string,
+    file?: string,
+    plugin?: string
+  )
 
   /**
    * Returns a few lines of CSS source that caused the error.
@@ -241,6 +228,19 @@ declare class CssSyntaxError_ {
    * @return Few lines of CSS source that caused the error.
    */
   showSourceCode(color?: boolean): string
+
+  /**
+   * Returns error position, message and source code of the broken part.
+   *
+   * ```js
+   * error.toString() //=> "CssSyntaxError: app.css:1:1: Unclosed block
+   *                  //    > 1 | a {
+   *                  //        | ^"
+   * ```
+   *
+   * @return Error position, message and source code.
+   */
+  toString(): string
 }
 
 declare class CssSyntaxError extends CssSyntaxError_ {}

package/lib/css-syntax-error.js

@@ -64,7 +64,7 @@ class CssSyntaxError extends Error {
 
     let mark, aside
     if (color) {
-      let { bold, red, gray } = pico.createColors(true)
+      let { bold, gray, red } = pico.createColors(true)
       mark = text => bold(red(text))
       aside = text => gray(text)
     } else {

package/lib/declaration.d.ts

@@ -23,20 +23,20 @@ declare namespace Declaration {
      * Declaration value with comments.
      */
     value?: {
-      value: string
       raw: string
+      value: string
     }
   }
 
   export interface DeclarationProps {
-    /** Name of the declaration. */
-    prop: string
-    /** Value of the declaration. */
-    value: string
     /** Whether the declaration has an `!important` annotation. */
     important?: boolean
+    /** Name of the declaration. */
+    prop: string
     /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
     raws?: DeclarationRaws
+    /** Value of the declaration. */
+    value: string
   }
 
   // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -44,88 +44,101 @@ declare namespace Declaration {
 }
 
 /**
- * Represents a CSS declaration.
+ * It represents a class that handles
+ * [CSS declarations](https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax#css_declarations)
  *
  * ```js
  * Once (root, { Declaration }) {
- *   let color = new Declaration({ prop: 'color', value: 'black' })
+ *   const color = new Declaration({ prop: 'color', value: 'black' })
  *   root.append(color)
  * }
  * ```
  *
  * ```js
  * const root = postcss.parse('a { color: black }')
- * const decl = root.first.first
- * decl.type       //=> 'decl'
- * decl.toString() //=> ' color: black'
+ * const decl = root.first?.first
+ *
+ * console.log(decl.type)       //=> 'decl'
+ * console.log(decl.toString()) //=> ' color: black'
  * ```
  */
 declare class Declaration_ extends Node {
-  type: 'decl'
-  parent: Container | undefined
-  raws: Declaration.DeclarationRaws
-
   /**
-   * The declaration's property name.
+   * It represents a specificity of the declaration.
+   *
+   * If true, the CSS declaration will have an
+   * [important](https://developer.mozilla.org/en-US/docs/Web/CSS/important)
+   * specifier.
    *
    * ```js
-   * const root = postcss.parse('a { color: black }')
-   * const decl = root.first.first
-   * decl.prop //=> 'color'
+   * const root = postcss.parse('a { color: black !important; color: red }')
+   *
+   * console.log(root.first?.first?.important) //=> true
+   * console.log(root.first?.last?.important)  //=> undefined
    * ```
    */
-  prop: string
-
+  important: boolean
+  parent: Container | undefined
   /**
-   * The declaration’s value.
-   *
-   * This value will be cleaned of comments. If the source value contained
-   * comments, those comments will be available in the `raws` property.
-   * If you have not changed the value, the result of `decl.toString()`
-   * will include the original raws value (comments and all).
+   * The property name for a CSS declaration.
    *
    * ```js
    * const root = postcss.parse('a { color: black }')
-   * const decl = root.first.first
-   * decl.value //=> 'black'
+   * const decl = root.first?.first
+   *
+   * console.log(decl.prop) //=> 'color'
    * ```
    */
-  value: string
+  prop: string
+
+  raws: Declaration.DeclarationRaws
+
+  type: 'decl'
 
   /**
-   * `true` if the declaration has an `!important` annotation.
+   * The property value for a CSS declaration.
+   *
+   * Any CSS comments inside the value string will be filtered out.
+   * CSS comments present in the source value will be available in
+   * the `raws` property.
+   *
+   * Assigning new `value` would ignore the comments in `raws`
+   * property while compiling node to string.
    *
    * ```js
-   * const root = postcss.parse('a { color: black !important; color: red }')
-   * root.first.first.important //=> true
-   * root.first.last.important  //=> undefined
+   * const root = postcss.parse('a { color: black }')
+   * const decl = root.first?.first
+   *
+   * console.log(decl.value) //=> 'black'
    * ```
    */
-  important: boolean
+  value: string
 
   /**
-   * `true` if declaration is declaration of CSS Custom Property
-   * or Sass variable.
+   * It represents a getter that returns `true` if a declaration starts with
+   * `--` or `$`, which are used to declare variables in CSS and SASS/SCSS.
    *
    * ```js
    * const root = postcss.parse(':root { --one: 1 }')
-   * let one = root.first.first
-   * one.variable //=> true
+   * const one = root.first?.first
+   *
+   * console.log(one?.variable) //=> true
    * ```
    *
    * ```js
    * const root = postcss.parse('$one: 1')
-   * let one = root.first
-   * one.variable //=> true
+   * const one = root.first
+   *
+   * console.log(one?.variable) //=> true
    * ```
    */
   variable: boolean
 
   constructor(defaults?: Declaration.DeclarationProps)
-  assign(overrides: object | Declaration.DeclarationProps): this
+  assign(overrides: Declaration.DeclarationProps | object): this
   clone(overrides?: Partial<Declaration.DeclarationProps>): this
-  cloneBefore(overrides?: Partial<Declaration.DeclarationProps>): this
   cloneAfter(overrides?: Partial<Declaration.DeclarationProps>): this
+  cloneBefore(overrides?: Partial<Declaration.DeclarationProps>): this
 }
 
 declare class Declaration extends Declaration_ {}

package/lib/document.d.ts

@@ -35,8 +35,8 @@ declare namespace Document {
  * ```
  */
 declare class Document_ extends Container<Root> {
-  type: 'document'
   parent: undefined
+  type: 'document'
 
   constructor(defaults?: Document.DocumentProps)
 

package/lib/input.d.ts

@@ -4,39 +4,39 @@ import PreviousMap from './previous-map.js'
 declare namespace Input {
   export interface FilePosition {
     /**
-     * URL for the source file.
+     * Column of inclusive start position in source file.
      */
-    url: string
+    column: number
 
     /**
-     * Absolute path to the source file.
+     * Column of exclusive end position in source file.
      */
-    file?: string
+    endColumn?: number
 
     /**
-     * Line of inclusive start position in source file.
+     * Line of exclusive end position in source file.
      */
-    line: number
+    endLine?: number
 
     /**
-     * Column of inclusive start position in source file.
+     * Absolute path to the source file.
      */
-    column: number
+    file?: string
 
     /**
-     * Line of exclusive end position in source file.
+     * Line of inclusive start position in source file.
      */
-    endLine?: number
+    line: number
 
     /**
-     * Column of exclusive end position in source file.
+     * Source code.
      */
-    endColumn?: number
+    source?: string
 
     /**
-     * Source code.
+     * URL for the source file.
      */
-    source?: string
+    url: string
   }
 
   // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -62,16 +62,6 @@ declare class Input_ {
    */
   css: string
 
-  /**
-   * The input source map passed from a compilation step before PostCSS
-   * (for example, from Sass compiler).
-   *
-   * ```js
-   * root.source.input.map.consumer().sources //=> ['a.sass']
-   * ```
-   */
-  map: PreviousMap
-
   /**
    * The absolute path to the CSS source file defined
    * with the `from` option.
@@ -83,6 +73,11 @@ declare class Input_ {
    */
   file?: string
 
+  /**
+   * The flag to indicate whether or not the source code has Unicode BOM.
+   */
+  hasBOM: boolean
+
   /**
    * The unique ID of the CSS source. It will be created if `from` option
    * is not provided (because PostCSS does not know the file path).
@@ -96,9 +91,14 @@ declare class Input_ {
   id?: string
 
   /**
-   * The flag to indicate whether or not the source code has Unicode BOM.
+   * The input source map passed from a compilation step before PostCSS
+   * (for example, from Sass compiler).
+   *
+   * ```js
+   * root.source.input.map.consumer().sources //=> ['a.sass']
+   * ```
    */
-  hasBOM: boolean
+  map: PreviousMap
 
   /**
    * @param css  Input CSS source.
@@ -106,6 +106,43 @@ declare class Input_ {
    */
   constructor(css: string, opts?: ProcessOptions)
 
+  error(
+    message: string,
+    start:
+      | {
+          column: number
+          line: number
+        }
+      | {
+          offset: number
+        },
+    end:
+      | {
+          column: number
+          line: number
+        }
+      | {
+          offset: number
+        },
+    opts?: { plugin?: CssSyntaxError['plugin'] }
+  ): CssSyntaxError
+
+  /**
+   * Returns `CssSyntaxError` with information about the error and its position.
+   */
+  error(
+    message: string,
+    line: number,
+    column: number,
+    opts?: { plugin?: CssSyntaxError['plugin'] }
+  ): CssSyntaxError
+
+  error(
+    message: string,
+    offset: number,
+    opts?: { plugin?: CssSyntaxError['plugin'] }
+  ): CssSyntaxError
+
   /**
    * The CSS source identifier. Contains `Input#file` if the user
    * set the `from` option, or `Input#id` if they did not.
@@ -119,7 +156,12 @@ declare class Input_ {
    * ```
    */
   get from(): string
-
+  /**
+   * Converts source offset to line and column.
+   *
+   * @param offset Source offset.
+   */
+  fromOffset(offset: number): { col: number; line: number } | null
   /**
    * Reads the input source map and returns a symbol position
    * in the input source (e.g., in a Sass file that was compiled
@@ -144,49 +186,7 @@ declare class Input_ {
     column: number,
     endLine?: number,
     endColumn?: number
-  ): Input.FilePosition | false
-
-  /**
-   * Converts source offset to line and column.
-   *
-   * @param offset Source offset.
-   */
-  fromOffset(offset: number): { line: number; col: number } | null
-
-  /**
-   * Returns `CssSyntaxError` with information about the error and its position.
-   */
-  error(
-    message: string,
-    line: number,
-    column: number,
-    opts?: { plugin?: CssSyntaxError['plugin'] }
-  ): CssSyntaxError
-  error(
-    message: string,
-    offset: number,
-    opts?: { plugin?: CssSyntaxError['plugin'] }
-  ): CssSyntaxError
-  error(
-    message: string,
-    start:
-      | {
-          offset: number
-        }
-      | {
-          line: number
-          column: number
-        },
-    end:
-      | {
-          offset: number
-        }
-      | {
-          line: number
-          column: number
-        },
-    opts?: { plugin?: CssSyntaxError['plugin'] }
-  ): CssSyntaxError
+  ): false | Input.FilePosition
 }
 
 declare class Input extends Input_ {}