@a11y-pulse/browser-adaptor 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -2
- package/dist/element-screenshot.d.ts +39 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +89 -2
- package/dist/index.js.map +1 -1
- package/dist/stashed-elements.d.ts +6 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@ npm install @a11y-pulse/browser-adaptor
|
|
|
20
20
|
|
|
21
21
|
| Entry | Contents |
|
|
22
22
|
| --- | --- |
|
|
23
|
-
| `@a11y-pulse/browser-adaptor` | `BrowserAdaptor`, `ElementRef`, `Rect`, `bufferedClip`, `contrastRatio`, `parseOpaqueRgb`, `relativeLuminance`, `stashedElementSelectors`, `releaseStashedElements` |
|
|
23
|
+
| `@a11y-pulse/browser-adaptor` | `BrowserAdaptor`, `ElementRef`, `Rect`, `bufferedClip`, `captureElementScreenshot`, `contrastRatio`, `parseOpaqueRgb`, `relativeLuminance`, `stashedElementHandle`, `stashedElementSelectors`, `releaseStashedElements`, and the page scripts `captureElementScreenshot` is built on |
|
|
24
24
|
| `@a11y-pulse/browser-adaptor/puppeteer` | `PuppeteerAdaptor` |
|
|
25
25
|
| `@a11y-pulse/browser-adaptor/playwright` | `PlaywrightAdaptor` |
|
|
26
26
|
| `@a11y-pulse/browser-adaptor/dom` | `getSelector`, `truncateHtml` |
|
|
@@ -108,7 +108,7 @@ import { getSelector, truncateHtml } from "@a11y-pulse/browser-adaptor/dom";
|
|
|
108
108
|
|
|
109
109
|
`getSelector` builds a compact selector for an element (intended to run in page context). `truncateHtml` shortens an element's opening tag for display in results.
|
|
110
110
|
|
|
111
|
-
A page script that collects many elements in one evaluate can leave them on `window` under a key of its own, then fetch selectors for only the ones it reports:
|
|
111
|
+
A page script that collects many elements in one evaluate can leave them on `window` under a key of its own, then fetch selectors (or, with `stashedElementHandle`, a handle) for only the ones it reports:
|
|
112
112
|
|
|
113
113
|
```js
|
|
114
114
|
import { releaseStashedElements, stashedElementSelectors } from "@a11y-pulse/browser-adaptor";
|
|
@@ -122,6 +122,10 @@ try {
|
|
|
122
122
|
}
|
|
123
123
|
```
|
|
124
124
|
|
|
125
|
+
## Element screenshots
|
|
126
|
+
|
|
127
|
+
`captureElementScreenshot(adaptor, handle, { clipBuffer, settleDelay })` screenshots an element clipped to its box plus `clipBuffer` padding. It first centres the element in the viewport if the clip would not fit there or something covers the element's centre, then waits `settleDelay` ms. The caller owns `handle`, and restores the scroll position if that matters.
|
|
128
|
+
|
|
125
129
|
## License
|
|
126
130
|
|
|
127
131
|
[MIT](./LICENSE.md). Use it however you like, including in commercial and competing products.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IMPORTANT: The `*Script` functions in this file are serialized and injected into the audited page,
|
|
3
|
+
* so they must not reference any symbols outside their own scope.
|
|
4
|
+
*/
|
|
5
|
+
import type { BrowserAdaptor, ElementRef, Rect } from "./adaptor";
|
|
6
|
+
export declare function pageDimensionsScript(): {
|
|
7
|
+
width: number;
|
|
8
|
+
height: number;
|
|
9
|
+
};
|
|
10
|
+
export declare function elementRectScript(el: Element | null): Rect;
|
|
11
|
+
/**
|
|
12
|
+
* Whether the element should be centred in the viewport before its screenshots are taken: either
|
|
13
|
+
* something unrelated covers its centre, or its screenshot clip (its box padded by `buffer`, cut
|
|
14
|
+
* off at the document edges like bufferedClip) reaches past an edge of the viewport. A capture only
|
|
15
|
+
* shows what is inside the viewport, so such a clip would lose an indicator drawn in the padding. A
|
|
16
|
+
* clip larger than the viewport does not count, since scrolling cannot fit it anyway.
|
|
17
|
+
*/
|
|
18
|
+
export declare function needsCentringScript(el: Element | null, buffer: number): boolean;
|
|
19
|
+
/**
|
|
20
|
+
* Scroll the window so the element sits at the vertical centre of the viewport and is inside it
|
|
21
|
+
* horizontally with `buffer` to spare, instantly so a screenshot taken immediately afterwards isn't
|
|
22
|
+
* captured mid-animation. Scrolls the window directly rather than via scrollIntoView(): Chromium
|
|
23
|
+
* moves the sequential focus navigation starting point to the element passed to scrollIntoView(),
|
|
24
|
+
* so when focus cannot be handed back afterwards (a closed shadow host) the next Tab would re-enter
|
|
25
|
+
* the same element instead of moving on.
|
|
26
|
+
*/
|
|
27
|
+
export declare function scrollToCenterScript(el: Element | null, buffer?: number): void;
|
|
28
|
+
export type ElementScreenshotOptions = {
|
|
29
|
+
/** Padding around the element's box. */
|
|
30
|
+
clipBuffer: number;
|
|
31
|
+
/** How long to wait (ms) after scrolling for the page to settle. */
|
|
32
|
+
settleDelay: number;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Screenshot the element `handle` refers to, clipped to its box plus `clipBuffer` padding, first
|
|
36
|
+
* centring it in the viewport when its clip would not fit or something covers it. The caller owns
|
|
37
|
+
* `handle`.
|
|
38
|
+
*/
|
|
39
|
+
export declare function captureElementScreenshot(adaptor: Pick<BrowserAdaptor, "evaluate" | "screenshotClip" | "screenshotClipScale">, handle: ElementRef, options: ElementScreenshotOptions): Promise<Uint8Array>;
|
package/dist/index.d.ts
CHANGED
|
@@ -2,4 +2,5 @@ export type { BrowserAdaptor, ElementRef, KeyName, Rect } from "./adaptor";
|
|
|
2
2
|
export { bufferedClip } from "./clip";
|
|
3
3
|
export type { Rgb } from "./contrast";
|
|
4
4
|
export { contrastRatio, parseOpaqueRgb, relativeLuminance } from "./contrast";
|
|
5
|
-
export {
|
|
5
|
+
export { captureElementScreenshot, type ElementScreenshotOptions, elementRectScript, needsCentringScript, pageDimensionsScript, scrollToCenterScript, } from "./element-screenshot";
|
|
6
|
+
export { releaseStashedElements, stashedElementHandle, stashedElementSelectors, } from "./stashed-elements";
|
package/dist/index.js
CHANGED
|
@@ -41,6 +41,84 @@ function contrastRatio(a, b) {
|
|
|
41
41
|
return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
|
|
42
42
|
}
|
|
43
43
|
|
|
44
|
+
// src/element-screenshot.ts
|
|
45
|
+
function pageDimensionsScript() {
|
|
46
|
+
return {
|
|
47
|
+
width: document.documentElement.scrollWidth,
|
|
48
|
+
height: document.documentElement.scrollHeight
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
function elementRectScript(el) {
|
|
52
|
+
if (!el) {
|
|
53
|
+
return { x: 0, y: 0, width: 0, height: 0 };
|
|
54
|
+
}
|
|
55
|
+
const rect = el.getBoundingClientRect();
|
|
56
|
+
return {
|
|
57
|
+
x: rect.left + window.scrollX,
|
|
58
|
+
y: rect.top + window.scrollY,
|
|
59
|
+
width: rect.width,
|
|
60
|
+
height: rect.height
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
function needsCentringScript(el, buffer) {
|
|
64
|
+
if (!el) {
|
|
65
|
+
return false;
|
|
66
|
+
}
|
|
67
|
+
const rect = el.getBoundingClientRect();
|
|
68
|
+
const viewport = document.scrollingElement ?? document.documentElement;
|
|
69
|
+
const viewportWidth = viewport.clientWidth;
|
|
70
|
+
const viewportHeight = viewport.clientHeight;
|
|
71
|
+
const x = Math.min(Math.max(rect.left + rect.width / 2, 0), viewportWidth - 1);
|
|
72
|
+
const y = Math.min(Math.max(rect.top + rect.height / 2, 0), viewportHeight - 1);
|
|
73
|
+
let hit = document.elementFromPoint(x, y);
|
|
74
|
+
while (hit?.shadowRoot) {
|
|
75
|
+
const inner = hit.shadowRoot.elementFromPoint(x, y);
|
|
76
|
+
if (!inner || inner === hit) {
|
|
77
|
+
break;
|
|
78
|
+
}
|
|
79
|
+
hit = inner;
|
|
80
|
+
}
|
|
81
|
+
if (hit && hit !== el && !el.contains(hit) && !hit.contains(el)) {
|
|
82
|
+
return true;
|
|
83
|
+
}
|
|
84
|
+
const docLeft = -window.scrollX;
|
|
85
|
+
const docTop = -window.scrollY;
|
|
86
|
+
const left = Math.max(rect.left - buffer, docLeft);
|
|
87
|
+
const top = Math.max(rect.top - buffer, docTop);
|
|
88
|
+
const right = Math.min(rect.right + buffer, docLeft + document.documentElement.scrollWidth);
|
|
89
|
+
const bottom = Math.min(rect.bottom + buffer, docTop + document.documentElement.scrollHeight);
|
|
90
|
+
if (right - left > viewportWidth || bottom - top > viewportHeight) {
|
|
91
|
+
return false;
|
|
92
|
+
}
|
|
93
|
+
return left < 0 || top < 0 || right > viewportWidth || bottom > viewportHeight;
|
|
94
|
+
}
|
|
95
|
+
function scrollToCenterScript(el, buffer = 0) {
|
|
96
|
+
if (!el) {
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
const rect = el.getBoundingClientRect();
|
|
100
|
+
const viewport = document.scrollingElement ?? document.documentElement;
|
|
101
|
+
const viewportWidth = viewport.clientWidth;
|
|
102
|
+
const top = rect.top + rect.height / 2 - viewport.clientHeight / 2;
|
|
103
|
+
let left = 0;
|
|
104
|
+
if (rect.left - buffer < 0) {
|
|
105
|
+
left = rect.left - buffer;
|
|
106
|
+
} else if (rect.right + buffer > viewportWidth) {
|
|
107
|
+
left = Math.min(rect.right + buffer - viewportWidth, rect.left - buffer);
|
|
108
|
+
}
|
|
109
|
+
window.scrollBy({ top, left, behavior: "instant" });
|
|
110
|
+
}
|
|
111
|
+
async function captureElementScreenshot(adaptor, handle, options) {
|
|
112
|
+
if (await adaptor.evaluate(needsCentringScript, handle, options.clipBuffer)) {
|
|
113
|
+
await adaptor.evaluate(scrollToCenterScript, handle, options.clipBuffer);
|
|
114
|
+
await new Promise((resolve) => setTimeout(resolve, options.settleDelay));
|
|
115
|
+
}
|
|
116
|
+
const { width: pageWidth, height: pageHeight } = await adaptor.evaluate(pageDimensionsScript);
|
|
117
|
+
const rect = await adaptor.evaluate(elementRectScript, handle);
|
|
118
|
+
const clip = bufferedClip(rect, pageWidth, pageHeight, options.clipBuffer);
|
|
119
|
+
return adaptor.screenshotClip(clip, adaptor.screenshotClipScale ?? 1);
|
|
120
|
+
}
|
|
121
|
+
|
|
44
122
|
// src/stashed-elements.ts
|
|
45
123
|
function pickStashedScript(stashKey, index) {
|
|
46
124
|
const stash = window[stashKey];
|
|
@@ -53,11 +131,14 @@ function releaseStashScript(stashKey) {
|
|
|
53
131
|
delete window[stashKey];
|
|
54
132
|
delete window.__a11yPulsePickedElement;
|
|
55
133
|
}
|
|
134
|
+
async function stashedElementHandle(adaptor, stashKey, index) {
|
|
135
|
+
await adaptor.evaluate(pickStashedScript, stashKey, index);
|
|
136
|
+
return adaptor.evaluateHandle(pickedElementScript);
|
|
137
|
+
}
|
|
56
138
|
async function stashedElementSelectors(adaptor, stashKey, indices) {
|
|
57
139
|
const selectors = [];
|
|
58
140
|
for (const index of indices) {
|
|
59
|
-
await adaptor
|
|
60
|
-
const handle = await adaptor.evaluateHandle(pickedElementScript);
|
|
141
|
+
const handle = await stashedElementHandle(adaptor, stashKey, index);
|
|
61
142
|
try {
|
|
62
143
|
selectors.push(await adaptor.evaluate(getSelector, handle));
|
|
63
144
|
} finally {
|
|
@@ -71,10 +152,16 @@ async function releaseStashedElements(adaptor, stashKey) {
|
|
|
71
152
|
}
|
|
72
153
|
export {
|
|
73
154
|
bufferedClip,
|
|
155
|
+
captureElementScreenshot,
|
|
74
156
|
contrastRatio,
|
|
157
|
+
elementRectScript,
|
|
158
|
+
needsCentringScript,
|
|
159
|
+
pageDimensionsScript,
|
|
75
160
|
parseOpaqueRgb,
|
|
76
161
|
relativeLuminance,
|
|
77
162
|
releaseStashedElements,
|
|
163
|
+
scrollToCenterScript,
|
|
164
|
+
stashedElementHandle,
|
|
78
165
|
stashedElementSelectors
|
|
79
166
|
};
|
|
80
167
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/clip.ts","../src/contrast.ts","../src/stashed-elements.ts"],"sourcesContent":["import type { Rect } from \"./adaptor\";\n\n/**\n * A screenshot clip framing `rect` with up to `buffer` pixels of padding on each side, shrunk where\n * the page edges leave less room. The padding allows for indicators drawn just outside the element\n * box (outlines, shadows) and for anti-aliasing.\n */\nexport function bufferedClip(\n\trect: Rect,\n\tpageWidth: number,\n\tpageHeight: number,\n\tbuffer: number,\n): Rect {\n\tconst left = Math.max(0, Math.min(buffer, rect.x));\n\tconst top = Math.max(0, Math.min(buffer, rect.y));\n\tconst right = Math.max(0, Math.min(buffer, pageWidth - rect.x - rect.width));\n\tconst bottom = Math.max(0, Math.min(buffer, pageHeight - rect.y - rect.height));\n\n\t// Clamp to non-negative origins: an element positioned partially off the top or left of the\n\t// document has a negative page-relative rect, and Puppeteer rejects a screenshot clip with\n\t// negative x/y.\n\treturn {\n\t\tx: Math.max(0, rect.x - left),\n\t\ty: Math.max(0, rect.y - top),\n\t\twidth: rect.width + left + right,\n\t\theight: rect.height + top + bottom,\n\t};\n}\n","export type Rgb = readonly [number, number, number];\n\n// Computed colours serialise as `rgb()` or `rgba()` with comma separators for sRGB values. Colours\n// authored in other spaces (oklch, display-p3) keep their own notation and are not parsed.\nconst RGB_PATTERN = /^rgba?\\(\\s*([\\d.]+),\\s*([\\d.]+),\\s*([\\d.]+)(?:,\\s*([\\d.]+))?\\s*\\)$/;\n\n/**\n * Parse a computed `rgb()` or `rgba()` colour, or return null when it is translucent or in another\n * notation.\n */\nexport function parseOpaqueRgb(value: string): Rgb | null {\n\tconst match = RGB_PATTERN.exec(value.trim());\n\n\tif (!match) {\n\t\treturn null;\n\t}\n\n\tif (match[4] !== undefined && Number(match[4]) < 1) {\n\t\treturn null;\n\t}\n\n\treturn [Number(match[1]), Number(match[2]), Number(match[3])];\n}\n\nfunction linearise(channel: number): number {\n\tconst c = channel / 255;\n\n\treturn c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;\n}\n\n/**\n * The WCAG relative luminance of an sRGB colour, from 0 (black) to 1 (white).\n */\nexport function relativeLuminance([r, g, b]: Rgb): number {\n\treturn 0.2126 * linearise(r) + 0.7152 * linearise(g) + 0.0722 * linearise(b);\n}\n\n/**\n * The WCAG contrast ratio between two colours, from 1 to 21.\n */\nexport function contrastRatio(a: Rgb, b: Rgb): number {\n\tconst la = relativeLuminance(a);\n\tconst lb = relativeLuminance(b);\n\n\treturn (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);\n}\n","import type { BrowserAdaptor } from \"./adaptor\";\nimport { getSelector } from \"./get-selector\";\n\ntype PickWindow = Window & { __a11yPulsePickedElement?: Element | null };\n\nfunction pickStashedScript(stashKey: string, index: number): void {\n\tconst stash = (window as unknown as Record<string, unknown>)[stashKey];\n\n\t(window as PickWindow).__a11yPulsePickedElement = Array.isArray(stash)\n\t\t? (stash[index] ?? null)\n\t\t: null;\n}\n\nfunction pickedElementScript(): Element | null {\n\treturn (window as PickWindow).__a11yPulsePickedElement ?? null;\n}\n\nfunction releaseStashScript(stashKey: string): void {\n\tdelete (window as unknown as Record<string, unknown>)[stashKey];\n\tdelete (window as PickWindow).__a11yPulsePickedElement;\n}\n\n/**\n * Return a selector (see getSelector) for each element at `indices` of the array a page script\n * left on `window[stashKey]`.\n */\nexport async function stashedElementSelectors(\n\tadaptor: BrowserAdaptor,\n\tstashKey: string,\n\tindices: readonly number[],\n): Promise<string[]> {\n\tconst selectors: string[] = [];\n\n\tfor (const index of indices) {\n\t\tawait adaptor.evaluate(pickStashedScript, stashKey, index);\n\t\tconst handle = await adaptor.evaluateHandle(pickedElementScript);\n\n\t\ttry {\n\t\t\tselectors.push(await adaptor.evaluate(getSelector, handle));\n\t\t} finally {\n\t\t\tawait adaptor.disposeRef(handle);\n\t\t}\n\t}\n\n\treturn selectors;\n}\n\n/**\n * Remove the array on `window[stashKey]` from the page.\n */\nexport async function releaseStashedElements(\n\tadaptor: BrowserAdaptor,\n\tstashKey: string,\n): Promise<void> {\n\tawait adaptor.evaluate(releaseStashScript, stashKey);\n}\n"],"mappings":";;;;;AAOO,SAAS,aACf,MACA,WACA,YACA,QACO;AACP,QAAM,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,KAAK,CAAC,CAAC;AACjD,QAAM,MAAM,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,KAAK,CAAC,CAAC;AAChD,QAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,YAAY,KAAK,IAAI,KAAK,KAAK,CAAC;AAC3E,QAAM,SAAS,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,aAAa,KAAK,IAAI,KAAK,MAAM,CAAC;AAK9E,SAAO;AAAA,IACN,GAAG,KAAK,IAAI,GAAG,KAAK,IAAI,IAAI;AAAA,IAC5B,GAAG,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG;AAAA,IAC3B,OAAO,KAAK,QAAQ,OAAO;AAAA,IAC3B,QAAQ,KAAK,SAAS,MAAM;AAAA,EAC7B;AACD;;;ACvBA,IAAM,cAAc;AAMb,SAAS,eAAe,OAA2B;AACzD,QAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,CAAC;AAE3C,MAAI,CAAC,OAAO;AACX,WAAO;AAAA,EACR;AAEA,MAAI,MAAM,CAAC,MAAM,UAAa,OAAO,MAAM,CAAC,CAAC,IAAI,GAAG;AACnD,WAAO;AAAA,EACR;AAEA,SAAO,CAAC,OAAO,MAAM,CAAC,CAAC,GAAG,OAAO,MAAM,CAAC,CAAC,GAAG,OAAO,MAAM,CAAC,CAAC,CAAC;AAC7D;AAEA,SAAS,UAAU,SAAyB;AAC3C,QAAM,IAAI,UAAU;AAEpB,SAAO,KAAK,UAAU,IAAI,UAAU,IAAI,SAAS,UAAU;AAC5D;AAKO,SAAS,kBAAkB,CAAC,GAAG,GAAG,CAAC,GAAgB;AACzD,SAAO,SAAS,UAAU,CAAC,IAAI,SAAS,UAAU,CAAC,IAAI,SAAS,UAAU,CAAC;AAC5E;AAKO,SAAS,cAAc,GAAQ,GAAgB;AACrD,QAAM,KAAK,kBAAkB,CAAC;AAC9B,QAAM,KAAK,kBAAkB,CAAC;AAE9B,UAAQ,KAAK,IAAI,IAAI,EAAE,IAAI,SAAS,KAAK,IAAI,IAAI,EAAE,IAAI;AACxD;;;ACxCA,SAAS,kBAAkB,UAAkB,OAAqB;AACjE,QAAM,QAAS,OAA8C,QAAQ;AAErE,EAAC,OAAsB,2BAA2B,MAAM,QAAQ,KAAK,IACjE,MAAM,KAAK,KAAK,OACjB;AACJ;AAEA,SAAS,sBAAsC;AAC9C,SAAQ,OAAsB,4BAA4B;AAC3D;AAEA,SAAS,mBAAmB,UAAwB;AACnD,SAAQ,OAA8C,QAAQ;AAC9D,SAAQ,OAAsB;AAC/B;AAMA,eAAsB,wBACrB,SACA,UACA,SACoB;AACpB,QAAM,YAAsB,CAAC;AAE7B,aAAW,SAAS,SAAS;AAC5B,UAAM,QAAQ,SAAS,mBAAmB,UAAU,KAAK;AACzD,UAAM,SAAS,MAAM,QAAQ,eAAe,mBAAmB;AAE/D,QAAI;AACH,gBAAU,KAAK,MAAM,QAAQ,SAAS,aAAa,MAAM,CAAC;AAAA,IAC3D,UAAE;AACD,YAAM,QAAQ,WAAW,MAAM;AAAA,IAChC;AAAA,EACD;AAEA,SAAO;AACR;AAKA,eAAsB,uBACrB,SACA,UACgB;AAChB,QAAM,QAAQ,SAAS,oBAAoB,QAAQ;AACpD;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../src/clip.ts","../src/contrast.ts","../src/element-screenshot.ts","../src/stashed-elements.ts"],"sourcesContent":["import type { Rect } from \"./adaptor\";\n\n/**\n * A screenshot clip framing `rect` with up to `buffer` pixels of padding on each side, shrunk where\n * the page edges leave less room. The padding allows for indicators drawn just outside the element\n * box (outlines, shadows) and for anti-aliasing.\n */\nexport function bufferedClip(\n\trect: Rect,\n\tpageWidth: number,\n\tpageHeight: number,\n\tbuffer: number,\n): Rect {\n\tconst left = Math.max(0, Math.min(buffer, rect.x));\n\tconst top = Math.max(0, Math.min(buffer, rect.y));\n\tconst right = Math.max(0, Math.min(buffer, pageWidth - rect.x - rect.width));\n\tconst bottom = Math.max(0, Math.min(buffer, pageHeight - rect.y - rect.height));\n\n\t// Clamp to non-negative origins: an element positioned partially off the top or left of the\n\t// document has a negative page-relative rect, and Puppeteer rejects a screenshot clip with\n\t// negative x/y.\n\treturn {\n\t\tx: Math.max(0, rect.x - left),\n\t\ty: Math.max(0, rect.y - top),\n\t\twidth: rect.width + left + right,\n\t\theight: rect.height + top + bottom,\n\t};\n}\n","export type Rgb = readonly [number, number, number];\n\n// Computed colours serialise as `rgb()` or `rgba()` with comma separators for sRGB values. Colours\n// authored in other spaces (oklch, display-p3) keep their own notation and are not parsed.\nconst RGB_PATTERN = /^rgba?\\(\\s*([\\d.]+),\\s*([\\d.]+),\\s*([\\d.]+)(?:,\\s*([\\d.]+))?\\s*\\)$/;\n\n/**\n * Parse a computed `rgb()` or `rgba()` colour, or return null when it is translucent or in another\n * notation.\n */\nexport function parseOpaqueRgb(value: string): Rgb | null {\n\tconst match = RGB_PATTERN.exec(value.trim());\n\n\tif (!match) {\n\t\treturn null;\n\t}\n\n\tif (match[4] !== undefined && Number(match[4]) < 1) {\n\t\treturn null;\n\t}\n\n\treturn [Number(match[1]), Number(match[2]), Number(match[3])];\n}\n\nfunction linearise(channel: number): number {\n\tconst c = channel / 255;\n\n\treturn c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;\n}\n\n/**\n * The WCAG relative luminance of an sRGB colour, from 0 (black) to 1 (white).\n */\nexport function relativeLuminance([r, g, b]: Rgb): number {\n\treturn 0.2126 * linearise(r) + 0.7152 * linearise(g) + 0.0722 * linearise(b);\n}\n\n/**\n * The WCAG contrast ratio between two colours, from 1 to 21.\n */\nexport function contrastRatio(a: Rgb, b: Rgb): number {\n\tconst la = relativeLuminance(a);\n\tconst lb = relativeLuminance(b);\n\n\treturn (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);\n}\n","/**\n * IMPORTANT: The `*Script` functions in this file are serialized and injected into the audited page,\n * so they must not reference any symbols outside their own scope.\n */\n\nimport type { BrowserAdaptor, ElementRef, Rect } from \"./adaptor\";\nimport { bufferedClip } from \"./clip\";\n\nexport function pageDimensionsScript(): { width: number; height: number } {\n\treturn {\n\t\twidth: document.documentElement.scrollWidth,\n\t\theight: document.documentElement.scrollHeight,\n\t};\n}\n\nexport function elementRectScript(el: Element | null): Rect {\n\tif (!el) {\n\t\treturn { x: 0, y: 0, width: 0, height: 0 };\n\t}\n\n\tconst rect = el.getBoundingClientRect();\n\n\treturn {\n\t\tx: rect.left + window.scrollX,\n\t\ty: rect.top + window.scrollY,\n\t\twidth: rect.width,\n\t\theight: rect.height,\n\t};\n}\n\n/**\n * Whether the element should be centred in the viewport before its screenshots are taken: either\n * something unrelated covers its centre, or its screenshot clip (its box padded by `buffer`, cut\n * off at the document edges like bufferedClip) reaches past an edge of the viewport. A capture only\n * shows what is inside the viewport, so such a clip would lose an indicator drawn in the padding. A\n * clip larger than the viewport does not count, since scrolling cannot fit it anyway.\n */\nexport function needsCentringScript(el: Element | null, buffer: number): boolean {\n\tif (!el) {\n\t\treturn false;\n\t}\n\n\tconst rect = el.getBoundingClientRect();\n\t// In quirks mode the viewport's size is on <body>, and <html> measures the whole document.\n\tconst viewport = document.scrollingElement ?? document.documentElement;\n\tconst viewportWidth = viewport.clientWidth;\n\tconst viewportHeight = viewport.clientHeight;\n\n\tconst x = Math.min(Math.max(rect.left + rect.width / 2, 0), viewportWidth - 1);\n\tconst y = Math.min(Math.max(rect.top + rect.height / 2, 0), viewportHeight - 1);\n\n\tlet hit = document.elementFromPoint(x, y);\n\n\twhile (hit?.shadowRoot) {\n\t\tconst inner = hit.shadowRoot.elementFromPoint(x, y);\n\n\t\tif (!inner || inner === hit) {\n\t\t\tbreak;\n\t\t}\n\n\t\thit = inner;\n\t}\n\n\tif (hit && hit !== el && !el.contains(hit) && !hit.contains(el)) {\n\t\treturn true;\n\t}\n\n\tconst docLeft = -window.scrollX;\n\tconst docTop = -window.scrollY;\n\tconst left = Math.max(rect.left - buffer, docLeft);\n\tconst top = Math.max(rect.top - buffer, docTop);\n\tconst right = Math.min(rect.right + buffer, docLeft + document.documentElement.scrollWidth);\n\tconst bottom = Math.min(rect.bottom + buffer, docTop + document.documentElement.scrollHeight);\n\n\tif (right - left > viewportWidth || bottom - top > viewportHeight) {\n\t\treturn false;\n\t}\n\n\treturn left < 0 || top < 0 || right > viewportWidth || bottom > viewportHeight;\n}\n\n/**\n * Scroll the window so the element sits at the vertical centre of the viewport and is inside it\n * horizontally with `buffer` to spare, instantly so a screenshot taken immediately afterwards isn't\n * captured mid-animation. Scrolls the window directly rather than via scrollIntoView(): Chromium\n * moves the sequential focus navigation starting point to the element passed to scrollIntoView(),\n * so when focus cannot be handed back afterwards (a closed shadow host) the next Tab would re-enter\n * the same element instead of moving on.\n */\nexport function scrollToCenterScript(el: Element | null, buffer = 0): void {\n\tif (!el) {\n\t\treturn;\n\t}\n\n\tconst rect = el.getBoundingClientRect();\n\t// In quirks mode the viewport's size is on <body>, and <html> measures the whole document.\n\tconst viewport = document.scrollingElement ?? document.documentElement;\n\tconst viewportWidth = viewport.clientWidth;\n\tconst top = rect.top + rect.height / 2 - viewport.clientHeight / 2;\n\tlet left = 0;\n\n\tif (rect.left - buffer < 0) {\n\t\tleft = rect.left - buffer;\n\t} else if (rect.right + buffer > viewportWidth) {\n\t\tleft = Math.min(rect.right + buffer - viewportWidth, rect.left - buffer);\n\t}\n\n\twindow.scrollBy({ top, left, behavior: \"instant\" });\n}\n\nexport type ElementScreenshotOptions = {\n\t/** Padding around the element's box. */\n\tclipBuffer: number;\n\t/** How long to wait (ms) after scrolling for the page to settle. */\n\tsettleDelay: number;\n};\n\n/**\n * Screenshot the element `handle` refers to, clipped to its box plus `clipBuffer` padding, first\n * centring it in the viewport when its clip would not fit or something covers it. The caller owns\n * `handle`.\n */\nexport async function captureElementScreenshot(\n\tadaptor: Pick<BrowserAdaptor, \"evaluate\" | \"screenshotClip\" | \"screenshotClipScale\">,\n\thandle: ElementRef,\n\toptions: ElementScreenshotOptions,\n): Promise<Uint8Array> {\n\tif (await adaptor.evaluate(needsCentringScript, handle, options.clipBuffer)) {\n\t\tawait adaptor.evaluate(scrollToCenterScript, handle, options.clipBuffer);\n\t\tawait new Promise((resolve) => setTimeout(resolve, options.settleDelay));\n\t}\n\n\tconst { width: pageWidth, height: pageHeight } = await adaptor.evaluate(pageDimensionsScript);\n\tconst rect = await adaptor.evaluate(elementRectScript, handle);\n\tconst clip = bufferedClip(rect, pageWidth, pageHeight, options.clipBuffer);\n\n\treturn adaptor.screenshotClip(clip, adaptor.screenshotClipScale ?? 1);\n}\n","import type { BrowserAdaptor, ElementRef } from \"./adaptor\";\nimport { getSelector } from \"./get-selector\";\n\ntype PickWindow = Window & { __a11yPulsePickedElement?: Element | null };\n\nfunction pickStashedScript(stashKey: string, index: number): void {\n\tconst stash = (window as unknown as Record<string, unknown>)[stashKey];\n\n\t(window as PickWindow).__a11yPulsePickedElement = Array.isArray(stash)\n\t\t? (stash[index] ?? null)\n\t\t: null;\n}\n\nfunction pickedElementScript(): Element | null {\n\treturn (window as PickWindow).__a11yPulsePickedElement ?? null;\n}\n\nfunction releaseStashScript(stashKey: string): void {\n\tdelete (window as unknown as Record<string, unknown>)[stashKey];\n\tdelete (window as PickWindow).__a11yPulsePickedElement;\n}\n\n/**\n * Return a handle to the element at `index` of the array a page script left on `window[stashKey]`.\n * The caller owns the handle.\n */\nexport async function stashedElementHandle(\n\tadaptor: BrowserAdaptor,\n\tstashKey: string,\n\tindex: number,\n): Promise<ElementRef> {\n\tawait adaptor.evaluate(pickStashedScript, stashKey, index);\n\n\treturn adaptor.evaluateHandle(pickedElementScript);\n}\n\n/**\n * Return a selector (see getSelector) for each element at `indices` of the array a page script\n * left on `window[stashKey]`.\n */\nexport async function stashedElementSelectors(\n\tadaptor: BrowserAdaptor,\n\tstashKey: string,\n\tindices: readonly number[],\n): Promise<string[]> {\n\tconst selectors: string[] = [];\n\n\tfor (const index of indices) {\n\t\tconst handle = await stashedElementHandle(adaptor, stashKey, index);\n\n\t\ttry {\n\t\t\tselectors.push(await adaptor.evaluate(getSelector, handle));\n\t\t} finally {\n\t\t\tawait adaptor.disposeRef(handle);\n\t\t}\n\t}\n\n\treturn selectors;\n}\n\n/**\n * Remove the array on `window[stashKey]` from the page.\n */\nexport async function releaseStashedElements(\n\tadaptor: BrowserAdaptor,\n\tstashKey: string,\n): Promise<void> {\n\tawait adaptor.evaluate(releaseStashScript, stashKey);\n}\n"],"mappings":"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","names":[]}
|
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
import type { BrowserAdaptor } from "./adaptor";
|
|
1
|
+
import type { BrowserAdaptor, ElementRef } from "./adaptor";
|
|
2
|
+
/**
|
|
3
|
+
* Return a handle to the element at `index` of the array a page script left on `window[stashKey]`.
|
|
4
|
+
* The caller owns the handle.
|
|
5
|
+
*/
|
|
6
|
+
export declare function stashedElementHandle(adaptor: BrowserAdaptor, stashKey: string, index: number): Promise<ElementRef>;
|
|
2
7
|
/**
|
|
3
8
|
* Return a selector (see getSelector) for each element at `indices` of the array a page script
|
|
4
9
|
* left on `window[stashKey]`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@a11y-pulse/browser-adaptor",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Shared browser adaptor primitives and DOM helpers for A11y Pulse accessibility audits.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -77,7 +77,7 @@
|
|
|
77
77
|
}
|
|
78
78
|
},
|
|
79
79
|
"devDependencies": {
|
|
80
|
-
"happy-dom": "^21.0.
|
|
80
|
+
"happy-dom": "^21.0.3",
|
|
81
81
|
"playwright-core": "^1.64.1",
|
|
82
82
|
"puppeteer": "^25.14.0"
|
|
83
83
|
}
|