PostCSS Value Parser

const valueParser = require('postcss-value-parser');

import valueParser from 'postcss-value-parser';

const valueParser = require('postcss-value-parser');

// Parse a CSS value
const cssValue = 'rgba(233, 45, 66, .5) no-repeat center/contain';
const parsed = valueParser(cssValue);

// Walk through all nodes
parsed.walk(function(node) {
  if (node.type === 'function' && node.value === 'rgba') {
    // Transform rgba() to hex
    const values = node.nodes.filter(n => n.type === 'word').map(n => n.value);
    node.type = 'word';
    node.value = '#E92D42';
  }
});

// Convert back to CSS string
console.log(parsed.toString()); // "#E92D42 no-repeat center/contain"

/**
 * Parse a CSS value into a series of nodes
 * Can be called as function or constructor
 * @param value - The CSS value string to parse
 * @returns ParsedValue instance with nodes array and methods
 */
function valueParser(value: string): ParsedValue;

/**
 * Constructor form of the parser
 * @param value - The CSS value string to parse
 * @returns ParsedValue instance
 */
new valueParser(value: string): ParsedValue;

interface ParsedValue {
  /** Array of parsed nodes */
  nodes: Node[];
  /** Convert parsed nodes back to CSS string */
  toString(): string;
  /** Walk all parsed nodes with callback function */
  walk(callback: WalkCallback, bubble?: boolean): this;
}

// Parse background shorthand - both patterns work
const parsed1 = valueParser('url(bg.jpg) no-repeat 50% 75%');
const parsed2 = new valueParser('url(bg.jpg) no-repeat 50% 75%');
console.log(parsed1.nodes.length); // 7 nodes

// Parse function with parameters
const rgba = valueParser('rgba(255, 0, 128, 0.5)');
console.log(rgba.nodes[0].type); // 'function'
console.log(rgba.nodes[0].value); // 'rgba'
console.log(rgba.nodes[0].nodes.length); // 7 (4 values + 3 dividers)

/**
 * Walk all parsed nodes, applying callback function
 * @param callback - Visitor function called for each node
 * @param bubble - When true, traverse inside-out instead of outside-in
 * @returns this (chainable)
 */
walk(callback: WalkCallback, bubble?: boolean): this;

/**
 * Static walk function for node arrays
 * @param nodes - Array of nodes to walk
 * @param callback - Visitor function called for each node  
 * @param bubble - When true, traverse inside-out instead of outside-in
 */
function walk(nodes: Node[], callback: WalkCallback, bubble?: boolean): void;

interface WalkCallback {
  /**
   * @param node - Current node being visited
   * @param index - Index of node in parent's nodes array
   * @param nodes - Parent's complete nodes array
   * @returns Returning false prevents traversal of descendant nodes (only when bubble=false)
   */
  (node: Node, index: number, nodes: Node[]): void | boolean;
}

// Find and modify all function calls
parsed.walk(function(node) {
  if (node.type === 'function') {
    console.log(`Found function: ${node.value}`);
    // Modify function name
    node.value = 'new-' + node.value;
  }
});

// Shallow walk (don't traverse into functions)
parsed.walk(function(node) {
  console.log(node.type);
  if (node.type === 'function') {
    return false; // Skip function contents
  }
}, false);

// Reverse traversal (inside-out)
parsed.walk(function(node) {
  console.log(node.value);
}, true);

/**
 * Convert parsed nodes back to CSS string
 * @returns Reconstructed CSS value string
 */
toString(): string;

/**
 * Static stringify function for nodes
 * @param nodes - Node or array of nodes to stringify
 * @param custom - Optional custom stringifier callback
 * @returns CSS string representation
 */
function stringify(nodes: Node | Node[], custom?: CustomStringifierCallback): string;

interface CustomStringifierCallback {
  /**
   * @param node - Node to stringify
   * @returns Custom string representation, or undefined to use default
   */
  (node: Node): string | undefined;
}

