@a11y-pulse/skip-link-audit 0.1.2 → 0.3.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 +72 -12
- package/dist/adaptor.d.ts +8 -0
- package/dist/audit.d.ts +36 -6
- package/dist/browser-scripts.d.ts +94 -21
- package/dist/index.d.ts +1 -1
- package/dist/index.js +500 -107
- package/dist/index.js.map +1 -1
- package/dist/result.d.ts +53 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml)
|
|
5
5
|
[](./LICENSE.md)
|
|
6
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
|
|
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 appears in the first few tab stops, it activates the link with Enter and checks that keyboard focus moves to the target or past it. It also reports skip links that are in the document but can never receive focus. 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
8
|
|
|
9
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
10
|
|
|
@@ -32,7 +32,7 @@ await page.goto("https://who.likesdogs.nz/");
|
|
|
32
32
|
const result = await runSkipLinkAudit(new PuppeteerAdaptor(page));
|
|
33
33
|
|
|
34
34
|
console.log(result.summary);
|
|
35
|
-
// { found: 1, passed: 1, failed: 0 }
|
|
35
|
+
// { found: 1, passed: 1, failed: 0, unreachable: 0 }
|
|
36
36
|
|
|
37
37
|
console.log(result.skipLinks);
|
|
38
38
|
// [
|
|
@@ -42,7 +42,11 @@ console.log(result.skipLinks);
|
|
|
42
42
|
// fragment: "#main",
|
|
43
43
|
// tabIndex: 1,
|
|
44
44
|
// passed: true,
|
|
45
|
-
// failureReason: null
|
|
45
|
+
// failureReason: null,
|
|
46
|
+
// linkText: "Skip to content",
|
|
47
|
+
// target: { selector: "#main", html: '<main id="main" tabindex="-1">', rendered: true },
|
|
48
|
+
// focusAfterEnter: { position: "inside-target", selector: "#main", html: '<main id="main" tabindex="-1">' },
|
|
49
|
+
// focusAfterTab: null
|
|
46
50
|
// }
|
|
47
51
|
// ]
|
|
48
52
|
|
|
@@ -76,37 +80,81 @@ The following options can be passed to `runSkipLinkAudit` as `SkipLinkOptions`:
|
|
|
76
80
|
|
|
77
81
|
```ts
|
|
78
82
|
type SkipLinkResult = {
|
|
79
|
-
/** Skip
|
|
83
|
+
/** Skip links found in the first tab stops. Empty when none were found. */
|
|
80
84
|
skipLinks: Array<{
|
|
81
85
|
selector: string;
|
|
82
86
|
html: string;
|
|
83
87
|
fragment: string;
|
|
84
88
|
tabIndex: number;
|
|
85
89
|
passed: boolean;
|
|
86
|
-
failureReason: "target-missing" | "activation-no-effect" | null;
|
|
90
|
+
failureReason: "target-missing" | "target-hidden" | "activation-no-effect" | null;
|
|
91
|
+
/** Text of the link, falling back to its aria-label. */
|
|
92
|
+
linkText?: string;
|
|
93
|
+
/** The element the fragment resolves to, or null when nothing matches it. */
|
|
94
|
+
target?: { selector: string; html: string; rendered: boolean } | null;
|
|
95
|
+
/** Where focus was once Enter had been pressed on the link. */
|
|
96
|
+
focusAfterEnter?: SkipLinkFocusLanding;
|
|
97
|
+
/** Where focus was after the follow-up Tab, or null when it was not pressed. */
|
|
98
|
+
focusAfterTab?: SkipLinkFocusLanding | null;
|
|
99
|
+
/** PNG bytes of the focused skip link, clipped and padded. Only captured when it failed. */
|
|
100
|
+
screenshot?: Uint8Array;
|
|
101
|
+
}>;
|
|
102
|
+
/** Skip links that can never be focused. Only looked for when tabbing reached no skip link. */
|
|
103
|
+
unreachable: Array<{
|
|
104
|
+
selector: string;
|
|
105
|
+
html: string;
|
|
106
|
+
fragment: string;
|
|
107
|
+
linkText: string;
|
|
108
|
+
reason: "not-rendered" | "visibility-hidden" | "inert" | "negative-tabindex";
|
|
87
109
|
}>;
|
|
88
110
|
summary: {
|
|
89
111
|
found: number;
|
|
90
112
|
passed: number;
|
|
91
113
|
failed: number;
|
|
114
|
+
unreachable: number;
|
|
92
115
|
};
|
|
93
116
|
};
|
|
117
|
+
|
|
118
|
+
type SkipLinkFocusLanding = {
|
|
119
|
+
position: "inside-target" | "after-target" | "after-link" | "skip-link" | "body" | "elsewhere";
|
|
120
|
+
/** Selector and opening tag of the focused element, or null when nothing was focused. */
|
|
121
|
+
selector: string | null;
|
|
122
|
+
html: string | null;
|
|
123
|
+
};
|
|
94
124
|
```
|
|
95
125
|
|
|
96
|
-
When no
|
|
126
|
+
When no skip link is found, `skipLinks` and `unreachable` are empty and the summary is zeros. Landmark-only pages are not flagged.
|
|
127
|
+
|
|
128
|
+
| `failureReason` | Meaning |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| `target-missing` | Nothing in the page matches the fragment (an `id`, or an `<a name>`), and activating the link did not move focus to later content. |
|
|
131
|
+
| `target-hidden` | The target exists but is not rendered, for example inside a `display: none` container, and activating the link did not focus it. |
|
|
132
|
+
| `activation-no-effect` | The target exists, but neither Enter nor the Tab after it put focus in or after the target. `focusAfterEnter` and `focusAfterTab` say where focus went instead. |
|
|
97
133
|
|
|
98
134
|
## How it works
|
|
99
135
|
|
|
100
136
|
1. Enable focus reporting so Tab, Enter, and `:focus` behave as they would in a foreground tab.
|
|
101
|
-
2. Press Tab up to `candidateLimit` times. After each press, inspect the focused element (descending open shadow roots).
|
|
102
|
-
3.
|
|
103
|
-
|
|
137
|
+
2. Press Tab up to `candidateLimit` times. After each press, inspect the focused element (descending open shadow roots). The scan stops early on `<body>` or if focus cycles.
|
|
138
|
+
3. A focused `<a>` is a skip link when its resolved `href` is a fragment of the current document (`#main`, `/this-page#main` or the absolute URL, but not a bare `#`, `#top` or a hash-router path such as `#/home`) and at least one of these holds:
|
|
139
|
+
- its text or `aria-label` uses skip wording: "skip", or a "go to" verb followed by a content or navigation noun ("Jump to content", "Aller au contenu", "Ga naar inhoud", and equivalents in a handful of other languages). Matching is on whole words, so "Popular posts" and "Aller au panier" are not skip wording;
|
|
140
|
+
- its `class` or `id` is a skip token such as `skip`, `skip-link` or `skip-to-content`;
|
|
141
|
+
- its target comes after the link, is rendered, is not a navigation block, and is the page's main content: a heading, the `main` landmark, a wrapper around it or something inside it, or, on a page with no `main` landmark, an element with a conventional id such as `content` or `main-content`.
|
|
142
|
+
|
|
143
|
+
Skipping past other tab stops is not enough on its own: a "Menu" link to a navigation block further down the page does that too, and following it would open the menu.
|
|
144
|
+
|
|
145
|
+
Links with `aria-expanded`, `role="tab"` or `role="button"` are never skip links: they are disclosure triggers, tabs and buttons, and the audit must not activate them.
|
|
146
|
+
4. For each skip link: record the URL and scroll position, re-focus the link, press Enter, and poll for up to 250ms. It passes if focus is now in the target or after it. A link whose fragment matches nothing is activated too, and passes if a script moved focus to content after the link.
|
|
147
|
+
5. If focus did not visibly move and the target is rendered, press Tab once. Browsers move the sequential focus navigation starting point on fragment navigation even when the target is not focusable, so the link passes if the newly focused element is inside the target, or follows it in document order and the fragment was actually followed. That covers targets with nothing focusable inside, such as `<h1 id="title">` or an empty `<a id="content"></a>`. Otherwise record `activation-no-effect`.
|
|
148
|
+
6. Undo each activation: go back in history when following the link added an entry, which restores the URL and clears `:target`, or rewrite the URL in place when it did not, then put the scroll position back. When the audit finishes, including when it throws, drop focus and move the point Tab starts from back to the top of the document, so whatever runs next sees the page as it was loaded and tabs from its first stop.
|
|
149
|
+
7. If tabbing reached no skip link, look through the first links in the document for one whose text or `aria-label` has skip wording and that can never be focused (`display: none`, `visibility: hidden`, inert, or a negative `tabindex`) and report it under `unreachable`.
|
|
104
150
|
|
|
105
151
|
Activation uses a real Enter keypress rather than a synthetic click, so the keyboard path is the one being checked.
|
|
106
152
|
|
|
153
|
+
A failed skip link is focused again and screenshotted, so a link that only appears on focus is visible in the evidence.
|
|
154
|
+
|
|
107
155
|
## Adaptors
|
|
108
156
|
|
|
109
|
-
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.
|
|
157
|
+
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, take a screenshot) that the audit calls without knowing which browser automation library is behind it.
|
|
110
158
|
|
|
111
159
|
[`@a11y-pulse/browser-adaptor`](../browser-adaptor) ships two implementations, `PuppeteerAdaptor` and `PlaywrightAdaptor`. Other environments (Selenium, WebDriver) can be supported by implementing the same interface, exported as `SkipLinkAuditAdaptor` (aliased as `BrowserAdaptor` from the package root).
|
|
112
160
|
|
|
@@ -119,6 +167,8 @@ The audit itself is framework-agnostic: it drives a page through an **adaptor**,
|
|
|
119
167
|
| `disposeRef(ref)` | Releases a handle previously returned by `evaluateHandle`. |
|
|
120
168
|
| `pressTab()` | Presses the Tab key, advancing focus to the next focusable element. |
|
|
121
169
|
| `pressEnter()` | Presses the Enter key, activating the focused element. |
|
|
170
|
+
| `screenshotClip(clip, scale?)` | Screenshots the `clip` region of the page, in document coordinates, at `scale` bitmap pixels per CSS pixel, and returns PNG bytes. |
|
|
171
|
+
| `screenshotClipScale` | Optional. The scale for evidence screenshots. Defaults to 1. |
|
|
122
172
|
| `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. |
|
|
123
173
|
|
|
124
174
|
### Writing a new adaptor
|
|
@@ -130,7 +180,7 @@ import type { SkipLinkAuditAdaptor } from "@a11y-pulse/skip-link-audit";
|
|
|
130
180
|
|
|
131
181
|
class MyFrameworkAdaptor implements SkipLinkAuditAdaptor {
|
|
132
182
|
// ...implement evaluate, evaluateHandle, disposeRef, pressTab,
|
|
133
|
-
// pressEnter, and ensureFocusReporting for your framework
|
|
183
|
+
// pressEnter, screenshotClip, and ensureFocusReporting for your framework
|
|
134
184
|
}
|
|
135
185
|
```
|
|
136
186
|
|
|
@@ -140,10 +190,20 @@ Use [`@a11y-pulse/browser-adaptor`'s `src/adaptors/puppeteer.ts`](../browser-ada
|
|
|
140
190
|
|
|
141
191
|
- **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.
|
|
142
192
|
- **First tab stops only.** Skip links beyond `candidateLimit` (default 3) are not detected. The audit stays silent, which never flags a conformant page.
|
|
143
|
-
- **
|
|
193
|
+
- **Links only.** Button-based skip controls are out of scope. A script-driven skip link is checked as long as it is an `<a>` with a fragment `href`.
|
|
194
|
+
- **Skip wording is a short multilingual list.** A skip link whose target is missing, is a navigation block, or is not the page's main content is only recognised by its wording or a skip class or id. One in a language the list does not cover, pointing at a `<div>` with an unconventional id on a page with no `main` landmark, is not evaluated, which never flags a conformant page.
|
|
195
|
+
- **Changes made by activation are not all undone.** The URL, `:target`, scroll position, focus and tab starting point are restored, but anything else a page does when its skip link is activated stays done. The history entry that following a fragment link adds cannot be removed: the page is returned to the entry it was on, and the added one remains as a forward entry, so `history.length` stays one higher. A page whose URL changed without a new history entry has its URL rewritten in place, and `:target` then keeps pointing at the skip target.
|
|
196
|
+
- **A leftover node on positive-tabindex pages.** Where a page uses a positive `tabindex`, resetting the tab starting point leaves an empty, `aria-hidden` `<span data-a11y-pulse-skip-link-focus-start>` in front of the first element in the tab order. It removes itself the next time anything is focused.
|
|
144
197
|
- **Closed shadow roots** are opaque; a skip link inside one is invisible to the scan.
|
|
145
198
|
- **Landmarks and headings** that satisfy 2.4.1 without a skip link are out of scope by design.
|
|
146
199
|
|
|
200
|
+
## Known false positives
|
|
201
|
+
|
|
202
|
+
Cases where the audit reports a problem that is not one. Each says which bucket it lands in: `incomplete` asks for a human to check, `violations` claims a failure.
|
|
203
|
+
|
|
204
|
+
- **Skip links hidden at this viewport** (`violations`). A skip link that is `display: none` at the audited viewport size and shown at another is reported as unreachable.
|
|
205
|
+
- **Skip links that move focus slowly** (`violations`). The audit waits 250ms (`activationPollMs`) for focus to arrive. A skip link that only moves focus after a longer smooth-scroll animation is reported as having no effect.
|
|
206
|
+
|
|
147
207
|
## Releasing
|
|
148
208
|
|
|
149
209
|
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`.
|
package/dist/adaptor.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { Rect } from "@a11y-pulse/browser-adaptor";
|
|
1
2
|
/**
|
|
2
3
|
* An element handle in the page. This type is adaptor-specific and is opaque to the audit.
|
|
3
4
|
*/
|
|
@@ -27,6 +28,13 @@ export interface SkipLinkAuditAdaptor {
|
|
|
27
28
|
* Activate the focused element via a real Enter keypress.
|
|
28
29
|
*/
|
|
29
30
|
pressEnter(): Promise<void>;
|
|
31
|
+
/**
|
|
32
|
+
* Screenshot a clipped region of the page defined by `clip`, in document coordinates, at `scale`
|
|
33
|
+
* bitmap pixels per CSS pixel. This function must return PNG bytes.
|
|
34
|
+
*/
|
|
35
|
+
screenshotClip(clip: Rect, scale?: number): Promise<Uint8Array>;
|
|
36
|
+
/** Device scale factor for evidence screenshots. Defaults to 1. */
|
|
37
|
+
readonly screenshotClipScale?: number;
|
|
30
38
|
/**
|
|
31
39
|
* Ensure the page reports focus for its lifetime. In particular, `document.hasFocus()` must
|
|
32
40
|
* function correctly and :focus styles must be applied, even when the page is not the foreground.
|
package/dist/audit.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ElementRef, SkipLinkAuditAdaptor } from "./adaptor";
|
|
2
|
-
import type
|
|
2
|
+
import { type SkipLinkFocusPosition, type SkipLinkPageState } from "./browser-scripts";
|
|
3
|
+
import type { SkipLinkResult, SkipLinkTarget, SkipLinkUnreachableResult } from "./result";
|
|
3
4
|
export declare const DEFAULT_CANDIDATE_LIMIT = 3;
|
|
4
5
|
export declare const DEFAULT_ACTIVATION_POLL_MS = 250;
|
|
5
6
|
export type SkipLinkOptions = {
|
|
@@ -14,7 +15,9 @@ export type SkipLinkCandidate = {
|
|
|
14
15
|
selector: string;
|
|
15
16
|
html: string;
|
|
16
17
|
fragment: string;
|
|
17
|
-
|
|
18
|
+
linkText: string;
|
|
19
|
+
/** The element the fragment resolves to, or null when nothing matches it. */
|
|
20
|
+
target: SkipLinkTarget | null;
|
|
18
21
|
handle: ElementRef;
|
|
19
22
|
};
|
|
20
23
|
export type TabStopProbe = {
|
|
@@ -23,19 +26,46 @@ export type TabStopProbe = {
|
|
|
23
26
|
identity: string;
|
|
24
27
|
candidate: SkipLinkCandidate | null;
|
|
25
28
|
};
|
|
29
|
+
/** Where focus is relative to a skip link, read after a key press. */
|
|
30
|
+
export type FocusReading = {
|
|
31
|
+
position: SkipLinkFocusPosition;
|
|
32
|
+
/** Whether the document's URL fragment is the one the link points at. */
|
|
33
|
+
navigated: boolean;
|
|
34
|
+
/** Whether the link's target exists. */
|
|
35
|
+
targetExists: boolean;
|
|
36
|
+
/** Whether the link's target exists and is rendered. */
|
|
37
|
+
targetRendered: boolean;
|
|
38
|
+
};
|
|
26
39
|
/** The browser-coupled seams the loop drives. Mocked in unit tests. */
|
|
27
40
|
export type SkipLinkProbe = {
|
|
28
41
|
pressTab(): Promise<void>;
|
|
29
42
|
pressEnter(): Promise<void>;
|
|
30
43
|
probeTabStop(): Promise<TabStopProbe>;
|
|
31
44
|
focusHandle(ref: ElementRef): Promise<void>;
|
|
32
|
-
|
|
45
|
+
/** Where focus is now, relative to the skip link behind `ref` and its target. */
|
|
46
|
+
readFocus(ref: ElementRef): Promise<FocusReading>;
|
|
47
|
+
/** Selector and opening tag of the focused element, or null when nothing is focused. */
|
|
48
|
+
describeFocused(): Promise<{
|
|
49
|
+
selector: string;
|
|
50
|
+
html: string;
|
|
51
|
+
} | null>;
|
|
52
|
+
/** Skip links in the document that can never receive keyboard focus. */
|
|
53
|
+
findUnreachable(): Promise<SkipLinkUnreachableResult[]>;
|
|
54
|
+
/** Record the URL, history length and scroll position so activating a link can be undone. */
|
|
55
|
+
saveState(): Promise<SkipLinkPageState>;
|
|
56
|
+
restoreState(state: SkipLinkPageState): Promise<void>;
|
|
57
|
+
/**
|
|
58
|
+
* Drop focus and start the tab order from the top again, so the next Tab press does not carry on
|
|
59
|
+
* from a skip target or from the last stop the audit looked at.
|
|
60
|
+
*/
|
|
61
|
+
clearFocus(): Promise<void>;
|
|
62
|
+
/** Focus the element and screenshot it, so a link that only appears on focus is visible. */
|
|
63
|
+
screenshotFocused(ref: ElementRef): Promise<Uint8Array>;
|
|
33
64
|
disposeRef(ref: ElementRef): Promise<void>;
|
|
34
65
|
};
|
|
35
66
|
/**
|
|
36
|
-
* Tab through the first few stops looking for skip
|
|
37
|
-
*
|
|
38
|
-
* loop.
|
|
67
|
+
* Tab through the first few stops looking for skip links, then activate each one and check that
|
|
68
|
+
* keyboard focus moves. Enables focus reporting up front, then drives the loop.
|
|
39
69
|
*/
|
|
40
70
|
export declare function runSkipLinkAudit(adaptor: SkipLinkAuditAdaptor, options?: SkipLinkOptions): Promise<SkipLinkResult>;
|
|
41
71
|
/** The engine-neutral two-phase loop. Exported for unit testing with a fake probe. */
|
|
@@ -1,38 +1,111 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* IMPORTANT: Functions in this file
|
|
3
|
-
* reference any symbols outside their own scope.
|
|
4
|
-
*
|
|
2
|
+
* IMPORTANT: Functions in this file are serialized and injected into the audited page, so they must
|
|
3
|
+
* not reference any symbols outside their own scope. Everything that needs the fragment parsing,
|
|
4
|
+
* target resolution or skip-link heuristics goes through `inspectSkipLinkScript`, so there is one
|
|
5
|
+
* copy of that logic and the tests exercise the code that ships.
|
|
5
6
|
*/
|
|
6
|
-
/**
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
*/
|
|
15
|
-
|
|
16
|
-
|
|
7
|
+
/** Where the focused element sits relative to a skip link and its target. */
|
|
8
|
+
export type SkipLinkFocusPosition =
|
|
9
|
+
/** Focus is on the target or inside it. */
|
|
10
|
+
"inside-target"
|
|
11
|
+
/** Focus is on content that follows the target in document order. */
|
|
12
|
+
| "after-target"
|
|
13
|
+
/** Focus is on content after the link, and the link has no target to compare against. */
|
|
14
|
+
| "after-link"
|
|
15
|
+
/** Focus is still on the skip link. */
|
|
16
|
+
| "skip-link"
|
|
17
|
+
/** Nothing is focused. */
|
|
18
|
+
| "body"
|
|
19
|
+
/** Focus is somewhere else, such as before the link or between the link and its target. */
|
|
20
|
+
| "elsewhere";
|
|
21
|
+
export type SkipLinkUnreachableReason = "not-rendered" | "visibility-hidden" | "inert" | "negative-tabindex";
|
|
22
|
+
export type SkipLinkTargetInspection = {
|
|
23
|
+
selector: string;
|
|
24
|
+
/** Opening tag of the target. */
|
|
25
|
+
html: string;
|
|
26
|
+
/** False when the target or an ancestor is `display: none` (or otherwise not rendered). */
|
|
27
|
+
rendered: boolean;
|
|
28
|
+
};
|
|
29
|
+
export type SkipLinkInspection = {
|
|
30
|
+
/** True when the inspected element is missing or is `<body>`. */
|
|
17
31
|
isBody: boolean;
|
|
32
|
+
/** Opening tag of the inspected element. */
|
|
18
33
|
html: string;
|
|
34
|
+
/** Visible text of the link, falling back to its `aria-label`. */
|
|
35
|
+
linkText: string;
|
|
19
36
|
/**
|
|
20
|
-
*
|
|
37
|
+
* The same-document fragment the link points at, such as "#main". Null when the element is not a
|
|
38
|
+
* link to a fragment of this document.
|
|
21
39
|
*/
|
|
22
40
|
fragment: string | null;
|
|
23
|
-
|
|
41
|
+
/** Whether the link looks like a skip link rather than a menu toggle or other in-page link. */
|
|
42
|
+
skipLike: boolean;
|
|
43
|
+
target: SkipLinkTargetInspection | null;
|
|
44
|
+
focus: {
|
|
45
|
+
position: SkipLinkFocusPosition;
|
|
46
|
+
/** Whether the document's URL fragment is the one the link points at. */
|
|
47
|
+
navigated: boolean;
|
|
48
|
+
};
|
|
49
|
+
};
|
|
50
|
+
export type SkipLinkUnreachableInspection = {
|
|
51
|
+
html: string;
|
|
52
|
+
linkText: string;
|
|
53
|
+
fragment: string;
|
|
54
|
+
reason: SkipLinkUnreachableReason;
|
|
55
|
+
};
|
|
56
|
+
export type SkipLinkInspectionResult = {
|
|
57
|
+
/** The inspected element. Null in "unreachable" mode. */
|
|
58
|
+
link: SkipLinkInspection | null;
|
|
59
|
+
/** Skip links that can never receive focus. Only filled in "unreachable" mode. */
|
|
60
|
+
unreachable: SkipLinkUnreachableInspection[];
|
|
24
61
|
};
|
|
62
|
+
/** Attribute that marks unreachable skip links so a handle can be taken to each one in turn. */
|
|
63
|
+
export declare const UNREACHABLE_MARKER = "data-a11y-pulse-unreachable-skip-link";
|
|
25
64
|
/**
|
|
26
|
-
*
|
|
27
|
-
*
|
|
65
|
+
* Inspect skip links in the page.
|
|
66
|
+
*
|
|
67
|
+
* - "classify": describe `el` and decide whether it is a skip link.
|
|
68
|
+
* - "focus": describe `el` and where keyboard focus is relative to it and its target.
|
|
69
|
+
* - "unreachable": ignore `el` and find skip links that can never receive keyboard focus, marking
|
|
70
|
+
* each with `data-a11y-pulse-unreachable-skip-link`.
|
|
28
71
|
*/
|
|
29
|
-
export declare function
|
|
72
|
+
export declare function inspectSkipLinkScript(el: Element | null, mode: "classify" | "focus" | "unreachable", limit?: number): SkipLinkInspectionResult;
|
|
30
73
|
/**
|
|
31
74
|
* Return the focused element, descending open shadow roots.
|
|
32
75
|
*/
|
|
33
76
|
export declare function activeElementHandleScript(): Element | null;
|
|
34
77
|
/**
|
|
35
|
-
*
|
|
78
|
+
* Return the next skip link marked by `inspectSkipLinkScript` in "unreachable" mode, removing its
|
|
79
|
+
* marker so the following call returns the one after it.
|
|
36
80
|
*/
|
|
37
|
-
export declare function
|
|
81
|
+
export declare function takeUnreachableSkipLinkScript(): Element | null;
|
|
82
|
+
export type SkipLinkPageState = {
|
|
83
|
+
href: string;
|
|
84
|
+
scrollX: number;
|
|
85
|
+
scrollY: number;
|
|
86
|
+
/** `history.length` before the link was activated, to tell whether following it added an entry. */
|
|
87
|
+
historyLength: number;
|
|
88
|
+
};
|
|
89
|
+
export declare function readPageStateScript(): SkipLinkPageState;
|
|
90
|
+
/**
|
|
91
|
+
* Put the URL, the `:target` element and the scroll position back the way they were before a skip
|
|
92
|
+
* link was activated, so whatever runs next sees the page as it was loaded.
|
|
93
|
+
*
|
|
94
|
+
* Following a fragment link adds a history entry, so the way back is to go back: that returns the
|
|
95
|
+
* document to the entry it was on, which also resets `:target` (rewriting the URL with
|
|
96
|
+
* `replaceState` does not). The entry that was added stays ahead in the history as a forward entry,
|
|
97
|
+
* because nothing can remove one. When the URL changed without a new entry, or by more than its
|
|
98
|
+
* fragment, the URL is rewritten in place instead and `:target` is left as it is.
|
|
99
|
+
*/
|
|
100
|
+
export declare function restorePageStateScript(state: SkipLinkPageState): Promise<void>;
|
|
38
101
|
export declare function focusScript(el: Element | null): void;
|
|
102
|
+
/**
|
|
103
|
+
* Drop focus and put the point sequential focus navigation starts from back at the top of the
|
|
104
|
+
* document, so the next Tab press reaches the first tab stop as it would on a freshly loaded page.
|
|
105
|
+
* Blurring alone leaves that point where focus last was: on a skip link's target, mid-page.
|
|
106
|
+
*
|
|
107
|
+
* The point is moved by focusing a throwaway node. On a page with a positive `tabindex` the node
|
|
108
|
+
* has to stay in front of the first element in the tab order until focus next moves, and removes
|
|
109
|
+
* itself then; otherwise it is taken straight out again and nothing is left behind.
|
|
110
|
+
*/
|
|
111
|
+
export declare function resetFocusScript(): Promise<void>;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
export type { SkipLinkAuditAdaptor } from "./adaptor";
|
|
2
2
|
export type { SkipLinkOptions } from "./audit";
|
|
3
3
|
export { runSkipLinkAudit } from "./audit";
|
|
4
|
-
export type { SkipLinkElementResult, SkipLinkFailureReason, SkipLinkResult, } from "./result";
|
|
4
|
+
export type { SkipLinkElementResult, SkipLinkFailureReason, SkipLinkFocusLanding, SkipLinkFocusPosition, SkipLinkResult, SkipLinkTarget, SkipLinkUnreachableReason, SkipLinkUnreachableResult, } from "./result";
|