@ismail-elkorchi/css-parser 0.1.0 → 0.2.0

package/dist/internal/grammar/catalog-types.d.ts

@@ -0,0 +1,26 @@
+export interface CssPropertyData {
+    readonly name: string;
+    readonly href: string;
+    readonly styleDeclaration: readonly string[];
+    readonly syntax?: string;
+    readonly legacyAliasOf?: string;
+    readonly longhands?: readonly string[];
+    readonly resetLonghands?: readonly string[];
+    readonly initial?: string;
+    readonly appliesTo?: string;
+    readonly inherited?: string;
+    readonly percentages?: string;
+    readonly computedValue?: string;
+    readonly animationType?: string;
+    readonly canonicalOrder?: string;
+}
+export interface CssGrammarData {
+    readonly name: string;
+    readonly syntax?: string;
+}
+export interface CssWebrefData {
+    readonly properties: readonly CssPropertyData[];
+    readonly functions: readonly CssGrammarData[];
+    readonly selectors: readonly string[];
+    readonly types: readonly CssGrammarData[];
+}

package/dist/internal/grammar/value-definition.d.ts

@@ -0,0 +1,63 @@
+export interface GrammarSpan {
+    readonly start: number;
+    readonly end: number;
+}
+interface GrammarNodeBase {
+    readonly span: GrammarSpan;
+}
+export interface GrammarKeyword extends GrammarNodeBase {
+    readonly kind: "keyword";
+    readonly value: string;
+}
+export interface GrammarLiteral extends GrammarNodeBase {
+    readonly kind: "literal";
+    readonly value: string;
+}
+export interface GrammarRangeBoundary {
+    readonly value: number;
+    readonly unit: string | null;
+}
+export interface GrammarRange {
+    readonly minimum: GrammarRangeBoundary;
+    readonly maximum: GrammarRangeBoundary;
+}
+export type GrammarReferenceConstraint = {
+    readonly kind: "range";
+    readonly value: GrammarRange;
+} | {
+    readonly kind: "parameter";
+    readonly value: string;
+};
+export interface GrammarReference extends GrammarNodeBase {
+    readonly kind: "reference";
+    readonly name: string;
+    readonly referenceKind: "type" | "property" | "function";
+    readonly constraint: GrammarReferenceConstraint | null;
+}
+export interface GrammarFunction extends GrammarNodeBase {
+    readonly kind: "function";
+    readonly name: string;
+    readonly value: ValueDefinition | null;
+}
+export interface GrammarCombination extends GrammarNodeBase {
+    readonly kind: "sequence" | "all-of" | "any-of" | "one-of";
+    readonly values: readonly ValueDefinition[];
+}
+export interface GrammarMultiplier extends GrammarNodeBase {
+    readonly kind: "multiplier";
+    readonly value: ValueDefinition;
+    readonly minimum: number;
+    readonly maximum: number;
+    readonly separator: "space" | "comma";
+}
+export interface GrammarRequired extends GrammarNodeBase {
+    readonly kind: "required";
+    readonly value: ValueDefinition;
+}
+export type ValueDefinition = GrammarKeyword | GrammarLiteral | GrammarReference | GrammarFunction | GrammarCombination | GrammarMultiplier | GrammarRequired;
+export declare class CssValueDefinitionSyntaxError extends SyntaxError {
+    readonly offset: number;
+    constructor(message: string, offset: number);
+}
+export declare function parseCssValueDefinition(source: string): ValueDefinition;
+export {};

package/dist/internal/grammar/value-definition.js

