@tbela99/css-parser 0.0.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 # css-parser
 
-CSS parser for node and the browser
+CSS parser and minifier for node and the browser
 
 ## Installation
 
@@ -12,11 +12,15 @@ $ npm install @tbela99/css-parser
 
 ## Features
 
-- fault tolerant parser, will try to fix invalid tokens according to the CSS syntax module 3 recommendations.
+- fault-tolerant parser, will try to fix invalid tokens according to the CSS syntax module 3 recommendations.
 - efficient minification, see [benchmark](https://tbela99.github.io/css-parser/benchmark/index.html)
 - automatically generate nested css rules
+- generate sourcemap
 - compute css shorthands. see the list below
-- expand nested css
+- compute calc() expression
+- nested css expansion
+- remove duplicate properties
+- flatten @import rules
 - works the same way in node and web browser
 
 ## Transform
@@ -25,9 +29,9 @@ Parse and render css in a single pass.
 
 ### Usage
 
-```javascript
+```typescript
 
-transform(css, transformOptions = {})
+transform(css, transformOptions: TransformOptions = {}): TransformResult
 ```
 
 ### Example
@@ -36,7 +40,7 @@ transform(css, transformOptions = {})
 
 import {transform} from '@tbela99/css-parser';
 
-const {ast, code, errors, stats} = await transform(css, {minify: true, resolveImport: true, cwd: 'files/css'});
+const {ast, code, map, errors, stats} = await transform(css, {minify: true, resolveImport: true, cwd: 'files/css'});
 ```
 
 ### TransformOptions
@@ -45,23 +49,37 @@ Include ParseOptions and RenderOptions
 
 #### ParseOptions
 
-- src: string, optional. css file location to be used with sourcemap.
 - minify: boolean, optional. default to _true_. optimize ast.
+- src: string, optional. original css file location to be used with sourcemap.
+- sourcemap: boolean, optional. preserve node location data.
 - nestingRules: boolean, optional. automatically generated nested rules.
-- removeEmpty: boolean, remove empty nodes from the ast.
-- location: boolean, optional. includes node location in the ast, required for sourcemap generation.
+- expandNestingRules: boolean, optional. convert nesting rules into separate rules. will automatically set nestingRules to false.
+- removeCharset: boolean, optional. remove @charset.
+- removeEmpty: boolean, optional. remove empty rule lists from the ast.
+- resolveUrls: boolean, optional. resolve css 'url()' according to the parameters 'src' and 'cwd'
+- resolveImport: boolean, optional. replace @import rule by the content of its referenced stylesheet.
 - cwd: string, optional. the current working directory. when specified url() are resolved using this value
-- resolveImport: boolean, optional. replace @import node by the content of the referenced stylesheet.
-- resolveUrls: boolean, optional. resolve css url() according to the parameters 'src' and 'cwd'
+- removeDuplicateDeclarations: boolean, optional. remove duplicate declarations.
+- computeShorthand: boolean, optional. compute shorthand properties.
+- inlineCssVariables: boolean, optional. replace css variables with their current value.
+- computeCalcExpression: boolean, optional. evaluate calc() expression
+- inlineCssVariables: boolean, optional. replace some css variables with their actual value. they must be declared once in the :root {} rule.
+- visitor: VisitorNodeMap, optional. node visitor used to transform the ast.
+- signal: AbortSignal, optional. abort parsing.
 
 #### RenderOptions
+
 - minify: boolean, optional. default to _true_. minify css output.
+- expandNestingRules: boolean, optional. expand nesting rules.
+- sourcemap: boolean, optional. generate sourcemap
+- preserveLicense: boolean, force preserving comments starting with '/\*!' when minify is enabled.
+- sourcemap: boolean, optional. generate sourcemap.
 - indent: string, optional. css indention string. uses space character by default.
-- newLine: string, new line character.
+- newLine: string, optional. new line character.
 - removeComments: boolean, remove comments in generated css.
-- preserveLicense: boolean, force preserving comments starting with '/\*!' when minify is enabled.
 - colorConvert: boolean, convert colors to hex.
-
+- output: string, optional. file where to store css. url() are resolved according to the specified value. no file is created though.
+- cwd: string, optional. value used as current working directory. when output is not provided, urls are resolved according to this value.
 
 ## Parsing
 
@@ -163,34 +181,27 @@ Single JavaScript file
 
 CSS
 
-```css
+```javascript
+const {parse, render} = require("@tbela99/css-parser/cjs");
 
+const css = `
 table.colortable td {
-  text-align:center;
+ text-align:center;
 }
 table.colortable td.c {
-  text-transform:uppercase;
+ text-transform:uppercase;
 }
 table.colortable td:first-child, table.colortable td:first-child+td {
-  border:1px solid black;
+ border:1px solid black;
 }
 table.colortable th {
-  text-align:center;
-  background:black;
-  color:white;
+ text-align:center;
+ background:black;
+ color:white;
 }
-```
-
-Javascript
-```javascript
-import {parse, render} from '@tbela99/css-parser';
+`;
 
-
-const options = {minify: true, nestingRules: true};
-
-const {code} = await parse(css, options).then(result => render(result.ast, {minify: false}));
-//
-console.debug(code);
+const result = await parse(css, {nestingRules:true}).then(result => render(result.ast, {minify:false}).code);
 ```
 
 Result
@@ -270,6 +281,69 @@ table.colortable th {
 }
 ```
 
+### Example 3
+
+### Calc() resolution
+
+```javascript
+
+import {parse, render} from '@tbela99/css-parser';
+
+const css = `
+
+.foo-bar {
+    width: calc(100px * 2);
+    height: calc(((75.37% - 63.5px) - 900px) + (2 * 100px));
+    max-width: calc(3.5rem + calc(var(--bs-border-width) * 2));
+}
+`;
+
+const prettyPrint = await parse(css).then(result => render(result.ast, {minify: false}).code);
+
+```
+result
+
+```css
+.foo-bar {
+    width: 200px;
+    height: calc(75.37% - 763.5px);
+    max-width: calc(3.5rem + var(--bs-border-width)*2)
+}
+```
+
+### Example 4
+
+### CSS variable inlining
+
+```javascript
+
+import {parse, render} from '@tbela99/css-parser';
+
+const css = `
+
+:root {
+
+--preferred-width: 20px;
+}
+.foo-bar {
+
+    width: calc(calc(var(--preferred-width) + 1px) / 3 + 5px);
+    height: calc(100% / 4);}
+`
+
+const prettyPrint = await parse(css, {inlineCssVariables: true}).then(result => render(result.ast, {minify: false}).code);
+
+```
+result
+
+```css
+.foo-bar {
+    width: 12px;
+    height: 25%
+}
+
+```
+
 ## AST
 
 ### Comment
@@ -300,8 +374,14 @@ table.colortable th {
 - typ: string 'Stylesheet'
 - chi: array of children
 
+## Sourcemap
+
+- [x] sourcemap generation
+
 ## Minification
 
+- [x] reduce calc()
+- [x] inline css variables
 - [x] merge identical rules
 - [x] merge adjacent rules
 - [x] minify colors
@@ -311,12 +391,12 @@ table.colortable th {
 - [x] conditionally unwrap :is()
 - [x] automatic css nesting
 - [x] automatically wrap selectors using :is()
-- [x] multi-level shorthand properties (border - [border-width, border-color, border-style, etc.]) https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties
 - [x] avoid reparsing (declarations, selectors, at-rule)
 - [x] node and browser versions
 - [x] decode and replace utf-8 escape sequence
 
-## Computed shorthands
+## Computed shorthands properties
+- [x] animation
 - [x] background
 - [x] border
 - [x] border-bottom
@@ -329,12 +409,216 @@ table.colortable th {
 - [x] border-width
 - [x] font
 - [x] inset
+- [x] list-style
 - [x] margin
 - [x] outline
 - [x] overflow
 - [x] padding
 - [x] text-decoration
+- [x] text-emphasis
+- [x] transition
 
 ## Performance
 
 - [x] flatten @import
+
+## Node Transformation
+
+Ast can be transformed using node visitors
+
+### Exemple 1: Declaration
+
+```typescript
+
+import {AstDeclaration, ParserOptions} from "../src/@types";
+
+const options: ParserOptions = {
+
+    visitor: {
+
+        Declaration: (node: AstDeclaration) => {
+
+            if (node.nam == '-webkit-transform') {
+
+                node.nam = 'transform'
+            }
+        }
+    }
+}
+
+const css = `
+
+.foo {
+    -webkit-transform: scale(calc(100 * 2/ 15));
+}
+`;
+
+console.debug(await transform(css, options));
+
+// .foo{transform:scale(calc(40/3))}
+```
+
+### Exemple 2: Declaration
+
+```typescript
+
+import {AstDeclaration, LengthToken, ParserOptions} from "../src/@types";
+import {EnumToken, NodeType} from "../src/lib";
+import {transform} from "../src/node";
+
+const options: ParserOptions = {
+
+    visitor: {
+
+        Declaration: {
+
+            // called only for height declaration
+            height: (node: AstDeclaration): AstDeclaration[] => {
+
+
+                return [
+                    node,
+                    {
+
+                        typ: NodeType.DeclarationNodeType,
+                        nam: 'width',
+                        val: [
+                            <LengthToken>{
+                                typ: EnumToken.Length,
+                                val: '3',
+                                unit: 'px'
+                            }
+                        ]
+                    }
+                ];
+            }
+        }
+    }
+};
+
+const css = `
+
+.foo {
+    height: calc(100px * 2/ 15);
+}
+`;
+
+console.debug(await transform(css, options));
+
+// .foo{height:calc(40px/3);width:3px}
+
+```
+
+### Exemple 3: At-Rule
+
+```typescript
+
+import {AstAtRule, ParserOptions} from "../src/@types";
+import {transform} from "../src/node";
+
+
+const options: ParserOptions = {
+
+    visitor: {
+
+        AtRule: (node: AstAtRule): AstAtRule => {
+            
+            if (node.nam == 'media') {
+
+                return {...node, val: 'all'}
+            }
+        }
+    }
+};
+
+const css = `
+
+@media screen {
+       
+    .foo {
+
+            height: calc(100px * 2/ 15);    
+    } 
+}
+`;
+
+console.debug(await transform(css, options));
+
+// .foo{height:calc(40px/3)}
+
+```
+
+### Exemple 4: At-Rule
+
+```typescript
+
+import {AstAtRule, ParserOptions} from "../src/@types";
+import {transform} from "../src/node";
+
+const options: ParserOptions = {
+
+    visitor: {
+
+        AtRule: {
+
+            media: (node: AstAtRule): AstAtRule => {
+
+                return {...node, val: 'all'}
+            }
+        }
+    }
+};
+
+const css = `
+
+@media screen {
+       
+    .foo {
+
+            height: calc(100px * 2/ 15);    
+    } 
+}
+`;
+
+console.debug(await transform(css, options));
+
+// .foo{height:calc(40px/3)}
+
+```
+
+### Exemple 5: Rule
+
+```typescript
+
+import {AstAtRule, ParserOptions} from "../src/@types";
+import {transform} from "../src/node";
+
+const options: ParserOptions = {
+
+    visitor: {
+
+
+        Rule (node: AstRule): AstRule {
+
+            return {...node, sel: '.foo,.bar,.fubar'};
+        }
+    }
+};
+
+const css = `
+
+    .foo {
+
+            height: calc(100px * 2/ 15);    
+    } 
+`;
+
+console.debug(await transform(css, options));
+
+// .foo,.bar,.fubar{height:calc(40px/3)}
+
+```
+
+---
+
+Thanks to [Jetbrains](https://jetbrains.com) for sponsoring this project with a free license