// Basic stringification
const cssString = parsed.toString();

// Custom stringification
const customCss = valueParser.stringify(parsed.nodes, function(node) {
  if (node.type === 'function' && node.value === 'rgb') {
    // Convert rgb() to hex
    return '#FF0000';
  }
  // Return undefined to use default stringification
});

/**
 * Parse CSS dimension into numeric and unit parts
 * @param value - CSS dimension string (e.g., "2rem", "100px", "1.5em")
 * @returns Dimension object with number and unit, or false if parsing fails
 */
function unit(value: string): Dimension | false;

interface Dimension {
  /** Numeric part as string (preserves original precision) */
  number: string;
  /** Unit part as string (empty string for unitless numbers) */
  unit: string;
}

// Parse various dimensions
console.log(valueParser.unit('2rem'));      // { number: '2', unit: 'rem' }
console.log(valueParser.unit('100px'));     // { number: '100', unit: 'px' }  
console.log(valueParser.unit('1.5em'));     // { number: '1.5', unit: 'em' }
console.log(valueParser.unit('50'));        // { number: '50', unit: '' }
console.log(valueParser.unit('auto'));      // false (not a dimension)

// Use in node walking
parsed.walk(function(node) {
  if (node.type === 'word') {
    const dimension = valueParser.unit(node.value);
    if (dimension && dimension.unit === 'px') {
      // Convert px to rem
      const remValue = parseFloat(dimension.number) / 16;
      node.value = remValue + 'rem';
    }
  }
});

interface BaseNode {
  /** Node type identifier */
  type: string;
  /** The node's characteristic value */
  value: string;
  /** Start position in original CSS string (inclusive) */
  sourceIndex: number;
  /** End position in original CSS string (exclusive) */
  sourceEndIndex: number;
}

/** Mixin interface for nodes that can be unclosed */
interface ClosableNode {
  /** True if the node was not properly closed in CSS */
  unclosed?: true;
}

/** Mixin interface for nodes with adjacent whitespace */
interface AdjacentAwareNode {
  /** Whitespace before the node content */
  before: string;
  /** Whitespace after the node content */
  after: string;
}

interface WordNode extends BaseNode {
  type: 'word';
  /** The word value (e.g., 'no-repeat', '20px', '#e6e6e6') */
  value: string;
}

interface StringNode extends BaseNode, ClosableNode {
  type: 'string';
  /** Text content without quotes */
  value: string;
  /** Quote character used (" or ') */
  quote: '"' | "'";
}

interface FunctionNode extends BaseNode, ClosableNode, AdjacentAwareNode {
  type: 'function';
  /** Function name (e.g., 'rgb', 'url', 'calc') */
  value: string;
  /** Child nodes representing function arguments */
  nodes: Node[];
}

interface DivNode extends BaseNode, AdjacentAwareNode {
  type: 'div';
  /** Divider character (',', '/', or ':') */
  value: ',' | '/' | ':';
}

interface SpaceNode extends BaseNode {
  type: 'space';
  /** Whitespace characters */
  value: string;
}

interface CommentNode extends BaseNode, ClosableNode {
  type: 'comment';
  /** Comment content without /* and */ delimiters */
  value: string;
}

interface UnicodeRangeNode extends BaseNode {
  type: 'unicode-range';
  /** Unicode range value (e.g., 'U+0025-00FF') used in @font-face rules */
  value: string;
}

type Node = 
  | WordNode 
  | StringNode 
  | FunctionNode 
  | DivNode 
  | SpaceNode 
  | CommentNode 
  | UnicodeRangeNode;

/** CSS dimension parsing utility */
valueParser.unit: (value: string) => Dimension | false;

/** Static tree walking utility */
valueParser.walk: (nodes: Node[], callback: WalkCallback, bubble?: boolean) => void;

/** Static stringification utility */
valueParser.stringify: (nodes: Node | Node[], custom?: CustomStringifierCallback) => string;