@@ -0,0 +1,439 @@
+const INFINITY = Number.POSITIVE_INFINITY;
+export class CssValueDefinitionSyntaxError extends SyntaxError {
+    offset;
+    constructor(message, offset) {
+        super(`${message} at offset ${String(offset)}.`);
+        this.name = "CssValueDefinitionSyntaxError";
+        this.offset = offset;
+    }
+}
+function freezeSpan(start, end) {
+    return Object.freeze({ start, end });
+}
+function freezeValues(values) {
+    return Object.freeze(values);
+}
+function boundary(value, unit) {
+    return Object.freeze({ value, unit });
+}
+class ValueDefinitionParser {
+    #source;
+    #offset = 0;
+    constructor(source) {
+        this.#source = source;
+    }
+    parse() {
+        this.#skipWhitespace();
+        if (this.#done) {
+            throw this.#error("A value definition cannot be empty");
+        }
+        const result = this.#parseOneOf(null);
+        this.#skipWhitespace();
+        if (this.#source.slice(this.#offset).length > 0) {
+            throw this.#error(`Unexpected ${JSON.stringify(this.#next)}`);
+        }
+        return result;
+    }
+    #parseOneOf(terminator) {
+        const start = this.#offset;
+        const values = [this.#parseAnyOf(terminator)];
+        while (this.#consumeCombinator("|", "||")) {
+            values.push(this.#parseAnyOf(terminator));
+        }
+        return this.#combine("one-of", values, start);
+    }
+    #parseAnyOf(terminator) {
+        const start = this.#offset;
+        const values = [this.#parseAllOf(terminator)];
+        while (this.#consumeExact("||")) {
+            values.push(this.#parseAllOf(terminator));
+        }
+        return this.#combine("any-of", values, start);
+    }
+    #parseAllOf(terminator) {
+        const start = this.#offset;
+        const values = [this.#parseSequence(terminator)];
+        while (this.#consumeExact("&&")) {
+            values.push(this.#parseSequence(terminator));
+        }
+        return this.#combine("all-of", values, start);
+    }
+    #parseSequence(terminator) {
+        const start = this.#offset;
+        const values = [];
+        while (this.#canStartTerm(terminator)) {
+            values.push(this.#parseTerm(terminator));
+        }
+        if (values.length === 0) {
+            throw this.#error("Expected a grammar component");
+        }
+        return this.#combine("sequence", values, start);
+    }
+    #parseTerm(terminator) {
+        let value = this.#parsePrimary(terminator);
+        let refinableCommaMultiplier = false;
+        for (;;) {
+            this.#skipWhitespace();
+            const start = value.span.start;
+            if (this.#consumeExact("*")) {
+                value = this.#multiplier(value, 0, INFINITY, "space", start);
+                refinableCommaMultiplier = false;
+            }
+            else if (this.#consumeExact("+")) {
+                value = this.#multiplier(value, 1, INFINITY, "space", start);
+                refinableCommaMultiplier = false;
+            }
+            else if (this.#consumeExact("?")) {
+                value = this.#multiplier(value, 0, 1, "space", start);
+                refinableCommaMultiplier = false;
+            }
+            else if (this.#consumeExact("#")) {
+                value = this.#multiplier(value, 1, INFINITY, "comma", start);
+                refinableCommaMultiplier = true;
+            }
+            else {
+                const repetition = this.#consumeRepetition();
+                if (repetition !== null) {
+                    if (refinableCommaMultiplier && value.kind === "multiplier") {
+                        value = this.#multiplier(value.value, repetition.minimum, repetition.maximum, "comma", start);
+                    }
+                    else {
+                        value = this.#multiplier(value, repetition.minimum, repetition.maximum, "space", start);
+                    }
+                    refinableCommaMultiplier = false;
+                }
+                else if (this.#consumeExact("!")) {
+                    value = Object.freeze({
+                        kind: "required",
+                        value,
+                        span: freezeSpan(start, this.#offset)
+                    });
+                    refinableCommaMultiplier = false;
+                }
+                else {
+                    return value;
+                }
+            }
+        }
+    }
+    #parsePrimary(terminator) {
+        this.#skipWhitespace();
+        const start = this.#offset;
+        if (this.#consumeExact("[")) {
+            const value = this.#parseOneOf("]");
+            this.#skipWhitespace();
+            this.#expect("]");
+            return this.#withSpan(value, start, this.#offset);
+        }
+        if (this.#consumeExact("<")) {
+            return this.#consumeReference(start);
+        }
+        if (this.#next === "'") {
+            return this.#consumeQuotedLiteral();
+        }
+        if (this.#isLiteralPunctuation(this.#next)) {
+            this.#offset += 1;
+            return Object.freeze({
+                kind: "literal",
+                value: this.#source.slice(start, this.#offset),
+                span: freezeSpan(start, this.#offset)
+            });
+        }
+        const name = this.#consumeWord(terminator);
+        if (name.length === 0) {
+            throw this.#error("Expected a grammar component");
+        }
+        if (this.#next === "(") {
+            this.#offset += 1;
+            this.#skipWhitespace();
+            let body = null;
+            if (!this.#at(")")) {
+                body = this.#parseOneOf(")");
+                this.#skipWhitespace();
+            }
+            this.#expect(")");
+            return Object.freeze({
+                kind: "function",
+                name,
+                value: body,
+                span: freezeSpan(start, this.#offset)
+            });
+        }
+        return Object.freeze({
+            kind: "keyword",
+            value: name,
+            span: freezeSpan(start, this.#offset)
+        });
+    }
+    #consumeReference(start) {
+        let quote = null;
+        let nestedAngles = 0;
+        let content = "";
+        while (!this.#done) {
+            const character = this.#next;
+            if (character === "'" && quote === null) {
+                quote = "'";
+            }
+            else if (character === "'" && quote === "'") {
+                quote = null;
+            }
+            else if (quote === null) {
+                if (character === "<") {
+                    nestedAngles += 1;
+                }
+                else if (character === ">") {
+                    if (nestedAngles === 0)
+                        break;
+                    nestedAngles -= 1;
+                }
+            }
+            content += character;
+            this.#offset += 1;
+        }
+        if (this.#done) {
+            throw this.#error("Unterminated type reference");
+        }
+        this.#offset += 1;
+        const trimmed = content.trim();
+        if (trimmed.length === 0) {
+            throw new CssValueDefinitionSyntaxError("A type reference cannot be empty", start);
+        }
+        if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+            const name = trimmed.slice(1, -1);
+            if (name.length === 0 || name.includes("'")) {
+                throw new CssValueDefinitionSyntaxError("Invalid property reference", start);
+            }
+            return Object.freeze({
+                kind: "reference",
+                name,
+                referenceKind: "property",
+                constraint: null,
+                span: freezeSpan(start, this.#offset)
+            });
+        }
+        const range = this.#splitConstraint(trimmed);
+        const name = range.name.endsWith("()") ? range.name.slice(0, -2) : range.name;
+        if (name.length === 0) {
+            throw new CssValueDefinitionSyntaxError("A type name cannot be empty", start);
+        }
+        return Object.freeze({
+            kind: "reference",
+            name,
+            referenceKind: range.name.endsWith("()") ? "function" : "type",
+            constraint: range.constraint,
+            span: freezeSpan(start, this.#offset)
+        });
+    }
+    #splitConstraint(value) {
+        if (!value.endsWith("]")) {
+            return { name: value, constraint: null };
+        }
+        const opening = value.indexOf("[");
+        if (opening < 1) {
+            return { name: value, constraint: null };
+        }
+        const name = value.slice(0, opening).trim();
+        const constraint = value.slice(opening + 1, -1).trim();
+        const comma = constraint.indexOf(",");
+        if (comma < 0) {
+            return {
+                name,
+                constraint: Object.freeze({ kind: "parameter", value: constraint })
+            };
+        }
+        const minimum = this.#parseRangeBoundary(constraint.slice(0, comma).trim());
+        const maximum = this.#parseRangeBoundary(constraint.slice(comma + 1).trim());
+        return {
+            name,
+            constraint: Object.freeze({
+                kind: "range",
+                value: Object.freeze({ minimum, maximum })
+            })
+        };
+    }
+    #parseRangeBoundary(source) {
+        if (source === "∞") {
+            return boundary(INFINITY, null);
+        }
+        if (source === "-∞") {
+            return boundary(Number.NEGATIVE_INFINITY, null);
+        }
+        const match = /^([+-]?(?:\d+(?:\.\d*)?|\.\d+))([A-Za-z%]*)$/u.exec(source);
+        if (match === null) {
+            throw this.#error(`Invalid range boundary ${JSON.stringify(source)}`);
+        }
+        const numeric = match[1];
+        const unit = match[2];
+        if (numeric === undefined || unit === undefined) {
+            throw this.#error(`Invalid range boundary ${JSON.stringify(source)}`);
+        }
+        return boundary(Number(numeric), unit.length === 0 ? null : unit);
+    }
+    #consumeQuotedLiteral() {
+        const start = this.#offset;
+        this.#offset += 1;
+        const contentStart = this.#offset;
+        while (!this.#done && this.#next !== "'") {
+            this.#offset += 1;
+        }
+        if (this.#done) {
+            throw this.#error("Unterminated quoted literal");
+        }
+        const value = this.#source.slice(contentStart, this.#offset);
+        this.#offset += 1;
+        if (value.length === 0) {
+            throw new CssValueDefinitionSyntaxError("A quoted literal cannot be empty", start);
+        }
+        return Object.freeze({
+            kind: "literal",
+            value,
+            span: freezeSpan(start, this.#offset)
+        });
+    }
+    #consumeWord(terminator) {
+        const start = this.#offset;
+        while (!this.#done) {
+            const character = this.#next;
+            if (this.#isWhitespace(character) ||
+                character === "<" ||
+                character === "'" ||
+                character === "[" ||
+                character === "(" ||
+                character === "|" ||
+                character === "&" ||
+                character === "?" ||
+                character === "*" ||
+                character === "+" ||
+                character === "#" ||
+                character === "!" ||
+                character === "," ||
+                character === "/" ||
+                character === ":" ||
+                character === ";" ||
+                character === "{" ||
+                character === "}" ||
+                character === terminator) {
+                break;
+            }
+            this.#offset += 1;
+        }
+        return this.#source.slice(start, this.#offset);
+    }
+    #consumeRepetition() {
+        this.#skipWhitespace();
+        const remainder = this.#source.slice(this.#offset);
+        const match = /^\{\s*(\d+)\s*(?:,\s*(\d*)\s*)?\}/u.exec(remainder);
+        if (match === null) {
+            return null;
+        }
+        const minimumText = match[1];
+        const maximumText = match[2];
+        if (minimumText === undefined) {
+            return null;
+        }
+        const minimum = Number(minimumText);
+        const maximum = maximumText === undefined
+            ? minimum
+            : maximumText.length === 0
+                ? INFINITY
+                : Number(maximumText);
+        if (minimum > maximum) {
+            throw this.#error("A repetition minimum cannot exceed its maximum");
+        }
+        this.#offset += match[0].length;
+        return { minimum, maximum };
+    }
+    #multiplier(value, minimum, maximum, separator, start) {
+        return Object.freeze({
+            kind: "multiplier",
+            value,
+            minimum,
+            maximum,
+            separator,
+            span: freezeSpan(start, this.#offset)
+        });
+    }
+    #combine(kind, values, start) {
+        if (values.length === 1) {
+            const value = values[0];
+            if (value === undefined) {
+                throw this.#error("Expected a grammar component");
+            }
+            return value;
+        }
+        return Object.freeze({
+            kind,
+            values: freezeValues(values),
+            span: freezeSpan(start, this.#offset)
+        });
+    }
+    #withSpan(value, start, end) {
+        return Object.freeze({ ...value, span: freezeSpan(start, end) });
+    }
+    #canStartTerm(terminator) {
+        this.#skipWhitespace();
+        if (this.#done || this.#next === terminator) {
+            return false;
+        }
+        if (this.#source.startsWith("&&", this.#offset)) {
+            return false;
+        }
+        return this.#next !== "|";
+    }
+    #consumeCombinator(single, longer) {
+        this.#skipWhitespace();
+        if (this.#source.startsWith(longer, this.#offset) ||
+            !this.#source.startsWith(single, this.#offset)) {
+            return false;
+        }
+        this.#offset += single.length;
+        this.#skipWhitespace();
+        return true;
+    }
+    #consumeExact(value) {
+        this.#skipWhitespace();
+        if (!this.#source.startsWith(value, this.#offset)) {
+            return false;
+        }
+        this.#offset += value.length;
+        this.#skipWhitespace();
+        return true;
+    }
+    #expect(value) {
+        if (!this.#consumeExact(value)) {
+            throw this.#error(`Expected ${JSON.stringify(value)}`);
+        }
+    }
+    #at(value) {
+        return this.#next === value;
+    }
+    #isLiteralPunctuation(value) {
+        return value === "," ||
+            value === "/" ||
+            value === ":" ||
+            value === ";" ||
+            value === "{" ||
+            value === "}" ||
+            value === "(";
+    }
+    #skipWhitespace() {
+        while (!this.#done && this.#isWhitespace(this.#next)) {
+            this.#offset += 1;
+        }
+    }
+    #isWhitespace(value) {
+        return value === " " || value === "\n" || value === "\r" || value === "\t";
+    }
+    #error(message) {
+        return new CssValueDefinitionSyntaxError(message, this.#offset);
+    }
+    get #done() {
+        return this.#offset >= this.#source.length;
+    }
+    get #next() {
+        return this.#source[this.#offset] ?? "";
+    }
+}
+export function parseCssValueDefinition(source) {
+    return new ValueDefinitionParser(source).parse();
+}

