@wix/css-property-parser/commonjs/utils/shared-utils.d.ts

A comprehensive TypeScript library for parsing and serializing CSS property values with full MDN specification compliance

/**
 * Shared utility constants and functions for CSS property parsing
 */
import type { LengthValue, PercentageValue, GlobalKeyword } from '../types';
/**
 * Global CSS keywords that are valid for all CSS properties
 * Includes all standard global keywords per CSS specification
 */
export declare const GLOBAL_KEYWORDS: readonly ["inherit", "initial", "unset", "revert", "revert-layer"];
/**
 * Checks if a string is a global CSS keyword
 */
export declare function isGlobalKeyword(value: string): value is GlobalKeyword;
/**
 * Generic type-safe helper to check if a value is in a readonly keyword array
 * Replaces the need for "as any" throughout the codebase
 *
 * @param value - The string value to check
 * @param keywords - The readonly array of valid keywords
 * @returns Type predicate indicating if value is one of the keywords
 */
export declare function isKeywordInArray<T extends readonly string[]>(value: string, keywords: T): value is T[number];
/**
 * Type-safe helper to get a validated keyword from an array
 * Returns the lowercased keyword if valid, null otherwise
 *
 * @param value - The string value to validate
 * @param keywords - The readonly array of valid keywords
 * @returns The validated keyword or null
 */
export declare function getValidKeyword<T extends readonly string[]>(value: string, keywords: T): T[number] | null;
/**
 * Check if a value is a CSS variable
 */
export declare function isCssVariable(value: string): boolean;
/**
 * Check if a parsed length or percentage value is non-negative
 * Used for CSS properties that don't allow negative values
 *
 * @param parsed - The parsed length or percentage value
 * @returns true if non-negative, false otherwise
 */
export declare function isNonNegative(parsed: LengthValue | PercentageValue): boolean;
/**
 * Advanced tokenizer for CSS property values
 * Handles function calls, quoted strings, and nested structures
 *
 * @param value - The CSS property value to tokenize
 * @returns Array of tokens
 */
export declare function tokenize(value: string): string[];
/**
 * Splits a CSS value by commas while respecting function boundaries
 * Useful for parsing multi-value properties like background
 *
 * @param value - The CSS property value to split
 * @returns Array of comma-separated values
 */
export declare function splitByComma(value: string): string[];
/**
 * Splits a string on specific delimiter while respecting function boundaries
 *
 * @param value - The CSS property value to split
 * @param delimiter - The delimiter to split on (default: '/')
 * @returns Array of split values
 */
export declare function splitOnDelimiter(value: string, delimiter?: string): string[];
/**
 * Generic shorthand expansion for CSS properties that follow 1-4 value patterns
 * 1 value: applies to all sides
 * 2 values: top-bottom, left-right (for margin/padding) or top-left-bottom-right, top-right-bottom-left (for border-radius)
 * 3 values: top, left-right, bottom (for margin/padding) or top-left, top-right-bottom-left, bottom-right (for border-radius)
 * 4 values: top, right, bottom, left (clockwise)
 */
export declare function expandShorthandValues(values: string[]): [string, string, string, string];
export type CSSFunctionType = 'calc' | 'min' | 'max' | 'clamp';
export interface CSSFunctionExpression {
    type: 'expression';
    functionType: CSSFunctionType;
    value: string;
}
/**
 * Parse CSS function expressions (calc, min, max, clamp)
 * Returns a structured expression object for supported functions
 *
 * @param value - The CSS value to parse
 * @returns CSSFunctionExpression if valid function, null otherwise
 */
export declare function parseCSSFunction(value: string): CSSFunctionExpression | null;
/**
 * Convert CSS function expression back to CSS string
 *
 * @param parsed - The CSS function expression
 * @returns Original CSS function string
 */
export declare function cssFunctionToCSSValue(parsed: CSSFunctionExpression): string;
/**
 * Clean up JSON string before parsing to handle common formatting issues
 * @param jsonStr - The JSON string to clean up
 * @returns Cleaned JSON string
 */
export declare function cleanupJSON(jsonStr: string): string;
/**
 * Safe JSON parse with cleanup
 * @param jsonStr - The JSON string to parse
 * @returns Parsed JSON object or throws descriptive error
 */
export declare function safeJSONParse(jsonStr: string): unknown;