postcss/lib/postcss.d.ts

import { RawSourceMap, SourceMapGenerator } from 'source-map-js'

import AtRule, { AtRuleProps } from './at-rule.js'
import Comment, { CommentProps } from './comment.js'
import Container, { ContainerProps, NewChild } 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, {
  AnyNode,
  ChildNode,
  ChildProps,
  NodeErrorOptions,
  NodeProps,
  Position,
  Source
} from './node.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 Warning, { WarningOptions } from './warning.js'

type DocumentProcessor = (
  document: Document,
  helper: postcss.Helpers
) => Promise<void> | void
type RootProcessor = (
  root: Root,
  helper: postcss.Helpers
) => Promise<void> | void
type DeclarationProcessor = (
  decl: Declaration,
  helper: postcss.Helpers
) => Promise<void> | void
type RuleProcessor = (
  rule: Rule,
  helper: postcss.Helpers
) => Promise<void> | void
type AtRuleProcessor = (
  atRule: AtRule,
  helper: postcss.Helpers
) => Promise<void> | void
type CommentProcessor = (
  comment: Comment,
  helper: postcss.Helpers
) => Promise<void> | void

interface Processors {
  /**
   * Will be called on all`AtRule` nodes.
   *
   * Will be called again on node or children changes.
   */
  AtRule?: { [name: string]: AtRuleProcessor } | AtRuleProcessor

  /**
   * Will be called on all `AtRule` nodes, when all children will be processed.
   *
   * Will be called again on node or children changes.
   */
  AtRuleExit?: { [name: string]: AtRuleProcessor } | AtRuleProcessor

  /**
   * Will be called on all `Comment` nodes.
   *
   * Will be called again on node or children changes.
   */
  Comment?: CommentProcessor

  /**
   * Will be called on all `Comment` nodes after listeners
   * for `Comment` event.
   *
   * Will be called again on node or children changes.
   */
  CommentExit?: CommentProcessor

  /**
   * Will be called on all `Declaration` nodes after listeners
   * for `Declaration` event.
   *
   * Will be called again on node or children changes.
   */
  Declaration?: { [prop: string]: DeclarationProcessor } | DeclarationProcessor

  /**
   * Will be called on all `Declaration` nodes.
   *
   * Will be called again on node or children changes.
   */
  DeclarationExit?:
    | { [prop: string]: DeclarationProcessor }
    | DeclarationProcessor

  /**
   * Will be called on `Document` node.
   *
   * Will be called again on children changes.
   */
  Document?: DocumentProcessor

  /**
   * Will be called on `Document` node, 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.
   */
  OnceExit?: RootProcessor

  /**
   * Will be called on `Root` node.
   *
   * Will be called again on children changes.
   */
  Root?: RootProcessor

  /**
   * Will be called on `Root` node, when all children will be processed.
   *
   * Will be called again on children changes.
   */
  RootExit?: RootProcessor

  /**
   * Will be called on all `Rule` nodes.
   *
   * Will be called again on node or children changes.
   */
  Rule?: RuleProcessor

  /**
   * Will be called on all `Rule` nodes, when all children will be processed.
   *
   * Will be called again on node or children changes.
   */
  RuleExit?: RuleProcessor
}

declare namespace postcss {
  export {
    AnyNode,
    AtRule,
    AtRuleProps,
    ChildNode,
    ChildProps,
    Comment,
    CommentProps,
    Container,
    ContainerProps,
    CssSyntaxError,
    Declaration,
    DeclarationProps,
    Document,
    DocumentProps,
    FilePosition,
    Input,
    LazyResult,
    list,
    Message,
    NewChild,
    Node,
    NodeErrorOptions,
    NodeProps,
    Position,
    Processor,
    Result,
    Root,
    RootProps,
    Rule,
    RuleProps,
    Source,
    Warning,
    WarningOptions
  }

  export type SourceMap = {
    toJSON(): RawSourceMap
  } & SourceMapGenerator

  export type Helpers = { postcss: Postcss; result: Result } & Postcss

  export interface Plugin extends Processors {
    postcssPlugin: string
    prepare?: (result: Result) => Processors
  }

  export interface PluginCreator<PluginOptions> {
    (opts?: PluginOptions): Plugin | Processor
    postcss: true
  }

  export interface Transformer extends TransformCallback {
    postcssPlugin: string
    postcssVersion: string
  }

  export interface TransformCallback {
    (root: Root, result: Result): Promise<void> | void
  }

  export interface OldPlugin<T> extends Transformer {
    (opts?: T): Transformer
    postcss: Transformer
  }

  export type AcceptedPlugin =
    | {
        postcss: Processor | TransformCallback
      }
    | OldPlugin<any>
    | Plugin
    | PluginCreator<any>
    | Processor
    | TransformCallback

