postcss 8.4.23 → 8.4.25

package/lib/postcss.d.ts

@@ -1,28 +1,28 @@
-import { SourceMapGenerator, RawSourceMap } from 'source-map-js'
+import { RawSourceMap, SourceMapGenerator } from 'source-map-js'
 
+import AtRule, { AtRuleProps } from './at-rule.js'
+import Comment, { CommentProps } from './comment.js'
+import Container, { ContainerProps } from './container.js'
+import CssSyntaxError from './css-syntax-error.js'
+import Declaration, { DeclarationProps } from './declaration.js'
+import Document, { DocumentProps } from './document.js'
+import Input, { FilePosition } from './input.js'
+import LazyResult from './lazy-result.js'
+import list from './list.js'
 import Node, {
-  Position,
-  Source,
+  AnyNode,
   ChildNode,
+  ChildProps,
   NodeErrorOptions,
   NodeProps,
-  ChildProps,
-  AnyNode
+  Position,
+  Source
 } from './node.js'
-import Declaration, { DeclarationProps } from './declaration.js'
-import Container, { ContainerProps } from './container.js'
-import Document, { DocumentProps } from './document.js'
-import Warning, { WarningOptions } from './warning.js'
-import Comment, { CommentProps } from './comment.js'
-import AtRule, { AtRuleProps } from './at-rule.js'
-import Input, { FilePosition } from './input.js'
+import Processor from './processor.js'
 import Result, { Message } from './result.js'
 import Root, { RootProps } from './root.js'
 import Rule, { RuleProps } from './rule.js'
