@a11y-pulse/skip-link-audit 0.0.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/LICENSE.md +166 -0
- package/README.md +165 -0
- package/dist/adaptor.d.ts +38 -0
- package/dist/audit.d.ts +42 -0
- package/dist/browser-scripts.d.ts +41 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +210 -0
- package/dist/index.js.map +1 -0
- package/dist/result.d.ts +24 -0
- package/package.json +59 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
Copyright (c) 2026-present, A11y Pulse Limited (https://www.a11ypulse.com/). All rights reserved.
|
|
2
|
+
|
|
3
|
+
# PolyForm Shield License 1.0.0
|
|
4
|
+
|
|
5
|
+
<https://polyformproject.org/licenses/shield/1.0.0>
|
|
6
|
+
|
|
7
|
+
## Acceptance
|
|
8
|
+
|
|
9
|
+
In order to get any license under these terms, you must agree
|
|
10
|
+
to them as both strict obligations and conditions to all
|
|
11
|
+
your licenses.
|
|
12
|
+
|
|
13
|
+
## Copyright License
|
|
14
|
+
|
|
15
|
+
The licensor grants you a copyright license for the
|
|
16
|
+
software to do everything you might do with the software
|
|
17
|
+
that would otherwise infringe the licensor's copyright
|
|
18
|
+
in it for any permitted purpose. However, you may
|
|
19
|
+
only distribute the software according to [Distribution
|
|
20
|
+
License](#distribution-license) and make changes or new works
|
|
21
|
+
based on the software according to [Changes and New Works
|
|
22
|
+
License](#changes-and-new-works-license).
|
|
23
|
+
|
|
24
|
+
## Distribution License
|
|
25
|
+
|
|
26
|
+
The licensor grants you an additional copyright license
|
|
27
|
+
to distribute copies of the software. Your license
|
|
28
|
+
to distribute covers distributing the software with
|
|
29
|
+
changes and new works permitted by [Changes and New Works
|
|
30
|
+
License](#changes-and-new-works-license).
|
|
31
|
+
|
|
32
|
+
## Notices
|
|
33
|
+
|
|
34
|
+
You must ensure that anyone who gets a copy of any part of
|
|
35
|
+
the software from you also gets a copy of these terms or the
|
|
36
|
+
URL for them above, as well as copies of any plain-text lines
|
|
37
|
+
beginning with `Required Notice:` that the licensor provided
|
|
38
|
+
with the software. For example:
|
|
39
|
+
|
|
40
|
+
> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
|
|
41
|
+
|
|
42
|
+
## Changes and New Works License
|
|
43
|
+
|
|
44
|
+
The licensor grants you an additional copyright license to
|
|
45
|
+
make changes and new works based on the software for any
|
|
46
|
+
permitted purpose.
|
|
47
|
+
|
|
48
|
+
## Patent License
|
|
49
|
+
|
|
50
|
+
The licensor grants you a patent license for the software that
|
|
51
|
+
covers patent claims the licensor can license, or becomes able
|
|
52
|
+
to license, that you would infringe by using the software.
|
|
53
|
+
|
|
54
|
+
## Noncompete
|
|
55
|
+
|
|
56
|
+
Any purpose is a permitted purpose, except for providing any
|
|
57
|
+
product that competes with the software or any product the
|
|
58
|
+
licensor or any of its affiliates provides using the software.
|
|
59
|
+
|
|
60
|
+
## Competition
|
|
61
|
+
|
|
62
|
+
Goods and services compete even when they provide functionality
|
|
63
|
+
through different kinds of interfaces or for different technical
|
|
64
|
+
platforms. Applications can compete with services, libraries
|
|
65
|
+
with plugins, frameworks with development tools, and so on,
|
|
66
|
+
even if they're written in different programming languages
|
|
67
|
+
or for different computer architectures. Goods and services
|
|
68
|
+
compete even when provided free of charge. If you market a
|
|
69
|
+
product as a practical substitute for the software or another
|
|
70
|
+
product, it definitely competes.
|
|
71
|
+
|
|
72
|
+
## New Products
|
|
73
|
+
|
|
74
|
+
If you are using the software to provide a product that does
|
|
75
|
+
not compete, but the licensor or any of its affiliates brings
|
|
76
|
+
your product into competition by providing a new version of
|
|
77
|
+
the software or another product using the software, you may
|
|
78
|
+
continue using versions of the software available under these
|
|
79
|
+
terms beforehand to provide your competing product, but not
|
|
80
|
+
any later versions.
|
|
81
|
+
|
|
82
|
+
## Discontinued Products
|
|
83
|
+
|
|
84
|
+
You may begin using the software to compete with a product
|
|
85
|
+
or service that the licensor or any of its affiliates has
|
|
86
|
+
stopped providing, unless the licensor includes a plain-text
|
|
87
|
+
line beginning with `Licensor Line of Business:` with the
|
|
88
|
+
software that mentions that line of business. For example:
|
|
89
|
+
|
|
90
|
+
> Licensor Line of Business: YoyodyneCMS Content Management
|
|
91
|
+
System (http://example.com/cms)
|
|
92
|
+
|
|
93
|
+
## Sales of Business
|
|
94
|
+
|
|
95
|
+
If the licensor or any of its affiliates sells a line of
|
|
96
|
+
business developing the software or using the software
|
|
97
|
+
to provide a product, the buyer can also enforce
|
|
98
|
+
[Noncompete](#noncompete) for that product.
|
|
99
|
+
|
|
100
|
+
## Fair Use
|
|
101
|
+
|
|
102
|
+
You may have "fair use" rights for the software under the
|
|
103
|
+
law. These terms do not limit them.
|
|
104
|
+
|
|
105
|
+
## No Other Rights
|
|
106
|
+
|
|
107
|
+
These terms do not allow you to sublicense or transfer any of
|
|
108
|
+
your licenses to anyone else, or prevent the licensor from
|
|
109
|
+
granting licenses to anyone else. These terms do not imply
|
|
110
|
+
any other licenses.
|
|
111
|
+
|
|
112
|
+
## Patent Defense
|
|
113
|
+
|
|
114
|
+
If you make any written claim that the software infringes or
|
|
115
|
+
contributes to infringement of any patent, your patent license
|
|
116
|
+
for the software granted under these terms ends immediately. If
|
|
117
|
+
your company makes such a claim, your patent license ends
|
|
118
|
+
immediately for work on behalf of your company.
|
|
119
|
+
|
|
120
|
+
## Violations
|
|
121
|
+
|
|
122
|
+
The first time you are notified in writing that you have
|
|
123
|
+
violated any of these terms, or done anything with the software
|
|
124
|
+
not covered by your licenses, your licenses can nonetheless
|
|
125
|
+
continue if you come into full compliance with these terms,
|
|
126
|
+
and take practical steps to correct past violations, within
|
|
127
|
+
32 days of receiving notice. Otherwise, all your licenses
|
|
128
|
+
end immediately.
|
|
129
|
+
|
|
130
|
+
## No Liability
|
|
131
|
+
|
|
132
|
+
***As far as the law allows, the software comes as is, without
|
|
133
|
+
any warranty or condition, and the licensor will not be liable
|
|
134
|
+
to you for any damages arising out of these terms or the use
|
|
135
|
+
or nature of the software, under any kind of legal claim.***
|
|
136
|
+
|
|
137
|
+
## Definitions
|
|
138
|
+
|
|
139
|
+
The **licensor** is the individual or entity offering these
|
|
140
|
+
terms, and the **software** is the software the licensor makes
|
|
141
|
+
available under these terms.
|
|
142
|
+
|
|
143
|
+
A **product** can be a good or service, or a combination
|
|
144
|
+
of them.
|
|
145
|
+
|
|
146
|
+
**You** refers to the individual or entity agreeing to these
|
|
147
|
+
terms.
|
|
148
|
+
|
|
149
|
+
**Your company** is any legal entity, sole proprietorship,
|
|
150
|
+
or other kind of organization that you work for, plus all
|
|
151
|
+
its affiliates.
|
|
152
|
+
|
|
153
|
+
**Affiliates** means the other organizations than an
|
|
154
|
+
organization has control over, is under the control of, or is
|
|
155
|
+
under common control with.
|
|
156
|
+
|
|
157
|
+
**Control** means ownership of substantially all the assets of
|
|
158
|
+
an entity, or the power to direct its management and policies
|
|
159
|
+
by vote, contract, or otherwise. Control can be direct or
|
|
160
|
+
indirect.
|
|
161
|
+
|
|
162
|
+
**Your licenses** are all the licenses granted to you for the
|
|
163
|
+
software under these terms.
|
|
164
|
+
|
|
165
|
+
**Use** means anything you do with the software requiring one
|
|
166
|
+
of your licenses.
|
package/README.md
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# @a11y-pulse/skip-link-audit
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@a11y-pulse/skip-link-audit)
|
|
4
|
+
[](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml)
|
|
5
|
+
[](./LICENSE.md)
|
|
6
|
+
|
|
7
|
+
An accessibility audit that aims to verify the skip-link technique for [**WCAG 2.4.1 Bypass Blocks**](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html). When a skip-link-like in-page fragment anchor appears in the first few tab stops, it activates the link with Enter and checks that keyboard focus moves to the target. It is built to be framework-agnostic and can be used in any environment that allows you to programmatically tab, press Enter, and read the focused element, such as Puppeteer, Playwright, or Selenium.
|
|
8
|
+
|
|
9
|
+
This audit was developed by [A11y Pulse](https://www.a11ypulse.com/) for its accessibility monitoring service. It is released as source-available under the [PolyForm Shield License 1.0.0](#license).
|
|
10
|
+
|
|
11
|
+
WCAG 2.4.1 can also be satisfied by landmarks or a heading structure. A page with no skip link is not necessarily failing. This audit only evaluates pages that have a skip-link-like anchor; it stays silent otherwise.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @a11y-pulse/skip-link-audit puppeteer
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`puppeteer` is an optional peer dependency. It is only required if you use the bundled [Puppeteer adaptor](#adaptors). Other frameworks can supply their own adaptor without installing Puppeteer at all.
|
|
20
|
+
|
|
21
|
+
## Quickstart
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
import { runSkipLinkAudit } from "@a11y-pulse/skip-link-audit";
|
|
25
|
+
import { PuppeteerAdaptor } from "@a11y-pulse/skip-link-audit/puppeteer";
|
|
26
|
+
import puppeteer from "puppeteer";
|
|
27
|
+
|
|
28
|
+
const browser = await puppeteer.launch();
|
|
29
|
+
const page = await browser.newPage();
|
|
30
|
+
await page.goto("https://who.likesdogs.nz/");
|
|
31
|
+
|
|
32
|
+
const result = await runSkipLinkAudit(new PuppeteerAdaptor(page));
|
|
33
|
+
|
|
34
|
+
console.log(result.summary);
|
|
35
|
+
// { found: 1, passed: 1, failed: 0 }
|
|
36
|
+
|
|
37
|
+
console.log(result.skipLinks);
|
|
38
|
+
// [
|
|
39
|
+
// {
|
|
40
|
+
// selector: 'a[href="#main"]',
|
|
41
|
+
// html: '<a href="#main">',
|
|
42
|
+
// fragment: "#main",
|
|
43
|
+
// tabIndex: 1,
|
|
44
|
+
// passed: true,
|
|
45
|
+
// failureReason: null
|
|
46
|
+
// }
|
|
47
|
+
// ]
|
|
48
|
+
|
|
49
|
+
await browser.close();
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
See [`examples/puppeteer`](./examples/puppeteer) for a complete, runnable example.
|
|
53
|
+
|
|
54
|
+
## Options
|
|
55
|
+
|
|
56
|
+
The following options can be passed to `runSkipLinkAudit` as `SkipLinkOptions`:
|
|
57
|
+
|
|
58
|
+
| Option | Type | Default | Description |
|
|
59
|
+
| ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `candidateLimit` | `number` | `3` | Max tab stops to scan for skip-link candidates. A skip link beyond this limit is not evaluated. |
|
|
61
|
+
|
|
62
|
+
## Result shape
|
|
63
|
+
|
|
64
|
+
`runSkipLinkAudit` resolves to a `SkipLinkResult`:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
type SkipLinkResult = {
|
|
68
|
+
/** Skip-link candidates found in the first tab stops. Empty when none were found. */
|
|
69
|
+
skipLinks: Array<{
|
|
70
|
+
selector: string;
|
|
71
|
+
html: string;
|
|
72
|
+
fragment: string;
|
|
73
|
+
tabIndex: number;
|
|
74
|
+
passed: boolean;
|
|
75
|
+
failureReason: "target-missing" | "activation-no-effect" | null;
|
|
76
|
+
}>;
|
|
77
|
+
summary: {
|
|
78
|
+
found: number;
|
|
79
|
+
passed: number;
|
|
80
|
+
failed: number;
|
|
81
|
+
};
|
|
82
|
+
};
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
When no candidate is found, `skipLinks` is empty and the summary is zeros. Landmark-only pages are not flagged.
|
|
86
|
+
|
|
87
|
+
## How it works
|
|
88
|
+
|
|
89
|
+
1. Enable focus reporting so Tab, Enter, and `:focus` behave as they would in a foreground tab.
|
|
90
|
+
2. Press Tab up to `candidateLimit` times. After each press, inspect the focused element (descending open shadow roots). An `<a>` whose `href` is an in-page fragment (`#name`, not bare `#` and not `#top`) is recorded as a candidate, along with whether a matching `id` or `name` exists. The scan stops early on `<body>` or if focus cycles.
|
|
91
|
+
3. For each candidate whose target is missing, record `target-missing`.
|
|
92
|
+
4. For each candidate whose target exists: re-focus the link, press Enter, and poll for up to 250ms. The candidate passes if `document.activeElement` is the target or inside it. If not, press Tab once and pass if the newly focused element is inside the target (browsers set the sequential focus navigation starting point on fragment navigation even when the target is not focusable). Otherwise record `activation-no-effect`.
|
|
93
|
+
|
|
94
|
+
Activation uses a real Enter keypress rather than a synthetic click, so the keyboard path is the one being checked.
|
|
95
|
+
|
|
96
|
+
## Adaptors
|
|
97
|
+
|
|
98
|
+
The audit itself is framework-agnostic: it drives a page through an **adaptor**, a small interface of primitives (evaluate JS in the page, press Tab, press Enter) that the audit calls without knowing which browser automation library is behind it.
|
|
99
|
+
|
|
100
|
+
The package ships one implementation, `PuppeteerAdaptor`, backed by a Puppeteer `Page`. Other environments (Playwright, Selenium, WebDriver) can be supported by implementing the same interface, exported as `SkipLinkAuditAdaptor` (aliased as `BrowserAdaptor` from the package root).
|
|
101
|
+
|
|
102
|
+
### `SkipLinkAuditAdaptor` / `BrowserAdaptor`
|
|
103
|
+
|
|
104
|
+
| Method | Description |
|
|
105
|
+
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
106
|
+
| `evaluate(fn, ...args)` | Runs `fn` in the page context, passing in any serialisable `args`, and returns its result. |
|
|
107
|
+
| `evaluateHandle(fn)` | Runs `fn` in the page context and returns an opaque `ElementRef` handle to the `Element` it returns, without serialising it. |
|
|
108
|
+
| `disposeRef(ref)` | Releases a handle previously returned by `evaluateHandle`. |
|
|
109
|
+
| `pressTab()` | Presses the Tab key, advancing focus to the next focusable element. |
|
|
110
|
+
| `pressEnter()` | Presses the Enter key, activating the focused element. |
|
|
111
|
+
| `ensureFocusReporting()` | Ensures the page reports focus for its lifetime, in particular that `document.hasFocus()` works and `:focus` styles apply even when the page is not the foreground tab/window. Must not throw. |
|
|
112
|
+
|
|
113
|
+
### Writing a new adaptor
|
|
114
|
+
|
|
115
|
+
Implement `SkipLinkAuditAdaptor` from `@a11y-pulse/skip-link-audit` (or its `BrowserAdaptor` alias) against your automation library's page/session object, then pass an instance to `runSkipLinkAudit`:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import type { SkipLinkAuditAdaptor } from "@a11y-pulse/skip-link-audit";
|
|
119
|
+
|
|
120
|
+
class MyFrameworkAdaptor implements SkipLinkAuditAdaptor {
|
|
121
|
+
// ...implement evaluate, evaluateHandle, disposeRef, pressTab,
|
|
122
|
+
// pressEnter, and ensureFocusReporting for your framework
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Use [`src/adaptors/puppeteer.ts`](./src/adaptors/puppeteer.ts) as a reference implementation. It is a small, self-contained example of every method the audit needs.
|
|
127
|
+
|
|
128
|
+
## Limitations
|
|
129
|
+
|
|
130
|
+
- **Chromium focus emulation.** Accurate `:focus` / `document.hasFocus()` reporting for a backgrounded page relies on Chromium's CDP focus emulation (used by `PuppeteerAdaptor.ensureFocusReporting`). Other browser engines may not offer an equivalent, and results may be less reliable if the page genuinely loses focus during the audit.
|
|
131
|
+
- **First tab stops only.** Skip links beyond `candidateLimit` (default 3) are not detected. The audit stays silent, which never flags a conformant page.
|
|
132
|
+
- **Fragment anchors only.** Button-based skip controls and JavaScript-only focus movers are out of scope.
|
|
133
|
+
- **Closed shadow roots** are opaque; a skip link inside one is invisible to the scan.
|
|
134
|
+
- **Landmarks and headings** that satisfy 2.4.1 without a skip link are out of scope by design.
|
|
135
|
+
|
|
136
|
+
## Releasing
|
|
137
|
+
|
|
138
|
+
Releases are managed in the [A11y-Pulse/audits](https://github.com/A11y-Pulse/audits) monorepo with [Changesets](https://github.com/changesets/changesets). Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC). There is no long-lived `NPM_TOKEN`.
|
|
139
|
+
|
|
140
|
+
### Ship a change
|
|
141
|
+
|
|
142
|
+
1. Open a PR against `main` that includes a changeset (`npx changeset`) naming `@a11y-pulse/skip-link-audit`.
|
|
143
|
+
2. After merge, the Release workflow opens a Version PR. Merging that PR publishes this package to npm and tags `@a11y-pulse/skip-link-audit@<version>`.
|
|
144
|
+
|
|
145
|
+
Trusted Publisher on npm must stay configured for:
|
|
146
|
+
|
|
147
|
+
| Field | Value |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| Organization or user | `A11y-Pulse` |
|
|
150
|
+
| Repository | `audits` |
|
|
151
|
+
| Workflow filename | `release.yml` |
|
|
152
|
+
|
|
153
|
+
### Consumers (e.g. the A11y Pulse runner)
|
|
154
|
+
|
|
155
|
+
Bumping the published version in downstream apps is a separate change. Update the dependency range / lockfile there after the npm release lands.
|
|
156
|
+
|
|
157
|
+
## License
|
|
158
|
+
|
|
159
|
+
Released under the [PolyForm Shield License 1.0.0](./LICENSE.md), in plain language:
|
|
160
|
+
|
|
161
|
+
- **Source-available.** The source is public and you can read, fork, and modify it.
|
|
162
|
+
- **Permitted for non-competing use.** You can use this package freely in your own products and services, as long as they don't compete with A11y Pulse.
|
|
163
|
+
- **Competing products are forbidden.** You may not use this software (or a modified version of it) to build a product or service that competes with A11y Pulse's accessibility monitoring offering.
|
|
164
|
+
|
|
165
|
+
See [LICENSE.md](./LICENSE.md) for the full, binding terms.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An element handle in the page. This type is adaptor-specific and is opaque to the audit.
|
|
3
|
+
*/
|
|
4
|
+
export type ElementRef = unknown;
|
|
5
|
+
/**
|
|
6
|
+
* A framework-specific adaptor that provides the primitives needed by the audit. An adaptor wraps
|
|
7
|
+
* a single page in a web browser.
|
|
8
|
+
*/
|
|
9
|
+
export interface SkipLinkAuditAdaptor {
|
|
10
|
+
/**
|
|
11
|
+
* Run `fn` in the page context, passing in any serialisable `args`
|
|
12
|
+
*/
|
|
13
|
+
evaluate<T>(fn: (...args: any[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
|
|
14
|
+
/**
|
|
15
|
+
* Return an opaque handle to an element in the page
|
|
16
|
+
*/
|
|
17
|
+
evaluateHandle(fn: () => Element | null): Promise<ElementRef>;
|
|
18
|
+
/**
|
|
19
|
+
* Release a handle previously returned by evaluateHandle
|
|
20
|
+
*/
|
|
21
|
+
disposeRef(ref: ElementRef): Promise<void>;
|
|
22
|
+
/**
|
|
23
|
+
* Press the tab key
|
|
24
|
+
*/
|
|
25
|
+
pressTab(): Promise<void>;
|
|
26
|
+
/**
|
|
27
|
+
* Activate the focused element via a real Enter keypress.
|
|
28
|
+
*/
|
|
29
|
+
pressEnter(): Promise<void>;
|
|
30
|
+
/**
|
|
31
|
+
* Ensure the page reports focus for its lifetime. In particular, `document.hasFocus()` must
|
|
32
|
+
* function correctly and :focus styles must be applied, even when the page is not the
|
|
33
|
+
* foreground.
|
|
34
|
+
*
|
|
35
|
+
* This function must not throw.
|
|
36
|
+
*/
|
|
37
|
+
ensureFocusReporting(): Promise<void>;
|
|
38
|
+
}
|
package/dist/audit.d.ts
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { ElementRef, SkipLinkAuditAdaptor } from "./adaptor";
|
|
2
|
+
import type { SkipLinkResult } from "./result";
|
|
3
|
+
export declare const DEFAULT_CANDIDATE_LIMIT = 3;
|
|
4
|
+
export declare const DEFAULT_ACTIVATION_POLL_MS = 250;
|
|
5
|
+
export type SkipLinkOptions = {
|
|
6
|
+
/** Max tab stops to scan for skip-link candidates. Defaults to 3. */
|
|
7
|
+
candidateLimit?: number;
|
|
8
|
+
};
|
|
9
|
+
export type ResolvedSkipLinkOptions = {
|
|
10
|
+
candidateLimit: number;
|
|
11
|
+
activationPollMs: number;
|
|
12
|
+
};
|
|
13
|
+
export type SkipLinkCandidate = {
|
|
14
|
+
selector: string;
|
|
15
|
+
html: string;
|
|
16
|
+
fragment: string;
|
|
17
|
+
targetResolves: boolean;
|
|
18
|
+
handle: ElementRef;
|
|
19
|
+
};
|
|
20
|
+
export type TabStopProbe = {
|
|
21
|
+
isBody: boolean;
|
|
22
|
+
/** Unique identity of the focused element, used to detect a focus cycle. */
|
|
23
|
+
identity: string;
|
|
24
|
+
candidate: SkipLinkCandidate | null;
|
|
25
|
+
};
|
|
26
|
+
/** The browser-coupled seams the loop drives. Mocked in unit tests. */
|
|
27
|
+
export type SkipLinkProbe = {
|
|
28
|
+
pressTab(): Promise<void>;
|
|
29
|
+
pressEnter(): Promise<void>;
|
|
30
|
+
probeTabStop(): Promise<TabStopProbe>;
|
|
31
|
+
focusHandle(ref: ElementRef): Promise<void>;
|
|
32
|
+
isFocusInsideTarget(fragment: string): Promise<boolean>;
|
|
33
|
+
disposeRef(ref: ElementRef): Promise<void>;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Tab through the first few stops looking for skip-link-like fragment anchors,
|
|
37
|
+
* then activate each candidate and check that keyboard focus moves. Enables
|
|
38
|
+
* focus reporting up front, then drives the loop.
|
|
39
|
+
*/
|
|
40
|
+
export declare function runSkipLinkAudit(adaptor: SkipLinkAuditAdaptor, options?: SkipLinkOptions): Promise<SkipLinkResult>;
|
|
41
|
+
/** The engine-neutral two-phase loop. Exported for unit testing with a fake probe. */
|
|
42
|
+
export declare function runSkipLinkLoop(probe: SkipLinkProbe, options: ResolvedSkipLinkOptions): Promise<SkipLinkResult>;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IMPORTANT: Functions in this file that are serialized and injected into the
|
|
3
|
+
* audited page must not reference any symbols outside their own scope. Common
|
|
4
|
+
* logic (fragment parsing, target resolution, shadow-root descent) is therefore
|
|
5
|
+
* duplicated inside each injected function.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Return the in-page fragment for a skip-link-like href, or null if the href is
|
|
9
|
+
* not a same-document hash (including the bare `#` and `#top`, which have no
|
|
10
|
+
* element target).
|
|
11
|
+
*/
|
|
12
|
+
export declare function parseInPageFragment(href: string | null): string | null;
|
|
13
|
+
/**
|
|
14
|
+
* Resolve a fragment to an element, preferring `id` then a matching `name`.
|
|
15
|
+
* Serialized and run in the page; must stay self-contained.
|
|
16
|
+
*/
|
|
17
|
+
export declare function resolveFragmentTargetScript(fragment: string): Element | null;
|
|
18
|
+
export type SkipLinkActiveElementBase = {
|
|
19
|
+
isBody: boolean;
|
|
20
|
+
html: string;
|
|
21
|
+
/** In-page fragment such as "#main", or null when the focused node is not a skip-link candidate. */
|
|
22
|
+
fragment: string | null;
|
|
23
|
+
targetResolves: boolean;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Read the currently focused element (descending open shadow roots) and report
|
|
27
|
+
* whether it is a skip-link-like in-page fragment anchor.
|
|
28
|
+
*/
|
|
29
|
+
export declare function probeActiveElementScript(): SkipLinkActiveElementBase;
|
|
30
|
+
/**
|
|
31
|
+
* Return the focused element, descending open shadow roots.
|
|
32
|
+
*/
|
|
33
|
+
export declare function activeElementHandleScript(): Element | null;
|
|
34
|
+
/**
|
|
35
|
+
* Whether document.activeElement is the fragment target or inside it.
|
|
36
|
+
*/
|
|
37
|
+
export declare function isFocusInsideTargetScript(fragment: string): boolean;
|
|
38
|
+
/**
|
|
39
|
+
* Focus an element.
|
|
40
|
+
*/
|
|
41
|
+
export declare function focusScript(el: Element | null): void;
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
// src/audit.ts
|
|
2
|
+
import { getSelector, truncateHtml } from "@a11y-pulse/browser-adaptor/dom";
|
|
3
|
+
|
|
4
|
+
// src/browser-scripts.ts
|
|
5
|
+
function probeActiveElementScript() {
|
|
6
|
+
let el = document.activeElement;
|
|
7
|
+
while (el?.shadowRoot?.activeElement) {
|
|
8
|
+
el = el.shadowRoot.activeElement;
|
|
9
|
+
}
|
|
10
|
+
if (!el || el === document.body) {
|
|
11
|
+
return {
|
|
12
|
+
isBody: true,
|
|
13
|
+
html: "",
|
|
14
|
+
fragment: null,
|
|
15
|
+
targetResolves: false
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
const openingTag = el.cloneNode(false).outerHTML;
|
|
19
|
+
const href = el.tagName === "A" ? el.getAttribute("href") : null;
|
|
20
|
+
let fragment = null;
|
|
21
|
+
if (href?.startsWith("#") && href !== "#" && href !== "#top" && !href.startsWith("#/") && !href.startsWith("#!/")) {
|
|
22
|
+
fragment = href;
|
|
23
|
+
}
|
|
24
|
+
let targetResolves = false;
|
|
25
|
+
if (fragment) {
|
|
26
|
+
const raw = fragment.slice(1);
|
|
27
|
+
let decoded = raw;
|
|
28
|
+
try {
|
|
29
|
+
decoded = decodeURIComponent(raw);
|
|
30
|
+
} catch {
|
|
31
|
+
}
|
|
32
|
+
targetResolves = Boolean(
|
|
33
|
+
document.getElementById(decoded) ?? document.getElementsByName(decoded)[0]
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
return {
|
|
37
|
+
isBody: false,
|
|
38
|
+
html: openingTag,
|
|
39
|
+
fragment,
|
|
40
|
+
targetResolves
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
function activeElementHandleScript() {
|
|
44
|
+
let el = document.activeElement;
|
|
45
|
+
while (el?.shadowRoot?.activeElement) {
|
|
46
|
+
el = el.shadowRoot.activeElement;
|
|
47
|
+
}
|
|
48
|
+
return el;
|
|
49
|
+
}
|
|
50
|
+
function isFocusInsideTargetScript(fragment) {
|
|
51
|
+
const raw = fragment.startsWith("#") ? fragment.slice(1) : fragment;
|
|
52
|
+
let decoded = raw;
|
|
53
|
+
try {
|
|
54
|
+
decoded = decodeURIComponent(raw);
|
|
55
|
+
} catch {
|
|
56
|
+
}
|
|
57
|
+
const target = document.getElementById(decoded) ?? document.getElementsByName(decoded)[0] ?? null;
|
|
58
|
+
if (!target) {
|
|
59
|
+
return false;
|
|
60
|
+
}
|
|
61
|
+
let el = document.activeElement;
|
|
62
|
+
while (el?.shadowRoot?.activeElement) {
|
|
63
|
+
el = el.shadowRoot.activeElement;
|
|
64
|
+
}
|
|
65
|
+
if (!el) {
|
|
66
|
+
return false;
|
|
67
|
+
}
|
|
68
|
+
return el === target || target.contains(el);
|
|
69
|
+
}
|
|
70
|
+
function focusScript(el) {
|
|
71
|
+
el?.focus();
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
// src/audit.ts
|
|
75
|
+
var DEFAULT_CANDIDATE_LIMIT = 3;
|
|
76
|
+
var DEFAULT_ACTIVATION_POLL_MS = 250;
|
|
77
|
+
function resolveOptions(options) {
|
|
78
|
+
return {
|
|
79
|
+
candidateLimit: options.candidateLimit ?? DEFAULT_CANDIDATE_LIMIT,
|
|
80
|
+
activationPollMs: DEFAULT_ACTIVATION_POLL_MS
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
async function runSkipLinkAudit(adaptor, options = {}) {
|
|
84
|
+
await adaptor.ensureFocusReporting();
|
|
85
|
+
return runSkipLinkLoop(createAdaptorProbe(adaptor), resolveOptions(options));
|
|
86
|
+
}
|
|
87
|
+
async function runSkipLinkLoop(probe, options) {
|
|
88
|
+
const collected = [];
|
|
89
|
+
const seen = /* @__PURE__ */ new Set();
|
|
90
|
+
for (let i = 0; i < options.candidateLimit; i++) {
|
|
91
|
+
await probe.pressTab();
|
|
92
|
+
const tabStop = await probe.probeTabStop();
|
|
93
|
+
if (tabStop.isBody || seen.has(tabStop.identity)) {
|
|
94
|
+
break;
|
|
95
|
+
}
|
|
96
|
+
seen.add(tabStop.identity);
|
|
97
|
+
if (tabStop.candidate) {
|
|
98
|
+
collected.push({ ...tabStop.candidate, tabIndex: i + 1 });
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
const skipLinks = [];
|
|
102
|
+
for (const found of collected) {
|
|
103
|
+
try {
|
|
104
|
+
if (!found.targetResolves) {
|
|
105
|
+
skipLinks.push({
|
|
106
|
+
selector: found.selector,
|
|
107
|
+
html: found.html,
|
|
108
|
+
fragment: found.fragment,
|
|
109
|
+
tabIndex: found.tabIndex,
|
|
110
|
+
passed: false,
|
|
111
|
+
failureReason: "target-missing"
|
|
112
|
+
});
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
await probe.focusHandle(found.handle);
|
|
116
|
+
await probe.pressEnter();
|
|
117
|
+
let passed2 = await pollFocusInsideTarget(
|
|
118
|
+
probe,
|
|
119
|
+
found.fragment,
|
|
120
|
+
options.activationPollMs
|
|
121
|
+
);
|
|
122
|
+
if (!passed2) {
|
|
123
|
+
await probe.pressTab();
|
|
124
|
+
passed2 = await probe.isFocusInsideTarget(found.fragment);
|
|
125
|
+
}
|
|
126
|
+
skipLinks.push({
|
|
127
|
+
selector: found.selector,
|
|
128
|
+
html: found.html,
|
|
129
|
+
fragment: found.fragment,
|
|
130
|
+
tabIndex: found.tabIndex,
|
|
131
|
+
passed: passed2,
|
|
132
|
+
failureReason: passed2 ? null : "activation-no-effect"
|
|
133
|
+
});
|
|
134
|
+
} finally {
|
|
135
|
+
await probe.disposeRef(found.handle);
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
const passed = skipLinks.filter((link) => link.passed).length;
|
|
139
|
+
return {
|
|
140
|
+
skipLinks,
|
|
141
|
+
summary: {
|
|
142
|
+
found: skipLinks.length,
|
|
143
|
+
passed,
|
|
144
|
+
failed: skipLinks.length - passed
|
|
145
|
+
}
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
async function pollFocusInsideTarget(probe, fragment, pollMs) {
|
|
149
|
+
if (await probe.isFocusInsideTarget(fragment)) {
|
|
150
|
+
return true;
|
|
151
|
+
}
|
|
152
|
+
if (pollMs <= 0) {
|
|
153
|
+
return false;
|
|
154
|
+
}
|
|
155
|
+
const deadline = Date.now() + pollMs;
|
|
156
|
+
while (Date.now() < deadline) {
|
|
157
|
+
await new Promise((resolve) => setTimeout(resolve, 16));
|
|
158
|
+
if (await probe.isFocusInsideTarget(fragment)) {
|
|
159
|
+
return true;
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return false;
|
|
163
|
+
}
|
|
164
|
+
function createAdaptorProbe(adaptor) {
|
|
165
|
+
return {
|
|
166
|
+
pressTab() {
|
|
167
|
+
return adaptor.pressTab();
|
|
168
|
+
},
|
|
169
|
+
pressEnter() {
|
|
170
|
+
return adaptor.pressEnter();
|
|
171
|
+
},
|
|
172
|
+
async probeTabStop() {
|
|
173
|
+
const base = await adaptor.evaluate(probeActiveElementScript);
|
|
174
|
+
if (base.isBody) {
|
|
175
|
+
return { isBody: true, identity: "body", candidate: null };
|
|
176
|
+
}
|
|
177
|
+
const handle = await adaptor.evaluateHandle(activeElementHandleScript);
|
|
178
|
+
const selector = await adaptor.evaluate(getSelector, handle);
|
|
179
|
+
const html = truncateHtml(base.html);
|
|
180
|
+
if (base.fragment) {
|
|
181
|
+
return {
|
|
182
|
+
isBody: false,
|
|
183
|
+
identity: selector,
|
|
184
|
+
candidate: {
|
|
185
|
+
selector,
|
|
186
|
+
html,
|
|
187
|
+
fragment: base.fragment,
|
|
188
|
+
targetResolves: base.targetResolves,
|
|
189
|
+
handle
|
|
190
|
+
}
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
await adaptor.disposeRef(handle);
|
|
194
|
+
return { isBody: false, identity: selector, candidate: null };
|
|
195
|
+
},
|
|
196
|
+
focusHandle(ref) {
|
|
197
|
+
return adaptor.evaluate(focusScript, ref);
|
|
198
|
+
},
|
|
199
|
+
isFocusInsideTarget(fragment) {
|
|
200
|
+
return adaptor.evaluate(isFocusInsideTargetScript, fragment);
|
|
201
|
+
},
|
|
202
|
+
disposeRef(ref) {
|
|
203
|
+
return adaptor.disposeRef(ref);
|
|
204
|
+
}
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
export {
|
|
208
|
+
runSkipLinkAudit
|
|
209
|
+
};
|
|
210
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/audit.ts","../src/browser-scripts.ts"],"sourcesContent":["import { getSelector, truncateHtml } from \"@a11y-pulse/browser-adaptor/dom\";\nimport type { ElementRef, SkipLinkAuditAdaptor } from \"./adaptor\";\nimport {\n\tactiveElementHandleScript,\n\tfocusScript,\n\tisFocusInsideTargetScript,\n\tprobeActiveElementScript,\n} from \"./browser-scripts\";\nimport type { SkipLinkElementResult, SkipLinkResult } from \"./result\";\n\nexport const DEFAULT_CANDIDATE_LIMIT = 3;\nexport const DEFAULT_ACTIVATION_POLL_MS = 250;\n\nexport type SkipLinkOptions = {\n\t/** Max tab stops to scan for skip-link candidates. Defaults to 3. */\n\tcandidateLimit?: number;\n};\n\nexport type ResolvedSkipLinkOptions = {\n\tcandidateLimit: number;\n\tactivationPollMs: number;\n};\n\nexport type SkipLinkCandidate = {\n\tselector: string;\n\thtml: string;\n\tfragment: string;\n\ttargetResolves: boolean;\n\thandle: ElementRef;\n};\n\nexport type TabStopProbe = {\n\tisBody: boolean;\n\t/** Unique identity of the focused element, used to detect a focus cycle. */\n\tidentity: string;\n\tcandidate: SkipLinkCandidate | null;\n};\n\n/** The browser-coupled seams the loop drives. Mocked in unit tests. */\nexport type SkipLinkProbe = {\n\tpressTab(): Promise<void>;\n\tpressEnter(): Promise<void>;\n\tprobeTabStop(): Promise<TabStopProbe>;\n\tfocusHandle(ref: ElementRef): Promise<void>;\n\tisFocusInsideTarget(fragment: string): Promise<boolean>;\n\tdisposeRef(ref: ElementRef): Promise<void>;\n};\n\nfunction resolveOptions(options: SkipLinkOptions): ResolvedSkipLinkOptions {\n\treturn {\n\t\tcandidateLimit: options.candidateLimit ?? DEFAULT_CANDIDATE_LIMIT,\n\t\tactivationPollMs: DEFAULT_ACTIVATION_POLL_MS,\n\t};\n}\n\n/**\n * Tab through the first few stops looking for skip-link-like fragment anchors,\n * then activate each candidate and check that keyboard focus moves. Enables\n * focus reporting up front, then drives the loop.\n */\nexport async function runSkipLinkAudit(\n\tadaptor: SkipLinkAuditAdaptor,\n\toptions: SkipLinkOptions = {},\n): Promise<SkipLinkResult> {\n\tawait adaptor.ensureFocusReporting();\n\n\treturn runSkipLinkLoop(createAdaptorProbe(adaptor), resolveOptions(options));\n}\n\n/** The engine-neutral two-phase loop. Exported for unit testing with a fake probe. */\nexport async function runSkipLinkLoop(\n\tprobe: SkipLinkProbe,\n\toptions: ResolvedSkipLinkOptions,\n): Promise<SkipLinkResult> {\n\tconst collected: Array<SkipLinkCandidate & { tabIndex: number }> = [];\n\tconst seen = new Set<string>();\n\n\tfor (let i = 0; i < options.candidateLimit; i++) {\n\t\tawait probe.pressTab();\n\n\t\tconst tabStop = await probe.probeTabStop();\n\n\t\tif (tabStop.isBody || seen.has(tabStop.identity)) {\n\t\t\tbreak;\n\t\t}\n\n\t\tseen.add(tabStop.identity);\n\n\t\tif (tabStop.candidate) {\n\t\t\tcollected.push({ ...tabStop.candidate, tabIndex: i + 1 });\n\t\t}\n\t}\n\n\tconst skipLinks: SkipLinkElementResult[] = [];\n\n\tfor (const found of collected) {\n\t\ttry {\n\t\t\tif (!found.targetResolves) {\n\t\t\t\tskipLinks.push({\n\t\t\t\t\tselector: found.selector,\n\t\t\t\t\thtml: found.html,\n\t\t\t\t\tfragment: found.fragment,\n\t\t\t\t\ttabIndex: found.tabIndex,\n\t\t\t\t\tpassed: false,\n\t\t\t\t\tfailureReason: \"target-missing\",\n\t\t\t\t});\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tawait probe.focusHandle(found.handle);\n\t\t\tawait probe.pressEnter();\n\n\t\t\tlet passed = await pollFocusInsideTarget(\n\t\t\t\tprobe,\n\t\t\t\tfound.fragment,\n\t\t\t\toptions.activationPollMs,\n\t\t\t);\n\n\t\t\tif (!passed) {\n\t\t\t\tawait probe.pressTab();\n\t\t\t\tpassed = await probe.isFocusInsideTarget(found.fragment);\n\t\t\t}\n\n\t\t\tskipLinks.push({\n\t\t\t\tselector: found.selector,\n\t\t\t\thtml: found.html,\n\t\t\t\tfragment: found.fragment,\n\t\t\t\ttabIndex: found.tabIndex,\n\t\t\t\tpassed,\n\t\t\t\tfailureReason: passed ? null : \"activation-no-effect\",\n\t\t\t});\n\t\t} finally {\n\t\t\tawait probe.disposeRef(found.handle);\n\t\t}\n\t}\n\n\tconst passed = skipLinks.filter((link) => link.passed).length;\n\n\treturn {\n\t\tskipLinks,\n\t\tsummary: {\n\t\t\tfound: skipLinks.length,\n\t\t\tpassed,\n\t\t\tfailed: skipLinks.length - passed,\n\t\t},\n\t};\n}\n\nasync function pollFocusInsideTarget(\n\tprobe: SkipLinkProbe,\n\tfragment: string,\n\tpollMs: number,\n): Promise<boolean> {\n\tif (await probe.isFocusInsideTarget(fragment)) {\n\t\treturn true;\n\t}\n\n\tif (pollMs <= 0) {\n\t\treturn false;\n\t}\n\n\tconst deadline = Date.now() + pollMs;\n\n\twhile (Date.now() < deadline) {\n\t\tawait new Promise((resolve) => setTimeout(resolve, 16));\n\n\t\tif (await probe.isFocusInsideTarget(fragment)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\n\treturn false;\n}\n\nfunction createAdaptorProbe(adaptor: SkipLinkAuditAdaptor): SkipLinkProbe {\n\treturn {\n\t\tpressTab() {\n\t\t\treturn adaptor.pressTab();\n\t\t},\n\n\t\tpressEnter() {\n\t\t\treturn adaptor.pressEnter();\n\t\t},\n\n\t\tasync probeTabStop() {\n\t\t\tconst base = await adaptor.evaluate(probeActiveElementScript);\n\n\t\t\tif (base.isBody) {\n\t\t\t\treturn { isBody: true, identity: \"body\", candidate: null };\n\t\t\t}\n\n\t\t\tconst handle = await adaptor.evaluateHandle(activeElementHandleScript);\n\t\t\tconst selector = await adaptor.evaluate(getSelector, handle);\n\t\t\tconst html = truncateHtml(base.html);\n\n\t\t\tif (base.fragment) {\n\t\t\t\treturn {\n\t\t\t\t\tisBody: false,\n\t\t\t\t\tidentity: selector,\n\t\t\t\t\tcandidate: {\n\t\t\t\t\t\tselector,\n\t\t\t\t\t\thtml,\n\t\t\t\t\t\tfragment: base.fragment,\n\t\t\t\t\t\ttargetResolves: base.targetResolves,\n\t\t\t\t\t\thandle,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tawait adaptor.disposeRef(handle);\n\n\t\t\treturn { isBody: false, identity: selector, candidate: null };\n\t\t},\n\n\t\tfocusHandle(ref) {\n\t\t\treturn adaptor.evaluate(focusScript, ref);\n\t\t},\n\n\t\tisFocusInsideTarget(fragment) {\n\t\t\treturn adaptor.evaluate(isFocusInsideTargetScript, fragment);\n\t\t},\n\n\t\tdisposeRef(ref) {\n\t\t\treturn adaptor.disposeRef(ref);\n\t\t},\n\t};\n}\n","/**\n * IMPORTANT: Functions in this file that are serialized and injected into the\n * audited page must not reference any symbols outside their own scope. Common\n * logic (fragment parsing, target resolution, shadow-root descent) is therefore\n * duplicated inside each injected function.\n */\n\n/**\n * Return the in-page fragment for a skip-link-like href, or null if the href is\n * not a same-document hash (including the bare `#` and `#top`, which have no\n * element target).\n */\nexport function parseInPageFragment(href: string | null): string | null {\n\tif (href === null || href === \"\") {\n\t\treturn null;\n\t}\n\n\tif (!href.startsWith(\"#\")) {\n\t\treturn null;\n\t}\n\n\tif (href === \"#\" || href === \"#top\") {\n\t\treturn null;\n\t}\n\n\t// Hash-router and hashbang paths are not element ids.\n\tif (href.startsWith(\"#/\") || href.startsWith(\"#!/\")) {\n\t\treturn null;\n\t}\n\n\treturn href;\n}\n\n/**\n * Resolve a fragment to an element, preferring `id` then a matching `name`.\n * Serialized and run in the page; must stay self-contained.\n */\nexport function resolveFragmentTargetScript(fragment: string): Element | null {\n\tconst raw = fragment.startsWith(\"#\") ? fragment.slice(1) : fragment;\n\tlet decoded = raw;\n\n\ttry {\n\t\tdecoded = decodeURIComponent(raw);\n\t} catch {\n\t\t// Keep the raw id when it is not valid percent-encoding.\n\t}\n\n\treturn (\n\t\tdocument.getElementById(decoded) ??\n\t\tdocument.getElementsByName(decoded)[0] ??\n\t\tnull\n\t);\n}\n\nexport type SkipLinkActiveElementBase = {\n\tisBody: boolean;\n\thtml: string;\n\t/** In-page fragment such as \"#main\", or null when the focused node is not a skip-link candidate. */\n\tfragment: string | null;\n\ttargetResolves: boolean;\n};\n\n/**\n * Read the currently focused element (descending open shadow roots) and report\n * whether it is a skip-link-like in-page fragment anchor.\n */\nexport function probeActiveElementScript(): SkipLinkActiveElementBase {\n\tlet el = document.activeElement;\n\n\twhile (el?.shadowRoot?.activeElement) {\n\t\tel = el.shadowRoot.activeElement;\n\t}\n\n\tif (!el || el === document.body) {\n\t\treturn {\n\t\t\tisBody: true,\n\t\t\thtml: \"\",\n\t\t\tfragment: null,\n\t\t\ttargetResolves: false,\n\t\t};\n\t}\n\n\tconst openingTag = (el.cloneNode(false) as Element).outerHTML;\n\tconst href =\n\t\tel.tagName === \"A\" ? (el as HTMLAnchorElement).getAttribute(\"href\") : null;\n\n\tlet fragment: string | null = null;\n\n\tif (\n\t\thref?.startsWith(\"#\") &&\n\t\thref !== \"#\" &&\n\t\thref !== \"#top\" &&\n\t\t!href.startsWith(\"#/\") &&\n\t\t!href.startsWith(\"#!/\")\n\t) {\n\t\tfragment = href;\n\t}\n\n\tlet targetResolves = false;\n\n\tif (fragment) {\n\t\tconst raw = fragment.slice(1);\n\t\tlet decoded = raw;\n\n\t\ttry {\n\t\t\tdecoded = decodeURIComponent(raw);\n\t\t} catch {\n\t\t\t// Keep the raw id when it is not valid percent-encoding.\n\t\t}\n\n\t\ttargetResolves = Boolean(\n\t\t\tdocument.getElementById(decoded) ??\n\t\t\t\tdocument.getElementsByName(decoded)[0],\n\t\t);\n\t}\n\n\treturn {\n\t\tisBody: false,\n\t\thtml: openingTag,\n\t\tfragment,\n\t\ttargetResolves,\n\t};\n}\n\n/**\n * Return the focused element, descending open shadow roots.\n */\nexport function activeElementHandleScript(): Element | null {\n\tlet el = document.activeElement;\n\n\twhile (el?.shadowRoot?.activeElement) {\n\t\tel = el.shadowRoot.activeElement;\n\t}\n\n\treturn el;\n}\n\n/**\n * Whether document.activeElement is the fragment target or inside it.\n */\nexport function isFocusInsideTargetScript(fragment: string): boolean {\n\tconst raw = fragment.startsWith(\"#\") ? fragment.slice(1) : fragment;\n\tlet decoded = raw;\n\n\ttry {\n\t\tdecoded = decodeURIComponent(raw);\n\t} catch {\n\t\t// Keep the raw id when it is not valid percent-encoding.\n\t}\n\n\tconst target =\n\t\tdocument.getElementById(decoded) ??\n\t\tdocument.getElementsByName(decoded)[0] ??\n\t\tnull;\n\n\tif (!target) {\n\t\treturn false;\n\t}\n\n\tlet el = document.activeElement;\n\n\twhile (el?.shadowRoot?.activeElement) {\n\t\tel = el.shadowRoot.activeElement;\n\t}\n\n\tif (!el) {\n\t\treturn false;\n\t}\n\n\treturn el === target || target.contains(el);\n}\n\n/**\n * Focus an element.\n */\nexport function focusScript(el: Element | null): void {\n\t(el as HTMLElement | null)?.focus();\n}\n"],"mappings":"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","names":["passed"]}
|
package/dist/result.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export type SkipLinkFailureReason = "target-missing" | "activation-no-effect";
|
|
2
|
+
export type SkipLinkElementResult = {
|
|
3
|
+
/** Selector for the skip-link element (see getSelector). */
|
|
4
|
+
selector: string;
|
|
5
|
+
/** Truncated opening tag. */
|
|
6
|
+
html: string;
|
|
7
|
+
/** The href fragment, e.g. "#main". */
|
|
8
|
+
fragment: string;
|
|
9
|
+
/** 1-based tab stop at which this skip link was reached. */
|
|
10
|
+
tabIndex: number;
|
|
11
|
+
/** Whether activating the skip link moved keyboard focus to the target. */
|
|
12
|
+
passed: boolean;
|
|
13
|
+
/** Why the candidate failed, or null when it passed. */
|
|
14
|
+
failureReason: SkipLinkFailureReason | null;
|
|
15
|
+
};
|
|
16
|
+
export type SkipLinkResult = {
|
|
17
|
+
/** Skip-link candidates found in the first tab stops. Empty when none were found. */
|
|
18
|
+
skipLinks: SkipLinkElementResult[];
|
|
19
|
+
summary: {
|
|
20
|
+
found: number;
|
|
21
|
+
passed: number;
|
|
22
|
+
failed: number;
|
|
23
|
+
};
|
|
24
|
+
};
|
package/package.json
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@a11y-pulse/skip-link-audit",
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "WCAG 2.4.1 Bypass Blocks audit that finds skip-link-like in-page anchors in the first tab stops and verifies that activating them moves keyboard focus.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "SEE LICENSE IN LICENSE.md",
|
|
7
|
+
"author": "A11y Pulse Limited",
|
|
8
|
+
"homepage": "https://github.com/A11y-Pulse/audits/tree/main/packages/skip-link-audit#readme",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/A11y-Pulse/audits.git",
|
|
12
|
+
"directory": "packages/skip-link-audit"
|
|
13
|
+
},
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/A11y-Pulse/audits/issues"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"accessibility",
|
|
19
|
+
"a11y",
|
|
20
|
+
"wcag",
|
|
21
|
+
"bypass-blocks",
|
|
22
|
+
"skip-link",
|
|
23
|
+
"audit"
|
|
24
|
+
],
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": ">=22"
|
|
27
|
+
},
|
|
28
|
+
"exports": {
|
|
29
|
+
".": {
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"import": "./dist/index.js"
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
"files": [
|
|
35
|
+
"dist",
|
|
36
|
+
"README.md",
|
|
37
|
+
"LICENSE.md"
|
|
38
|
+
],
|
|
39
|
+
"scripts": {
|
|
40
|
+
"build": "tsup && tsc -p tsconfig.build.json",
|
|
41
|
+
"typecheck": "tsc --noEmit",
|
|
42
|
+
"lint": "biome check",
|
|
43
|
+
"lint:fix": "biome check --fix",
|
|
44
|
+
"test:unit": "vitest run",
|
|
45
|
+
"test:integration": "vitest run --config vitest.integration.config.ts",
|
|
46
|
+
"test": "npm run typecheck && npm run test:unit",
|
|
47
|
+
"prepublishOnly": "npm run build"
|
|
48
|
+
},
|
|
49
|
+
"publishConfig": {
|
|
50
|
+
"access": "public"
|
|
51
|
+
},
|
|
52
|
+
"dependencies": {
|
|
53
|
+
"@a11y-pulse/browser-adaptor": "*"
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"happy-dom": "^20.11.2",
|
|
57
|
+
"puppeteer": "^25.5.0"
|
|
58
|
+
}
|
|
59
|
+
}
|