@ismail-elkorchi/css-parser 0.1.1 → 0.2.0

package/README.md

@@ -1,112 +1,98 @@
 # @ismail-elkorchi/css-parser
 
-Deterministic CSS parsing and selector utilities for automation across Node, Deno, Bun, and modern browsers.
-
-No runtime dependencies: this package ships with zero runtime dependencies.
-
-## When To Use
-
-- You need deterministic CSS parse/serialize output.
-- You need selector querying without browser-engine side effects.
-- You need explicit resource budgets for untrusted stylesheets.
-
-## When Not To Use
-
-- You need browser layout/cascade computation.
-- You need stylesheet sanitization and policy enforcement in one step.
-- You need script or DOM runtime semantics.
+A CSS syntax parser, serializer, CSSOM declaration model, property validator,
+and Selectors Level 4 engine for Node.js, Deno, Bun, and modern browsers. It has
+no runtime dependencies.
 
 ## Install
 
-```bash
+```sh
 npm install @ismail-elkorchi/css-parser
 ```
 
-```bash
+```sh
 deno add jsr:@ismail-elkorchi/css-parser
 ```
 
-## Import
+## Parse and serialize CSS
 
 ```ts
-import { parse } from "@ismail-elkorchi/css-parser";
-```
+import { parseStylesheet, serialize } from "@ismail-elkorchi/css-parser";
 
-```txt
-import { parse } from "jsr:@ismail-elkorchi/css-parser";
+const result = parseStylesheet(".card { color: red; margin: 1rem; }");
+if (!result.ok) {
+  throw new Error(result.errors.map((error) => error.message).join("\n"));
+}
+
+console.log(serialize(result.value));
 ```
 
-## Copy/Paste Examples
+Parse results are discriminated by `ok`. Successful results contain `value`,
+recoverable `errors`, and measured `usage`. Resource or abort limits throw
+`SyntaxResourceError` or `SyntaxAbortError`.
 
-### Example 1: Parse CSS
+The package provides the CSS Syntax parsing entrypoints for stylesheets,
+stylesheet contents, block contents, rules, declarations, component values, and
+comma-separated component values. See the [API guide](./docs/api.md) for their
+exact names and result types.
 
-```ts
-import { parse } from "@ismail-elkorchi/css-parser";
+## Parse bytes and streams
 
-const tree = parse(".card { color: red; }");
-console.log(tree.kind);
-```
-
-### Example 2: Parse streaming input
+`parseStylesheetBytes()` and `parseStylesheetStream()` apply the CSS encoding
+detection order and include the selected encoding in their result.
 
 ```ts
-import { parseStream } from "@ismail-elkorchi/css-parser";
-
-const stream = new ReadableStream({
-  start(controller) {
-    controller.enqueue(new TextEncoder().encode(".a{display:block}"));
-    controller.close();
+import { parseStylesheetStream } from "@ismail-elkorchi/css-parser";
+
+const response = await fetch("https://example.test/site.css");
+if (response.body === null) throw new Error("Response has no body");
+
+const result = await parseStylesheetStream(response.body, {
+  limits: {
+    maxInputBytes: 1_000_000,
+    maxBufferedBytes: 64_000,
+    maxTokens: 100_000,
+    maxNodes: 50_000,
+    maxDepth: 128,
+    maxSteps: 1_000_000
   }
 });
-
-const tree = await parseStream(stream, { budgets: { maxInputBytes: 4096, maxBufferedBytes: 512 } });
-console.log(tree.kind);
 ```
 
-### Example 3: Query selectors
-
-```ts
-import { compileSelectorList, querySelectorAll } from "@ismail-elkorchi/css-parser";
-
-const selector = compileSelectorList(".card");
-console.log(selector.supported, querySelectorAll(selector, { kind: "document", children: [] }).length);
-```
+Stream decoding is incremental; tree construction starts after the decoded
+stylesheet reaches EOF. `tokenizeBytes()` and `tokenizeStream()` expose the same
+encoding and resource accounting for tokenization.
 
-### Example 4: Extract render signals
+## CSSOM declarations and selectors
 
-```ts
-import { extractRenderSignals, parse } from "@ismail-elkorchi/css-parser";
-
-const tree = parse(".card { color: red; }");
-console.log(extractRenderSignals(tree).length >= 0);
-```
-
-Run packaged examples:
-
-```bash
-npm run examples:run
-```
+`CssDeclarationBlock` implements declaration parsing, priority, property-name,
+mutation, and serialization semantics. `resolveCssProperty()` and
+`validateCssPropertyValue()` use pinned WebRef grammar data.
 