package/dist/internal/properties/matcher.d.ts

@@ -0,0 +1,29 @@
+import type { CssDeclaration } from "../syntax/ast.js";
+import type { ResourceUsage } from "../syntax/types.js";
+import type { CssPropertySemantics } from "./registry.js";
+export interface PropertyValidationOptions {
+    readonly maxSteps?: number;
+    readonly signal?: AbortSignal;
+}
+interface PropertyValidationBase {
+    readonly property: CssPropertySemantics | null;
+    readonly usage: ResourceUsage;
+}
+export interface ValidPropertyValue extends PropertyValidationBase {
+    readonly status: "valid";
+    readonly property: CssPropertySemantics;
+    readonly valueKind: "custom" | "css-wide" | "grammar";
+}
+export interface InvalidPropertyValue extends PropertyValidationBase {
+    readonly status: "invalid";
+    readonly reason: "unknown-property" | "invalid-value";
+}
+export interface UnsupportedPropertyValue extends PropertyValidationBase {
+    readonly status: "unsupported";
+    readonly property: CssPropertySemantics;
+    readonly reason: "missing-property-syntax" | "unresolved-grammar" | "dynamic-custom-property-reference" | "arbitrary-substitution";
+    readonly unresolvedReferences: readonly string[];
+}
+export type PropertyValueValidation = ValidPropertyValue | InvalidPropertyValue | UnsupportedPropertyValue;
+export declare function validateCssPropertyValue(declaration: CssDeclaration, options?: PropertyValidationOptions): PropertyValueValidation;
+export {};