AK-21/Graphite-Industrial-Intelligence
0
1import AtRule = require('./at-rule.js')2import { AtRuleProps } from './at-rule.js'3import Comment, { CommentProps } from './comment.js'4import Container, { NewChild } from './container.js'5import CssSyntaxError from './css-syntax-error.js'6import Declaration, { DeclarationProps } from './declaration.js'7import Document from './document.js'8import Input from './input.js'9import { Stringifier, Syntax } from './postcss.js'10import Result from './result.js'11import Root from './root.js'12import Rule, { RuleProps } from './rule.js'13import Warning, { WarningOptions } from './warning.js'14 15declare namespace Node {16 export type ChildNode = AtRule.default | Comment | Declaration | Rule17 18 export type AnyNode =19 | AtRule.default20 | Comment21 | Declaration22 | Document23 | Root24 | Rule25 26 export type ChildProps =27 | AtRuleProps28 | CommentProps29 | DeclarationProps30 | RuleProps31 32 export interface Position {33 /**34 * Source line in file. In contrast to `offset` it starts from 1.35 */36 column: number37 38 /**39 * Source column in file.40 */41 line: number42 43 /**44 * Source offset in file. It starts from 0.45 */46 offset: number47 }48 49 export interface Range {50 /**51 * End position, exclusive.52 */53 end: Position54 55 /**56 * Start position, inclusive.57 */58 start: Position59 }60 61 /**62 * Source represents an interface for the {@link Node.source} property.63 */64 export interface Source {65 /**66 * The inclusive ending position for the source67 * code of a node.68 *69 * However, `end.offset` of a non `Root` node is the exclusive position.70 * See https://github.com/postcss/postcss/pull/1879 for details.71 *72 * ```js73 * const root = postcss.parse('a { color: black }')74 * const a = root.first75 * const color = a.first76 *77 * // The offset of `Root` node is the inclusive position78 * css.source.end // { line: 1, column: 19, offset: 18 }79 *80 * // The offset of non `Root` node is the exclusive position81 * a.source.end // { line: 1, column: 18, offset: 18 }82 * color.source.end // { line: 1, column: 16, offset: 16 }83 * ```84 */85 end?: Position86 87 /**88 * The source file from where a node has originated.89 */90 input: Input91 92 /**93 * The inclusive starting position for the source94 * code of a node.95 */96 start?: Position97 }98 99 /**100 * Interface represents an interface for an object received101 * as parameter by Node class constructor.102 */103 export interface NodeProps {104 source?: Source105 }106 107 export interface NodeErrorOptions {108 /**109 * An ending index inside a node's string that should be highlighted as110 * source of error.111 */112 endIndex?: number113 /**114 * An index inside a node's string that should be highlighted as source115 * of error.116 */117 index?: number118 /**119 * Plugin name that created this error. PostCSS will set it automatically.120 */121 plugin?: string122 /**123 * A word inside a node's string, that should be highlighted as source124 * of error.125 */126 word?: string127 }128 129 class Node extends Node_ {}130 export { Node as default }131}132 133/**134 * It represents an abstract class that handles common135 * methods for other CSS abstract syntax tree nodes.136 *137 * Any node that represents CSS selector or value should138 * not extend the `Node` class.139 */140declare abstract class Node_ {141 /**142 * It represents parent of the current node.143 *144 * ```js145 * root.nodes[0].parent === root //=> true146 * ```147 */148 parent: Container | Document | undefined149 150 /**151 * It represents unnecessary whitespace and characters present152 * in the css source code.153 *154 * Information to generate byte-to-byte equal node string as it was155 * in the origin input.156 *157 * The properties of the raws object are decided by parser,158 * the default parser uses the following properties:159 *160 * * `before`: the space symbols before the node. It also stores `*`161 * and `_` symbols before the declaration (IE hack).162 * * `after`: the space symbols after the last child of the node163 * to the end of the node.164 * * `between`: the symbols between the property and value165 * for declarations, selector and `{` for rules, or last parameter166 * and `{` for at-rules.167 * * `semicolon`: contains true if the last child has168 * an (optional) semicolon.169 * * `afterName`: the space between the at-rule name and its parameters.170 * * `left`: the space symbols between `/*` and the comment’s text.171 * * `right`: the space symbols between the comment’s text172 * and <code>*/</code>.173 * - `important`: the content of the important statement,174 * if it is not just `!important`.175 *176 * PostCSS filters out the comments inside selectors, declaration values177 * and at-rule parameters but it stores the origin content in raws.178 *179 * ```js180 * const root = postcss.parse('a {\n color:black\n}')181 * root.first.first.raws //=> { before: '\n ', between: ':' }182 * ```183 */184 raws: any185 186 /**187 * It represents information related to origin of a node and is required188 * for generating source maps.189 *190 * The nodes that are created manually using the public APIs191 * provided by PostCSS will have `source` undefined and192 * will be absent in the source map.193 *194 * For this reason, the plugin developer should consider195 * duplicating nodes as the duplicate node will have the196 * same source as the original node by default or assign197 * source to a node created manually.198 *199 * ```js200 * decl.source.input.from //=> '/home/ai/source.css'201 * decl.source.start //=> { line: 10, column: 2 }202 * decl.source.end //=> { line: 10, column: 12 }203 * ```204 *205 * ```js206 * // Incorrect method, source not specified!207 * const prefixed = postcss.decl({208 * prop: '-moz-' + decl.prop,209 * value: decl.value210 * })211 *212 * // Correct method, source is inherited when duplicating.213 * const prefixed = decl.clone({214 * prop: '-moz-' + decl.prop215 * })216 * ```217 *218 * ```js219 * if (atrule.name === 'add-link') {220 * const rule = postcss.rule({221 * selector: 'a',222 * source: atrule.source223 * })224 *225 * atrule.parent.insertBefore(atrule, rule)226 * }227 * ```228 */229 source?: Node.Source230 231 /**232 * It represents type of a node in233 * an abstract syntax tree.234 *235 * A type of node helps in identification of a node236 * and perform operation based on it's type.237 *238 * ```js239 * const declaration = new Declaration({240 * prop: 'color',241 * value: 'black'242 * })243 *244 * declaration.type //=> 'decl'245 * ```246 */247 type: string248 249 constructor(defaults?: object)250 251 /**252 * Insert new node after current node to current node’s parent.253 *254 * Just alias for `node.parent.insertAfter(node, add)`.255 *256 * ```js257 * decl.after('color: black')258 * ```259 *260 * @param newNode New node.261 * @return This node for methods chain.262 */263 after(264 newNode: Node | Node.ChildProps | readonly Node[] | string | undefined265 ): this266 267 /**268 * It assigns properties to an existing node instance.269 *270 * ```js271 * decl.assign({ prop: 'word-wrap', value: 'break-word' })272 * ```273 *274 * @param overrides New properties to override the node.275 *276 * @return `this` for method chaining.277 */278 assign(overrides: object): this279 280 /**281 * Insert new node before current node to current node’s parent.282 *283 * Just alias for `node.parent.insertBefore(node, add)`.284 *285 * ```js286 * decl.before('content: ""')287 * ```288 *289 * @param newNode New node.290 * @return This node for methods chain.291 */292 before(293 newNode: Node | Node.ChildProps | readonly Node[] | string | undefined294 ): this295 296 /**297 * Clear the code style properties for the node and its children.298 *299 * ```js300 * node.raws.before //=> ' '301 * node.cleanRaws()302 * node.raws.before //=> undefined303 * ```304 *305 * @param keepBetween Keep the `raws.between` symbols.306 */307 cleanRaws(keepBetween?: boolean): void308 309 /**310 * It creates clone of an existing node, which includes all the properties311 * and their values, that includes `raws` but not `type`.312 *313 * ```js314 * decl.raws.before //=> "\n "315 * const cloned = decl.clone({ prop: '-moz-' + decl.prop })316 * cloned.raws.before //=> "\n "317 * cloned.toString() //=> -moz-transform: scale(0)318 * ```319 *320 * @param overrides New properties to override in the clone.321 *322 * @return Duplicate of the node instance.323 */324 clone(overrides?: object): this325 326 /**327 * Shortcut to clone the node and insert the resulting cloned node328 * after the current node.329 *330 * @param overrides New properties to override in the clone.331 * @return New node.332 */333 cloneAfter(overrides?: object): this334 335 /**336 * Shortcut to clone the node and insert the resulting cloned node337 * before the current node.338 *339 * ```js340 * decl.cloneBefore({ prop: '-moz-' + decl.prop })341 * ```342 *343 * @param overrides Mew properties to override in the clone.344 *345 * @return New node346 */347 cloneBefore(overrides?: object): this348 349 /**350 * It creates an instance of the class `CssSyntaxError` and parameters passed351 * to this method are assigned to the error instance.352 *353 * The error instance will have description for the354 * error, original position of the node in the355 * source, showing line and column number.356 *357 * If any previous map is present, it would be used358 * to get original position of the source.359 *360 * The Previous Map here is referred to the source map361 * generated by previous compilation, example: Less,362 * Stylus and Sass.363 *364 * This method returns the error instance instead of365 * throwing it.366 *367 * ```js368 * if (!variables[name]) {369 * throw decl.error(`Unknown variable ${name}`, { word: name })370 * // CssSyntaxError: postcss-vars:a.sass:4:3: Unknown variable $black371 * // color: $black372 * // a373 * // ^374 * // background: white375 * }376 * ```377 *378 * @param message Description for the error instance.379 * @param options Options for the error instance.380 *381 * @return Error instance is returned.382 */383 error(message: string, options?: Node.NodeErrorOptions): CssSyntaxError384 385 /**386 * Returns the next child of the node’s parent.387 * Returns `undefined` if the current node is the last child.388 *389 * ```js390 * if (comment.text === 'delete next') {391 * const next = comment.next()392 * if (next) {393 * next.remove()394 * }395 * }396 * ```397 *398 * @return Next node.399 */400 next(): Node.ChildNode | undefined401 402 /**403 * Get the position for a word or an index inside the node.404 *405 * @param opts Options.406 * @return Position.407 */408 positionBy(opts?: Pick<WarningOptions, 'index' | 'word'>): Node.Position409 410 /**411 * Convert string index to line/column.412 *413 * @param index The symbol number in the node’s string.414 * @return Symbol position in file.415 */416 positionInside(index: number): Node.Position417 418 /**419 * Returns the previous child of the node’s parent.420 * Returns `undefined` if the current node is the first child.421 *422 * ```js423 * const annotation = decl.prev()424 * if (annotation.type === 'comment') {425 * readAnnotation(annotation.text)426 * }427 * ```428 *429 * @return Previous node.430 */431 prev(): Node.ChildNode | undefined432 433 /**434 * Get the range for a word or start and end index inside the node.435 * The start index is inclusive; the end index is exclusive.436 *437 * @param opts Options.438 * @return Range.439 */440 rangeBy(441 opts?: Pick<WarningOptions, 'end' | 'endIndex' | 'index' | 'start' | 'word'>442 ): Node.Range443 444 /**445 * Returns a `raws` value. If the node is missing446 * the code style property (because the node was manually built or cloned),447 * PostCSS will try to autodetect the code style property by looking448 * at other nodes in the tree.449 *450 * ```js451 * const root = postcss.parse('a { background: white }')452 * root.nodes[0].append({ prop: 'color', value: 'black' })453 * root.nodes[0].nodes[1].raws.before //=> undefined454 * root.nodes[0].nodes[1].raw('before') //=> ' '455 * ```456 *457 * @param prop Name of code style property.458 * @param defaultType Name of default value, it can be missed459 * if the value is the same as prop.460 * @return {string} Code style value.461 */462 raw(prop: string, defaultType?: string): string463 464 /**465 * It removes the node from its parent and deletes its parent property.466 *467 * ```js468 * if (decl.prop.match(/^-webkit-/)) {469 * decl.remove()470 * }471 * ```472 *473 * @return `this` for method chaining.474 */475 remove(): this476 477 /**478 * Inserts node(s) before the current node and removes the current node.479 *480 * ```js481 * AtRule: {482 * mixin: atrule => {483 * atrule.replaceWith(mixinRules[atrule.params])484 * }485 * }486 * ```487 *488 * @param nodes Mode(s) to replace current one.489 * @return Current node to methods chain.490 */491 replaceWith(...nodes: NewChild[]): this492 493 /**494 * Finds the Root instance of the node’s tree.495 *496 * ```js497 * root.nodes[0].nodes[0].root() === root498 * ```499 *500 * @return Root parent.501 */502 root(): Root503 504 /**505 * Fix circular links on `JSON.stringify()`.506 *507 * @return Cleaned object.508 */509 toJSON(): object510 511 /**512 * It compiles the node to browser readable cascading style sheets string513 * depending on it's type.514 *515 * ```js516 * new Rule({ selector: 'a' }).toString() //=> "a {}"517 * ```518 *519 * @param stringifier A syntax to use in string generation.520 * @return CSS string of this node.521 */522 toString(stringifier?: Stringifier | Syntax): string523 524 /**525 * It is a wrapper for {@link Result#warn}, providing convenient526 * way of generating warnings.527 *528 * ```js529 * Declaration: {530 * bad: (decl, { result }) => {531 * decl.warn(result, 'Deprecated property: bad')532 * }533 * }534 * ```535 *536 * @param result The `Result` instance that will receive the warning.537 * @param message Description for the warning.538 * @param options Options for the warning.539 *540 * @return `Warning` instance is returned541 */542 warn(result: Result, message: string, options?: WarningOptions): Warning543 544 /**545 * If this node isn't already dirty, marks it and its ancestors as such. This546 * indicates to the LazyResult processor that the {@link Root} has been547 * modified by the current plugin and may need to be processed again by other548 * plugins.549 */550 protected markDirty(): void551}552 553declare class Node extends Node_ {}554 555export = Node556