-## Compatibility
+`matchSelectorList()` and `querySelectorList()` require an explicit typed
+environment for tree access, namespaces, document mode, attributes, and dynamic
+pseudo-classes. Their results preserve `match`, `no-match`, and `unknown`
+outcomes instead of guessing. See [Selector matching](./docs/selectors.md).
 
-Runtime compatibility matrix:
+## Traversal and source edits
 
-| Runtime | Status |
-| --- | --- |
-| Node.js | Supported |
-| Deno | Supported |
-| Bun | Supported |
-| Browser (evergreen) | Supported |
+`walkCss()`, `findNodeById()`, and `findNodesByKind()` operate on the typed
+structural syntax tree. `computePatch()` plans source-preserving remove, replace,
+and boundary insert edits against node spans; `applyPatch()` verifies and
+applies the resulting plan.
 
-## Security and Safety Notes
+Parsing and serialization are structural operations. They do not sanitize CSS,
+resolve the cascade, or perform layout.
 
-Parsing is not sanitization. For untrusted input:
-- configure strict budgets,
-- handle `BudgetExceededError` explicitly,
-- apply separate policy checks before execution or rendering.
+## Project information
 
-## Documentation
+- [API guide](./docs/api.md)
+- [Selector matching](./docs/selectors.md)
+- [Runnable examples](./examples/)
+- [Development](./docs/development.md)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
 
-- [Docs index](./docs/index.md)
-- [First parse success tutorial](./docs/tutorial/first-parse.md)
-- [Options reference](./docs/reference/options.md)
+Node.js 20, 22, and 24 are tested. Cross-runtime qualification covers Node.js,
+Deno, Bun, and Chromium. Release qualification also compares CSSOM
+serialization with Chromium, Firefox, and WebKit.

package/dist/internal/cssom/declarations.d.ts

@@ -0,0 +1,36 @@
+import type { PropertyValidationOptions } from "../properties/matcher.js";
+import type { SyntaxParserOptions } from "../syntax/parser.js";
+export interface CssDeclarationBlockOptions {
+    readonly parser?: SyntaxParserOptions;
+    readonly validation?: PropertyValidationOptions;
+}
+export interface CssomDeclaration {
+    readonly name: string;
+    readonly value: string;
+    readonly important: boolean;
+}
+export type CssDeclarationMutation = {
+    readonly status: "set";
+    readonly declaration: CssomDeclaration;
+    readonly previousValue: string;
+} | {
+    readonly status: "removed";
+    readonly previousValue: string;
+} | {
+    readonly status: "ignored";
+    readonly reason: "invalid-priority" | "unknown-property" | "invalid-value";
+};
+export declare class CssDeclarationBlock {
+    #private;
+    private constructor();
+    static parse(input: string, options?: CssDeclarationBlockOptions): CssDeclarationBlock;
+    static empty(options?: CssDeclarationBlockOptions): CssDeclarationBlock;
+    get length(): number;
+    get declarations(): readonly CssomDeclaration[];
+    get cssText(): string;
+    item(index: number): string;
+    getPropertyValue(name: string): string;
+    getPropertyPriority(name: string): "" | "important";
+    setProperty(name: string, value: string, priority?: string): CssDeclarationMutation;
+    removeProperty(name: string): string;
+}

package/dist/internal/cssom/declarations.js

