Skip to content

Commit 8bcc780

Browse files
rviscomirviscomi
authored
Ship v2 (#114)
1 parent 4adf681 commit 8bcc780

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+11590
-7673
lines changed

‎.github/workflows/test.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: test
2+
3+
on:
4+
pull_request:
5+
6+
jobs:
7+
test:
8+
runs-on: ubuntu-latest
9+
10+
steps:
11+
- uses: actions/checkout@v4
12+
- name: Use Node.js
13+
uses: actions/setup-node@v4
14+
with:
15+
node-version: '20'
16+
cache: 'npm'
17+
- name: Install root dependencies
18+
run: npm ci
19+
- name: Run root tests
20+
run: npm test
21+
- name: Install docs dependencies
22+
run: npm ci
23+
working-directory: ./docs
24+
- name: Run docs tests
25+
run: npm test
26+
working-directory: ./docs

‎README.md‎

Lines changed: 97 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,27 +15,115 @@ This script helps you identify which elements are out of order.
1515

1616
✨ _New: Install the [Capo Chrome extension](https://chrome.google.com/webstore/detail/capo-get-your-%3Chead%3E-in-o/ohabpnaccigjhkkebjofhpmebofgpbeb)_ ✨
1717

18-
1. Copy [capo.js](https://raw.githubusercontent.com/rviscomi/capo.js/main/snippet/capo.js)
19-
2. Run it in a new [DevTools snippet](https://developer.chrome.com/docs/devtools/javascript/snippets/), or use a [bookmarklet](https://caiorss.github.io/bookmarklet-maker/) generator
18+
1. Install the [Chrome extension](https://chrome.google.com/webstore/detail/capo/ohkeehjepccojmgephomofandmjaafid)
2019
3. Explore the console logs
2120

2221
<img width="1552" alt="capo screenshot" src="https://github.com/rviscomi/capo.js/assets/1120896/b29672f9-1f05-4a05-a85e-df27acd153bd">
2322

2423
For applications that add lots of dynamic content to the `<head>` on the client, it'd be more accurate to look at the server-rendered `<head>` instead.
2524

26-
### Chrome extension
25+
## Programmatic API (v2.0)
2726

28-
![Capo.js Chrome extension](https://github.com/rviscomi/capo.js/assets/1120896/389bcec0-567d-448f-9897-eee5ca373e6b)
27+
You can also use capo.js programmatically to analyze HTML `<head>` elements in Node.js or other JavaScript environments.
2928

30-
WIP see [crx/](crx/)
29+
### Installation
30+
31+
```bash
32+
npm install @rviscomi/capo.js
33+
```
34+
35+
### Basic Usage
36+
37+
```javascript
38+
// Analyze a head element
39+
const head = /* your head element */;
40+
const adapter = new BrowserAdapter(); // Or other adapter
41+
const result = analyzeHead(head, adapter);
42+
43+
console.log(result.elements); // Array of head elements with weights
44+
console.log(result.violations); // Number of ordering violations
45+
console.log(result.warnings); // Validation warnings
46+
```
47+
48+
### Using Adapters
49+
50+
Capo.js uses adapters to work with different HTML representations:
51+
52+
```javascript
53+
import { analyzeHead, BrowserAdapter } from '@rviscomi/capo.js';
54+
55+
// For browser DOM (if using in browser context)
56+
const browserAdapter = new BrowserAdapter();
57+
const browserResult = analyzeHead(document.head, browserAdapter);
58+
```
59+
60+
### Subpath Exports
61+
62+
Import only what you need for smaller bundle sizes:
63+
64+
```javascript
65+
// Import just the core analyzer
66+
import { analyzeHead, checkOrdering } from '@rviscomi/capo.js';
67+
68+
// Import just adapters
69+
import { BrowserAdapter } from '@rviscomi/capo.js/adapters';
70+
71+
// Import specific adapters
72+
import { BrowserAdapter } from '@rviscomi/capo.js/adapters/browser';
73+
74+
// Import rules API
75+
import { ElementWeights, getWeight } from '@rviscomi/capo.js/rules';
3176

32-
### WebPageTest
77+
// Import validation API
78+
import { isValidElement, getValidationWarnings } from '@rviscomi/capo.js/validation';
79+
```
3380

34-
You can use the [`capo` WebPageTest custom metric](webpagetest/) to evaluate only the server-rendered HTML `<head>`. Note that because this approach doesn't output to the console, we lose the visualization.
81+
### API Reference
3582

36-
### BigQuery
83+
#### Core Functions
84+
85+
- `analyzeHead(head, adapter)` - Analyzes a head element and returns detailed results
86+
- `analyzeHeadWithOrdering(head, adapter)` - Analyzes with ordering violations
87+
- `checkOrdering(elements)` - Checks for ordering violations in element array
88+
- `getWeightCategory(weight)` - Gets the category name for a weight value
89+
90+
#### Rules API
91+
92+
- `ElementWeights` - Constant object mapping element types to weight values
93+
- `getWeight(element, adapter)` - Gets the weight for a specific element
94+
- `getHeadWeights(head, adapter)` - Gets weights for all elements in head
95+
96+
Plus individual detector functions: `isMeta()`, `isTitle()`, `isPreconnect()`, etc.
97+
98+
#### Validation API
99+
100+
- `VALID_HEAD_ELEMENTS` - Array of valid head element names
101+
- `isValidElement(element, adapter)` - Checks if an element is valid in head
102+
- `hasValidationWarning(element, adapter)` - Checks if element has warnings
103+
- `getValidationWarnings(head, adapter)` - Gets all validation warnings
104+
- `getCustomValidations(element, adapter)` - Gets custom validation rules
105+
106+
#### Adapters
107+
108+
- `BrowserAdapter` - For working with browser DOM elements
109+
- `AdapterInterface` - Base interface for custom adapters
110+
- `validateAdapter(adapter)` - Validates an adapter implementation
111+
112+
### Migration from v1.x
113+
114+
See [MIGRATION.md](MIGRATION.md) for detailed migration guide.
115+
116+
**Key changes:**
117+
- All analysis functions now require an adapter parameter
118+
- New subpath exports for granular imports
119+
- Enhanced TypeScript support via JSDoc
120+
121+
### Chrome extension
122+
123+
![Capo.js Chrome extension](https://github.com/rviscomi/capo.js/assets/1120896/389bcec0-567d-448f-9897-eee5ca373e6b)
124+
125+
WIP see [crx/](crx/)
37126

38-
You can also use the [`httparchive.fn.CAPO`](bigquery/) function on BigQuery to process HTML response bodies in the HTTP Archive dataset. Similar to the WebPageTest approach, the output is very basic.
39127

40128
### Other
41129

‎bigquery/README.md‎

Lines changed: 0 additions & 116 deletions
This file was deleted.

‎bigquery/capo.sql‎

Lines changed: 0 additions & 112 deletions
This file was deleted.

‎crx/capo.js‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎crx/manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"manifest_version": 3,
33
"name": "Capo: get your ﹤𝚑𝚎𝚊𝚍﹥ in order",
44
"description": "Visualize the optimal ordering of ﹤𝚑𝚎𝚊𝚍﹥ elements on any web page",
5-
"version": "1.5.3",
5+
"version": "2.0.0",
66
"permissions": [
77
"scripting",
88
"activeTab",

‎crx/options/options.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)