postcss 8.3.9 → 8.4.31

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

@@ -1,5 +1,25 @@
 import { FilePosition } from './input.js'
 
+declare namespace CssSyntaxError {
+  /**
+   * A position that is part of a range.
+   */
+  export interface RangePosition {
+    /**
+     * The column number in the input.
+     */
+    column: number
+
+    /**
+     * The line number in the input.
+     */
+    line: number
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { CssSyntaxError_ as default }
+}
+
 /**
  * The CSS parser throws this error for broken CSS.
  *
@@ -29,58 +49,47 @@ import { FilePosition } from './input.js'
  * }
  * ```
  */
-export default class CssSyntaxError {
-  /**
-   * @param message Error message.
-   * @param line    Source line of the error.
-   * @param column  Source column 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,
-    line?: number,
-    column?: number,
-    source?: string,
-    file?: string,
-    plugin?: string
-  )
-
-  stack: string
-
+declare class CssSyntaxError_ {
   /**
-   * 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.
@@ -95,6 +104,20 @@ export default class CssSyntaxError {
    */
   file?: 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.
+   *
+   * ```js
+   * error.input.file //=> 'a.css'
+   * error.file       //=> 'a.sass'
+   * ```
+   */
+  input?: FilePosition
+
   /**
    * Source line of the error.
    *
@@ -109,27 +132,28 @@ export default class CssSyntaxError {
   line?: number
 
   /**
-   * Source column of the error.
+   * Full error text in the GNU error format
+   * with plugin, file, line and column.
    *
    * ```js
-   * error.column       //=> 1
-   * error.input.column //=> 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.column`.
    */
-  column?: 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.
@@ -141,31 +165,46 @@ export default 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.
@@ -189,4 +228,21 @@ export default 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_ {}
+
+export = CssSyntaxError

package/lib/css-syntax-error.js

@@ -20,8 +20,15 @@ class CssSyntaxError extends Error {
       this.plugin = plugin
     }
     if (typeof line !== 'undefined' && typeof column !== 'undefined') {
-      this.line = line
-      this.column = column
+      if (typeof line === 'number') {
+        this.line = line
+        this.column = column
+      } else {
+        this.line = line.line
+        this.column = line.column
+        this.endLine = column.line
+        this.endColumn = column.column
+      }
     }
 
     this.setMessage()
@@ -57,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

@@ -1,124 +1,148 @@
 import Container from './container.js'
 import Node from './node.js'
 
-interface DeclarationRaws {
-  /**
-   * The space symbols before the node. It also stores `*`
-   * and `_` symbols before the declaration (IE hack).
-   */
-  before?: string
+declare namespace Declaration {
+  export interface DeclarationRaws extends Record<string, unknown> {
+    /**
+     * The space symbols before the node. It also stores `*`
+     * and `_` symbols before the declaration (IE hack).
+     */
+    before?: string
 
-  /**
-   * The symbols between the property and value for declarations.
-   */
-  between?: string
+    /**
+     * The symbols between the property and value for declarations.
+     */
+    between?: string
 
-  /**
-   * The content of the important statement, if it is not just `!important`.
-   */
-  important?: string
+    /**
+     * The content of the important statement, if it is not just `!important`.
+     */
+    important?: string
 
-  /**
-   * Declaration value with comments.
-   */
-  value: {
+    /**
+     * Declaration value with comments.
+     */
+    value?: {
+      raw: string
+      value: string
+    }
+  }
+
+  export interface DeclarationProps {
+    /** 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
-    raw: 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
-  /** Information used to generate byte-to-byte equal node string as it was in the origin input. */
-  raws?: DeclarationRaws
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { Declaration_ as default }
 }
 
 /**
- * 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
+ * const decl = root.first?.first
+ *
  * decl.type       //=> 'decl'
  * decl.toString() //=> ' color: black'
  * ```
  */
-export default class Declaration extends Node {
-  type: 'decl'
+declare class Declaration_ extends Node {
+  /**
+   * 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 !important; color: red }')
+   *
+   * root.first.first.important //=> true
+   * root.first.last.important  //=> undefined
+   * ```
+   */
+  important: boolean
+
   parent: Container | undefined
-  raws: DeclarationRaws
 
   /**
-   * The declaration's property name.
+   * The property name for a CSS declaration.
    *
    * ```js
    * const root = postcss.parse('a { color: black }')
    * const decl = root.first.first
+   *
    * decl.prop //=> 'color'
    * ```
    */
   prop: string
 
+  raws: Declaration.DeclarationRaws
+
+  type: 'decl'
+
   /**
-   * The declaration’s value.
+   * 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.
    *
-   * 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).
+   * Assigning new `value` would ignore the comments in `raws`
+   * property while compiling node to string.
    *
    * ```js
    * const root = postcss.parse('a { color: black }')
    * const decl = root.first.first
+   *
    * decl.value //=> 'black'
    * ```
    */
   value: string
 
   /**
-   * `true` if the declaration has an `!important` annotation.
-   *
-   * ```js
-   * const root = postcss.parse('a { color: black !important; color: red }')
-   * root.first.first.important //=> true
-   * root.first.last.important  //=> undefined
-   * ```
-   */
-  important: boolean
-
-  /**
-   * `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
+   * const one = root.first.first
+   *
    * one.variable //=> true
    * ```
    *
    * ```js
    * const root = postcss.parse('$one: 1')
-   * let one = root.first
+   * const one = root.first
+   *
    * one.variable //=> true
    * ```
    */
   variable: boolean
 
-  constructor(defaults?: DeclarationProps)
-  assign(overrides: object | DeclarationProps): this
-  clone(overrides?: Partial<DeclarationProps>): this
-  cloneBefore(overrides?: Partial<DeclarationProps>): this
-  cloneAfter(overrides?: Partial<DeclarationProps>): this
+  constructor(defaults?: Declaration.DeclarationProps)
+  assign(overrides: Declaration.DeclarationProps | object): this
+  clone(overrides?: Partial<Declaration.DeclarationProps>): Declaration
+  cloneAfter(overrides?: Partial<Declaration.DeclarationProps>): Declaration
+  cloneBefore(overrides?: Partial<Declaration.DeclarationProps>): Declaration
 }
+
+declare class Declaration extends Declaration_ {}
+
+export = Declaration

package/lib/document.d.ts

@@ -1,22 +1,24 @@
 import Container, { ContainerProps } from './container.js'
 import { ProcessOptions } from './postcss.js'
 import Result from './result.js'
-import Root, { RootProps } from './root.js'
+import Root from './root.js'
 
-export interface DocumentProps extends ContainerProps {
-  nodes?: Root[]
+declare namespace Document {
+  export interface DocumentProps extends ContainerProps {
+    nodes?: Root[]
 
-  /**
-   * Information to generate byte-to-byte equal node string as it was
-   * in the origin input.
-   *
-   * Every parser saves its own properties.
-   */
-  raws?: Record<string, any>
-}
+    /**
+     * Information to generate byte-to-byte equal node string as it was
+     * in the origin input.
+     *
+     * Every parser saves its own properties.
+     */
+    raws?: Record<string, any>
+  }
 
-type ChildNode = Root
-type ChildProps = RootProps
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { Document_ as default }
+}
 
 /**
  * Represents a file and contains all its parsed nodes.
@@ -32,11 +34,16 @@ type ChildProps = RootProps
  * document.nodes.length //=> 2
  * ```
  */
-export default class Document extends Container<Root> {
-  type: 'document'
+declare class Document_ extends Container<Root> {
   parent: undefined
+  type: 'document'
+
+  constructor(defaults?: Document.DocumentProps)
 
-  constructor(defaults?: DocumentProps)
+  assign(overrides: Document.DocumentProps | object): this
+  clone(overrides?: Partial<Document.DocumentProps>): Document
+  cloneAfter(overrides?: Partial<Document.DocumentProps>): Document
+  cloneBefore(overrides?: Partial<Document.DocumentProps>): Document
 
   /**
    * Returns a `Result` instance representing the document’s CSS roots.
@@ -55,3 +62,7 @@ export default class Document extends Container<Root> {
    */
   toResult(options?: ProcessOptions): Result
 }
+
+declare class Document extends Document_ {}
+
+export = Document

package/lib/fromJSON.d.ts

@@ -1,5 +1,9 @@
 import { JSONHydrator } from './postcss.js'
 
-declare const fromJSON: JSONHydrator
+interface FromJSON extends JSONHydrator {
+  default: FromJSON
+}
 
-export default fromJSON
+declare const fromJSON: FromJSON
+
+export = fromJSON