@@ -0,0 +1,177 @@
+import { validateCssPropertyValue } from "../properties/matcher.js";
+import { resolveCssProperty } from "../properties/registry.js";
+import { parseCssBlockContents, parseCssDeclaration } from "../syntax/parser.js";
+import { serializeCssSyntax } from "../syntax/serialize.js";
+function lowerAscii(value) {
+    return value.replace(/[A-Z]/gu, (character) => character.toLowerCase());
+}
+function propertyIdentity(name) {
+    const property = resolveCssProperty(name);
+    if (property === null)
+        return null;
+    if (property.kind === "custom") {
+        return Object.freeze({ key: property.name, name: property.name });
+    }
+    return Object.freeze({
+        key: lowerAscii(property.name),
+        name: property.name
+    });
+}
+function significant(values) {
+    return values.filter((value) => value.kind !== "whitespace");
+}
+function serializeCssomValue(declaration) {
+    if (declaration.name.startsWith("--")) {
+        return declaration.originalText ?? "";
+    }
+    let result = "";
+    for (const value of significant(declaration.value)) {
+        const serialized = serializeCssSyntax(value);
+        if (value.kind === "comma") {
+            result = result.trimEnd();
+            result += ",";
+        }
+        else {
+            if (result.length > 0)
+                result += " ";
+            result += serialized;
+        }
+    }
+    return result.trim();
+}
+function normalizedDeclaration(declaration, options) {
+    const validation = validateCssPropertyValue(declaration, options.validation);
+    if (validation.status === "invalid")
+        return null;
+    const identity = propertyIdentity(declaration.name);
+    if (identity === null)
+        return null;
+    return Object.freeze({
+        key: identity.key,
+        declaration: Object.freeze({
+            name: identity.name,
+            value: serializeCssomValue(declaration),
+            important: declaration.important
+        })
+    });
+}
+function parseMutationDeclaration(name, value, important, options) {
+    const source = `${name}:${value}${important ? "!important" : ""}`;
+    const result = parseCssDeclaration(source, options.parser);
+    return result.ok ? normalizedDeclaration(result.value, options) : null;
+}
+function priorityStatus(priority) {
+    const normalized = lowerAscii(priority.trim());
+    if (normalized === "")
+        return false;
+    if (normalized === "important")
+        return true;
+    return null;
+}
+export class CssDeclarationBlock {
+    #options;
+    #entries = new Map();
+    constructor(options) {
+        this.#options = options;
+    }
+    static parse(input, options = {}) {
+        const block = new CssDeclarationBlock(options);
+        const parsed = parseCssBlockContents(input, options.parser);
+        if (!parsed.ok)
+            return block;
+        for (const item of parsed.value) {
+            if (item.kind !== "declaration")
+                continue;
+            const normalized = normalizedDeclaration(item, options);
+            if (normalized === null)
+                continue;
+            block.#setNormalized(normalized);
+        }
+        return block;
+    }
+    static empty(options = {}) {
+        return new CssDeclarationBlock(options);
+    }
+    get length() {
+        return this.#entries.size;
+    }
+    get declarations() {
+        return Object.freeze([...this.#entries.values()]);
+    }
+    get cssText() {
+        return [...this.#entries.values()]
+            .map((declaration) => `${declaration.name}: ${declaration.value}` +
+            `${declaration.important ? " !important" : ""};`)
+            .join(" ");
+    }
+    item(index) {
+        if (!Number.isInteger(index) || index < 0)
+            return "";
+        return [...this.#entries.values()][index]?.name ?? "";
+    }
+    getPropertyValue(name) {
+        const identity = propertyIdentity(name);
+        return identity === null
+            ? ""
+            : this.#entries.get(identity.key)?.value ?? "";
+    }
+    getPropertyPriority(name) {
+        const identity = propertyIdentity(name);
+        return identity !== null && this.#entries.get(identity.key)?.important === true
+            ? "important"
+            : "";
+    }
+    setProperty(name, value, priority = "") {
+        const important = priorityStatus(priority);
+        if (important === null) {
+            return Object.freeze({
+                status: "ignored",
+                reason: "invalid-priority"
+            });
+        }
+        if (value.length === 0) {
+            const previousValue = this.removeProperty(name);
+            return Object.freeze({
+                status: "removed",
+                previousValue
+            });
+        }
+        const identity = propertyIdentity(name);
+        if (identity === null) {
+            return Object.freeze({
+                status: "ignored",
+                reason: "unknown-property"
+            });
+        }
+        const normalized = parseMutationDeclaration(name, value, important, this.#options);
+        if (normalized === null) {
+            return Object.freeze({
+                status: "ignored",
+                reason: "invalid-value"
+            });
+        }
+        const previousValue = this.#entries.get(identity.key)?.value ?? "";
+        this.#entries.set(normalized.key, normalized.declaration);
+        return Object.freeze({
+            status: "set",
+            declaration: normalized.declaration,
+            previousValue
+        });
+    }
+    removeProperty(name) {
+        const identity = propertyIdentity(name);
+        if (identity === null)
+            return "";
+        const previous = this.#entries.get(identity.key);
+        this.#entries.delete(identity.key);
+        return previous?.value ?? "";
+    }
+    #setNormalized(normalized) {
+        const previous = this.#entries.get(normalized.key);
+        if (previous?.important === true &&
+            !normalized.declaration.important) {
+            return;
+        }
+        this.#entries.set(normalized.key, normalized.declaration);
+    }
+}

package/dist/internal/generated/css-data.d.ts

@@ -0,0 +1,2 @@
+import type { CssWebrefData } from "../grammar/catalog-types.js";
+export declare const CSS_WEBREF_DATA: CssWebrefData;