CSS Value Parsing

/**
 * Prepares stringified value for CSS property assignment
 * @param value - Value to prepare (any type)
 * @param globalObject - Global object for error context (default: globalThis)
 * @returns Prepared string value
 * @throws TypeError for symbols or unconvertible values
 */
function prepareValue(value: any, globalObject?: object): string;

const { prepareValue } = require("cssstyle/lib/parsers");

console.log(prepareValue("  red  ")); // "red" (trimmed)
console.log(prepareValue(42)); // "42"
console.log(prepareValue(null)); // ""
console.log(prepareValue(undefined)); // "undefined"

// Throws TypeError for symbols
try {
  prepareValue(Symbol("test"));
} catch (e) {
  console.log(e.message); // "Can not convert symbol to string."
}

/**
 * Checks if value contains CSS var() function
 * @param val - CSS value to check
 * @returns True if value contains var() function
 */
function hasVarFunc(val: string): boolean;

const { hasVarFunc } = require("cssstyle/lib/parsers");

console.log(hasVarFunc("red")); // false
console.log(hasVarFunc("var(--main-color)")); // true
console.log(hasVarFunc("calc(var(--size) * 2)")); // true
console.log(hasVarFunc("rgb(255, var(--green), 0)")); // true

/**
 * Parses CSS numeric values
 * @param val - Value to parse
 * @param restrictToPositive - If true, negative numbers return undefined
 * @returns Parsed number as string, or undefined if invalid
 */
function parseNumber(val: string, restrictToPositive?: boolean): string | undefined;

const { parseNumber } = require("cssstyle/lib/parsers");

console.log(parseNumber("42")); // "42"
console.log(parseNumber("-3.14")); // "-3.14"
console.log(parseNumber("0")); // "0"
console.log(parseNumber("invalid")); // undefined

// With positive restriction
console.log(parseNumber("-5", true)); // undefined (negative)
console.log(parseNumber("5", true)); // "5"

// CSS variables and calc() pass through
console.log(parseNumber("var(--count)")); // "var(--count)"
console.log(parseNumber("calc(100% - 20px)")); // calculated result

/**
 * Parses CSS length values (px, em, rem, %, etc.)
 * @param val - Length value to parse
 * @param restrictToPositive - If true, negative lengths return undefined
 * @returns Parsed length as string, or undefined if invalid
 */
function parseLength(val: string, restrictToPositive?: boolean): string | undefined;

const { parseLength } = require("cssstyle/lib/parsers");

console.log(parseLength("16px")); // "16px"
console.log(parseLength("2.5em")); // "2.5em"
console.log(parseLength("100%")); // "100%"
console.log(parseLength("0")); // "0px" (zero converts to px)

// Invalid values
console.log(parseLength("16")); // undefined (missing unit for non-zero)
console.log(parseLength("invalid")); // undefined

// With positive restriction
console.log(parseLength("-10px", true)); // undefined
console.log(parseLength("10px", true)); // "10px"

// CSS variables pass through
console.log(parseLength("var(--width)")); // "var(--width)"

/**
 * Parses CSS percentage values
 * @param val - Percentage value to parse
 * @param restrictToPositive - If true, negative percentages return undefined
 * @returns Parsed percentage as string, or undefined if invalid
 */
function parsePercent(val: string, restrictToPositive?: boolean): string | undefined;

const { parsePercent } = require("cssstyle/lib/parsers");

console.log(parsePercent("50%")); // "50%"
console.log(parsePercent("100%")); // "100%"
console.log(parsePercent("0")); // "0%" (zero converts to %)

// Invalid values
console.log(parsePercent("50")); // undefined (missing %)
console.log(parsePercent("50px")); // undefined (wrong unit)

/**
 * Parses CSS measurement values (length or percentage)
 * @param val - Measurement value to parse
 * @param restrictToPositive - If true, negative values return undefined
 * @returns Parsed measurement as string, or undefined if invalid
 */
function parseMeasurement(val: string, restrictToPositive?: boolean): string | undefined;

const { parseMeasurement } = require("cssstyle/lib/parsers");

