@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 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
+ [![npm version](https://img.shields.io/npm/v/@a11y-pulse/skip-link-audit)](https://www.npmjs.com/package/@a11y-pulse/skip-link-audit)
4
+ [![CI](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml/badge.svg)](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml)
5
+ [![License: PolyForm Shield 1.0.0](https://img.shields.io/badge/license-PolyForm%20Shield%201.0.0-blue)](./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
+ }
@@ -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;
@@ -0,0 +1,4 @@
1
+ export type { SkipLinkAuditAdaptor } from "./adaptor";
2
+ export type { SkipLinkOptions } from "./audit";
3
+ export { runSkipLinkAudit } from "./audit";
4
+ export type { SkipLinkElementResult, SkipLinkFailureReason, SkipLinkResult, } from "./result";
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"]}
@@ -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
+ }