@ismail-elkorchi/css-parser 0.1.1 → 0.2.0

package/dist/internal/properties/matcher.js

@@ -0,0 +1,791 @@
+import { CSS_WEBREF_DATA } from "../generated/css-data.js";
+import { parseCssValueDefinition } from "../grammar/value-definition.js";
+import { resolveCssProperty } from "./registry.js";
+import { ResourceGuard } from "../syntax/resources.js";
+const CSS_WIDE_KEYWORDS = new Set([
+    "initial",
+    "inherit",
+    "unset",
+    "revert",
+    "revert-layer",
+    "revert-rule"
+]);
+const LENGTH_UNITS = new Set([
+    "cap", "ch", "cm", "dvb", "dvh", "dvi", "dvmax", "dvmin", "dvw",
+    "em", "ex", "ic", "in", "lh", "lvb", "lvh", "lvi", "lvmax", "lvmin",
+    "lvw", "mm", "pc", "pt", "px", "q", "rcap", "rch", "rem", "rex", "ric",
+    "rlh", "svb", "svh", "svi", "svmax", "svmin", "svw", "vb", "vh", "vi",
+    "vmax", "vmin", "vw"
+]);
+const ANGLE_UNITS = new Set(["deg", "grad", "rad", "turn"]);
+const TIME_UNITS = new Set(["ms", "s"]);
+const FREQUENCY_UNITS = new Set(["hz", "khz"]);
+const RESOLUTION_UNITS = new Set(["dpcm", "dpi", "dppx", "x"]);
+const FLEX_UNITS = new Set(["fr"]);
+const MATH_FUNCTIONS = new Set([
+    "abs", "acos", "asin", "atan", "atan2", "calc", "clamp", "cos", "exp",
+    "hypot", "log", "max", "min", "mod", "pow", "progress", "random",
+    "random-item-mix", "rem", "round", "sign", "sin", "sqrt", "tan"
+]);
+const BORDER_STYLES = new Set([
+    "none", "hidden", "dotted", "dashed", "solid", "double", "groove",
+    "ridge", "inset", "outset"
+]);
+const BORDER_WIDTH_KEYWORDS = new Set(["hairline", "thin", "medium", "thick"]);
+const CSS_GENERIC_KEYWORD_EXCLUSIONS = new Set([...CSS_WIDE_KEYWORDS, "default"]);
+const DEFAULT_MAX_STEPS = 250_000;
+const PAINT_SYNTAX = "none | <color> | <url> [ none | <color> ]? | context-fill | context-stroke | <image> | <svg-paint>";
+const TYPE_DATA = groupGrammarData(CSS_WEBREF_DATA.types);
+const FUNCTION_DATA = groupGrammarData(CSS_WEBREF_DATA.functions);
+const GRAMMAR_CACHE = new Map();
+function groupGrammarData(entries) {
+    const grouped = new Map();
+    for (const entry of entries) {
+        const values = grouped.get(entry.name);
+        if (values === undefined)
+            grouped.set(entry.name, [entry]);
+        else
+            values.push(entry);
+    }
+    return grouped;
+}
+function grammar(source) {
+    const cached = GRAMMAR_CACHE.get(source);
+    if (cached !== undefined)
+        return cached;
+    const parsed = parseCssValueDefinition(source);
+    GRAMMAR_CACHE.set(source, parsed);
+    return parsed;
+}
+function lowerAscii(value) {
+    return value.replace(/[A-Z]/gu, (character) => character.toLowerCase());
+}
+function significant(values) {
+    return Object.freeze(values.filter((value) => value.kind !== "whitespace"));
+}
+function result(ends = [], unsupported = []) {
+    return {
+        ends: new Set(ends),
+        unsupported: new Set(unsupported)
+    };
+}
+function mergeResults(results) {
+    const ends = new Set();
+    const unsupported = new Set();
+    for (const item of results) {
+        for (const end of item.ends)
+            ends.add(end);
+        for (const name of item.unsupported)
+            unsupported.add(name);
+    }
+    return { ends, unsupported };
+}
+function singleEnd(end) {
+    return result([end]);
+}
+function emptyResult() {
+    return result();
+}
+class PropertyGrammarMatcher {
+    #guard;
+    #arrayIds = new WeakMap();
+    #activeReferences = new Set();
+    #nextArrayId = 1;
+    constructor(options) {
+        this.#guard = new ResourceGuard({ maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS }, options.signal);
+    }
+    match(definition, values) {
+        return this.#match(definition, values, 0);
+    }
+    usage() {
+        return this.#guard.snapshot();
+    }
+    step() {
+        this.#guard.step();
+    }
+    #match(definition, values, start) {
+        this.#guard.step();
+        switch (definition.kind) {
+            case "keyword":
+                return this.#matchKeyword(definition.value, values, start);
+            case "literal":
+                return this.#matchLiteral(definition.value, values, start);
+            case "reference":
+                return this.#matchReference(definition, values, start);
+            case "function":
+                return this.#matchFunction(definition.name, definition.value, values, start);
+            case "sequence":
+                return this.#matchSequence(definition.values, values, start);
+            case "one-of":
+                return mergeResults(definition.values.map((value) => this.#match(value, values, start)));
+            case "all-of":
+                return this.#matchShuffle(definition.values, values, start, true);
+            case "any-of":
+                return this.#matchShuffle(definition.values, values, start, false);
+            case "multiplier":
+                return this.#matchMultiplier(definition, values, start);
+            case "required":
+                return this.#match(definition.value, values, start);
+        }
+    }
+    #matchSequence(definitions, values, start) {
+        const ends = new Set();
+        const unsupported = new Set();
+        this.#matchSequenceFrom(definitions, values, 0, start, false, false, ends, unsupported, new Set());
+        return result(ends, unsupported);
+    }
+    #matchSequenceFrom(definitions, values, definitionIndex, position, hasContent, contentSinceComma, ends, unsupported, visited) {
+        this.#guard.step();
+        const state = [
+            definitionIndex,
+            position,
+            hasContent ? 1 : 0,
+            contentSinceComma ? 1 : 0
+        ].join(":");
+        if (visited.has(state))
+            return;
+        visited.add(state);
+        if (definitionIndex === definitions.length) {
+            ends.add(position);
+            return;
+        }
+        const definition = definitions[definitionIndex];
+        if (definition === undefined)
+            return;
+        const comma = definition.kind === "literal" && definition.value === ",";
+        const matched = this.#match(definition, values, position);
+        for (const name of matched.unsupported)
+            unsupported.add(name);
+        for (const end of matched.ends) {
+            const consumed = end > position;
+            this.#matchSequenceFrom(definitions, values, definitionIndex + 1, end, hasContent || (consumed && !comma), comma && consumed ? false : contentSinceComma || consumed, ends, unsupported, visited);
+        }
+        if (comma &&
+            (!hasContent ||
+                !contentSinceComma ||
+                this.#sequenceSuffixCanBeEmpty(definitions, definitionIndex + 1))) {
+            this.#matchSequenceFrom(definitions, values, definitionIndex + 1, position, hasContent, contentSinceComma, ends, unsupported, visited);
+        }
+    }
+    #sequenceSuffixCanBeEmpty(definitions, start) {
+        for (let index = start; index < definitions.length; index += 1) {
+            const definition = definitions[index];
+            if (definition !== undefined && !this.#canBeEmpty(definition))
+                return false;
+        }
+        return true;
+    }
+    #canBeEmpty(definition) {
+        switch (definition.kind) {
+            case "multiplier":
+                return definition.minimum === 0;
+            case "sequence":
+            case "all-of":
+                return definition.values.every((value) => this.#canBeEmpty(value));
+            case "one-of":
+            case "any-of":
+                return definition.values.some((value) => this.#canBeEmpty(value));
+            case "required":
+            case "keyword":
+            case "literal":
+            case "reference":
+            case "function":
+                return false;
+        }
+    }
+    #matchMultiplier(definition, values, start) {
+        const ends = new Set();
+        const unsupported = new Set();
+        let states = new Set([start]);
+        const inputBound = values.length - start + 1;
+        const maximum = Math.min(definition.maximum, inputBound);
+        for (let count = 0; count <= maximum; count += 1) {
+            this.#guard.step();
+            if (count >= definition.minimum) {
+                for (const state of states)
+                    ends.add(state);
+            }
+            if (count === maximum || states.size === 0)
+                break;
+            const next = new Set();
+            for (const state of states) {
+                let itemStart = state;
+                if (count > 0 && definition.separator === "comma") {
+                    if (values[state]?.kind !== "comma")
+                        continue;
+                    itemStart += 1;
+                }
+                const matched = this.#matchRepeatedItem(definition.value, values, itemStart, definition.separator);
+                for (const end of matched.ends) {
+                    if (end > state)
+                        next.add(end);
+                }
+                for (const name of matched.unsupported)
+                    unsupported.add(name);
+            }
+            states = next;
+        }
+        return result(ends, unsupported);
+    }
+    #matchRepeatedItem(definition, values, start, separator) {
+        if (separator === "space")
+            return this.#match(definition, values, start);
+        const nextComma = values.findIndex((value, index) => index >= start && value.kind === "comma");
+        const boundary = nextComma < 0 ? values.length : nextComma;
+        const item = values.slice(start, boundary);
+        const isolated = this.#match(definition, item, 0);
+        if (isolated.ends.has(item.length)) {
+            return result([boundary], isolated.unsupported);
+        }
+        return mergeResults([
+            result([], isolated.unsupported),
+            this.#match(definition, values, start)
+        ]);
+    }
+    #matchShuffle(definitions, values, start, requireAll) {
+        const ends = new Set();
+        const unsupported = new Set();
+        this.#permuteCombination(definitions, values, start, Array.from({ length: definitions.length }, () => false), 0, requireAll, ends, unsupported, new Set());
+        return result(ends, unsupported);
+    }
+    #permuteCombination(definitions, values, position, used, usedCount, requireAll, ends, unsupported, visited) {
+        this.#guard.step();
+        const state = `${String(position)}:${used.map((value) => value ? "1" : "0").join("")}`;
+        if (visited.has(state))
+            return;
+        visited.add(state);
+        if ((requireAll && usedCount === definitions.length) || (!requireAll && usedCount > 0)) {
+            ends.add(position);
+        }
+        if (usedCount === definitions.length)
+            return;
+        for (let itemIndex = 0; itemIndex < definitions.length; itemIndex += 1) {
+            if (used[itemIndex] === true)
+                continue;
+            const definition = definitions[itemIndex];
+            if (definition === undefined)
+                continue;
+            const matched = this.#match(definition, values, position);
+            for (const name of matched.unsupported)
+                unsupported.add(name);
+            used[itemIndex] = true;
+            for (const end of matched.ends) {
+                this.#permuteCombination(definitions, values, end, used, usedCount + 1, requireAll, ends, unsupported, visited);
+            }
+            used[itemIndex] = false;
+        }
+    }
+    #matchKeyword(keyword, values, start) {
+        const value = values[start];
+        if (value === undefined)
+            return emptyResult();
+        if (keyword.startsWith("@")) {
+            return value.kind === "at-keyword" &&
+                lowerAscii(value.value) === lowerAscii(keyword.slice(1))
+                ? singleEnd(start + 1)
+                : emptyResult();
+        }
+        if (value.kind === "ident" && lowerAscii(value.value) === lowerAscii(keyword)) {
+            return singleEnd(start + 1);
+        }
+        const numeric = /^([+-]?(?:\d+(?:\.\d*)?|\.\d+))(%|[A-Za-z]+)?$/u.exec(keyword);
+        if (numeric === null)
+            return emptyResult();
+        const numberText = numeric[1];
+        const unit = numeric[2] ?? null;
+        if (numberText === undefined)
+            return emptyResult();
+        const number = Number(numberText);
+        if (unit === null && value.kind === "number" && value.value === number) {
+            return singleEnd(start + 1);
+        }
+        if (unit === "%" && value.kind === "percentage" && value.value === number) {
+            return singleEnd(start + 1);
+        }
+        return unit !== null &&
+            unit !== "%" &&
+            value.kind === "dimension" &&
+            value.value === number &&
+            lowerAscii(value.unit) === lowerAscii(unit)
+            ? singleEnd(start + 1)
+            : emptyResult();
+    }
+    #matchLiteral(literal, values, start) {
+        const value = values[start];
+        if (value === undefined)
+            return emptyResult();
+        const tokenKind = {
+            ",": "comma",
+            ":": "colon",
+            ";": "semicolon"
+        }[literal];
+        if (tokenKind !== undefined) {
+            return value.kind === tokenKind ? singleEnd(start + 1) : emptyResult();
+        }
+        if (literal === "(" &&
+            value.kind === "simple-block" &&
+            value.associatedToken === "open-paren") {
+            return singleEnd(start + 1);
+        }
+        const codePoint = literal.codePointAt(0);
+        return codePoint !== undefined &&
+            String.fromCodePoint(codePoint) === literal &&
+            value.kind === "delim" &&
+            value.value === codePoint
+            ? singleEnd(start + 1)
+            : emptyResult();
+    }
+    #matchFunction(name, definition, values, start) {
+        const value = values[start];
+        if (value?.kind !== "function-block" ||
+            lowerAscii(value.name) !== lowerAscii(name)) {
+            return emptyResult();
+        }
+        if (definition === null) {
+            return value.value.every((item) => item.kind === "whitespace")
+                ? singleEnd(start + 1)
+                : emptyResult();
+        }
+        const contents = significant(value.value);
+        const matched = this.#match(definition, contents, 0);
+        return {
+            ends: matched.ends.has(contents.length) ? new Set([start + 1]) : new Set(),
+            unsupported: matched.unsupported
+        };
+    }
+    #matchReference(reference, values, start) {
+        const key = `${reference.referenceKind}:${reference.name}:${String(this.#arrayId(values))}:${String(start)}`;
+        if (this.#activeReferences.has(key)) {
+            return result([], [`<${reference.name}>`]);
+        }
+        this.#activeReferences.add(key);
+        try {
+            if (reference.referenceKind === "property") {
+                const property = resolveCssProperty(reference.name);
+                if (property?.kind !== "standard" || property.syntax === null) {
+                    return result([], [`<'${reference.name}'>`]);
+                }
+                let propertyGrammar = grammar(property.syntax);
+                if (propertyGrammar.kind === "multiplier" &&
+                    propertyGrammar.separator === "comma") {
+                    propertyGrammar = propertyGrammar.value;
+                }
+                return this.#match(propertyGrammar, values, start);
+            }
+            if (reference.referenceKind === "function") {
+                return this.#matchCatalog(FUNCTION_DATA.get(`${reference.name}()`) ?? [], reference, values, start);
+            }
+            const builtin = this.#matchBuiltin(reference, values, start);
+            if (builtin !== null)
+                return builtin;
+            return this.#applyReferenceRange(reference, this.#matchCatalog(TYPE_DATA.get(reference.name) ?? [], reference, values, start), values, start);
+        }
+        finally {
+            this.#activeReferences.delete(key);
+        }
+    }
+    #matchCatalog(entries, reference, values, start) {
+        if (reference.constraint?.kind === "parameter") {
+            return result([], [`<${reference.name}[${reference.constraint.value}]>`]);
+        }
+        const definitions = entries
+            .map((entry) => entry.syntax)
+            .filter((syntax) => syntax !== undefined);
+        if (definitions.length === 0) {
+            return result([], [`<${reference.name}>`]);
+        }
+        return mergeResults(definitions.map((source) => this.#match(grammar(source), values, start)));
+    }
+    #applyReferenceRange(reference, matched, values, start) {
+        if (reference.constraint?.kind !== "range")
+            return matched;
+        const value = values[start];
+        if (value?.kind === "function-block" &&
+            MATH_FUNCTIONS.has(lowerAscii(value.name))) {
+            return result([], [
+                ...matched.unsupported,
+                `<${reference.name}:math-function>`
+            ]);
+        }
+        return value !== undefined &&
+            matched.ends.has(start + 1) &&
+            this.#rangeMatches(reference, value)
+            ? result([start + 1], matched.unsupported)
+            : result([], matched.unsupported);
+    }
+    #matchBuiltin(reference, values, start) {
+        const value = values[start];
+        const atomic = (matches) => matches && value !== undefined && this.#rangeMatches(reference, value)
+            ? singleEnd(start + 1)
+            : emptyResult();
+        switch (reference.name) {
+            case "ident":
+            case "ident-token":
+            case "identifier":
+            case "id":
+                return atomic(value?.kind === "ident");
+            case "custom-ident":
+                return atomic(value?.kind === "ident" &&
+                    !CSS_GENERIC_KEYWORD_EXCLUSIONS.has(lowerAscii(value.value)));
+            case "dashed-ident":
+            case "custom-property-name":
+                return atomic(value?.kind === "ident" &&
+                    value.value.startsWith("--") &&
+                    value.value.length > 2);
+            case "string":
+            case "string-token":
+                return atomic(value?.kind === "string");
+            case "url":
+            case "uri":
+            case "url-token":
+                return atomic(value?.kind === "url" ||
+                    (value?.kind === "function-block" && lowerAscii(value.name) === "url"));
+            case "hash-token":
+                return atomic(value?.kind === "hash");
+            case "hex-color":
+                return atomic(value?.kind === "hash" &&
+                    /^[0-9A-Fa-f]{3,4}(?:[0-9A-Fa-f]{2}){0,2}$/u.test(value.value));
+            case "number":
+            case "number-token":
+                return this.#matchNumeric(reference, value, start, false);
+            case "integer":
+                return this.#matchNumeric(reference, value, start, true);
+            case "zero":
+                return atomic(value?.kind === "number" && value.value === 0);
+            case "percentage":
+            case "percentage-token":
+                return atomic(value?.kind === "percentage");
+            case "dimension":
+            case "dimension-token":
+                return atomic(value?.kind === "dimension");
+            case "length":
+            case "quirky-length":
+                return this.#matchDimensionType(reference, value, start, LENGTH_UNITS, true);
+            case "angle":
+                return this.#matchDimensionType(reference, value, start, ANGLE_UNITS, false);
+            case "time":
+                return this.#matchDimensionType(reference, value, start, TIME_UNITS, false);
+            case "frequency":
+                return this.#matchDimensionType(reference, value, start, FREQUENCY_UNITS, false);
+            case "resolution":
+                return this.#matchDimensionType(reference, value, start, RESOLUTION_UNITS, false);
+            case "flex":
+                return this.#matchDimensionType(reference, value, start, FLEX_UNITS, false);
+            case "unicode-range-token":
+                return atomic(value?.kind === "unicode-range");
+            case "at-keyword-token":
+                return atomic(value?.kind === "at-keyword");
+            case "function-token":
+                return atomic(value?.kind === "function-block");
+            case "comma-token":
+                return atomic(value?.kind === "comma");
+            case "colon-token":
+                return atomic(value?.kind === "colon");
+            case "semicolon-token":
+                return atomic(value?.kind === "semicolon");
+            case "delim-token":
+                return atomic(value?.kind === "delim");
+            case "bad-string-token":
+                return atomic(value?.kind === "bad-string");
+            case "bad-url-token":
+                return atomic(value?.kind === "bad-url");
+            case "CDO-token":
+                return atomic(value?.kind === "cdo");
+            case "CDC-token":
+                return atomic(value?.kind === "cdc");
+            case "(-token":
+                return atomic(value?.kind === "simple-block" && value.associatedToken === "open-paren");
+            case "[-token":
+                return atomic(value?.kind === "simple-block" && value.associatedToken === "open-square");
+            case "{-token":
+                return atomic(value?.kind === "simple-block" && value.associatedToken === "open-curly");
+            case "border-style":
+                return atomic(value?.kind === "ident" && BORDER_STYLES.has(lowerAscii(value.value)));
+            case "border-width":
+            case "line-width":
+                if (value?.kind === "ident" &&
+                    BORDER_WIDTH_KEYWORDS.has(lowerAscii(value.value))) {
+                    return singleEnd(start + 1);
+                }
+                return this.#matchDimensionType(reference, value, start, LENGTH_UNITS, true);
+            case "paint":
+                return this.#match(grammar(PAINT_SYNTAX), values, start);
+            case "any-value":
+                return result(Array.from({ length: values.length - start + 1 }, (_, index) => start + index));
+            case "declaration-value":
+                return result(Array.from({ length: Math.max(0, values.length - start) }, (_, index) => start + index + 1));
+            case "whitespace-token":
+            case "eof-token":
+            case ")-token":
+            case "]-token":
+            case "}-token":
+                return emptyResult();
+            default:
+                return null;
+        }
+    }
+    #matchNumeric(reference, value, start, integer) {
+        if (value?.kind === "function-block" && MATH_FUNCTIONS.has(lowerAscii(value.name))) {
+            return result([], [`<${reference.name}:math-function>`]);
+        }
+        return value?.kind === "number" &&
+            (!integer || value.numberType === "integer") &&
+            this.#rangeMatches(reference, value)
+            ? singleEnd(start + 1)
+            : emptyResult();
+    }
+    #matchDimensionType(reference, value, start, units, acceptsZero) {
+        if (value === undefined)
+            return emptyResult();
+        if (value.kind === "function-block" && MATH_FUNCTIONS.has(lowerAscii(value.name))) {
+            return result([], [`<${reference.name}:math-function>`]);
+        }
+        const matches = (value.kind === "dimension" && units.has(lowerAscii(value.unit))) ||
+            (acceptsZero && value.kind === "number" && value.value === 0);
+        return matches && this.#rangeMatches(reference, value)
+            ? singleEnd(start + 1)
+            : emptyResult();
+    }
+    #rangeMatches(reference, value) {
+        if (reference.constraint?.kind !== "range")
+            return true;
+        const numeric = this.#numericValue(value, reference.constraint.value);
+        return numeric !== null &&
+            numeric >= reference.constraint.value.minimum.value &&
+            numeric <= reference.constraint.value.maximum.value;
+    }
+    #numericValue(value, range) {
+        if (value.kind !== "number" &&
+            value.kind !== "percentage" &&
+            value.kind !== "dimension") {
+            return null;
+        }
+        const boundaryUnit = range.minimum.unit ?? range.maximum.unit;
+        if (boundaryUnit === null || value.kind !== "dimension")
+            return value.value;
+        return convertUnit(value.value, lowerAscii(value.unit), lowerAscii(boundaryUnit));
+    }
+    #arrayId(values) {
+        const existing = this.#arrayIds.get(values);
+        if (existing !== undefined)
+            return existing;
+        const id = this.#nextArrayId;
+        this.#nextArrayId += 1;
+        this.#arrayIds.set(values, id);
+        return id;
+    }
+}
+function convertUnit(value, from, to) {
+    if (from === to)
+        return value;
+    const angleToDegrees = {
+        deg: 1,
+        grad: 0.9,
+        rad: 180 / Math.PI,
+        turn: 360
+    };
+    const timeToSeconds = { ms: 0.001, s: 1 };
+    const frequencyToHertz = { hz: 1, khz: 1000 };
+    const groups = [angleToDegrees, timeToSeconds, frequencyToHertz];
+    for (const group of groups) {
+        const sourceFactor = group[from];
+        const targetFactor = group[to];
+        if (sourceFactor !== undefined && targetFactor !== undefined) {
+            return value * sourceFactor / targetFactor;
+        }
+    }
+    return null;
+}
+function isCssWideKeyword(values) {
+    return (values.length === 1 &&
+        values[0]?.kind === "ident" &&
+        CSS_WIDE_KEYWORDS.has(lowerAscii(values[0].value)));
+}
+function customPropertyValueStatus(values, matcher, topLevel = true) {
+    let unsupported = false;
+    for (const value of values) {
+        matcher.step();
+        if (value.kind === "bad-string" ||
+            value.kind === "bad-url" ||
+            value.kind === "close-paren" ||
+            value.kind === "close-square" ||
+            value.kind === "close-curly" ||
+            (topLevel && value.kind === "semicolon") ||
+            (topLevel && value.kind === "delim" && value.value === 0x21)) {
+            return "invalid";
+        }
+        if (value.kind === "simple-block") {
+            const child = customPropertyValueStatus(value.value, matcher, false);
+            if (child === "invalid")
+                return "invalid";
+            if (child === "unsupported")
+                unsupported = true;
+        }
+        else if (value.kind === "function-block") {
+            if (lowerAscii(value.name) === "var") {
+                const reference = customReferenceStatus(value);
+                if (reference === "invalid")
+                    return "invalid";
+                if (reference === "unsupported")
+                    unsupported = true;
+            }
+            const child = customPropertyValueStatus(value.value, matcher, false);
+            if (child === "invalid")
+                return "invalid";
+            if (child === "unsupported")
+                unsupported = true;
+        }
+    }
+    return unsupported ? "unsupported" : "valid";
+}
+function customReferenceStatus(value) {
+    const arguments_ = significant(value.value);
+    const comma = arguments_.findIndex((argument) => argument.kind === "comma");
+    const name = arguments_.slice(0, comma < 0 ? arguments_.length : comma);
+    if (name.length === 1 &&
+        name[0]?.kind === "ident" &&
+        resolveCssProperty(name[0].value)?.kind === "custom") {
+        return "valid";
+    }
+    return name.some((argument) => argument.kind === "function-block" &&
+        lowerAscii(argument.name) === "var")
+        ? "unsupported"
+        : "invalid";
+}
+function substitutionStatus(values, matcher) {
+    let found = false;
+    let unsupported = false;
+    for (const value of values) {
+        matcher.step();
+        if (value.kind === "simple-block") {
+            const child = substitutionStatus(value.value, matcher);
+            if (child === "invalid")
+                return "invalid";
+            if (child === "present")
+                found = true;
+            if (child === "unsupported")
+                unsupported = true;
+        }
+        else if (value.kind === "function-block") {
+            if (lowerAscii(value.name) === "var") {
+                found = true;
+                const reference = customReferenceStatus(value);
+                if (reference === "invalid")
+                    return "invalid";
+                if (reference === "unsupported")
+                    unsupported = true;
+            }
+            const child = substitutionStatus(value.value, matcher);
+            if (child === "invalid")
+                return "invalid";
+            if (child === "present")
+                found = true;
+            if (child === "unsupported")
+                unsupported = true;
+        }
+    }
+    return unsupported ? "unsupported" : found ? "present" : "none";
+}
+function frozenUsage(matcher) {
+    return matcher.usage();
+}
+export function validateCssPropertyValue(declaration, options = {}) {
+    const matcher = new PropertyGrammarMatcher(options);
+    const property = resolveCssProperty(declaration.name);
+    if (property === null) {
+        return Object.freeze({
+            status: "invalid",
+            reason: "unknown-property",
+            property: null,
+            usage: frozenUsage(matcher)
+        });
+    }
+    if (property.kind === "custom") {
+        const customStatus = customPropertyValueStatus(declaration.value, matcher);
+        if (customStatus === "invalid") {
+            return Object.freeze({
+                status: "invalid",
+                reason: "invalid-value",
+                property,
+                usage: frozenUsage(matcher)
+            });
+        }
+        if (customStatus === "unsupported") {
+            return Object.freeze({
+                status: "unsupported",
+                property,
+                reason: "dynamic-custom-property-reference",
+                unresolvedReferences: Object.freeze(["var(dynamic-name)"]),
+                usage: frozenUsage(matcher)
+            });
+        }
+        return Object.freeze({
+            status: "valid",
+            property,
+            valueKind: "custom",
+            usage: frozenUsage(matcher)
+        });
+    }
+    const values = significant(declaration.value);
+    if (isCssWideKeyword(values)) {
+        return Object.freeze({
+            status: "valid",
+            property,
+            valueKind: "css-wide",
+            usage: frozenUsage(matcher)
+        });
+    }
+    const substitution = substitutionStatus(values, matcher);
+    if (substitution === "invalid") {
+        return Object.freeze({
+            status: "invalid",
+            reason: "invalid-value",
+            property,
+            usage: frozenUsage(matcher)
+        });
+    }
+    if (substitution === "present" || substitution === "unsupported") {
+        return Object.freeze({
+            status: "unsupported",
+            property,
+            reason: "arbitrary-substitution",
+            unresolvedReferences: Object.freeze([
+                substitution === "unsupported" ? "var(dynamic-name)" : "var()"
+            ]),
+            usage: frozenUsage(matcher)
+        });
+    }
+    if (property.syntax === null) {
+        return Object.freeze({
+            status: "unsupported",
+            property,
+            reason: "missing-property-syntax",
+            unresolvedReferences: Object.freeze([]),
+            usage: frozenUsage(matcher)
+        });
+    }
+    const matched = matcher.match(grammar(property.syntax), values);
+    if (matched.ends.has(values.length)) {
+        return Object.freeze({
+            status: "valid",
+            property,
+            valueKind: "grammar",
+            usage: frozenUsage(matcher)
+        });
+    }
+    if (matched.unsupported.size > 0) {
+        return Object.freeze({
+            status: "unsupported",
+            property,
+            reason: "unresolved-grammar",
+            unresolvedReferences: Object.freeze([...matched.unsupported].sort()),
+            usage: frozenUsage(matcher)
+        });
+    }
+    return Object.freeze({
+        status: "invalid",
+        reason: "invalid-value",
+        property,
+        usage: frozenUsage(matcher)
+    });
+}