feat(docs): update readme and docs

ReadMe.md

@@ -3,9 +3,30 @@
 [![npm version](https://img.shields.io/npm/v/css-patch?style=for-the-badge)](https://www.npmjs.com/package/css-patch)![node version](https://img.shields.io/node/v/css-patch?style=for-the-badge)[![Build status - Linux/OSX](https://img.shields.io/travis/com/Zekfad/css-patch?style=for-the-badge&logo=linux&logoColor=white)](https://travis-ci.com/github/Zekfad/css-patch)[![Build status - Windows](https://img.shields.io/appveyor/build/Zekfad/css-patch?style=for-the-badge&logo=windows&logoColor=white)](https://ci.appveyor.com/project/Zekfad/css-patch)[![Codecov](https://img.shields.io/codecov/c/gh/Zekfad/css-patch?style=for-the-badge)](https://codecov.io/gh/Zekfad/css-patch)
 
 
-css-patch module.
+Generating CSS patches (just like a diff).
 
-## Features
+## Reasons to use
+
+### Themes generation
+
+The easiest way to make a new theme is just copy the file and change some stuff
+or if you use preprocessor (such as SCSS, Less, etc.) you can just change some
+variables and get a new style.
+
+But serving files with big amount of literally the same code is not a good idea,
+so this is when css-patch can help you.
+
+You can pass 2 stylesheets (`original`/`base` and `expected`) to `generateCSSPatch`
+and get a new stylesheet. This new stylesheet is intended to be applied after
+`original` one and will have the same effect as if you applied `expected` one.
+In other words, the new stylesheet will consist of the resulting "overloads" for
+the `original` one.
+
+### Extracting difference
+
+Imagine if you have two versions of the same CSS.
+
+You can use this module to get the "difference" between them.
 
 ## Install
 
@@ -25,7 +46,32 @@ npm i css-patch
 
 [Read the docs on GitHub pages.](https://zekfad.github.io/css-patch/)
 
-## Example
+For advanced usage see the docs for [`transformCSS`](https://zekfad.github.io/css-patch/global.html#transformCSS) function and [`CSSTransformerBase`](https://zekfad.github.io/css-patch/CSSTransformerBase.html) class.
+
+## Possible caveats
+
+###  `unset`
+
+If something existed in `original` stylesheet missing in `expected` one, 
+will result of being transformed to `<something>: unset;`.
+
+### Combined rule orders
+
+Logically the same but with a different order combined rules (e.g. `.a,.b` and `.b,.a`)
+will be considered as a different rules.
+
+### Merged rules
+
+If rules have exact the same name their declarations would be merged (later appeared
+declarations will be a higher priority).
+
+For example `.a{a:1;c:3;}.a{a:2;b:2;}` will be threat as `.a{a:2;b:2;c;3}`.
+
+### Sorting
+
+Declarations are sorted alphabetically.
+
+## Usage example
 
 ### Import
 

docs/CSSTransformerBase.html

@@ -53,7 +53,12 @@ <h1><a href="index.html" class="link">css-patch</a></h1>
         <h2><span class="attribs"><span class="type-signature"></span></span>CSSTransformerBase<span class="signature">()</span><span class="type-signature"></span></h2>
 
             <div class="class-description"><p>CSS AST transformer.
-In order to apply this transformer use static <code>CSSTransformerBase.transform(el)</code>.</p></div>
+In order to apply this transformer use static <code>CSSTransformerBase.transform(el)</code>.
+Advanced usage notes:
+This is a base class for CSS AST transformer.
+You can subclass this class to implement your transformer.
+Just remember to call <code>this.transformSubElements(el.children)</code>
+if you deal with multi-level items (roots, rules, at rules).</p></div>
 
 
 </header>
@@ -73,7 +78,7 @@ <h4 class="name" id="CSSTransformerBase">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line10">line 10</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line15">line 15</a></code>
             </div>
 
         </h4>
@@ -184,7 +189,7 @@ <h4 class="name" id=".transform">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line15">line 15</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line20">line 20</a></code>
             </div>
 
         </h4>
@@ -326,7 +331,7 @@ <h4 class="name" id="atRule">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line75">line 75</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line83">line 83</a></code>
             </div>
 
         </h4>
@@ -570,7 +575,7 @@ <h4 class="name" id="comment">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line108">line 108</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line116">line 116</a></code>
             </div>
 
         </h4>
@@ -814,7 +819,7 @@ <h4 class="name" id="declaration">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line97">line 97</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line105">line 105</a></code>
             </div>
 
         </h4>
@@ -1058,7 +1063,7 @@ <h4 class="name" id="getTransformer">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line49">line 49</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line54">line 54</a></code>
             </div>
 
         </h4>
@@ -1218,7 +1223,7 @@ <h4 class="name" id="root">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line60">line 60</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line65">line 65</a></code>
             </div>
 
         </h4>
@@ -1466,7 +1471,7 @@ <h4 class="name" id="rule">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line86">line 86</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line94">line 94</a></code>
             </div>
 
         </h4>
@@ -1710,7 +1715,7 @@ <h4 class="name" id="transformSubElements">
 
             <div class="container-source members">
                 <code><a href="CSSTransformers_CSSTransformerBase.js.html">CSSTransformers/CSSTransformerBase.js</a></code>,
-                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line31">line 31</a></code>
+                <code><a href="CSSTransformers_CSSTransformerBase.js.html#line36">line 36</a></code>
             </div>
 
         </h4>

docs/CSSTransformers_CSSTransformerBase.js.html

@@ -58,6 +58,11 @@ <h1><a href="index.html" class="link">css-patch</a></h1>
 /**
  * CSS AST transformer.
  * In order to apply this transformer use static `CSSTransformerBase.transform(el)`.
+ * Advanced usage notes:
+ * This is a base class for CSS AST transformer.
+ * You can subclass this class to implement your transformer.
+ * Just remember to call `this.transformSubElements(el.children)`
+ * if you deal with multi-level items (roots, rules, at rules).
  */
 class CSSTransformerBase {
 	/**
@@ -112,7 +117,10 @@ <h1><a href="index.html" class="link">css-patch</a></h1>
 	root(el, i, parentChildren, cb) { // eslint-disable-line no-unused-vars
 		const rootAnchor = Object.create(null);
 
-		el.forEach(child => child.parent = rootAnchor);
+		el.forEach(child => {
+			if ('object' !== typeof (child.parent ?? void 0))
+				child.parent = rootAnchor;
+		});
 
 		return this.transformSubElements(el);
 	}

docs/global.html

@@ -2456,8 +2456,8 @@ <h4 class="name" id="transformCSS">
 
     <div class="description">
         <p>Apply transformations to CSS AST.
-Transformer function can ether return AST or return falsy value
-if transformations was applied to original AST.</p>
+Transformer function can ether return AST or falsy value
+(if transformations was applied to the original AST).</p>
     </div>
 
 

docs/index.html

@@ -61,8 +61,22 @@ <h1><a href="index.html" class="link">css-patch</a></h1>
     <section>
         <article class="readme"><h1>css-patch</h1>
 <p><a href="https://www.npmjs.com/package/css-patch"><img src="https://img.shields.io/npm/v/css-patch?style=for-the-badge" alt="npm version"></a><img src="https://img.shields.io/node/v/css-patch?style=for-the-badge" alt="node version"><a href="https://travis-ci.com/github/Zekfad/css-patch"><img src="https://img.shields.io/travis/com/Zekfad/css-patch?style=for-the-badge&amp;logo=linux&amp;logoColor=white" alt="Build status - Linux/OSX"></a><a href="https://ci.appveyor.com/project/Zekfad/css-patch"><img src="https://img.shields.io/appveyor/build/Zekfad/css-patch?style=for-the-badge&amp;logo=windows&amp;logoColor=white" alt="Build status - Windows"></a><a href="https://codecov.io/gh/Zekfad/css-patch"><img src="https://img.shields.io/codecov/c/gh/Zekfad/css-patch?style=for-the-badge" alt="Codecov"></a></p>
-<p>css-patch module.</p>
-<h2>Features</h2>
+<p>Generating CSS patches (just like a diff).</p>
+<h2>Reasons to use</h2>
+<h3>Themes generation</h3>
+<p>The easiest way to make a new theme is just copy the file and change some stuff
+or if you use preprocessor (such as SCSS, Less, etc.) you can just change some
+variables and get a new style.</p>
+<p>But serving files with big amount of literally the same code is not a good idea,
+so this is when css-patch can help you.</p>
+<p>You can pass 2 stylesheets (<code>original</code>/<code>base</code> and <code>expected</code>) to <code>generateCSSPatch</code>
+and get a new stylesheet. This new stylesheet is intended to be applied after
+<code>original</code> one and will have the same effect as if you applied <code>expected</code> one.
+In other words, the new stylesheet will consist of the resulting &quot;overloads&quot; for
+the <code>original</code> one.</p>
+<h3>Extracting difference</h3>
+<p>Imagine if you have two versions of the same CSS.</p>
+<p>You can use this module to get the &quot;difference&quot; between them.</p>
 <h2>Install</h2>
 <p>Install via yarn:</p>
 <pre class="prettyprint source"><code>yarn add css-patch
@@ -72,7 +86,21 @@ <h2>Install</h2>
 </code></pre>
 <h2>Docs</h2>
 <p><a href="https://zekfad.github.io/css-patch/">Read the docs on GitHub pages.</a></p>
-<h2>Example</h2>
+<p>For advanced usage see the docs for <a href="https://zekfad.github.io/css-patch/global.html#transformCSS"><code>transformCSS</code></a> function and <a href="https://zekfad.github.io/css-patch/CSSTransformerBase.html"><code>CSSTransformerBase</code></a> class.</p>
+<h2>Possible caveats</h2>
+<h3><code>unset</code></h3>
+<p>If something existed in <code>original</code> stylesheet missing in <code>expected</code> one,
+will result of being transformed to <code>&lt;something&gt;: unset;</code>.</p>
+<h3>Combined rule orders</h3>
+<p>Logically the same but with a different order combined rules (e.g. <code>.a,.b</code> and <code>.b,.a</code>)
+will be considered as a different rules.</p>
+<h3>Merged rules</h3>
+<p>If rules have exact the same name their declarations would be merged (later appeared
+declarations will be a higher priority).</p>
+<p>For example <code>.a{a:1;c:3;}.a{a:2;b:2;}</code> will be threat as <code>.a{a:2;b:2;c;3}</code>.</p>
+<h3>Sorting</h3>
+<p>Declarations are sorted alphabetically.</p>
+<h2>Usage example</h2>
 <h3>Import</h3>
 <h4>CommonJS</h4>
 <pre class="prettyprint source lang-js"><code>const { generateCSSPatch, } = require('css-patch');

docs/transformCSS.js.html

@@ -55,8 +55,8 @@ <h1><a href="index.html" class="link">css-patch</a></h1>
 
 /**
  * Apply transformations to CSS AST.
- * Transformer function can ether return AST or return falsy value
- * if transformations was applied to original AST.
+ * Transformer function can ether return AST or falsy value
+ * (if transformations was applied to the original AST).
  * @param {string}   css         Stylesheet to transform.
  * @param {Function} transformer Transformer function.
  * @returns {string} Transformed stylesheet.

src/CSSTransformers/CSSTransformerBase.js

@@ -6,6 +6,11 @@ import { getNodeType, } from '../AST';
 /**
  * CSS AST transformer.
  * In order to apply this transformer use static `CSSTransformerBase.transform(el)`.
+ * Advanced usage notes:
+ * This is a base class for CSS AST transformer.
+ * You can subclass this class to implement your transformer.
+ * Just remember to call `this.transformSubElements(el.children)`
+ * if you deal with multi-level items (roots, rules, at rules).
  */
 class CSSTransformerBase {
 	/**
@@ -60,7 +65,10 @@ class CSSTransformerBase {
 	root(el, i, parentChildren, cb) { // eslint-disable-line no-unused-vars
 		const rootAnchor = Object.create(null);
 
-		el.forEach(child => child.parent = rootAnchor);
+		el.forEach(child => {
+			if ('object' !== typeof (child.parent ?? void 0))
+				child.parent = rootAnchor;
+		});
 
 		return this.transformSubElements(el);
 	}

src/transformCSS.js

@@ -3,8 +3,8 @@ import { compile, serialize, stringify, } from 'stylis';
 
 /**
  * Apply transformations to CSS AST.
- * Transformer function can ether return AST or return falsy value
- * if transformations was applied to original AST.
+ * Transformer function can ether return AST or falsy value
+ * (if transformations was applied to the original AST).
  * @param {string}   css         Stylesheet to transform.
  * @param {Function} transformer Transformer function.
  * @returns {string} Transformed stylesheet.

types/CSSTransformers/CSSTransformerBase.d.ts

@@ -2,6 +2,11 @@ export default CSSTransformerBase;
 /**
  * CSS AST transformer.
  * In order to apply this transformer use static `CSSTransformerBase.transform(el)`.
+ * Advanced usage notes:
+ * This is a base class for CSS AST transformer.
+ * You can subclass this class to implement your transformer.
+ * Just remember to call `this.transformSubElements(el.children)`
+ * if you deal with multi-level items (roots, rules, at rules).
  */
 declare class CSSTransformerBase {
     /**

types/transformCSS.d.ts

@@ -1,8 +1,8 @@
 export default transformCSS;
 /**
  * Apply transformations to CSS AST.
- * Transformer function can ether return AST or return falsy value
- * if transformations was applied to original AST.
+ * Transformer function can ether return AST or falsy value
+ * (if transformations was applied to the original AST).
  * @param {string}   css         Stylesheet to transform.
  * @param {Function} transformer Transformer function.
  * @returns {string} Transformed stylesheet.