postcss.d.ts 56 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307
  1. declare module "postcss" {
  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. function postcss(plugins?: (typeof postcss.acceptedPlugin)[]): postcss.Processor;
  7. function postcss(...plugins: (typeof postcss.acceptedPlugin)[]): postcss.Processor;
  8. namespace postcss {
  9. var 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: typeof 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: {
  404. generated: {
  405. line: number;
  406. column: number;
  407. };
  408. original: {
  409. line: number;
  410. column: number;
  411. };
  412. /**
  413. * The original source file (relative to the sourceRoot).
  414. */
  415. source: string;
  416. name?: string;
  417. }): void;
  418. /**
  419. * Set the source content for an original source file.
  420. * @param sourceFile The URL of the original source file.
  421. * @param sourceContent The content of the source file.
  422. */
  423. setSourceContent(sourceFile: string, sourceContent: string): void;
  424. /**
  425. * Applies a SourceMap for a source file to the SourceMap. Each mapping to
  426. * the supplied source file is rewritten using the supplied SourceMap.
  427. * Note: The resolution for the resulting mappings is the minimium of this
  428. * map and the supplied map.
  429. * @param sourceMapConsumer The SourceMap to be applied.
  430. * @param sourceFile The filename of the source file. If omitted, sourceMapConsumer
  431. * file will be used, if it exists. Otherwise an error will be thrown.
  432. * @param sourceMapPath The dirname of the path to the SourceMap to be applied.
  433. * If relative, it is relative to the SourceMap. This parameter is needed when
  434. * the two SourceMaps aren't in the same directory, and the SourceMap to be
  435. * applied contains relative source paths. If so, those relative source paths
  436. * need to be rewritten relative to the SourceMap.
  437. * If omitted, it is assumed that both SourceMaps are in the same directory;
  438. * thus, not needing any rewriting (Supplying '.' has the same effect).
  439. */
  440. applySourceMap(sourceMapConsumer: any, sourceFile?: string, sourceMapPath?: string): void;
  441. /**
  442. * Renders the source map being generated to JSON.
  443. */
  444. toJSON: () => any;
  445. /**
  446. * Renders the source map being generated to a string.
  447. */
  448. toString: () => string;
  449. }
  450. interface ResultMessage {
  451. type: string;
  452. text?: string;
  453. plugin?: string;
  454. browsers?: string[];
  455. }
  456. /**
  457. * Represents a plugin warning. It can be created using Result#warn().
  458. */
  459. interface Warning {
  460. /**
  461. * @returns Error position, message.
  462. */
  463. toString(): string;
  464. /**
  465. * Contains the warning message.
  466. */
  467. text: string;
  468. /**
  469. * Contains the name of the plugin that created this warning. When you
  470. * call Result#warn(), it will fill this property automatically.
  471. */
  472. plugin: string;
  473. /**
  474. * The CSS node that caused the warning.
  475. */
  476. node: Node;
  477. /**
  478. * The line in the input file with this warning's source.
  479. */
  480. line: number;
  481. /**
  482. * Column in the input file with this warning's source.
  483. */
  484. column: number;
  485. }
  486. interface WarningOptions extends ResultOptions {
  487. /**
  488. * A word inside a node's string that should be highlighted as source
  489. * of warning.
  490. */
  491. word?: string;
  492. /**
  493. * The index inside a node's string that should be highlighted as
  494. * source of warning.
  495. */
  496. index?: number;
  497. }
  498. /**
  499. * The CSS parser throws this error for broken CSS.
  500. */
  501. interface CssSyntaxError extends InputOrigin {
  502. name: string;
  503. /**
  504. * @returns Error position, message and source code of broken part.
  505. */
  506. toString(): string;
  507. /**
  508. * @param color Whether arrow should be colored red by terminal color codes.
  509. * By default, PostCSS will use process.stdout.isTTY and
  510. * process.env.NODE_DISABLE_COLORS.
  511. * @returns A few lines of CSS source that caused the error. If CSS has
  512. * input source map without sourceContent this method will return an empty
  513. * string.
  514. */
  515. showSourceCode(color?: boolean): string;
  516. /**
  517. * Contains full error text in the GNU error format.
  518. */
  519. message: string;
  520. /**
  521. * Contains only the error description.
  522. */
  523. reason: string;
  524. /**
  525. * Contains the PostCSS plugin name if the error didn't come from the
  526. * CSS parser.
  527. */
  528. plugin?: string;
  529. input?: InputOrigin;
  530. }
  531. interface InputOrigin {
  532. /**
  533. * If parser's from option is set, contains the absolute path to the
  534. * broken file. PostCSS will use the input source map to detect the
  535. * original error location. If you wrote a Sass file, then compiled it
  536. * to CSS and parsed it with PostCSS, PostCSS will show the original
  537. * position in the Sass file. If you need the position in the PostCSS
  538. * input (e.g., to debug the previous compiler), use error.input.file.
  539. */
  540. file?: string;
  541. /**
  542. * Contains the source line of the error. PostCSS will use the input
  543. * source map to detect the original error location. If you wrote a Sass
  544. * file, then compiled it to CSS and parsed it with PostCSS, PostCSS
  545. * will show the original position in the Sass file. If you need the
  546. * position in the PostCSS input (e.g., to debug the previous
  547. * compiler), use error.input.line.
  548. */
  549. line?: number;
  550. /**
  551. * Contains the source column of the error. PostCSS will use input
  552. * source map to detect the original error location. If you wrote a
  553. * Sass file, then compiled it to CSS and parsed it with PostCSS,
  554. * PostCSS will show the original position in the Sass file. If you
  555. * need the position in the PostCSS input (e.g., to debug the
  556. * previous compiler), use error.input.column.
  557. */
  558. column?: number;
  559. /**
  560. * Contains the source code of the broken file. PostCSS will use the
  561. * input source map to detect the original error location. If you wrote
  562. * a Sass file, then compiled it to CSS and parsed it with PostCSS,
  563. * PostCSS will show the original position in the Sass file. If you need
  564. * the position in the PostCSS input (e.g., to debug the previous
  565. * compiler), use error.input.source.
  566. */
  567. source?: string;
  568. }
  569. export class PreviousMap {
  570. private inline;
  571. annotation: string;
  572. root: string;
  573. private consumerCache;
  574. text: string;
  575. file: string;
  576. constructor(css: any, opts: any);
  577. consumer(): any;
  578. withContent(): boolean;
  579. startWith(string: any, start: any): boolean;
  580. loadAnnotation(css: any): void;
  581. decodeInline(text: any): any;
  582. loadMap(file: any, prev: any): any;
  583. isMap(map: any): boolean;
  584. }
  585. /**
  586. * Represents the source CSS.
  587. */
  588. interface Input {
  589. /**
  590. * The absolute path to the CSS source file defined with the "from" option.
  591. */
  592. file: string;
  593. /**
  594. * The unique ID of the CSS source. Used if "from" option is not provided
  595. * (because PostCSS does not know the file path).
  596. */
  597. id: string;
  598. /**
  599. * The CSS source identifier. Contains input.file if the user set the
  600. * "from" option, or input.id if they did not.
  601. */
  602. from: string;
  603. /**
  604. * Represents the input source map passed from a compilation step before
  605. * PostCSS (e.g., from the Sass compiler).
  606. */
  607. map: PreviousMap;
  608. /**
  609. * Reads the input source map.
  610. * @returns A symbol position in the input source (e.g., in a Sass file
  611. * that was compiled to CSS before being passed to PostCSS):
  612. */
  613. origin(line: number, column: number): InputOrigin;
  614. }
  615. interface Node {
  616. /**
  617. * Returns a string representing the node's type. Possible values are
  618. * root, atrule, rule, decl or comment.
  619. */
  620. type: string;
  621. /**
  622. * Returns the node's parent node.
  623. */
  624. parent: Container;
  625. /**
  626. * Returns the input source of the node. The property is used in source
  627. * map generation. If you create a node manually
  628. * (e.g., with postcss.decl() ), that node will not have a source
  629. * property and will be absent from the source map. For this reason, the
  630. * plugin developer should consider cloning nodes to create new ones
  631. * (in which case the new node's source will reference the original,
  632. * cloned node) or setting the source property manually.
  633. */
  634. source: NodeSource;
  635. /**
  636. * Contains information to generate byte-to-byte equal node string as it
  637. * was in origin input.
  638. */
  639. raws: NodeRaws;
  640. /**
  641. * @returns A CSS string representing the node.
  642. */
  643. toString(): string;
  644. /**
  645. * This method produces very useful error messages. If present, an input
  646. * source map will be used to get the original position of the source, even
  647. * from a previous compilation step (e.g., from Sass compilation).
  648. * @returns The original position of the node in the source, showing line
  649. * and column numbers and also a small excerpt to facilitate debugging.
  650. */
  651. error(
  652. /**
  653. * Error description.
  654. */
  655. message: string, options?: NodeErrorOptions): CssSyntaxError;
  656. /**
  657. * Creates an instance of Warning and adds it to messages. This method is
  658. * provided as a convenience wrapper for Result#warn.
  659. * Note that `opts.node` is automatically passed to Result#warn for you.
  660. * @param result The result that will receive the warning.
  661. * @param text Warning message. It will be used in the `text` property of
  662. * the message object.
  663. * @param opts Properties to assign to the message object.
  664. */
  665. warn(result: Result, text: string, opts?: WarningOptions): void;
  666. /**
  667. * @returns The next child of the node's parent; or, returns undefined if
  668. * the current node is the last child.
  669. */
  670. next(): Node;
  671. /**
  672. * @returns The previous child of the node's parent; or, returns undefined
  673. * if the current node is the first child.
  674. */
  675. prev(): Node;
  676. /**
  677. * @returns The Root instance of the node's tree.
  678. */
  679. root(): Root;
  680. /**
  681. * Removes the node from its parent and cleans the parent property in the
  682. * node and its children.
  683. * @returns This node for chaining.
  684. */
  685. remove(): this;
  686. /**
  687. * Inserts node(s) before the current node and removes the current node.
  688. * @returns This node for chaining.
  689. */
  690. replaceWith(...nodes: (Node | Object)[]): this;
  691. /**
  692. * @param overrides New properties to override in the clone.
  693. * @returns A clone of this node. The node and its (cloned) children will
  694. * have a clean parent and code style properties.
  695. */
  696. clone(overrides?: Object): this;
  697. /**
  698. * Shortcut to clone the node and insert the resulting cloned node before
  699. * the current node.
  700. * @param overrides New Properties to override in the clone.
  701. * @returns The cloned node.
  702. */
  703. cloneBefore(overrides?: Object): this;
  704. /**
  705. * Shortcut to clone the node and insert the resulting cloned node after
  706. * the current node.
  707. * @param overrides New Properties to override in the clone.
  708. * @returns The cloned node.
  709. */
  710. cloneAfter(overrides?: Object): this;
  711. /**
  712. * Removes the node from its current parent and inserts it at the end of
  713. * newParent. This will clean the before and after code style properties
  714. * from the node and replace them with the indentation style of newParent.
  715. * It will also clean the between property if newParent is in another Root.
  716. * @param newParent Where the current node will be moved.
  717. * @returns This node for chaining.
  718. */
  719. moveTo(newParent: Container): this;
  720. /**
  721. * Removes the node from its current parent and inserts it into a new
  722. * parent before otherNode. This will also clean the node's code style
  723. * properties just as it would in node.moveTo(newParent).
  724. * @param otherNode Will be after the current node after moving.
  725. * @returns This node for chaining.
  726. */
  727. moveBefore(otherNode: Node): this;
  728. /**
  729. * Removes the node from its current parent and inserts it into a new
  730. * parent after otherNode. This will also clean the node's code style
  731. * properties just as it would in node.moveTo(newParent).
  732. * @param otherNode Will be before the current node after moving.
  733. * @returns This node for chaining.
  734. */
  735. moveAfter(otherNode: Node): this;
  736. /**
  737. * @param prop Name or code style property.
  738. * @param defaultType Name of default value. It can be easily missed if the
  739. * value is the same as prop.
  740. * @returns A code style property value. If the node is missing the code
  741. * style property (because the node was manually built or cloned), PostCSS
  742. * will try to autodetect the code style property by looking at other nodes
  743. * in the tree.
  744. */
  745. raw(prop: string, defaultType?: string): any;
  746. }
  747. interface NodeNewProps {
  748. raws?: NodeRaws;
  749. }
  750. interface NodeRaws {
  751. /**
  752. * The space symbols before the node. It also stores `*` and `_`
  753. * symbols before the declaration (IE hack).
  754. */
  755. before?: string;
  756. /**
  757. * The space symbols after the last child of the node to the end of
  758. * the node.
  759. */
  760. after?: string;
  761. /**
  762. * The symbols between the property and value for declarations,
  763. * selector and "{" for rules, last parameter and "{" for at-rules.
  764. */
  765. between?: string;
  766. /**
  767. * True if last child has (optional) semicolon.
  768. */
  769. semicolon?: boolean;
  770. /**
  771. * The space between the at-rule's name and parameters.
  772. */
  773. afterName?: string;
  774. /**
  775. * The space symbols between "/*" and comment's text.
  776. */
  777. left?: string;
  778. /**
  779. * The space symbols between comment's text and "*\/".
  780. */
  781. right?: string;
  782. /**
  783. * The content of important statement, if it is not just "!important".
  784. */
  785. important?: string;
  786. }
  787. interface NodeSource {
  788. input: Input;
  789. /**
  790. * The starting position of the node's source.
  791. */
  792. start?: {
  793. column: number;
  794. line: number;
  795. };
  796. /**
  797. * The ending position of the node's source.
  798. */
  799. end?: {
  800. column: number;
  801. line: number;
  802. };
  803. }
  804. interface NodeErrorOptions {
  805. /**
  806. * Plugin name that created this error. PostCSS will set it automatically.
  807. */
  808. plugin?: string;
  809. /**
  810. * A word inside a node's string, that should be highlighted as source
  811. * of error.
  812. */
  813. word?: string;
  814. /**
  815. * An index inside a node's string that should be highlighted as source
  816. * of error.
  817. */
  818. index?: number;
  819. }
  820. interface JsonNode {
  821. /**
  822. * Returns a string representing the node's type. Possible values are
  823. * root, atrule, rule, decl or comment.
  824. */
  825. type?: string;
  826. /**
  827. * Returns the node's parent node.
  828. */
  829. parent?: JsonContainer;
  830. /**
  831. * Returns the input source of the node. The property is used in source
  832. * map generation. If you create a node manually (e.g., with
  833. * postcss.decl() ), that node will not have a source property and
  834. * will be absent from the source map. For this reason, the plugin
  835. * developer should consider cloning nodes to create new ones (in which
  836. * case the new node's source will reference the original, cloned node)
  837. * or setting the source property manually.
  838. */
  839. source?: NodeSource;
  840. /**
  841. * Contains information to generate byte-to-byte equal node string as it
  842. * was in origin input.
  843. */
  844. raws?: NodeRaws;
  845. }
  846. /**
  847. * Containers can store any content. If you write a rule inside a rule,
  848. * PostCSS will parse it.
  849. */
  850. interface Container extends Node {
  851. /**
  852. * Returns the container's parent node.
  853. */
  854. parent: Container;
  855. /**
  856. * Contains the container's children.
  857. */
  858. nodes?: Node[];
  859. /**
  860. * @returns The container's first child.
  861. */
  862. first?: Node;
  863. /**
  864. * @returns The container's last child.
  865. */
  866. last?: Node;
  867. /**
  868. * @param overrides New properties to override in the clone.
  869. * @returns A clone of this node. The node and its (cloned) children will
  870. * have a clean parent and code style properties.
  871. */
  872. clone(overrides?: Object): this;
  873. /**
  874. * @param child Child of the current container.
  875. * @returns The child's index within the container's "nodes" array.
  876. */
  877. index(child: Node | number): number;
  878. /**
  879. * Determines whether all child nodes satisfy the specified test.
  880. * @param callback A function that accepts up to three arguments. The
  881. * every method calls the callback function for each node until the
  882. * callback returns false, or until the end of the array.
  883. * @returns True if the callback returns true for all of the container's
  884. * children.
  885. */
  886. every(callback: (node: Node, index: number, nodes: Node[]) => any, thisArg?: any): boolean;
  887. /**
  888. * Determines whether the specified callback returns true for any child node.
  889. * @param callback A function that accepts up to three arguments. The some
  890. * method calls the callback for each node until the callback returns true,
  891. * or until the end of the array.
  892. * @param thisArg An object to which the this keyword can refer in the
  893. * callback function. If thisArg is omitted, undefined is used as the
  894. * this value.
  895. * @returns True if callback returns true for (at least) one of the
  896. * container's children.
  897. */
  898. some(callback: (node: Node, index: number, nodes: Node[]) => boolean, thisArg?: any): boolean;
  899. /**
  900. * Iterates through the container's immediate children, calling the
  901. * callback function for each child. If you need to recursively iterate
  902. * through all the container's descendant nodes, use container.walk().
  903. * Unlike the for {} -cycle or Array#forEach() this iterator is safe if
  904. * you are mutating the array of child nodes during iteration.
  905. * @param callback Iterator. Returning false will break iteration. Safe
  906. * if you are mutating the array of child nodes during iteration. PostCSS
  907. * will adjust the current index to match the mutations.
  908. * @returns False if the callback returns false during iteration.
  909. */
  910. each(callback: (node: Node, index: number) => any): boolean | void;
  911. /**
  912. * Traverses the container's descendant nodes, calling `callback` for each
  913. * node. Like container.each(), this method is safe to use if you are
  914. * mutating arrays during iteration. If you only need to iterate through
  915. * the container's immediate children, use container.each().
  916. * @param callback Iterator.
  917. */
  918. walk(callback: (node: Node, index: number) => any): boolean | void;
  919. /**
  920. * Traverses the container's descendant nodes, calling `callback` for each
  921. * declaration. Like container.each(), this method is safe to use if you
  922. * are mutating arrays during iteration.
  923. * @param propFilter Filters declarations by property name. Only those
  924. * declarations whose property matches propFilter will be iterated over.
  925. * @param callback Called for each declaration node within the container.
  926. */
  927. walkDecls(propFilter: string | RegExp, callback?: (decl: Declaration, index: number) => any): boolean | void;
  928. walkDecls(callback: (decl: Declaration, index: number) => any): boolean | void;
  929. /**
  930. * Traverses the container's descendant nodes, calling `callback` for each
  931. * at-rule. Like container.each(), this method is safe to use if you are
  932. * mutating arrays during iteration.
  933. * @param nameFilter Filters at-rules by name. If provided, iteration
  934. * will only happen over at-rules that have matching names.
  935. * @param callback Iterator called for each at-rule node within the
  936. * container.
  937. */
  938. walkAtRules(nameFilter: string | RegExp, callback: (atRule: AtRule, index: number) => any): boolean | void;
  939. walkAtRules(callback: (atRule: AtRule, index: number) => any): boolean | void;
  940. /**
  941. * Traverses the container's descendant nodes, calling `callback` for each
  942. * rule. Like container.each(), this method is safe to use if you are
  943. * mutating arrays during iteration.
  944. * @param selectorFilter Filters rules by selector. If provided,
  945. * iteration will only happen over rules that have matching names.
  946. * @param callback Iterator called for each rule node within the
  947. * container.
  948. */
  949. walkRules(selectorFilter: string | RegExp, callback: (atRule: Rule, index: number) => any): boolean | void;
  950. walkRules(callback: (atRule: Rule, index: number) => any): boolean | void;
  951. walkRules(selectorFilter: any, callback?: (atRule: Rule, index: number) => any): boolean | void;
  952. /**
  953. * Traverses the container's descendant nodes, calling `callback` for each
  954. * comment. Like container.each(), this method is safe to use if you are
  955. * mutating arrays during iteration.
  956. * @param callback Iterator called for each comment node within the container.
  957. */
  958. walkComments(callback: (comment: Comment, indexed: number) => any): void | boolean;
  959. /**
  960. * Passes all declaration values within the container that match pattern
  961. * through the callback, replacing those values with the returned result of
  962. * callback. This method is useful if you are using a custom unit or
  963. * function and need to iterate through all values.
  964. * @param pattern Pattern that we need to replace.
  965. * @param options Options to speed up the search.
  966. * @param callbackOrReplaceValue String to replace pattern or callback
  967. * that will return a new value. The callback will receive the same
  968. * arguments as those passed to a function parameter of String#replace.
  969. */
  970. replaceValues(pattern: string | RegExp, options: {
  971. /**
  972. * Property names. The method will only search for values that match
  973. * regexp within declarations of listed properties.
  974. */
  975. props?: string[];
  976. /**
  977. * Used to narrow down values and speed up the regexp search. Searching
  978. * every single value with a regexp can be slow. If you pass a fast
  979. * string, PostCSS will first check whether the value contains the fast
  980. * string; and only if it does will PostCSS check that value against
  981. * regexp. For example, instead of just checking for /\d+rem/ on all
  982. * values, set fast: 'rem' to first check whether a value has the rem
  983. * unit, and only if it does perform the regexp check.
  984. */
  985. fast?: string;
  986. }, callbackOrReplaceValue: string | {
  987. (substring: string, ...args: any[]): string;
  988. }): this;
  989. replaceValues(pattern: string | RegExp, callbackOrReplaceValue: string | {
  990. (substring: string, ...args: any[]): string;
  991. }): this;
  992. /**
  993. * Inserts new nodes to the beginning of the container.
  994. * Because each node class is identifiable by unique properties, use the
  995. * following shortcuts to create nodes in insert methods:
  996. * root.prepend({ name: '@charset', params: '"UTF-8"' }); // at-rule
  997. * root.prepend({ selector: 'a' }); // rule
  998. * rule.prepend({ prop: 'color', value: 'black' }); // declaration
  999. * rule.prepend({ text: 'Comment' }) // comment
  1000. * A string containing the CSS of the new element can also be used. This
  1001. * approach is slower than the above shortcuts.
  1002. * root.prepend('a {}');
  1003. * root.first.prepend('color: black; z-index: 1');
  1004. * @param nodes New nodes.
  1005. * @returns This container for chaining.
  1006. */
  1007. prepend(...nodes: (Node | Object | string)[]): this;
  1008. /**
  1009. * Inserts new nodes to the end of the container.
  1010. * Because each node class is identifiable by unique properties, use the
  1011. * following shortcuts to create nodes in insert methods:
  1012. * root.append({ name: '@charset', params: '"UTF-8"' }); // at-rule
  1013. * root.append({ selector: 'a' }); // rule
  1014. * rule.append({ prop: 'color', value: 'black' }); // declaration
  1015. * rule.append({ text: 'Comment' }) // comment
  1016. * A string containing the CSS of the new element can also be used. This
  1017. * approach is slower than the above shortcuts.
  1018. * root.append('a {}');
  1019. * root.first.append('color: black; z-index: 1');
  1020. * @param nodes New nodes.
  1021. * @returns This container for chaining.
  1022. */
  1023. append(...nodes: (Node | Object | string)[]): this;
  1024. /**
  1025. * Insert newNode before oldNode within the container.
  1026. * @param oldNode Child or child's index.
  1027. * @returns This container for chaining.
  1028. */
  1029. insertBefore(oldNode: Node | number, newNode: Node | Object | string): this;
  1030. /**
  1031. * Insert newNode after oldNode within the container.
  1032. * @param oldNode Child or child's index.
  1033. * @returns This container for chaining.
  1034. */
  1035. insertAfter(oldNode: Node | number, newNode: Node | Object | string): this;
  1036. /**
  1037. * Removes the container from its parent and cleans the parent property in the
  1038. * container and its children.
  1039. * @returns This container for chaining.
  1040. */
  1041. remove(): this;
  1042. /**
  1043. * Removes child from the container and cleans the parent properties
  1044. * from the node and its children.
  1045. * @param child Child or child's index.
  1046. * @returns This container for chaining.
  1047. */
  1048. removeChild(child: Node | number): this;
  1049. /**
  1050. * Removes all children from the container and cleans their parent
  1051. * properties.
  1052. * @returns This container for chaining.
  1053. */
  1054. removeAll(): this;
  1055. }
  1056. interface ContainerNewProps extends NodeNewProps {
  1057. /**
  1058. * Contains the container's children.
  1059. */
  1060. nodes?: Node[];
  1061. raws?: ContainerRaws;
  1062. }
  1063. interface ContainerRaws extends NodeRaws {
  1064. indent?: string;
  1065. }
  1066. interface JsonContainer extends JsonNode {
  1067. /**
  1068. * Contains the container's children.
  1069. */
  1070. nodes?: Node[];
  1071. /**
  1072. * @returns The container's first child.
  1073. */
  1074. first?: Node;
  1075. /**
  1076. * @returns The container's last child.
  1077. */
  1078. last?: Node;
  1079. }
  1080. /**
  1081. * Represents a CSS file and contains all its parsed nodes.
  1082. */
  1083. interface Root extends Container {
  1084. /**
  1085. * Inherited from Container. Should always be undefined for a Root node.
  1086. */
  1087. parent: Container;
  1088. /**
  1089. * @param overrides New properties to override in the clone.
  1090. * @returns A clone of this node. The node and its (cloned) children will
  1091. * have a clean parent and code style properties.
  1092. */
  1093. clone(overrides?: Object): this;
  1094. /**
  1095. * @returns A Result instance representing the root's CSS.
  1096. */
  1097. toResult(options?: {
  1098. /**
  1099. * The path where you'll put the output CSS file. You should always
  1100. * set "to" to generate correct source maps.
  1101. */
  1102. to?: string;
  1103. map?: SourceMapOptions;
  1104. }): Result;
  1105. /**
  1106. * Deprecated. Use Root#removeChild.
  1107. */
  1108. remove(child?: Node | number): this;
  1109. /**
  1110. * Removes child from the root node, and the parent properties of node and
  1111. * its children.
  1112. * @param child Child or child's index.
  1113. * @returns This root node for chaining.
  1114. */
  1115. removeChild(child: Node | number): this;
  1116. }
  1117. interface RootNewProps extends ContainerNewProps {
  1118. }
  1119. interface JsonRoot extends JsonContainer {
  1120. }
  1121. /**
  1122. * Represents an at-rule. If it's followed in the CSS by a {} block, this
  1123. * node will have a nodes property representing its children.
  1124. */
  1125. interface AtRule extends Container {
  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;
  1135. /**
  1136. * @param overrides New properties to override in the clone.
  1137. * @returns A clone of this node. The node and its (cloned) children will
  1138. * have a clean parent and code style properties.
  1139. */
  1140. clone(overrides?: Object): this;
  1141. }
  1142. interface AtRuleNewProps extends ContainerNewProps {
  1143. /**
  1144. * The identifier that immediately follows the @.
  1145. */
  1146. name?: string;
  1147. /**
  1148. * These are the values that follow the at-rule's name, but precede any {}
  1149. * block. The spec refers to this area as the at-rule's "prelude".
  1150. */
  1151. params?: string | number;
  1152. raws?: AtRuleRaws;
  1153. }
  1154. interface AtRuleRaws extends NodeRaws {
  1155. params?: string;
  1156. }
  1157. interface JsonAtRule extends JsonContainer {
  1158. /**
  1159. * The identifier that immediately follows the @.
  1160. */
  1161. name?: string;
  1162. /**
  1163. * These are the values that follow the at-rule's name, but precede any {}
  1164. * block. The spec refers to this area as the at-rule's "prelude".
  1165. */
  1166. params?: string;
  1167. }
  1168. /**
  1169. * Represents a CSS rule: a selector followed by a declaration block.
  1170. */
  1171. interface Rule extends Container {
  1172. /**
  1173. * Returns the rule's parent node.
  1174. */
  1175. parent: Container;
  1176. /**
  1177. * The rule's full selector. If there are multiple comma-separated selectors,
  1178. * the entire group will be included.
  1179. */
  1180. selector: string;
  1181. /**
  1182. * An array containing the rule's individual selectors.
  1183. * Groups of selectors are split at commas.
  1184. */
  1185. selectors?: string[];
  1186. /**
  1187. * @param overrides New properties to override in the clone.
  1188. * @returns A clone of this node. The node and its (cloned) children will
  1189. * have a clean parent and code style properties.
  1190. */
  1191. clone(overrides?: Object): this;
  1192. }
  1193. interface RuleNewProps extends ContainerNewProps {
  1194. /**
  1195. * The rule's full selector. If there are multiple comma-separated selectors,
  1196. * the entire group will be included.
  1197. */
  1198. selector?: string;
  1199. /**
  1200. * An array containing the rule's individual selectors. Groups of selectors
  1201. * are split at commas.
  1202. */
  1203. selectors?: string[];
  1204. raws?: RuleRaws;
  1205. }
  1206. interface RuleRaws extends ContainerRaws {
  1207. /**
  1208. * The rule's full selector. If there are multiple comma-separated selectors,
  1209. * the entire group will be included.
  1210. */
  1211. selector?: string;
  1212. }
  1213. interface JsonRule extends JsonContainer {
  1214. /**
  1215. * The rule's full selector. If there are multiple comma-separated selectors,
  1216. * the entire group will be included.
  1217. */
  1218. selector?: string;
  1219. /**
  1220. * An array containing the rule's individual selectors.
  1221. * Groups of selectors are split at commas.
  1222. */
  1223. selectors?: string[];
  1224. }
  1225. /**
  1226. * Represents a CSS declaration.
  1227. */
  1228. interface Declaration extends Node {
  1229. /**
  1230. * The declaration's property name.
  1231. */
  1232. prop: string;
  1233. /**
  1234. * The declaration's value. This value will be cleaned of comments. If the
  1235. * source value contained comments, those comments will be available in the
  1236. * _value.raws property. If you have not changed the value, the result of
  1237. * decl.toString() will include the original raws value (comments and all).
  1238. */
  1239. value: string;
  1240. /**
  1241. * True if the declaration has an !important annotation.
  1242. */
  1243. important: boolean;
  1244. /**
  1245. * @param overrides New properties to override in the clone.
  1246. * @returns A clone of this node. The node and its (cloned) children will
  1247. * have a clean parent and code style properties.
  1248. */
  1249. clone(overrides?: Object): this;
  1250. }
  1251. interface DeclarationNewProps {
  1252. /**
  1253. * The declaration's property name.
  1254. */
  1255. prop?: string;
  1256. /**
  1257. * The declaration's value. This value will be cleaned of comments. If the
  1258. * source value contained comments, those comments will be available in the
  1259. * _value.raws property. If you have not changed the value, the result of
  1260. * decl.toString() will include the original raws value (comments and all).
  1261. */
  1262. value?: string;
  1263. raws?: DeclarationRaws;
  1264. }
  1265. interface DeclarationRaws extends NodeRaws {
  1266. /**
  1267. * The declaration's value. This value will be cleaned of comments.
  1268. * If the source value contained comments, those comments will be
  1269. * available in the _value.raws property. If you have not changed the value, the result of
  1270. * decl.toString() will include the original raws value (comments and all).
  1271. */
  1272. value?: string;
  1273. }
  1274. interface JsonDeclaration extends JsonNode {
  1275. /**
  1276. * True if the declaration has an !important annotation.
  1277. */
  1278. important?: boolean;
  1279. }
  1280. /**
  1281. * Represents a comment between declarations or statements (rule and at-rules).
  1282. * Comments inside selectors, at-rule parameters, or declaration values will
  1283. * be stored in the Node#raws properties.
  1284. */
  1285. interface Comment extends Node {
  1286. /**
  1287. * The comment's text.
  1288. */
  1289. text: string;
  1290. /**
  1291. * @param overrides New properties to override in the clone.
  1292. * @returns A clone of this node. The node and its (cloned) children will
  1293. * have a clean parent and code style properties.
  1294. */
  1295. clone(overrides?: Object): this;
  1296. }
  1297. interface CommentNewProps {
  1298. /**
  1299. * The comment's text.
  1300. */
  1301. text?: string;
  1302. }
  1303. interface JsonComment extends JsonNode {
  1304. }
  1305. }
  1306. export = postcss;
  1307. }