# css-parser

## Project overview
- This repository contains css-parser, a dependency-free all-in-one CSS parsing solution for Node.js and browsers.
- The library follows the CSS Syntax Module Level 3 specification and uses MDN syntax data for validation.
- It is designed for fault-tolerant parsing, full AST and typed-token analysis, AST manipulation, CSS Modules, minification, color processing, and syntax lowering.
- CSS is always fully parsed into a structured AST, and token values are typed so plugins and transforms can work against semantic data instead of raw strings.

## Installation
- npm: npm install @tbela99/css-parser
- jsr: deno add @tbela99/css-parser
- Main entry points:
  - @tbela99/css-parser or @tbela99/css-parser/node
  - @tbela99/css-parser/web

## Core APIs
- parse(css, options): async api to parse CSS and returns an AST, errors, and stats.
- parseSync(css, options): sync api to parse CSS and returns an AST, errors, and stats.
- render(ast, options): renders an AST back to CSS text.
- transform(css, options): async api to parse CSS and generate output in one step.
- transformSync(css, options): sync api to parse CSS and generate output in one step.
- walk(ast, filter): traverses the AST for custom transformations.

## Common capabilities
- Parse CSS into an AST and inspect or modify it.
- Validate declarations against CSS syntax definitions.
- Support CSS Modules with scoped class generation.
- Minify CSS safely with options such as inlineCssVariables, computeCalcExpression, removeDuplicateDeclarations, and beautify.
- Transform ASTs through visitors and custom traversal logic.
- Support plugin-style extensions through the visitor API, where custom handlers can observe and mutate AST nodes during enter/visit/leave phases.
- Lower modern CSS syntax such as nested CSS and if() to broadly compatible output.
- Generate source maps and handle advanced color functions and conversions.

## Visitor-based plugin model
- The parser exposes a visitor option that accepts node-specific handlers keyed by AST node type and event type.
- Plugins can be implemented as reusable visitor maps that inspect or transform nodes such as Rule, AtRule, Declaration, KeyframesRule, and Value nodes.
- This allows extension code to run alongside the core parser without modifying the parser itself.

## Typical usage
```ts
import {transform, ColorType} from '@tbela99/css-parser';

const css = `.foo { color: red; }`;
const result = await transform(css, {
  beautify: true,
  convertColor: ColorType.SRGB,
});

console.log(result.code);
```

## Important behavior notes
- parse(), parseSync(), transform() and transformSync() are lenient by default and preserve unknown constructs unless configured otherwise.
- Comments are removed by default; preserve them with removeComments: false or preserveLicense: true.
- Validation errors are available through the parse/transform result and through node.state and node.errors.
- The library prioritizes compact output while preserving semantics.

## Useful concepts
- parse(), parseSync() return AST, errors, and stats.
- render() turns an AST into CSS text.
- transform(), transformSync() perform parsing and rendering together.
- AST node types include StyleSheet, Rule, AtRule, Declaration, Comment, and Keyframes variants.

## Documentation files
- files/getting-started.md
- files/usage.md
- files/validation.md
- files/css-module.md
- files/minification.md
- files/transform.md
- files/syntax-lowering.md
- files/ast.md
- files/utilities.md

## Repository layout
- src/: parser implementation and core library code
- test/: regression and behavior tests
- files/: documentation content used by the docs site
- benchmark/: performance and minification benchmarks
- scripts/: helper scripts and patches