  export interface Parser<RootNode = Document | Root> {
    (
      css: { toString(): string } | string,
      opts?: Pick<ProcessOptions, 'from' | 'map'>
    ): RootNode
  }

  export interface Builder {
    (part: string, node?: AnyNode, type?: 'end' | 'start'): void
  }

  export interface Stringifier {
    (node: AnyNode, builder: Builder): void
  }

  export interface JSONHydrator {
    (data: object): Node
    (data: object[]): Node[]
  }

  export interface Syntax<RootNode = Document | Root> {
    /**
     * Function to generate AST by string.
     */
    parse?: Parser<RootNode>

    /**
     * Class to generate string by AST.
     */
    stringify?: Stringifier
  }

  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`.
     * But if all previous maps are external, not inline, PostCSS will not embed
     * the map even if you do not set this option.
     *
     * If you have an inline source map, the result.map property will be empty,
     * as the source map will be contained within the text of `result.css`.
     */
    inline?: boolean

    /**
     * Source map content from a previous processing step (e.g., Sass).
     *
     * PostCSS will try to read the previous source map
     * automatically (based on comments within the source CSS), but you can use
     * this option to identify it manually.
     *
     * If desired, you can omit the previous map with prev: `false`.
     */
    prev?: ((file: string) => string) | boolean | object | string

    /**
     * Indicates that PostCSS should set the origin content (e.g., Sass source)
     * of the source map. By default, it is true. But if all previous maps do not
     * contain sources content, PostCSS will also leave it out even if you
     * do not set this option.
     */
    sourcesContent?: boolean
  }

  export interface ProcessOptions<RootNode = Document | Root> {
    /**
     * The path of the CSS source file. You should always set `from`,
     * because it is used in source map generation and syntax error messages.
     */
    from?: string | undefined

    /**
     * Source map options
     */
    map?: boolean | SourceMapOptions

    /**
     * Function to generate AST by string.
     */
    parser?: Parser<RootNode> | Syntax<RootNode>

    /**
     * Class to generate string by AST.
     */
    stringifier?: Stringifier | Syntax<RootNode>

    /**
     * Object with parse and stringify.
     */
    syntax?: Syntax<RootNode>

    /**
     * The path where you'll put the output CSS file. You should always set `to`
     * to generate correct source maps.
     */
    to?: string
  }

  export type Postcss = typeof postcss

  /**
   * Default function to convert a node tree into a CSS string.
   */
  export let stringify: Stringifier

  /**
   * Parses source css and returns a new `Root` or `Document` node,
   * which contains the source CSS nodes.
   *
   * ```js
   * // Simple CSS concatenation with source map support
   * const root1 = postcss.parse(css1, { from: file1 })
   * const root2 = postcss.parse(css2, { from: file2 })
   * root1.append(root2).toResult().css
   * ```
   */
  export let parse: Parser<Root>

  /**
   * Rehydrate a JSON AST (from `Node#toJSON`) back into the AST classes.
   *
   * ```js
   * const json = root.toJSON()
   * // save to file, send by network, etc
   * const root2  = postcss.fromJSON(json)
   * ```
   */
  export let fromJSON: JSONHydrator

  /**
   * Creates a new `Comment` node.
   *
   * @param defaults Properties for the new node.
   * @return New comment node
   */
  export function comment(defaults?: CommentProps): Comment

  /**
   * Creates a new `AtRule` node.
   *
   * @param defaults Properties for the new node.
   * @return New at-rule node.
   */
  export function atRule(defaults?: AtRuleProps): AtRule

  /**
   * Creates a new `Declaration` node.
   *
   * @param defaults Properties for the new node.
   * @return New declaration node.
   */
  export function decl(defaults?: DeclarationProps): Declaration

  /**
   * Creates a new `Rule` node.
   *
   * @param default Properties for the new node.
   * @return New rule node.
   */
  export function rule(defaults?: RuleProps): Rule

  /**
   * Creates a new `Root` node.
   *
   * @param defaults Properties for the new node.
   * @return New root node.
   */
  export function root(defaults?: RootProps): Root

  /**
   * Creates a new `Document` node.
   *
   * @param defaults Properties for the new node.
   * @return New document node.
   */
  export function document(defaults?: DocumentProps): Document

  export { postcss as default }
}

/**
 * Create a new `Processor` instance that will apply `plugins`
 * as CSS processors.
 *
 * ```js
 * let postcss = require('postcss')
 *
 * postcss(plugins).process(css, { from, to }).then(result => {
 *   console.log(result.css)
 * })
 * ```
 *
 * @param plugins PostCSS plugins.
 * @return Processor to process multiple CSS.
 */
declare function postcss(
  plugins?: readonly postcss.AcceptedPlugin[]
): Processor
declare function postcss(...plugins: postcss.AcceptedPlugin[]): Processor

export = postcss