postcss.d.ts 51 KB

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