-import CssSyntaxError from './css-syntax-error.js'
-import list from './list.js'
-import LazyResult from './lazy-result.js'
-import Processor from './processor.js'
+import Warning, { WarningOptions } from './warning.js'
 
 type DocumentProcessor = (
   document: Document,
@@ -42,42 +42,33 @@ type CommentProcessor = (
 
 interface Processors {
   /**
-   * Will be called on `Document` node.
+   * Will be called on all`AtRule` nodes.
    *
-   * Will be called again on children changes.
+   * Will be called again on node or children changes.
    */
-  Document?: DocumentProcessor
+  AtRule?: { [name: string]: AtRuleProcessor } | AtRuleProcessor
 
   /**
-   * Will be called on `Document` node, when all children will be processed.
+   * Will be called on all `AtRule` nodes, when all children will be processed.
    *
-   * Will be called again on children changes.
-   */
-  DocumentExit?: DocumentProcessor
-
-  /**
-   * Will be called on `Root` node once.
-   */
-  Once?: RootProcessor
-
-  /**
-   * Will be called on `Root` node once, when all children will be processed.
+   * Will be called again on node or children changes.
    */
-  OnceExit?: RootProcessor
+  AtRuleExit?: { [name: string]: AtRuleProcessor } | AtRuleProcessor
 
   /**
-   * Will be called on `Root` node.
+   * Will be called on all `Comment` nodes.
    *
-   * Will be called again on children changes.
+   * Will be called again on node or children changes.
    */
-  Root?: RootProcessor
+  Comment?: CommentProcessor
 
   /**
-   * Will be called on `Root` node, when all children will be processed.
+   * Will be called on all `Comment` nodes after listeners
+   * for `Comment` event.
    *
-   * Will be called again on children changes.
+   * Will be called again on node or children changes.
    */
-  RootExit?: RootProcessor
+  CommentExit?: CommentProcessor
 
   /**
    * Will be called on all `Declaration` nodes after listeners
@@ -85,7 +76,7 @@ interface Processors {
    *
    * Will be called again on node or children changes.
    */
-  Declaration?: DeclarationProcessor | { [prop: string]: DeclarationProcessor }
+  Declaration?: { [prop: string]: DeclarationProcessor } | DeclarationProcessor
 
   /**
    * Will be called on all `Declaration` nodes.
@@ -93,101 +84,103 @@ interface Processors {
    * Will be called again on node or children changes.
    */
   DeclarationExit?:
-    | DeclarationProcessor
     | { [prop: string]: DeclarationProcessor }
+    | DeclarationProcessor
 
   /**
-   * Will be called on all `Rule` nodes.
+   * Will be called on `Document` node.
    *
-   * Will be called again on node or children changes.
+   * Will be called again on children changes.
    */
-  Rule?: RuleProcessor
+  Document?: DocumentProcessor
 
   /**
-   * Will be called on all `Rule` nodes, when all children will be processed.
+   * Will be called on `Document` node, when all children will be processed.
    *
-   * Will be called again on node or children changes.
+   * Will be called again on children changes.
    */
-  RuleExit?: RuleProcessor
+  DocumentExit?: DocumentProcessor
 
   /**
-   * Will be called on all`AtRule` nodes.
-   *
-   * Will be called again on node or children changes.
+   * Will be called on `Root` node once.
    */
-  AtRule?: AtRuleProcessor | { [name: string]: AtRuleProcessor }
+  Once?: RootProcessor
 
   /**
-   * Will be called on all `AtRule` nodes, when all children will be processed.
+   * Will be called on `Root` node once, when all children will be processed.
+   */
+  OnceExit?: RootProcessor
+
+  /**
+   * Will be called on `Root` node.
    *
-   * Will be called again on node or children changes.
+   * Will be called again on children changes.
    */
-  AtRuleExit?: AtRuleProcessor | { [name: string]: AtRuleProcessor }
+  Root?: RootProcessor
 
   /**
-   * Will be called on all `Comment` nodes.
+   * Will be called on `Root` node, when all children will be processed.
    *
-   * Will be called again on node or children changes.
+   * Will be called again on children changes.
    */
-  Comment?: CommentProcessor
+  RootExit?: RootProcessor
 
   /**
-   * Will be called on all `Comment` nodes after listeners
-   * for `Comment` event.
+   * Will be called on all `Rule` nodes.
    *
    * Will be called again on node or children changes.
    */
-  CommentExit?: CommentProcessor
+  Rule?: RuleProcessor
 
   /**
-   * Will be called when all other listeners processed the document.
+   * Will be called on all `Rule` nodes, when all children will be processed.
    *
-   * This listener will not be called again.
+   * Will be called again on node or children changes.
    */
-  Exit?: RootProcessor
+  RuleExit?: RuleProcessor
 }
 
 declare namespace postcss {
   export {
-    NodeErrorOptions,
-    DeclarationProps,
-    CssSyntaxError,
+    AnyNode,
+    AtRule,
+    AtRuleProps,
+    ChildNode,
+    ChildProps,
+    Comment,
+    CommentProps,
+    Container,
     ContainerProps,
-    WarningOptions,
+    CssSyntaxError,
+    Declaration,
+    DeclarationProps,
+    Document,
     DocumentProps,
     FilePosition,
-    CommentProps,
-    AtRuleProps,
-    Declaration,
-    ChildProps,
+    Input,
     LazyResult,
-    ChildNode,
+    list,
+    Message,
+    Node,
+    NodeErrorOptions,
     NodeProps,
-    Processor,
-    RuleProps,
-    RootProps,
-    Container,
     Position,
-    Document,
-    AnyNode,
-    Warning,
-    Message,
-    Comment,
-    Source,
-    AtRule,
+    Processor,
     Result,
-    Input,
-    Node,
-    list,
+    Root,
+    RootProps,
     Rule,
-    Root
+    RuleProps,
+    Source,
+    Warning,
+    WarningOptions
   }
 
   export type SourceMap = SourceMapGenerator & {
     toJSON(): RawSourceMap
   }
 
-  export type Helpers = { result: Result; postcss: Postcss } & Postcss
+  export type Helpers = { postcss: Postcss; result: Result } & Postcss
 
   export interface Plugin extends Processors {
     postcssPlugin: string
@@ -214,24 +207,24 @@ declare namespace postcss {
   }
 
   export type AcceptedPlugin =
-    | Plugin
-    | PluginCreator<any>
-    | OldPlugin<any>
-    | TransformCallback
     | {
-        postcss: TransformCallback | Processor
+        postcss: Processor | TransformCallback
       }
+    | OldPlugin<any>
+    | Plugin
+    | PluginCreator<any>
     | Processor
+    | TransformCallback
 
-  export interface Parser<RootNode = Root | Document> {
+  export interface Parser<RootNode = Document | Root> {
     (
-      css: string | { toString(): string },
-      opts?: Pick<ProcessOptions, 'map' | 'from'>
+      css: { toString(): string } | string,
+      opts?: Pick<ProcessOptions, 'from' | 'map'>
     ): RootNode
   }
 
   export interface Builder {
-    (part: string, node?: AnyNode, type?: 'start' | 'end'): void
+    (part: string, node?: AnyNode, type?: 'end' | 'start'): void
   }
 
   export interface Stringifier {
@@ -239,8 +232,8 @@ declare namespace postcss {
   }
 
   export interface JSONHydrator {
-    (data: object[]): Node[]
     (data: object): Node
+    (data: object[]): Node[]
   }
 
   export interface Syntax {
@@ -256,6 +249,30 @@ declare namespace postcss {
   }
 
   export interface SourceMapOptions {
+    /**
+     * Use absolute path in generated source map.
+     */
+    absolute?: boolean
+
+    /**
+     * Indicates that PostCSS should add annotation comments to the CSS.
+     * By default, PostCSS will always add a comment with a path
+     * to the source map. PostCSS will not add annotations to CSS files
+     * that do not contain any comments.
+     *
+     * By default, PostCSS presumes that you want to save the source map as
+     * `opts.to + '.map'` and will use this path in the annotation comment.
+     * A different path can be set by providing a string value for annotation.
+     *
+     * If you have set `inline: true`, annotation cannot be disabled.
+     */
+    annotation?: ((file: string, root: Root) => string) | boolean | string
+
+    /**
+     * Override `from` in map’s sources.
+     */
+    from?: string
+
     /**
      * Indicates that the source map should be embedded in the output CSS
      * as a Base64-encoded comment. By default, it is `true`.
@@ -276,7 +293,7 @@ declare namespace postcss {
      *
      * If desired, you can omit the previous map with prev: `false`.
      */
-    prev?: string | boolean | object | ((file: string) => string)
+    prev?: ((file: string) => string) | boolean | object | string
 
     /**
      * Indicates that PostCSS should set the origin content (e.g., Sass source)
@@ -285,30 +302,6 @@ declare namespace postcss {
      * do not set this option.
      */
     sourcesContent?: boolean
-
-    /**
-     * Indicates that PostCSS should add annotation comments to the CSS.
-     * By default, PostCSS will always add a comment with a path
-     * to the source map. PostCSS will not add annotations to CSS files
-     * that do not contain any comments.
-     *
-     * By default, PostCSS presumes that you want to save the source map as
-     * `opts.to + '.map'` and will use this path in the annotation comment.
-     * A different path can be set by providing a string value for annotation.
-     *
-     * If you have set `inline: true`, annotation cannot be disabled.
-     */
-    annotation?: string | boolean | ((file: string, root: Root) => string)
-
-    /**
-     * Override `from` in map’s sources.
-     */
-    from?: string
-
-    /**
-     * Use absolute path in generated source map.
-     */
-    absolute?: boolean
   }
 
   export interface ProcessOptions {
@@ -319,20 +312,19 @@ declare namespace postcss {
     from?: string
 
     /**
-     * The path where you'll put the output CSS file. You should always set `to`
-     * to generate correct source maps.
+     * Source map options
      */
-    to?: string
+    map?: boolean | SourceMapOptions
 
     /**
      * Function to generate AST by string.
      */
-    parser?: Syntax | Parser
+    parser?: Parser | Syntax
 
     /**
      * Class to generate string by AST.
      */
-    stringifier?: Syntax | Stringifier
+    stringifier?: Stringifier | Syntax
 
     /**
      * Object with parse and stringify.
@@ -340,9 +332,10 @@ declare namespace postcss {
     syntax?: Syntax
 
     /**
-     * Source map options
+     * The path where you'll put the output CSS file. You should always set `to`
+     * to generate correct source maps.
      */
-    map?: SourceMapOptions | boolean
+    to?: string
   }
 
   export type Postcss = typeof postcss

package/lib/previous-map.d.ts

@@ -21,35 +21,35 @@ declare namespace PreviousMap {
  */
 declare class PreviousMap_ {
   /**
-   * Was source map inlined by data-uri to input CSS.
+   * `sourceMappingURL` content.
    */
-  inline: boolean
+  annotation?: string
 
   /**
-   * `sourceMappingURL` content.
+   * The CSS source identifier. Contains `Input#file` if the user
+   * set the `from` option, or `Input#id` if they did not.
    */
-  annotation?: string
+  file?: string
 
   /**
-   * Source map file content.
+   * Was source map inlined by data-uri to input CSS.
    */
-  text?: string
+  inline: boolean
 
   /**
-   * The directory with source map file, if source map is in separated file.
+   * Path to source map file.
    */
-  root?: string
+  mapFile?: string
 
   /**
-   * The CSS source identifier. Contains `Input#file` if the user
-   * set the `from` option, or `Input#id` if they did not.
+   * The directory with source map file, if source map is in separated file.
    */
-  file?: string
+  root?: string
 
   /**
-   * Path to source map file.
+   * Source map file content.
    */
-  mapFile?: string
+  text?: string
 
   /**
    * @param css  Input CSS source.

package/lib/previous-map.js

@@ -35,22 +35,37 @@ class PreviousMap {
     return this.consumerCache
   }
 
-  withContent() {
-    return !!(
-      this.consumer().sourcesContent &&
-      this.consumer().sourcesContent.length > 0
-    )
-  }
+  decodeInline(text) {
+    let baseCharsetUri = /^data:application\/json;charset=utf-?8;base64,/
+    let baseUri = /^data:application\/json;base64,/
+    let charsetUri = /^data:application\/json;charset=utf-?8,/
+    let uri = /^data:application\/json,/
 
-  startWith(string, start) {
-    if (!string) return false
-    return string.substr(0, start.length) === start
+    if (charsetUri.test(text) || uri.test(text)) {
+      return decodeURIComponent(text.substr(RegExp.lastMatch.length))
+    }
+
+    if (baseCharsetUri.test(text) || baseUri.test(text)) {
+      return fromBase64(text.substr(RegExp.lastMatch.length))
+    }
+
+    let encoding = text.match(/data:application\/json;([^,]+),/)[1]
+    throw new Error('Unsupported source map encoding ' + encoding)
   }
 
   getAnnotationURL(sourceMapString) {
     return sourceMapString.replace(/^\/\*\s*# sourceMappingURL=/, '').trim()
   }
 
+  isMap(map) {
+    if (typeof map !== 'object') return false
+    return (
+      typeof map.mappings === 'string' ||
+      typeof map._mappings === 'string' ||
+      Array.isArray(map.sections)
+    )
+  }
+
   loadAnnotation(css) {
     let comments = css.match(/\/\*\s*# sourceMappingURL=/gm)
     if (!comments) return
@@ -65,24 +80,6 @@ class PreviousMap {
     }
   }
 
-  decodeInline(text) {
-    let baseCharsetUri = /^data:application\/json;charset=utf-?8;base64,/
-    let baseUri = /^data:application\/json;base64,/
-    let charsetUri = /^data:application\/json;charset=utf-?8,/
-    let uri = /^data:application\/json,/
-
-    if (charsetUri.test(text) || uri.test(text)) {
-      return decodeURIComponent(text.substr(RegExp.lastMatch.length))
-    }
-
-    if (baseCharsetUri.test(text) || baseUri.test(text)) {
-      return fromBase64(text.substr(RegExp.lastMatch.length))
-    }
-
-    let encoding = text.match(/data:application\/json;([^,]+),/)[1]
-    throw new Error('Unsupported source map encoding ' + encoding)
-  }
-
   loadFile(path) {
     this.root = dirname(path)
     if (existsSync(path)) {
@@ -128,12 +125,15 @@ class PreviousMap {
     }
   }
 
-  isMap(map) {
-    if (typeof map !== 'object') return false
-    return (
-      typeof map.mappings === 'string' ||
-      typeof map._mappings === 'string' ||
-      Array.isArray(map.sections)
+  startWith(string, start) {
+    if (!string) return false
+    return string.substr(0, start.length) === start
+  }
+
+  withContent() {
+    return !!(
+      this.consumer().sourcesContent &&
+      this.consumer().sourcesContent.length > 0
     )
   }
 }

package/lib/processor.d.ts

@@ -1,14 +1,14 @@
+import LazyResult from './lazy-result.js'
+import NoWorkResult from './no-work-result.js'
 import {
   AcceptedPlugin,
   Plugin,
   ProcessOptions,
-  Transformer,
-  TransformCallback
+  TransformCallback,
+  Transformer
 } from './postcss.js'
-import LazyResult from './lazy-result.js'
 import Result from './result.js'
 import Root from './root.js'
-import NoWorkResult from './no-work-result.js'
 
 declare namespace Processor {
   // eslint-disable-next-line @typescript-eslint/no-use-before-define
@@ -27,31 +27,55 @@ declare namespace Processor {
  */
 declare class Processor_ {
   /**
-   * Current PostCSS version.
+   * Plugins added to this processor.
    *
    * ```js
-   * if (result.processor.version.split('.')[0] !== '6') {
-   *   throw new Error('This plugin works only with PostCSS 6')
-   * }
+   * const processor = postcss([autoprefixer, postcssNested])
+   * processor.plugins.length //=> 2
    * ```
    */
-  version: string
+  plugins: (Plugin | TransformCallback | Transformer)[]
 
   /**
-   * Plugins added to this processor.
+   * Current PostCSS version.
    *
    * ```js
-   * const processor = postcss([autoprefixer, postcssNested])
-   * processor.plugins.length //=> 2
+   * if (result.processor.version.split('.')[0] !== '6') {
+   *   throw new Error('This plugin works only with PostCSS 6')
+   * }
    * ```
    */
-  plugins: (Plugin | Transformer | TransformCallback)[]
+  version: string
 
   /**
    * @param plugins PostCSS plugins
    */
   constructor(plugins?: AcceptedPlugin[])
 
+  /**
+   * Parses source CSS and returns a `LazyResult` Promise proxy.
+   * Because some plugins can be asynchronous it doesn’t make
+   * any transformations. Transformations will be applied
+   * in the `LazyResult` methods.
+   *
+   * ```js
+   * processor.process(css, { from: 'a.css', to: 'a.out.css' })
+   *   .then(result => {
+   *      console.log(result.css)
+   *   })
+   * ```
+   *
+   * @param css String with input CSS or any object with a `toString()` method,
+   *            like a Buffer. Optionally, send a `Result` instance
+   *            and the processor will take the `Root` from it.
+   * @param opts Options.
+   * @return Promise proxy.
+   */
+  process(
+    css: { toString(): string } | LazyResult | Result | Root | string,
+    options?: ProcessOptions
+  ): LazyResult | NoWorkResult
+
   /**
    * Adds a plugin to be used as a CSS processor.
    *
@@ -80,30 +104,6 @@ declare class Processor_ {
    * @return Current processor to make methods chain.
    */
   use(plugin: AcceptedPlugin): this
-
-  /**
-   * Parses source CSS and returns a `LazyResult` Promise proxy.
-   * Because some plugins can be asynchronous it doesn’t make
-   * any transformations. Transformations will be applied
-   * in the `LazyResult` methods.
-   *
-   * ```js
-   * processor.process(css, { from: 'a.css', to: 'a.out.css' })
-   *   .then(result => {
-   *      console.log(result.css)
-   *   })
-   * ```
-   *
-   * @param css String with input CSS or any object with a `toString()` method,
-   *            like a Buffer. Optionally, send a `Result` instance
-   *            and the processor will take the `Root` from it.
-   * @param opts Options.
-   * @return Promise proxy.
-   */
-  process(
-    css: string | { toString(): string } | Result | LazyResult | Root,
-    options?: ProcessOptions
-  ): LazyResult | NoWorkResult
 }
 
 declare class Processor extends Processor_ {}