console.log(parseMeasurement("16px")); // "16px"
console.log(parseMeasurement("50%")); // "50%"
console.log(parseMeasurement("2em")); // "2em"
console.log(parseMeasurement("0")); // "0px"

// Both length and percentage units work
console.log(parseMeasurement("calc(100% - 20px)")); // calculated result

/**
 * Parses CSS angle values (deg, rad, grad, turn)
 * @param val - Angle value to parse
 * @param normalizeDeg - If true, normalizes negative degrees to positive
 * @returns Parsed angle as string, or undefined if invalid
 */
function parseAngle(val: string, normalizeDeg?: boolean): string | undefined;

const { parseAngle } = require("cssstyle/lib/parsers");

console.log(parseAngle("45deg")); // "45deg"
console.log(parseAngle("1.5708rad")); // "1.5708rad"
console.log(parseAngle("0.25turn")); // "0.25turn"
console.log(parseAngle("0")); // "0deg"

// With degree normalization
console.log(parseAngle("-90deg", true)); // "270deg"
console.log(parseAngle("450deg")); // "90deg" (automatically normalized)

/**
 * Parses CSS url() function values
 * @param val - URL value to parse
 * @returns Parsed url() as string, or undefined if invalid
 */
function parseUrl(val: string): string | undefined;

const { parseUrl } = require("cssstyle/lib/parsers");

console.log(parseUrl("url(image.png)")); // 'url("image.png")'
console.log(parseUrl("url('image.png')")); // 'url("image.png")'
console.log(parseUrl('url("image.png")')); // 'url("image.png")'

// Invalid URLs
console.log(parseUrl("image.png")); // undefined (not wrapped in url())
console.log(parseUrl("url(invalid url)")); // undefined (spaces not allowed)

/**
 * Parses CSS string values with quote handling
 * @param val - String value to parse
 * @returns Parsed string with proper escaping, or undefined if invalid
 */
function parseString(val: string): string | undefined;

const { parseString } = require("cssstyle/lib/parsers");

console.log(parseString('"hello world"')); // '"hello world"'
console.log(parseString("'hello world'")); // '"hello world"'
console.log(parseString('"text with \\"quotes\\""')); // '"text with \\"quotes\\""'

// Invalid strings
console.log(parseString("hello")); // undefined (not quoted)
console.log(parseString('"unclosed string')); // undefined

/**
 * Parses CSS keyword values
 * @param val - Keyword value to parse
 * @param validKeywords - Array of valid keyword values (optional)
 * @returns Parsed keyword as lowercase string, or undefined if invalid
 */
function parseKeyword(val: string, validKeywords?: string[]): string | undefined;

const { parseKeyword } = require("cssstyle/lib/parsers");

// Global CSS values are always valid
console.log(parseKeyword("inherit")); // "inherit"
console.log(parseKeyword("initial")); // "initial"
console.log(parseKeyword("unset")); // "unset"

// With valid keywords
console.log(parseKeyword("left", ["left", "right", "center"])); // "left"
console.log(parseKeyword("invalid", ["left", "right", "center"])); // undefined

// CSS variables pass through
console.log(parseKeyword("var(--alignment)")); // "var(--alignment)"

/**
 * Parses CSS color values
 * @param val - Color value to parse
 * @returns Parsed color as string, or undefined if invalid
 */
function parseColor(val: string): string | undefined;

const { parseColor } = require("cssstyle/lib/parsers");

// Named colors
console.log(parseColor("red")); // "red"
console.log(parseColor("transparent")); // "transparent"

// Hex colors
console.log(parseColor("#ff0000")); // "#ff0000"
console.log(parseColor("#f00")); // "#ff0000" (expanded)

// RGB/HSL functions
console.log(parseColor("rgb(255, 0, 0)")); // "rgb(255, 0, 0)"
console.log(parseColor("hsl(0, 100%, 50%)")); // "hsl(0, 100%, 50%)"

// System colors
console.log(parseColor("buttonface")); // "buttonface"
console.log(parseColor("highlight")); // "highlight"

// Invalid colors
console.log(parseColor("not-a-color")); // undefined
console.log(parseColor("#xyz")); // undefined

/**
 * Parses CSS image values (gradients, url(), keywords)
 * @param val - Image value to parse
 * @returns Parsed image as string, or undefined if invalid
 */
function parseImage(val: string): string | undefined;

const { parseImage } = require("cssstyle/lib/parsers");

// URL images
console.log(parseImage("url(image.png)")); // 'url("image.png")'

// Gradients
console.log(parseImage("linear-gradient(to right, red, blue)"));
// Returns normalized gradient syntax

console.log(parseImage("radial-gradient(circle, red, blue)"));
// Returns normalized gradient syntax

// Keywords
console.log(parseImage("none")); // "none"

// Invalid images
console.log(parseImage("invalid")); // undefined

/**
 * Parses CSS function values
 * @param val - Function value to parse
 * @returns Object with name and value properties, or undefined if invalid
 */
function parseFunction(val: string): { name: string; value: string } | undefined;

const { parseFunction } = require("cssstyle/lib/parsers");

console.log(parseFunction("rgb(255, 0, 0)"));
// { name: "rgb", value: "255, 0, 0" }

console.log(parseFunction("calc(100% - 20px)"));
// { name: "calc", value: "100% - 20px" }

console.log(parseFunction("var(--main-color)"));
// { name: "var", value: "--main-color" }

// Invalid functions
console.log(parseFunction("not-a-function")); // undefined
console.log(parseFunction("rgb(incomplete")); // undefined

/**
 * Validates if a property-value pair is valid
 * @param prop - CSS property name
 * @param val - CSS property value
 * @returns True if the property-value pair is valid
 */
function isValidPropertyValue(prop: string, val: string): boolean;

const { isValidPropertyValue } = require("cssstyle/lib/parsers");

// Valid combinations
console.log(isValidPropertyValue("color", "red")); // true
console.log(isValidPropertyValue("font-size", "16px")); // true
console.log(isValidPropertyValue("display", "flex")); // true

// Invalid combinations
console.log(isValidPropertyValue("color", "16px")); // false
console.log(isValidPropertyValue("font-size", "red")); // false

// CSS variables always pass validation
console.log(isValidPropertyValue("color", "var(--main-color)")); // true

/**
 * Validates if a value is a valid color (excludes global values)
 * @param val - Value to validate as color
 * @returns True if the value is a valid color
 */
function isValidColor(val: string): boolean;

const { isValidColor } = require("cssstyle/lib/parsers");

console.log(isValidColor("red")); // true
console.log(isValidColor("#ff0000")); // true
console.log(isValidColor("rgb(255, 0, 0)")); // true

// Global values are not considered valid colors for this function
console.log(isValidColor("inherit")); // false
console.log(isValidColor("initial")); // false

console.log(isValidColor("not-a-color")); // false

/**
 * Splits CSS value into component parts
 * @param val - CSS value to split
 * @returns Array of value components
 */
function splitValue(val: string): string[];

const { splitValue } = require("cssstyle/lib/parsers");

console.log(splitValue("10px 20px 30px 40px"));
// ["10px", "20px", "30px", "40px"]

console.log(splitValue("red blue"));
// ["red", "blue"]

console.log(splitValue("1px solid black"));
// ["1px", "solid", "black"]

// Handles functions and quotes properly
console.log(splitValue('url("image.png") no-repeat center'));
// ['url("image.png")', "no-repeat", "center"]

/**
 * Parses CSS using css-tree parser
 * @param val - CSS text to parse
 * @param opt - Parsing options (context, parseValue, etc.)
 * @param toObject - If true, returns plain object instead of AST
 * @returns CSS AST or plain object
 */
function parseCSS(val: string, opt?: object, toObject?: boolean): any;

const { parseCSS } = require("cssstyle/lib/parsers");

// Parse declaration list
const declarations = parseCSS("color: red; font-size: 16px;", {
  context: "declarationList"
});

// Parse single value
const value = parseCSS("rgb(255, 0, 0)", {
  context: "value"
});

// Get plain object
const obj = parseCSS("color: red;", {
  context: "declarationList"
}, true);