update docs #116

Author: tbela99

CHANGELOG.md

@@ -17,7 +17,7 @@
 - [x] selector
 - [x] dashed ident (custom properties)
 - [x] css at-rule property
-- [x] css at-rule values
+- [x] css at-rule value
 - [x] keyframe animations
 - [x] grid
 - naming

README.md

@@ -23,23 +23,23 @@ $ deno add @tbela99/css-parser
 ## Features
 
 - no dependency
-- validate CSS based upon mdn-data
-- generate CSS module output
-- fault-tolerant parser, will try to fix invalid tokens according to the CSS syntax module 3 recommendations.
+- CSS validation based upon mdn-data
+- CSS modules support
+- fault-tolerant parser implementing the CSS syntax module 3 recommendations.
 - fast and efficient minification without unsafe transforms,
   see [benchmark](https://tbela99.github.io/css-parser/benchmark/index.html)
-- minify colors: color(), lab(), lch(), oklab(), oklch(), color-mix(), light-dark(), system colors and
+- colors minification: color(), lab(), lch(), oklab(), oklch(), color-mix(), light-dark(), system colors and
   relative color
-- generate nested css rules
-- convert nested css rules to legacy syntax
-- convert colors to any supported color format
-- generate sourcemap
-- compute css shorthands. see supported properties list below
-- minify css transform functions
-- evaluate math functions: calc(), clamp(), min(), max(), etc.
-- inline css variables
-- remove duplicate properties
-- flatten @import rules
+- color conversion to any supported color format
+- automatic nested css rules generation
+- nested css rules conversion to legacy syntax
+- sourcemap generation
+- css shorthands computation. see the supported properties list below
+- css transform functions minification
+- css math functions evaluation: calc(), clamp(), min(), max(), etc.
+- css variables inlining
+- duplicate properties removal
+- @import rules flattening
 - experimental CSS prefix removal
 
 ## Online documentation
@@ -54,7 +54,7 @@ Try it [online](https://tbela99.github.io/css-parser/playground/)
 
 There are several ways to import the library into your application.
 
-### Node exports
+### Node
 
 import as a module
 
@@ -65,7 +65,7 @@ import {transform} from '@tbela99/css-parser';
 // ...
 ```
 
-### Deno exports
+### Deno
 
 import as a module
 
@@ -85,7 +85,7 @@ const {transform} = require('@tbela99/css-parser/cjs');
 // ...
 ```
 
-### Web export
+### Web 
 
 Programmatic import
 
@@ -163,19 +163,27 @@ Javascript umd module from cdn
 </script>
 ```
 
-## Transform
+## Exported functions
 
-Parse and render css in a single pass.
+```ts
 
-### Usage
-
-```typescript
+/* parse and render css */
+transform(css: string | ReadableStream<string>, options?: TransformOptions = {}): Promise<TransformResult>
+/* parse css */
+parse(css: string | ReadableStream<string>, options?: ParseOptions = {}): Promise<ParseResult>;
+/* render ast */
+render(ast: AstNode, options?: RenderOptions = {}): RenderResult;
+/* parse and render css file or url */
+transformFile(filePathOrUrl: string, options?: TransformOptions = {}, asStream?: boolean): Promise<TransformResult>;
+/* parse css file or url */
+parseFile(filePathOrUrl: string, options?: ParseOptions = {}, asStream?: boolean): Promise<ParseResult>;
 
-transform(css: string | ReadableStream<string>, transformOptions: TransformOptions = {}): TransformResult
-parse(css: string | ReadableStream<string>, parseOptions: ParseOptions = {}): ParseResult;
-render(ast: AstNode, renderOptions: RenderOptions = {}): RenderResult;
 ```
 
+## Transform
+
+Parse and render css in a single pass.
+
 ### Example
 
 ```javascript
@@ -209,7 +217,7 @@ Include ParseOptions and RenderOptions
 > Minify Options
 
 - minify: boolean, optional. default to _true_. optimize ast.
-- pass: number, optional. minification pass. default to 1
+- pass: number, optional. minification passes. default to 1
 - nestingRules: boolean, optional. automatically generated nested rules.
 - expandNestingRules: boolean, optional. convert nesting rules into separate rules. will automatically set nestingRules
   to false.
@@ -900,7 +908,7 @@ for (const {node, parent, root} of walk(ast)) {
 
 Ast can be transformed using node visitors
 
-### Exemple 1: Declaration
+### Example 1: Declaration
 
 the visitor is called for any declaration encountered
 
@@ -935,7 +943,7 @@ console.debug(result.code);
 // .foo{transform:scale(calc(40/3))}
 ```
 
-### Exemple 2: Declaration
+### Example 2: Declaration
 
 the visitor is called only on 'height' declarations
 
@@ -990,7 +998,7 @@ console.debug(result.code);
 
 ```
 
-### Exemple 3: At-Rule
+### Example 3: At-Rule
 
 the visitor is called on any at-rule
 
@@ -1032,7 +1040,7 @@ console.debug(result.code);
 
 ```
 
-### Exemple 4: At-Rule
+### Example 4: At-Rule
 
 the visitor is called only for at-rule media
 
@@ -1074,7 +1082,7 @@ console.debug(result.code);
 
 ```
 
-### Exemple 5: Rule
+### Example 5: Rule
 
 the visitor is called on any Rule
 
@@ -1110,7 +1118,7 @@ console.debug(result.code);
 
 ```
 
-### Exemple 6: Rule
+### Example 6: Rule
 
 Adding declarations to any rule
 

dist/index-umd-web.js

@@ -677,19 +677,19 @@
     exports.ModuleCaseTransformEnum = void 0;
     (function (ModuleCaseTransformEnum) {
         /**
-         * export as-is
+         * export class names as-is
          */
         ModuleCaseTransformEnum[ModuleCaseTransformEnum["IgnoreCase"] = 1] = "IgnoreCase";
         /**
-         * transform class names and mapping key name
+         * transform mapping key name
          */
         ModuleCaseTransformEnum[ModuleCaseTransformEnum["CamelCase"] = 2] = "CamelCase";
         /**
          * transform class names and mapping key name
          */
         ModuleCaseTransformEnum[ModuleCaseTransformEnum["CamelCaseOnly"] = 4] = "CamelCaseOnly";
         /**
-         * transform class names and mapping key name
+         * transform mapping key name
          */
         ModuleCaseTransformEnum[ModuleCaseTransformEnum["DashCase"] = 8] = "DashCase";
         /**
@@ -10985,7 +10985,10 @@
     		syntax: "none | discard-before || discard-after || discard-inner"
     	},
     	composes: {
-    		syntax: "<composes-selector>"
+    		syntax: "<composes-selector>#"
+    	},
+    	"composes-selector": {
+    		syntax: "<ident>+ [from [global&&<string>]]?"
     	}
     };
     var functions = {
@@ -11011,7 +11014,7 @@
     		syntax: "atan2( <calc-sum>, <calc-sum> )"
     	},
     	attr: {
-    		syntax: "attr( <attr-name> <type-or-unit>? [, <attr-fallback> ]? )"
+    		syntax: "attr( <attr-name> <attr-type>? , <declaration-value>? )"
     	},
     	blur: {
     		syntax: "blur( <length>? )"
@@ -11364,14 +11367,17 @@
     		syntax: "scroll | fixed | local"
     	},
     	"attr()": {
-    		syntax: "attr( <attr-name> <type-or-unit>? [, <attr-fallback> ]? )"
+    		syntax: "attr( <attr-name> <attr-type>? , <declaration-value>? )"
     	},
     	"attr-matcher": {
     		syntax: "[ '~' | '|' | '^' | '$' | '*' ]? '='"
     	},
     	"attr-modifier": {
     		syntax: "i | s"
     	},
+    	"attr-type": {
+    		syntax: "type( <syntax> ) | raw-string | number | <attr-unit>"
+    	},
     	"attribute-selector": {
     		syntax: "'[' <wq-name> ']' | '[' <wq-name> <attr-matcher> [ <string-token> | <ident-token> ] <attr-modifier>? ']'"
     	},
@@ -18004,6 +18010,7 @@
      * @param iter
      * @param options
      *
+     * @throws Error
      * @private
      */
     async function doParse(iter, options = {}) {

dist/index.cjs

@@ -678,19 +678,19 @@ exports.ColorType = void 0;
 exports.ModuleCaseTransformEnum = void 0;
 (function (ModuleCaseTransformEnum) {
     /**
-     * export as-is
+     * export class names as-is
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["IgnoreCase"] = 1] = "IgnoreCase";
     /**
-     * transform class names and mapping key name
+     * transform mapping key name
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["CamelCase"] = 2] = "CamelCase";
     /**
      * transform class names and mapping key name
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["CamelCaseOnly"] = 4] = "CamelCaseOnly";
     /**
-     * transform class names and mapping key name
+     * transform mapping key name
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["DashCase"] = 8] = "DashCase";
     /**
@@ -10986,7 +10986,10 @@ var declarations = {
 		syntax: "none | discard-before || discard-after || discard-inner"
 	},
 	composes: {
-		syntax: "<composes-selector>"
+		syntax: "<composes-selector>#"
+	},
+	"composes-selector": {
+		syntax: "<ident>+ [from [global&&<string>]]?"
 	}
 };
 var functions = {
@@ -11012,7 +11015,7 @@ var functions = {
 		syntax: "atan2( <calc-sum>, <calc-sum> )"
 	},
 	attr: {
-		syntax: "attr( <attr-name> <type-or-unit>? [, <attr-fallback> ]? )"
+		syntax: "attr( <attr-name> <attr-type>? , <declaration-value>? )"
 	},
 	blur: {
 		syntax: "blur( <length>? )"
@@ -11365,14 +11368,17 @@ var syntaxes = {
 		syntax: "scroll | fixed | local"
 	},
 	"attr()": {
-		syntax: "attr( <attr-name> <type-or-unit>? [, <attr-fallback> ]? )"
+		syntax: "attr( <attr-name> <attr-type>? , <declaration-value>? )"
 	},
 	"attr-matcher": {
 		syntax: "[ '~' | '|' | '^' | '$' | '*' ]? '='"
 	},
 	"attr-modifier": {
 		syntax: "i | s"
 	},
+	"attr-type": {
+		syntax: "type( <syntax> ) | raw-string | number | <attr-unit>"
+	},
 	"attribute-selector": {
 		syntax: "'[' <wq-name> ']' | '[' <wq-name> <attr-matcher> [ <string-token> | <ident-token> ] <attr-modifier>? ']'"
 	},
@@ -18144,6 +18150,7 @@ async function generateScopedName(localName, filePath, pattern, hashLength = 5)
  * @param iter
  * @param options
  *
+ * @throws Error
  * @private
  */
 async function doParse(iter, options = {}) {

dist/index.d.ts

@@ -662,19 +662,19 @@ declare enum ColorType {
 }
 declare enum ModuleCaseTransformEnum {
     /**
-     * export as-is
+     * export class names as-is
      */
     IgnoreCase = 1,
     /**
-     * transform class names and mapping key name
+     * transform mapping key name
      */
     CamelCase = 2,
     /**
      * transform class names and mapping key name
      */
     CamelCaseOnly = 4,
     /**
-     * transform class names and mapping key name
+     * transform mapping key name
      */
     DashCase = 8,
     /**
@@ -3385,7 +3385,7 @@ export declare interface ModuleOptions {
     hashLength?: number;
 
     /**
-     * the pattern use to generate scoped names. the supported placeholders are:
+     * the pattern used to generate scoped names. the supported placeholders are:
      * - name: the file base name without the extension
      * - hash: the file path hash
      * - local: the local name
@@ -3476,8 +3476,8 @@ export declare interface ModuleOptions {
      * optional function to generate scoped name
      * @param localName
      * @param filePath
-     * @param hashLength
      * @param pattern see {@link ModuleOptions.pattern}
+     * @param hashLength
      */
     generateScopedName?: (
         localName: string,

dist/lib/ast/types.js

@@ -671,19 +671,19 @@ var ColorType;
 var ModuleCaseTransformEnum;
 (function (ModuleCaseTransformEnum) {
     /**
-     * export as-is
+     * export class names as-is
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["IgnoreCase"] = 1] = "IgnoreCase";
     /**
-     * transform class names and mapping key name
+     * transform mapping key name
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["CamelCase"] = 2] = "CamelCase";
     /**
      * transform class names and mapping key name
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["CamelCaseOnly"] = 4] = "CamelCaseOnly";
     /**
-     * transform class names and mapping key name
+     * transform mapping key name
      */
     ModuleCaseTransformEnum[ModuleCaseTransformEnum["DashCase"] = 8] = "DashCase";
     /**

dist/lib/parser/parse.js

@@ -171,6 +171,7 @@ async function generateScopedName(localName, filePath, pattern, hashLength = 5)
  * @param iter
  * @param options
  *
+ * @throws Error
  * @private
  */
 async function doParse(iter, options = {}) {