readme improvements

Author: bartveneman

README.md

@@ -20,11 +20,53 @@ npm install @projectwallace/css-code-coverage
 
 ## Usage
 
-### Prerequisites
+```ts
+import { calculate_coverage } from '@projectwallace/css-code-coverage'
+
+function parse_html(html) {
+	return new DOMParser().parseFromString(html, 'text/html')
+}
+
+let report = calculcate_coverage(coverage_data, parse_html)
+```
+
+See [src/index.ts](https://github.com/projectwallace/css-code-coverage/blob/main/src/index.ts) for the data that's returned.
+
+## Collecting CSS Coverage
+
+There are two principal ways of collecting CSS Coverage data:
+
+### Browser devtools
+
+In Edge, Chrome or chromium you can manually collect coverage in the browser's DevTools. In all cases you'll generate coverage data manually and the browser will let you export the data to a JSON file. Note that this JSON contains both JS coverage as well as the CSS coverage. Learn how it works:
+
+- Collect coverage in Microsoft Edge: https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/
+- Collect coevrage in Google Chrome: https://developer.chrome.com/docs/devtools/coverage/
+
+Additionally, DevTools Tips writes about it in their [explainer](https://devtoolstips.org/tips/en/detect-unused-code/).
+
+### Coverage API
 
-You have collected browser coverage data of your CSS. There are several ways to do this:
+Both Puppeteer and Playwright provide an API to programmatically get the coverage data, allowing you to put that directly into this library. Here is the gist:
+
+```ts
+// Start collecting coverage
+await page.coverage.startCSSCoverage()
+// Load the page, do all sorts of interactions to increase coverage, etc.
+await page.goto('http://example.com')
+// Stop the coverage and store the result in a variable to pass along
+let coverage = await page.coverage.stopCSSCoverage()
+
+// Now we can process it
+import { calculate_coverage } from '@projectwallace/css-code-coverage'
+
+function parse_html(html) {
+	return new DOMParser().parseFromString(html, 'text/html')
+}
+
+let report = calculcate_coverage(coverage, parse_html)
+```
 
-1.  in the browser devtools in [Edge](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/)/[Chrome](https://developer.chrome.com/docs/devtools/coverage/)/chromium
 1.  Via the `coverage.startCSSCoverage()` API that headless browsers like [Playwright](https://playwright.dev/docs/api/class-coverage#coverage-start-css-coverage) or [Puppeteer](https://pptr.dev/api/puppeteer.coverage.startcsscoverage/) provide.
 
 Either way you end up with one or more JSON files that contain coverage data.
@@ -50,27 +92,17 @@ for (let file of files) {
 }
 ```
 
-### Bringing it together
-
-```ts
-import { calculate_coverage } from '@projectwallace/css-code-coverage'
-
-let report = calculcate_coverage(coverage_data, parse_html)
-```
-
-See [src/index.ts](https://github.com/projectwallace/css-code-coverage/blob/main/src/index.ts) for the data that's returned.
-
 ### Optional: coverage from `<style>` blocks
 
-Covergae generators also create coverage ranges for `<style>` blocks in HTML. If this applies to your code you should provide a HTML parser that we use to 'scrape' the HTML in case the browser gives us not just plain CSS contents. Depending on where you run this analysis you can use:
+Coverage generators also create coverage ranges for `<style>` blocks in HTML. If this applies to your code you should provide a HTML parser that we use to 'scrape' the HTML in case the browser gives us not just plain CSS contents. Depending on where you run this analysis you can use:
 
 1.  Browser:
     ```ts
     function parse_html(html) {
     	return new DOMParser().parseFromString(html, 'text/html')
     }
     ```
-1.  Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example):
+1.  Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example, but other parsers could work, too):
 
     ```ts
     // $ npm install linkedom