postcss.d.ts 50KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302
  1. import * as mozilla from 'source-map';
  2. /**
  3. * @param plugins Can also be included with the Processor#use method.
  4. * @returns A processor that will apply plugins as CSS processors.
  5. */
  6. declare function postcss(plugins?: postcss.AcceptedPlugin[]): postcss.Processor;
  7. declare function postcss(...plugins: postcss.AcceptedPlugin[]): postcss.Processor;
  8. declare namespace postcss {
  9. type AcceptedPlugin = Plugin<any> | Transformer | {
  10. postcss: TransformCallback | Processor;
  11. } | Processor;
  12. /**
  13. * Creates a PostCSS plugin with a standard API.
  14. * @param name Plugin name. Same as in name property in package.json. It will
  15. * be saved in plugin.postcssPlugin property.
  16. * @param initializer Will receive plugin options and should return functions
  17. * to modify nodes in input CSS.
  18. */
  19. function plugin<T>(name: string, initializer: PluginInitializer<T>): Plugin<T>;
  20. interface Plugin<T> extends Transformer {
  21. (opts?: T): Transformer;
  22. postcss: Transformer;
  23. process: (css: string | {
  24. toString(): string;
  25. } | Result, opts?: any) => LazyResult;
  26. }
  27. interface Transformer extends TransformCallback {
  28. postcssPlugin?: string;
  29. postcssVersion?: string;
  30. }
  31. interface TransformCallback {
  32. /**
  33. * @returns Asynchronous plugins should return a promise.
  34. */
  35. (root: Root, result?: Result): void | Function | any;
  36. }
  37. interface PluginInitializer<T> {
  38. (pluginOptions?: T): Transformer;
  39. }
  40. /**
  41. * Contains helpers for working with vendor prefixes.
  42. */
  43. export namespace vendor {
  44. /**
  45. * @returns The vendor prefix extracted from the input string.
  46. */
  47. function prefix(prop: string): string;
  48. /**
  49. * @returns The input string stripped of its vendor prefix.
  50. */
  51. function unprefixed(prop: string): string;
  52. }
  53. export class Stringifier {
  54. builder: Stringifier.Builder;
  55. constructor(builder?: Stringifier.Builder);
  56. stringify(node: Node, semicolon?: boolean): void;
  57. root(node: any): void;
  58. comment(node: any): void;
  59. decl(node: any, semicolon: any): void;
  60. rule(node: any): void;
  61. atrule(node: any, semicolon: any): void;
  62. body(node: any): void;
  63. block(node: any, start: any): void;
  64. raw(node: Node, own: string, detect?: string): any;
  65. rawSemicolon(root: any): any;
  66. rawEmptyBody(root: any): any;
  67. rawIndent(root: any): any;
  68. rawBeforeComment(root: any, node: any): any;
  69. rawBeforeDecl(root: any, node: any): any;
  70. rawBeforeRule(root: any): any;
  71. rawBeforeClose(root: any): any;
  72. rawBeforeOpen(root: any): any;
  73. rawColon(root: any): any;
  74. beforeAfter(node: any, detect: any): any;
  75. rawValue(node: any, prop: any): any;
  76. }
  77. export namespace Stringifier {
  78. interface Builder {
  79. (str: string, node?: Node, str2?: string): void;
  80. }
  81. }
  82. /**
  83. * Default function to convert a node tree into a CSS string.
  84. */
  85. function stringify(node: Node, builder: Stringifier.Builder): void;
  86. /**
  87. * Parses source CSS.
  88. * @param css The CSS to parse.
  89. * @param options
  90. * @returns {} A new Root node, which contains the source CSS nodes.
  91. */
  92. function parse(css: string | {
  93. toString(): string;
  94. } | LazyResult | Result, options?: {
  95. from?: string;
  96. map?: postcss.SourceMapOptions;
  97. }): Root;
  98. /**
  99. * Contains helpers for safely splitting lists of CSS values, preserving
  100. * parentheses and quotes.
  101. */
  102. export namespace list {
  103. /**
  104. * Safely splits space-separated values (such as those for background,
  105. * border-radius and other shorthand properties).
  106. */
  107. function space(str: string): string[];
  108. /**
  109. * Safely splits comma-separated values (such as those for transition-* and
  110. * background properties).
  111. */
  112. function comma(str: string): string[];
  113. }
  114. /**
  115. * Creates a new Comment node.
  116. * @param defaults Properties for the new Comment node.
  117. * @returns The new node.
  118. */
  119. function comment(defaults?: CommentNewProps): Comment;
  120. /**
  121. * Creates a new AtRule node.
  122. * @param defaults Properties for the new AtRule node.
  123. * @returns The new node.
  124. */
  125. function atRule(defaults?: AtRuleNewProps): AtRule;
  126. /**
  127. * Creates a new Declaration node.
  128. * @param defaults Properties for the new Declaration node.
  129. * @returns The new node.
  130. */
  131. function decl(defaults?: DeclarationNewProps): Declaration;
  132. /**
  133. * Creates a new Rule node.
  134. * @param defaults Properties for the new Rule node.
  135. * @returns The new node.
  136. */
  137. function rule(defaults?: RuleNewProps): Rule;
  138. /**
  139. * Creates a new Root node.
  140. * @param defaults Properties for the new Root node.
  141. * @returns The new node.
  142. */
  143. function root(defaults?: object): Root;
  144. interface SourceMapOptions {
  145. /**
  146. * Indicates that the source map should be embedded in the output CSS as a
  147. * Base64-encoded comment. By default, it is true. But if all previous maps
  148. * are external, not inline, PostCSS will not embed the map even if you do
  149. * not set this option.
  150. *
  151. * If you have an inline source map, the result.map property will be empty,
  152. * as the source map will be contained within the text of result.css.
  153. */
  154. inline?: boolean;
  155. /**
  156. * Source map content from a previous processing step (e.g., Sass compilation).
  157. * PostCSS will try to read the previous source map automatically (based on comments
  158. * within the source CSS), but you can use this option to identify it manually.
  159. * If desired, you can omit the previous map with prev: false.
  160. */
  161. prev?: any;
  162. /**
  163. * Indicates that PostCSS should set the origin content (e.g., Sass source)
  164. * of the source map. By default, it is true. But if all previous maps do not
  165. * contain sources content, PostCSS will also leave it out even if you do not set
  166. * this option.
  167. */
  168. sourcesContent?: boolean;
  169. /**
  170. * Indicates that PostCSS should add annotation comments to the CSS. By default,
  171. * PostCSS will always add a comment with a path to the source map. PostCSS will
  172. * not add annotations to CSS files that do not contain any comments.
  173. *
  174. * By default, PostCSS presumes that you want to save the source map as
  175. * opts.to + '.map' and will use this path in the annotation comment. A different
  176. * path can be set by providing a string value for annotation.
  177. *
  178. * If you have set inline: true, annotation cannot be disabled.
  179. */
  180. annotation?: boolean | string;
  181. /**
  182. * If true, PostCSS will try to correct any syntax errors that it finds in the CSS.
  183. * This is useful for legacy code filled with hacks. Another use-case is interactive
  184. * tools with live input — for example, the Autoprefixer demo.
  185. */
  186. safe?: boolean;
  187. }
  188. /**
  189. * A Processor instance contains plugins to process CSS. Create one
  190. * Processor instance, initialize its plugins, and then use that instance
  191. * on numerous CSS files.
  192. */
  193. interface Processor {
  194. /**
  195. * Adds a plugin to be used as a CSS processor. Plugins can also be
  196. * added by passing them as arguments when creating a postcss instance.
  197. */
  198. use(plugin: AcceptedPlugin): Processor;
  199. /**
  200. * Parses source CSS. Because some plugins can be asynchronous it doesn't
  201. * make any transformations. Transformations will be applied in LazyResult's
  202. * methods.
  203. * @param css Input CSS or any object with toString() method, like a file
  204. * stream. If a Result instance is passed the processor will take the
  205. * existing Root parser from it.
  206. */
  207. process(css: string | {
  208. toString(): string;
  209. } | Result, options?: ProcessOptions): LazyResult;
  210. /**
  211. * Contains plugins added to this processor.
  212. */
  213. plugins: Plugin<any>[];
  214. /**
  215. * Contains the current version of PostCSS (e.g., "4.0.5").
  216. */
  217. version: string;
  218. }
  219. interface ProcessOptions extends Syntax {
  220. /**
  221. * The path of the CSS source file. You should always set from, because it is
  222. * used in source map generation and syntax error messages.
  223. */
  224. from?: string;
  225. /**
  226. * The path where you'll put the output CSS file. You should always set it
  227. * to generate correct source maps.
  228. */
  229. to?: string;
  230. syntax?: Syntax;
  231. /**
  232. * Enable Safe Mode, in which PostCSS will try to fix CSS syntax errors.
  233. */
  234. safe?: boolean;
  235. map?: postcss.SourceMapOptions;
  236. /**
  237. * Function to generate AST by string.
  238. */
  239. parser?: Parse | Syntax;
  240. /**
  241. * Class to generate string by AST.
  242. */
  243. stringifier?: Stringify | Syntax;
  244. }
  245. interface Syntax {
  246. /**
  247. * Function to generate AST by string.
  248. */
  249. parse?: Parse;
  250. /**
  251. * Class to generate string by AST.
  252. */
  253. stringify?: Stringify;
  254. }
  255. interface Parse {
  256. (css?: string, opts?: postcss.SourceMapOptions): Root;
  257. }
  258. interface Stringify {
  259. (node?: postcss.Node, builder?: any): postcss.Result | void;
  260. }
  261. /**
  262. * A promise proxy for the result of PostCSS transformations.
  263. */
  264. interface LazyResult {
  265. /**
  266. * Processes input CSS through synchronous and asynchronous plugins.
  267. * @param onRejected Called if any plugin throws an error.
  268. */
  269. then(onFulfilled: (result: Result) => void, onRejected?: (error: Error) => void): Function | any;
  270. /**
  271. * Processes input CSS through synchronous and asynchronous plugins.
  272. * @param onRejected Called if any plugin throws an error.
  273. */
  274. catch(onRejected: (error: Error) => void): Function | any;
  275. /**
  276. * Alias for css property.
  277. */
  278. toString(): string;
  279. /**
  280. * Processes input CSS through synchronous plugins and converts Root to
  281. * CSS string. This property will only work with synchronous plugins. If
  282. * the processor contains any asynchronous plugins it will throw an error.
  283. * In this case, you should use LazyResult#then() instead.
  284. * @returns Result#css.
  285. */
  286. css: string;
  287. /**
  288. * Alias for css property to use when syntaxes generate non-CSS output.
  289. */
  290. content: string;
  291. /**
  292. * Processes input CSS through synchronous plugins. This property will
  293. * work only with synchronous plugins. If processor contains any
  294. * asynchronous plugins it will throw an error. You should use
  295. * LazyResult#then() instead.
  296. */
  297. map: ResultMap;
  298. /**
  299. * Processes input CSS through synchronous plugins. This property will work
  300. * only with synchronous plugins. If processor contains any asynchronous
  301. * plugins it will throw an error. You should use LazyResult#then() instead.
  302. */
  303. root: Root;
  304. /**
  305. * Processes input CSS through synchronous plugins and calls Result#warnings().
  306. * This property will only work with synchronous plugins. If the processor
  307. * contains any asynchronous plugins it will throw an error. In this case,
  308. * you should use LazyResult#then() instead.
  309. */
  310. warnings(): ResultMessage[];
  311. /**
  312. * Processes input CSS through synchronous plugins. This property will work
  313. * only with synchronous plugins. If processor contains any asynchronous
  314. * plugins it will throw an error. You should use LazyResult#then() instead.
  315. */
  316. messages: ResultMessage[];
  317. /**
  318. * @returns A processor used for CSS transformations.
  319. */
  320. processor: Processor;
  321. /**
  322. * @returns Options from the Processor#process(css, opts) call that produced
  323. * this Result instance.
  324. */
  325. opts: ResultOptions;
  326. }
  327. /**
  328. * Provides the result of the PostCSS transformations.
  329. */
  330. interface Result {
  331. /**
  332. * Alias for css property.
  333. */
  334. toString(): string;
  335. /**
  336. * Creates an instance of Warning and adds it to messages.
  337. * @param message Used in the text property of the message object.
  338. * @param options Properties for Message object.
  339. */
  340. warn(message: string, options?: WarningOptions): void;
  341. /**
  342. * @returns Warnings from plugins, filtered from messages.
  343. */
  344. warnings(): ResultMessage[];
  345. /**
  346. * A CSS string representing this Result's Root instance.
  347. */
  348. css: string;
  349. /**
  350. * Alias for css property to use with syntaxes that generate non-CSS output.
  351. */
  352. content: string;
  353. /**
  354. * An instance of the SourceMapGenerator class from the source-map library,
  355. * representing changes to the Result's Root instance.
  356. * This property will have a value only if the user does not want an inline
  357. * source map. By default, PostCSS generates inline source maps, written
  358. * directly into the processed CSS. The map property will be empty by default.
  359. * An external source map will be generated — and assigned to map — only if
  360. * the user has set the map.inline option to false, or if PostCSS was passed
  361. * an external input source map.
  362. */
  363. map: ResultMap;
  364. /**
  365. * Contains the Root node after all transformations.
  366. */
  367. root?: Root;
  368. /**
  369. * Contains messages from plugins (e.g., warnings or custom messages).
  370. * Add a warning using Result#warn() and get all warnings
  371. * using the Result#warnings() method.
  372. */
  373. messages: ResultMessage[];
  374. /**
  375. * The Processor instance used for this transformation.
  376. */
  377. processor?: Processor;
  378. /**
  379. * Options from the Processor#process(css, opts) or Root#toResult(opts) call
  380. * that produced this Result instance.
  381. */
  382. opts?: ResultOptions;
  383. }
  384. interface ResultOptions extends ProcessOptions {
  385. /**
  386. * The CSS node that was the source of the warning.
  387. */
  388. node?: postcss.Node;
  389. /**
  390. * Name of plugin that created this warning. Result#warn() will fill it
  391. * automatically with plugin.postcssPlugin value.
  392. */
  393. plugin?: string;
  394. }
  395. interface ResultMap {
  396. /**
  397. * Add a single mapping from original source line and column to the generated
  398. * source's line and column for this source map being created. The mapping
  399. * object should have the following properties:
  400. * @param mapping
  401. * @returns {}
  402. */
  403. addMapping(mapping: mozilla.Mapping): void;
  404. /**
  405. * Set the source content for an original source file.
  406. * @param sourceFile The URL of the original source file.
  407. * @param sourceContent The content of the source file.
  408. */
  409. setSourceContent(sourceFile: string, sourceContent: string): void;
  410. /**
  411. * Applies a SourceMap for a source file to the SourceMap. Each mapping to
  412. * the supplied source file is rewritten using the supplied SourceMap.
  413. * Note: The resolution for the resulting mappings is the minimium of this
  414. * map and the supplied map.
  415. * @param sourceMapConsumer The SourceMap to be applied.
  416. * @param sourceFile The filename of the source file. If omitted, sourceMapConsumer
  417. * file will be used, if it exists. Otherwise an error will be thrown.
  418. * @param sourceMapPath The dirname of the path to the SourceMap to be applied.
  419. * If relative, it is relative to the SourceMap. This parameter is needed when
  420. * the two SourceMaps aren't in the same directory, and the SourceMap to be
  421. * applied contains relative source paths. If so, those relative source paths
  422. * need to be rewritten relative to the SourceMap.
  423. * If omitted, it is assumed that both SourceMaps are in the same directory;
  424. * thus, not needing any rewriting (Supplying '.' has the same effect).
  425. */
  426. applySourceMap(
  427. sourceMapConsumer: mozilla.SourceMapConsumer,
  428. sourceFile?: string,
  429. sourceMapPath?: string
  430. ): void;
  431. /**
  432. * Renders the source map being generated to JSON.
  433. */
  434. toJSON: () => mozilla.RawSourceMap;
  435. /**
  436. * Renders the source map being generated to a string.
  437. */
  438. toString: () => string;
  439. }
  440. interface ResultMessage {
  441. type: string;
  442. text?: string;
  443. plugin?: string;
  444. browsers?: string[];
  445. }
  446. /**
  447. * Represents a plugin warning. It can be created using Result#warn().
  448. */
  449. interface Warning {
  450. /**
  451. * @returns Error position, message.
  452. */
  453. toString(): string;
  454. /**
  455. * Contains the warning message.
  456. */
  457. text: string;
  458. /**
  459. * Contains the name of the plugin that created this warning. When you
  460. * call Result#warn(), it will fill this property automatically.
  461. */
  462. plugin: string;
  463. /**
  464. * The CSS node that caused the warning.
  465. */
  466. node: Node;
  467. /**
  468. * The line in the input file with this warning's source.
  469. */
  470. line: number;
  471. /**
  472. * Column in the input file with this warning's source.
  473. */
  474. column: number;
  475. }
  476. interface WarningOptions extends ResultOptions {
  477. /**
  478. * A word inside a node's string that should be highlighted as source
  479. * of warning.
  480. */
  481. word?: string;
  482. /**
  483. * The index inside a node's string that should be highlighted as
  484. * source of warning.
  485. */
  486. index?: number;
  487. }
  488. /**
  489. * The CSS parser throws this error for broken CSS.
  490. */
  491. interface CssSyntaxError extends InputOrigin {
  492. name: string;
  493. /**
  494. * @returns Error position, message and source code of broken part.
  495. */
  496. toString(): string;
  497. /**
  498. * @param color Whether arrow should be colored red by terminal color codes.
  499. * By default, PostCSS will use process.stdout.isTTY and
  500. * process.env.NODE_DISABLE_COLORS.
  501. * @returns A few lines of CSS source that caused the error. If CSS has
  502. * input source map without sourceContent this method will return an empty
  503. * string.
  504. */
  505. showSourceCode(color?: boolean): string;
  506. /**
  507. * Contains full error text in the GNU error format.
  508. */
  509. message: string;
  510. /**
  511. * Contains only the error description.
  512. */
  513. reason: string;
  514. /**
  515. * Contains the PostCSS plugin name if the error didn't come from the
  516. * CSS parser.
  517. */
  518. plugin?: string;
  519. input?: InputOrigin;
  520. }
  521. interface InputOrigin {
  522. /**
  523. * If parser's from option is set, contains the absolute path to the
  524. * broken file. PostCSS will use the input source map to detect the
  525. * original error location. If you wrote a Sass file, then compiled it
  526. * to CSS and parsed it with PostCSS, PostCSS will show the original
  527. * position in the Sass file. If you need the position in the PostCSS
  528. * input (e.g., to debug the previous compiler), use error.input.file.
  529. */
  530. file?: string;
  531. /**
  532. * Contains the source line of the error. PostCSS will use the input
  533. * source map to detect the original error location. If you wrote a Sass
  534. * file, then compiled it to CSS and parsed it with PostCSS, PostCSS
  535. * will show the original position in the Sass file. If you need the
  536. * position in the PostCSS input (e.g., to debug the previous
  537. * compiler), use error.input.line.
  538. */
  539. line?: number;
  540. /**
  541. * Contains the source column of the error. PostCSS will use input
  542. * source map to detect the original error location. If you wrote a
  543. * Sass file, then compiled it to CSS and parsed it with PostCSS,
  544. * PostCSS will show the original position in the Sass file. If you
  545. * need the position in the PostCSS input (e.g., to debug the
  546. * previous compiler), use error.input.column.
  547. */
  548. column?: number;
  549. /**
  550. * Contains the source code of the broken file. PostCSS will use the
  551. * input source map to detect the original error location. If you wrote
  552. * a Sass file, then compiled it to CSS and parsed it with PostCSS,
  553. * PostCSS will show the original position in the Sass file. If you need
  554. * the position in the PostCSS input (e.g., to debug the previous
  555. * compiler), use error.input.source.
  556. */
  557. source?: string;
  558. }
  559. export class PreviousMap {
  560. private inline;
  561. annotation: string;
  562. root: string;
  563. private consumerCache;
  564. text: string;
  565. file: string;
  566. constructor(css: any, opts: any);
  567. consumer(): mozilla.SourceMapConsumer;
  568. withContent(): boolean;
  569. startWith(string: string, start: string): boolean;
  570. loadAnnotation(css: string): void;
  571. decodeInline(text: string): string;
  572. loadMap(
  573. file: any,
  574. prev: string | Function | mozilla.SourceMapConsumer | mozilla.SourceMapGenerator | mozilla.RawSourceMap
  575. ): string;
  576. isMap(map: any): boolean;
  577. }
  578. /**
  579. * Represents the source CSS.
  580. */
  581. interface Input {
  582. /**
  583. * The absolute path to the CSS source file defined with the "from" option.
  584. */
  585. file: string;
  586. /**
  587. * The unique ID of the CSS source. Used if "from" option is not provided
  588. * (because PostCSS does not know the file path).
  589. */
  590. id: string;
  591. /**
  592. * The CSS source identifier. Contains input.file if the user set the
  593. * "from" option, or input.id if they did not.
  594. */
  595. from: string;
  596. /**
  597. * Represents the input source map passed from a compilation step before
  598. * PostCSS (e.g., from the Sass compiler).
  599. */
  600. map: PreviousMap;
  601. /**
  602. * Reads the input source map.
  603. * @returns A symbol position in the input source (e.g., in a Sass file
  604. * that was compiled to CSS before being passed to PostCSS):
  605. */
  606. origin(line: number, column: number): InputOrigin;
  607. }
  608. type ChildNode = AtRule | Rule | Declaration | Comment;
  609. type Node = Root | ChildNode;
  610. interface NodeBase {
  611. /**
  612. * Returns the input source of the node. The property is used in source
  613. * map generation. If you create a node manually
  614. * (e.g., with postcss.decl() ), that node will not have a source
  615. * property and will be absent from the source map. For this reason, the
  616. * plugin developer should consider cloning nodes to create new ones
  617. * (in which case the new node's source will reference the original,
  618. * cloned node) or setting the source property manually.
  619. */
  620. source: NodeSource;
  621. /**
  622. * Contains information to generate byte-to-byte equal node string as it
  623. * was in origin input.
  624. */
  625. raws: NodeRaws;
  626. /**
  627. * @returns A CSS string representing the node.
  628. */
  629. toString(): string;
  630. /**
  631. * This method produces very useful error messages. If present, an input
  632. * source map will be used to get the original position of the source, even
  633. * from a previous compilation step (e.g., from Sass compilation).
  634. * @returns The original position of the node in the source, showing line
  635. * and column numbers and also a small excerpt to facilitate debugging.
  636. */
  637. error(
  638. /**
  639. * Error description.
  640. */
  641. message: string, options?: NodeErrorOptions): CssSyntaxError;
  642. /**
  643. * Creates an instance of Warning and adds it to messages. This method is
  644. * provided as a convenience wrapper for Result#warn.
  645. * Note that `opts.node` is automatically passed to Result#warn for you.
  646. * @param result The result that will receive the warning.
  647. * @param text Warning message. It will be used in the `text` property of
  648. * the message object.
  649. * @param opts Properties to assign to the message object.
  650. */
  651. warn(result: Result, text: string, opts?: WarningOptions): void;
  652. /**
  653. * @returns The next child of the node's parent; or, returns undefined if
  654. * the current node is the last child.
  655. */
  656. next(): ChildNode | void;
  657. /**
  658. * @returns The previous child of the node's parent; or, returns undefined
  659. * if the current node is the first child.
  660. */
  661. prev(): ChildNode | void;
  662. /**
  663. * Insert new node before current node to current node’s parent.
  664. *
  665. * Just an alias for `node.parent.insertBefore(node, newNode)`.
  666. *
  667. * @returns this node for method chaining.
  668. *
  669. * @example
  670. * decl.before('content: ""');
  671. */
  672. before(newNode: Node | object | string | Node[]): this;
  673. /**
  674. * Insert new node after current node to current node’s parent.
  675. *
  676. * Just an alias for `node.parent.insertAfter(node, newNode)`.
  677. *
  678. * @returns this node for method chaining.
  679. *
  680. * @example
  681. * decl.after('color: black');
  682. */
  683. after(newNode: Node | object | string | Node[]): this;
  684. /**
  685. * @returns The Root instance of the node's tree.
  686. */
  687. root(): Root;
  688. /**
  689. * Removes the node from its parent and cleans the parent property in the
  690. * node and its children.
  691. * @returns This node for chaining.
  692. */
  693. remove(): this;
  694. /**
  695. * Inserts node(s) before the current node and removes the current node.
  696. * @returns This node for chaining.
  697. */
  698. replaceWith(...nodes: (Node | object)[]): this;
  699. /**
  700. * @param overrides New properties to override in the clone.
  701. * @returns A clone of this node. The node and its (cloned) children will
  702. * have a clean parent and code style properties.
  703. */
  704. clone(overrides?: object): this;
  705. /**
  706. * Shortcut to clone the node and insert the resulting cloned node before
  707. * the current node.
  708. * @param overrides New Properties to override in the clone.
  709. * @returns The cloned node.
  710. */
  711. cloneBefore(overrides?: object): this;
  712. /**
  713. * Shortcut to clone the node and insert the resulting cloned node after
  714. * the current node.
  715. * @param overrides New Properties to override in the clone.
  716. * @returns The cloned node.
  717. */
  718. cloneAfter(overrides?: object): this;
  719. /**
  720. * @param prop Name or code style property.
  721. * @param defaultType Name of default value. It can be easily missed if the
  722. * value is the same as prop.
  723. * @returns A code style property value. If the node is missing the code
  724. * style property (because the node was manually built or cloned), PostCSS
  725. * will try to autodetect the code style property by looking at other nodes
  726. * in the tree.
  727. */
  728. raw(prop: string, defaultType?: string): any;
  729. }
  730. interface NodeNewProps {
  731. source?: NodeSource;
  732. raws?: NodeRaws;
  733. }
  734. interface NodeRaws {
  735. /**
  736. * The space symbols before the node. It also stores `*` and `_`
  737. * symbols before the declaration (IE hack).
  738. */
  739. before?: string;
  740. /**
  741. * The space symbols after the last child of the node to the end of
  742. * the node.
  743. */
  744. after?: string;
  745. /**
  746. * The symbols between the property and value for declarations,
  747. * selector and "{" for rules, last parameter and "{" for at-rules.
  748. */
  749. between?: string;
  750. /**
  751. * True if last child has (optional) semicolon.
  752. */
  753. semicolon?: boolean;
  754. /**
  755. * The space between the at-rule's name and parameters.
  756. */
  757. afterName?: string;
  758. /**
  759. * The space symbols between "/*" and comment's text.
  760. */
  761. left?: string;
  762. /**
  763. * The space symbols between comment's text and "*\/".
  764. */
  765. right?: string;
  766. /**
  767. * The content of important statement, if it is not just "!important".
  768. */
  769. important?: string;
  770. }
  771. interface NodeSource {
  772. input: Input;
  773. /**
  774. * The starting position of the node's source.
  775. */
  776. start?: {
  777. column: number;
  778. line: number;
  779. };
  780. /**
  781. * The ending position of the node's source.
  782. */
  783. end?: {
  784. column: number;
  785. line: number;
  786. };
  787. }
  788. interface NodeErrorOptions {
  789. /**
  790. * Plugin name that created this error. PostCSS will set it automatically.
  791. */
  792. plugin?: string;
  793. /**
  794. * A word inside a node's string, that should be highlighted as source
  795. * of error.
  796. */
  797. word?: string;
  798. /**
  799. * An index inside a node's string that should be highlighted as source
  800. * of error.
  801. */
  802. index?: number;
  803. }
  804. interface JsonNode {
  805. /**
  806. * Returns a string representing the node's type. Possible values are
  807. * root, atrule, rule, decl or comment.
  808. */
  809. type?: string;
  810. /**
  811. * Returns the node's parent node.
  812. */
  813. parent?: JsonContainer;
  814. /**
  815. * Returns the input source of the node. The property is used in source
  816. * map generation. If you create a node manually (e.g., with
  817. * postcss.decl() ), that node will not have a source property and
  818. * will be absent from the source map. For this reason, the plugin
  819. * developer should consider cloning nodes to create new ones (in which
  820. * case the new node's source will reference the original, cloned node)
  821. * or setting the source property manually.
  822. */
  823. source?: NodeSource;
  824. /**
  825. * Contains information to generate byte-to-byte equal node string as it
  826. * was in origin input.
  827. */
  828. raws?: NodeRaws;
  829. }
  830. type Container = Root | AtRule | Rule;
  831. /**
  832. * Containers can store any content. If you write a rule inside a rule,
  833. * PostCSS will parse it.
  834. */
  835. interface ContainerBase extends NodeBase {
  836. /**
  837. * Contains the container's children.
  838. */
  839. nodes?: ChildNode[];
  840. /**
  841. * @returns The container's first child.
  842. */
  843. first?: ChildNode;
  844. /**
  845. * @returns The container's last child.
  846. */
  847. last?: ChildNode;
  848. /**
  849. * @param overrides New properties to override in the clone.
  850. * @returns A clone of this node. The node and its (cloned) children will
  851. * have a clean parent and code style properties.
  852. */
  853. clone(overrides?: object): this;
  854. /**
  855. * @param child Child of the current container.
  856. * @returns The child's index within the container's "nodes" array.
  857. */
  858. index(child: ChildNode | number): number;
  859. /**
  860. * Determines whether all child nodes satisfy the specified test.
  861. * @param callback A function that accepts up to three arguments. The
  862. * every method calls the callback function for each node until the
  863. * callback returns false, or until the end of the array.
  864. * @returns True if the callback returns true for all of the container's
  865. * children.
  866. */
  867. every(callback: (node: ChildNode, index: number, nodes: ChildNode[]) => any, thisArg?: any): boolean;
  868. /**
  869. * Determines whether the specified callback returns true for any child node.
  870. * @param callback A function that accepts up to three arguments. The some
  871. * method calls the callback for each node until the callback returns true,
  872. * or until the end of the array.
  873. * @param thisArg An object to which the this keyword can refer in the
  874. * callback function. If thisArg is omitted, undefined is used as the
  875. * this value.
  876. * @returns True if callback returns true for (at least) one of the
  877. * container's children.
  878. */
  879. some(callback: (node: ChildNode, index: number, nodes: ChildNode[]) => boolean, thisArg?: any): boolean;
  880. /**
  881. * Iterates through the container's immediate children, calling the
  882. * callback function for each child. If you need to recursively iterate
  883. * through all the container's descendant nodes, use container.walk().
  884. * Unlike the for {} -cycle or Array#forEach() this iterator is safe if
  885. * you are mutating the array of child nodes during iteration.
  886. * @param callback Iterator. Returning false will break iteration. Safe
  887. * if you are mutating the array of child nodes during iteration. PostCSS
  888. * will adjust the current index to match the mutations.
  889. * @returns False if the callback returns false during iteration.
  890. */
  891. each(callback: (node: ChildNode, index: number) => any): boolean | void;
  892. /**
  893. * Traverses the container's descendant nodes, calling `callback` for each
  894. * node. Like container.each(), this method is safe to use if you are
  895. * mutating arrays during iteration. If you only need to iterate through
  896. * the container's immediate children, use container.each().
  897. * @param callback Iterator.
  898. */
  899. walk(callback: (node: ChildNode, index: number) => any): boolean | void;
  900. /**
  901. * Traverses the container's descendant nodes, calling `callback` for each
  902. * declaration. Like container.each(), this method is safe to use if you
  903. * are mutating arrays during iteration.
  904. * @param propFilter Filters declarations by property name. Only those
  905. * declarations whose property matches propFilter will be iterated over.
  906. * @param callback Called for each declaration node within the container.
  907. */
  908. walkDecls(propFilter: string | RegExp, callback?: (decl: Declaration, index: number) => any): boolean | void;
  909. walkDecls(callback: (decl: Declaration, index: number) => any): boolean | void;
  910. /**
  911. * Traverses the container's descendant nodes, calling `callback` for each
  912. * at-rule. Like container.each(), this method is safe to use if you are
  913. * mutating arrays during iteration.
  914. * @param nameFilter Filters at-rules by name. If provided, iteration
  915. * will only happen over at-rules that have matching names.
  916. * @param callback Iterator called for each at-rule node within the
  917. * container.
  918. */
  919. walkAtRules(nameFilter: string | RegExp, callback: (atRule: AtRule, index: number) => any): boolean | void;
  920. walkAtRules(callback: (atRule: AtRule, index: number) => any): boolean | void;
  921. /**
  922. * Traverses the container's descendant nodes, calling `callback` for each
  923. * rule. Like container.each(), this method is safe to use if you are
  924. * mutating arrays during iteration.
  925. * @param selectorFilter Filters rules by selector. If provided,
  926. * iteration will only happen over rules that have matching names.
  927. * @param callback Iterator called for each rule node within the
  928. * container.
  929. */
  930. walkRules(selectorFilter: string | RegExp, callback: (atRule: Rule, index: number) => any): boolean | void;
  931. walkRules(callback: (atRule: Rule, index: number) => any): boolean | void;
  932. walkRules(selectorFilter: any, callback?: (atRule: Rule, index: number) => any): boolean | void;
  933. /**
  934. * Traverses the container's descendant nodes, calling `callback` for each
  935. * comment. Like container.each(), this method is safe to use if you are
  936. * mutating arrays during iteration.
  937. * @param callback Iterator called for each comment node within the container.
  938. */
  939. walkComments(callback: (comment: Comment, indexed: number) => any): void | boolean;
  940. /**
  941. * Passes all declaration values within the container that match pattern
  942. * through the callback, replacing those values with the returned result of
  943. * callback. This method is useful if you are using a custom unit or
  944. * function and need to iterate through all values.
  945. * @param pattern Pattern that we need to replace.
  946. * @param options Options to speed up the search.
  947. * @param callbackOrReplaceValue String to replace pattern or callback
  948. * that will return a new value. The callback will receive the same
  949. * arguments as those passed to a function parameter of String#replace.
  950. */
  951. replaceValues(pattern: string | RegExp, options: {
  952. /**
  953. * Property names. The method will only search for values that match
  954. * regexp within declarations of listed properties.
  955. */
  956. props?: string[];
  957. /**
  958. * Used to narrow down values and speed up the regexp search. Searching
  959. * every single value with a regexp can be slow. If you pass a fast
  960. * string, PostCSS will first check whether the value contains the fast
  961. * string; and only if it does will PostCSS check that value against
  962. * regexp. For example, instead of just checking for /\d+rem/ on all
  963. * values, set fast: 'rem' to first check whether a value has the rem
  964. * unit, and only if it does perform the regexp check.
  965. */
  966. fast?: string;
  967. }, callbackOrReplaceValue: string | {
  968. (substring: string, ...args: any[]): string;
  969. }): this;
  970. replaceValues(pattern: string | RegExp, callbackOrReplaceValue: string | {
  971. (substring: string, ...args: any[]): string;
  972. }): this;
  973. /**
  974. * Inserts new nodes to the beginning of the container.
  975. * Because each node class is identifiable by unique properties, use the
  976. * following shortcuts to create nodes in insert methods:
  977. * root.prepend({ name: '@charset', params: '"UTF-8"' }); // at-rule
  978. * root.prepend({ selector: 'a' }); // rule
  979. * rule.prepend({ prop: 'color', value: 'black' }); // declaration
  980. * rule.prepend({ text: 'Comment' }) // comment
  981. * A string containing the CSS of the new element can also be used. This
  982. * approach is slower than the above shortcuts.
  983. * root.prepend('a {}');
  984. * root.first.prepend('color: black; z-index: 1');
  985. * @param nodes New nodes.
  986. * @returns This container for chaining.
  987. */
  988. prepend(...nodes: (Node | object | string)[]): this;
  989. /**
  990. * Inserts new nodes to the end of the container.
  991. * Because each node class is identifiable by unique properties, use the
  992. * following shortcuts to create nodes in insert methods:
  993. * root.append({ name: '@charset', params: '"UTF-8"' }); // at-rule
  994. * root.append({ selector: 'a' }); // rule
  995. * rule.append({ prop: 'color', value: 'black' }); // declaration
  996. * rule.append({ text: 'Comment' }) // comment
  997. * A string containing the CSS of the new element can also be used. This
  998. * approach is slower than the above shortcuts.
  999. * root.append('a {}');
  1000. * root.first.append('color: black; z-index: 1');
  1001. * @param nodes New nodes.
  1002. * @returns This container for chaining.
  1003. */
  1004. append(...nodes: (Node | object | string)[]): this;
  1005. /**
  1006. * Insert newNode before oldNode within the container.
  1007. * @param oldNode Child or child's index.
  1008. * @returns This container for chaining.
  1009. */
  1010. insertBefore(oldNode: ChildNode | number, newNode: ChildNode | object | string): this;
  1011. /**
  1012. * Insert newNode after oldNode within the container.
  1013. * @param oldNode Child or child's index.
  1014. * @returns This container for chaining.
  1015. */
  1016. insertAfter(oldNode: ChildNode | number, newNode: ChildNode | object | string): this;
  1017. /**
  1018. * Removes the container from its parent and cleans the parent property in the
  1019. * container and its children.
  1020. * @returns This container for chaining.
  1021. */
  1022. remove(): this;
  1023. /**
  1024. * Removes child from the container and cleans the parent properties
  1025. * from the node and its children.
  1026. * @param child Child or child's index.
  1027. * @returns This container for chaining.
  1028. */
  1029. removeChild(child: ChildNode | number): this;
  1030. /**
  1031. * Removes all children from the container and cleans their parent
  1032. * properties.
  1033. * @returns This container for chaining.
  1034. */
  1035. removeAll(): this;
  1036. }
  1037. interface ContainerNewProps extends NodeNewProps {
  1038. /**
  1039. * Contains the container's children.
  1040. */
  1041. nodes?: ChildNode[];
  1042. raws?: ContainerRaws;
  1043. }
  1044. interface ContainerRaws extends NodeRaws {
  1045. indent?: string;
  1046. }
  1047. interface JsonContainer extends JsonNode {
  1048. /**
  1049. * Contains the container's children.
  1050. */
  1051. nodes?: ChildNode[];
  1052. /**
  1053. * @returns The container's first child.
  1054. */
  1055. first?: ChildNode;
  1056. /**
  1057. * @returns The container's last child.
  1058. */
  1059. last?: ChildNode;
  1060. }
  1061. /**
  1062. * Represents a CSS file and contains all its parsed nodes.
  1063. */
  1064. interface Root extends ContainerBase {
  1065. type: 'root';
  1066. /**
  1067. * Inherited from Container. Should always be undefined for a Root node.
  1068. */
  1069. parent: void;
  1070. /**
  1071. * @param overrides New properties to override in the clone.
  1072. * @returns A clone of this node. The node and its (cloned) children will
  1073. * have a clean parent and code style properties.
  1074. */
  1075. clone(overrides?: object): this;
  1076. /**
  1077. * @returns A Result instance representing the root's CSS.
  1078. */
  1079. toResult(options?: {
  1080. /**
  1081. * The path where you'll put the output CSS file. You should always
  1082. * set "to" to generate correct source maps.
  1083. */
  1084. to?: string;
  1085. map?: SourceMapOptions;
  1086. }): Result;
  1087. /**
  1088. * Removes child from the root node, and the parent properties of node and
  1089. * its children.
  1090. * @param child Child or child's index.
  1091. * @returns This root node for chaining.
  1092. */
  1093. removeChild(child: ChildNode | number): this;
  1094. }
  1095. interface RootNewProps extends ContainerNewProps {
  1096. }
  1097. interface JsonRoot extends JsonContainer {
  1098. }
  1099. /**
  1100. * Represents an at-rule. If it's followed in the CSS by a {} block, this
  1101. * node will have a nodes property representing its children.
  1102. */
  1103. interface AtRule extends ContainerBase {
  1104. type: 'atrule';
  1105. /**
  1106. * Returns the atrule's parent node.
  1107. */
  1108. parent: Container;
  1109. /**
  1110. * The identifier that immediately follows the @.
  1111. */
  1112. name: string;
  1113. /**
  1114. * These are the values that follow the at-rule's name, but precede any {}
  1115. * block. The spec refers to this area as the at-rule's "prelude".
  1116. */
  1117. params: string;
  1118. /**
  1119. * @param overrides New properties to override in the clone.
  1120. * @returns A clone of this node. The node and its (cloned) children will
  1121. * have a clean parent and code style properties.
  1122. */
  1123. clone(overrides?: object): this;
  1124. }
  1125. interface AtRuleNewProps extends ContainerNewProps {
  1126. /**
  1127. * The identifier that immediately follows the @.
  1128. */
  1129. name?: string;
  1130. /**
  1131. * These are the values that follow the at-rule's name, but precede any {}
  1132. * block. The spec refers to this area as the at-rule's "prelude".
  1133. */
  1134. params?: string | number;
  1135. raws?: AtRuleRaws;
  1136. }
  1137. interface AtRuleRaws extends NodeRaws {
  1138. params?: string;
  1139. }
  1140. interface JsonAtRule extends JsonContainer {
  1141. /**
  1142. * The identifier that immediately follows the @.
  1143. */
  1144. name?: string;
  1145. /**
  1146. * These are the values that follow the at-rule's name, but precede any {}
  1147. * block. The spec refers to this area as the at-rule's "prelude".
  1148. */
  1149. params?: string;
  1150. }
  1151. /**
  1152. * Represents a CSS rule: a selector followed by a declaration block.
  1153. */
  1154. interface Rule extends ContainerBase {
  1155. type: 'rule';
  1156. /**
  1157. * Returns the rule's parent node.
  1158. */
  1159. parent: Container;
  1160. /**
  1161. * The rule's full selector. If there are multiple comma-separated selectors,
  1162. * the entire group will be included.
  1163. */
  1164. selector: string;
  1165. /**
  1166. * An array containing the rule's individual selectors.
  1167. * Groups of selectors are split at commas.
  1168. */
  1169. selectors?: string[];
  1170. /**
  1171. * @param overrides New properties to override in the clone.
  1172. * @returns A clone of this node. The node and its (cloned) children will
  1173. * have a clean parent and code style properties.
  1174. */
  1175. clone(overrides?: object): this;
  1176. }
  1177. interface RuleNewProps extends ContainerNewProps {
  1178. /**
  1179. * The rule's full selector. If there are multiple comma-separated selectors,
  1180. * the entire group will be included.
  1181. */
  1182. selector?: string;
  1183. /**
  1184. * An array containing the rule's individual selectors. Groups of selectors
  1185. * are split at commas.
  1186. */
  1187. selectors?: string[];
  1188. raws?: RuleRaws;
  1189. }
  1190. interface RuleRaws extends ContainerRaws {
  1191. /**
  1192. * The rule's full selector. If there are multiple comma-separated selectors,
  1193. * the entire group will be included.
  1194. */
  1195. selector?: string;
  1196. }
  1197. interface JsonRule extends JsonContainer {
  1198. /**
  1199. * The rule's full selector. If there are multiple comma-separated selectors,
  1200. * the entire group will be included.
  1201. */
  1202. selector?: string;
  1203. /**
  1204. * An array containing the rule's individual selectors.
  1205. * Groups of selectors are split at commas.
  1206. */
  1207. selectors?: string[];
  1208. }
  1209. /**
  1210. * Represents a CSS declaration.
  1211. */
  1212. interface Declaration extends NodeBase {
  1213. type: 'decl';
  1214. /**
  1215. * Returns the declaration's parent node.
  1216. */
  1217. parent: Container;
  1218. /**
  1219. * The declaration's property name.
  1220. */
  1221. prop: string;
  1222. /**
  1223. * The declaration's value. This value will be cleaned of comments. If the
  1224. * source value contained comments, those comments will be available in the
  1225. * _value.raws property. If you have not changed the value, the result of
  1226. * decl.toString() will include the original raws value (comments and all).
  1227. */
  1228. value: string;
  1229. /**
  1230. * True if the declaration has an !important annotation.
  1231. */
  1232. important: boolean;
  1233. /**
  1234. * @param overrides New properties to override in the clone.
  1235. * @returns A clone of this node. The node and its (cloned) children will
  1236. * have a clean parent and code style properties.
  1237. */
  1238. clone(overrides?: object): this;
  1239. }
  1240. interface DeclarationNewProps {
  1241. /**
  1242. * The declaration's property name.
  1243. */
  1244. prop?: string;
  1245. /**
  1246. * The declaration's value. This value will be cleaned of comments. If the
  1247. * source value contained comments, those comments will be available in the
  1248. * _value.raws property. If you have not changed the value, the result of
  1249. * decl.toString() will include the original raws value (comments and all).
  1250. */
  1251. value?: string;
  1252. raws?: DeclarationRaws;
  1253. }
  1254. interface DeclarationRaws extends NodeRaws {
  1255. /**
  1256. * The declaration's value. This value will be cleaned of comments.
  1257. * If the source value contained comments, those comments will be
  1258. * available in the _value.raws property. If you have not changed the value, the result of
  1259. * decl.toString() will include the original raws value (comments and all).
  1260. */
  1261. value?: string;
  1262. }
  1263. interface JsonDeclaration extends JsonNode {
  1264. /**
  1265. * True if the declaration has an !important annotation.
  1266. */
  1267. important?: boolean;
  1268. }
  1269. /**
  1270. * Represents a comment between declarations or statements (rule and at-rules).
  1271. * Comments inside selectors, at-rule parameters, or declaration values will
  1272. * be stored in the Node#raws properties.
  1273. */
  1274. interface Comment extends NodeBase {
  1275. type: 'comment';
  1276. /**
  1277. * Returns the comment's parent node.
  1278. */
  1279. parent: Container;
  1280. /**
  1281. * The comment's text.
  1282. */
  1283. text: string;
  1284. /**
  1285. * @param overrides New properties to override in the clone.
  1286. * @returns A clone of this node. The node and its (cloned) children will
  1287. * have a clean parent and code style properties.
  1288. */
  1289. clone(overrides?: object): this;
  1290. }
  1291. interface CommentNewProps {
  1292. /**
  1293. * The comment's text.
  1294. */
  1295. text?: string;
  1296. }
  1297. interface JsonComment extends JsonNode {
  1298. }
  1299. }
  1300. export = postcss;