Merge remote-tracking branch 'origin/refactor-generators' into master

Author: fczbkk

README.md

@@ -2,7 +2,32 @@
 
 JavaScript library for creating CSS selectors for a given DOM element or multiple DOM elements.
 
-It also generates shorter selectors and is faster and/or more robust than many other libraries - see this [comparison](https://github.com/fczbkk/css-selector-generator-benchmark) and select the best alternative for your use case.
+See the [benchmark](https://fczbkk.github.io/css-selector-generator-benchmark/) to compare the speed and features of CSS Selector Generator with similar libraries.
+
+## Table of Contents
+
+- [Install](#install)
+- [How to use](#how-to-use)
+  - [Usage without NPM](#usage-without-npm)
+  - [Usage with virtual DOM (e.g. JSDOM)](#usage-with-virtual-dom-eg-jsdom)
+  - [Shadow DOM](#shadow-dom)
+  - [TypeScript](#typescript)
+  - [Multi-element selector](#multi-element-selector)
+  - [Fallback](#fallback)
+- [Options](#options)
+  - [Selector types](#selector-types)
+  - [Root element](#root-element)
+  - [Blacklist](#blacklist)
+  - [Whitelist](#whitelist)
+  - [Combine within selector](#combine-within-selector)
+  - [Combine between selectors](#combine-between-selectors)
+  - [Include tag](#include-tag)
+  - [Max combinations](#max-combinations)
+  - [Max candidates](#max-candidates)
+  - [Max results](#max-results)
+  - [Use scope](#use-scope)
+- [Bug reports, feature requests and contact](#bug-reports-feature-requests-and-contact)
+- [License](#license)
 
 ## Try it
 
@@ -90,6 +115,24 @@ If you don't want to use this library with NPM, you can download it from the "bu
 If you want to use this library with Node, usually for testing, don't require it directly into the Node process. It will not work, because there's no `window` object and there are no elements to select. Instead, you have to add the library to the virtual `window` object. Here are instructions how to do it in JSDOM, other libraries will work in a similar way:
 https://github.com/jsdom/jsdom/wiki/Don't-stuff-jsdom-globals-onto-the-Node-global
 
+### Shadow DOM
+
+This library supports generating selectors for elements within shadow DOM. When you provide an element that is part of a shadow DOM tree, the library will automatically infer the shadow root and generate a selector relative to it.
+
+```javascript
+const shadowRoot = element.attachShadow({ mode: "open" });
+const shadowElement = shadowRoot.appendChild(document.createElement("div"));
+shadowElement.className = "shadowElement";
+
+// Automatically detects shadow root
+getCssSelector(shadowElement);
+// ".shadowElement"
+
+// Or explicitly specify the shadow root
+getCssSelector(shadowElement, { root: shadowRoot });
+// ".shadowElement"
+```
+
 ### TypeScript
 
 This library is written in TypeScript and includes type definitions. You can import the types directly: