@a11y-pulse/moving-content-audit 0.0.0-stage → 0.2.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 +221 -2
- package/dist/audit.d.ts +57 -0
- package/dist/browser-scripts.d.ts +113 -0
- package/dist/classify.d.ts +54 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +1076 -0
- package/dist/index.js.map +1 -0
- package/dist/result.d.ts +94 -0
- package/package.json +60 -5
package/LICENSE.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
Copyright (c) 2026-present, A11y Pulse (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
CHANGED
|
@@ -1,3 +1,222 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @a11y-pulse/moving-content-audit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@a11y-pulse/moving-content-audit)
|
|
4
|
+
[](https://github.com/A11y-Pulse/audits/actions/workflows/ci.yml)
|
|
5
|
+
[](./LICENSE.md)
|
|
6
|
+
|
|
7
|
+
An accessibility audit for [**WCAG 2.2: 2.2.2 Pause, Stop, Hide**](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide). Content that starts moving on its own, keeps moving for more than five seconds and sits beside other content needs a way to pause, stop or hide it. Carousels on a timer, news tickers and background videos are the usual offenders: they pull attention away from the rest of the page, and some people cannot read past them at all.
|
|
8
|
+
|
|
9
|
+
Static analysis cannot see movement. This audit loads nothing and presses nothing: it watches the page for five seconds, works out which regions are still moving at the end, and looks for a control that pauses them.
|
|
10
|
+
|
|
11
|
+
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).
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @a11y-pulse/moving-content-audit @a11y-pulse/browser-adaptor puppeteer
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quickstart
|
|
20
|
+
|
|
21
|
+
```js
|
|
22
|
+
import { runMovingContentAudit } from "@a11y-pulse/moving-content-audit";
|
|
23
|
+
import { PuppeteerAdaptor } from "@a11y-pulse/browser-adaptor/puppeteer";
|
|
24
|
+
import puppeteer from "puppeteer";
|
|
25
|
+
|
|
26
|
+
const browser = await puppeteer.launch();
|
|
27
|
+
const page = await browser.newPage();
|
|
28
|
+
await page.goto("https://who.likesdogs.nz/");
|
|
29
|
+
|
|
30
|
+
const result = await runMovingContentAudit(new PuppeteerAdaptor(page));
|
|
31
|
+
|
|
32
|
+
console.log(result.summary);
|
|
33
|
+
// { checked: 2, failed: 1, needsReview: 0, passed: 1, unchecked: 0,
|
|
34
|
+
// ignored: { essential: 1, tooSmall: 0 } }
|
|
35
|
+
|
|
36
|
+
console.log(result.failed);
|
|
37
|
+
// [
|
|
38
|
+
// {
|
|
39
|
+
// selector: "#offers",
|
|
40
|
+
// html: '<div class="carousel__viewport" id="offers">',
|
|
41
|
+
// rect: { x: 20, y: 132, width: 760, height: 280 },
|
|
42
|
+
// motion: "script",
|
|
43
|
+
// detectedBy: "dom-observation",
|
|
44
|
+
// finding: "no-pause-control",
|
|
45
|
+
// observedMs: 4900,
|
|
46
|
+
// animations: [],
|
|
47
|
+
// pauseControl: null,
|
|
48
|
+
// pausesOn: [],
|
|
49
|
+
// reducedMotion: null,
|
|
50
|
+
// screenshot: Uint8Array(…),
|
|
51
|
+
// laterScreenshot: Uint8Array(…)
|
|
52
|
+
// }
|
|
53
|
+
// ]
|
|
54
|
+
|
|
55
|
+
await browser.close();
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The audit takes at least as long as its observation window: five seconds by default, plus up to about a second and a half for screenshots when something is reported. Run it on a page nothing else is driving, since focus changes, key presses and scrolling by another audit would be seen as movement.
|
|
59
|
+
|
|
60
|
+
## How it decides
|
|
61
|
+
|
|
62
|
+
### What counts as moving
|
|
63
|
+
|
|
64
|
+
| Movement | How it is found | `motion` / `detectedBy` |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| A CSS animation that is endless, or runs for more than five seconds in total, and changes at least one property | `document.getAnimations()` at the end of the window | `css-animation` / `animation-api` |
|
|
67
|
+
| The same, started by a script with `element.animate()` | `document.getAnimations()` | `web-animation` / `animation-api` |
|
|
68
|
+
| A carousel, ticker or slideshow driven by a script | Elements a script touches during the window (their style, class or SVG geometry attributes, their children, their scroll offset) are sampled about fifty times; a region counts when its position, size, opacity, visibility, transform, scroll offset or image keeps changing, or short animations keep starting on it | `script` / `dom-observation` |
|
|
69
|
+
| `<marquee>` | The element itself | `marquee` / `element` |
|
|
70
|
+
| A `<video>` that is playing | Its playback state at the start and end of the window | `video` / `media-element` |
|
|
71
|
+
|
|
72
|
+
Script-driven movement has to be sustained and still going in the last two fifths of the window. Changes are grouped into bursts, a burst ending when the region holds still for a tenth of the window. Sustained means the movement came back after a pause (a carousel turning at least twice) or ran on without one for two fifths of the window (a ticker a script moves every frame). One burst late in the window, such as one turn of a slow carousel, is reported for review as `changed-once`.
|
|
73
|
+
|
|
74
|
+
Content arriving is not movement. The changes that bring an element into view (a consent bar sliding up, a slide fading in, a slot being filled) are left out, and a region whose moving elements all arrived during the window has to change more than once after that to be reported. So a region that settles early or arrives once (an entrance effect, a lazy-loaded banner, a notice that appears, an ad slot filled and then resized to its creative) is not reported. Animations that end within five seconds are allowed by the criterion and never reported, however short the observation window is.
|
|
75
|
+
|
|
76
|
+
At most 150 touched elements are watched at a time. Ones that were touched without changing, or that changed and have been still since, make room for new ones, so a burst of one-off changes while the page loads does not hide a carousel that starts later.
|
|
77
|
+
|
|
78
|
+
Moving elements are gathered into regions. A track sliding inside a smaller `overflow: hidden` box is reported as that box, an element moving inside another moving element is part of it, and slides stacked on top of each other are joined under their common parent. A region's `rect` is the part of it that can be seen.
|
|
79
|
+
|
|
80
|
+
### What is left alone
|
|
81
|
+
|
|
82
|
+
- **Loading and status indicators**: anything inside `role="progressbar"`, `status`, `alert`, `timer` or `log`, inside `aria-busy="true"`, a `<progress>` or `<meter>`, or with a class or id of `spinner`, `loader`, `loading`, `skeleton`, `shimmer` or `progress`. These are counted in `summary.ignored.essential`.
|
|
83
|
+
- **Small regions**: under `minRegionArea` (5000 CSS px², about 70 × 70). Counted in `summary.ignored.tooSmall`. An animated pseudo-element is measured by its own `width` and `height` where they can be read, so a ten-pixel "live" dot in the corner of a card is small however large the card is.
|
|
84
|
+
- **What nobody can see**: an element that is `visibility: hidden`, fully transparent (itself or through an ancestor), outside the page, or fixed outside the viewport, and that was not seen showing at any point in the window. A hidden preloader whose animation never stops is not reported; a slide that had just faded out when the window closed still counts.
|
|
85
|
+
- **Text updates**: a clock, counter or score changing its text is updating, not moving.
|
|
86
|
+
|
|
87
|
+
### Looking for a way to pause
|
|
88
|
+
|
|
89
|
+
For each moving region the audit looks for, in order:
|
|
90
|
+
|
|
91
|
+
1. A button, switch, checkbox or `<summary>` (an element with `role="button"` counts, a plain link does not) inside the region, or inside up to three ancestors that are no more than six times its size, or pointing at it with `aria-controls`, whose label says pause, stop, hide, close or dismiss (English plus Spanish, German, French, Dutch, Italian and Swedish words; see `controlNamePattern`). "Play" counts as the whole label, paired with pause ("Play/Pause"), or followed by what is moving ("Play slideshow"); "Play trailer" does not. Labels over 40 characters are ignored, so a slide headline such as "Stop wasting money on tents" is not taken for a control.
|
|
92
|
+
2. The same kind of control with no label but a class or id of `pause`, `play-pause` or `stop`. The missing label is another audit's finding.
|
|
93
|
+
3. A control or link anywhere on the page that turns animation off ("Pause animations", "Reduce motion").
|
|
94
|
+
4. For a video, the browser's own `controls`.
|
|
95
|
+
|
|
96
|
+
The audit does not press the control, so it does not check that it works.
|
|
97
|
+
|
|
98
|
+
### Verdicts
|
|
99
|
+
|
|
100
|
+
| List | `finding` | When |
|
|
101
|
+
| --- | --- | --- |
|
|
102
|
+
| `failed` | `no-pause-control` | A region of at least `largeRegionArea` (20000 CSS px², for example a 760 × 48 ticker) kept moving past the window and nothing above was found |
|
|
103
|
+
| `passed` | `pause-control` | A pause control was found |
|
|
104
|
+
| `passed` | `native-controls` | A playing video has `controls` |
|
|
105
|
+
| `needsReview` | `pauses-on-hover` | A stylesheet rule pauses the CSS animation on `:hover`. A keyboard user cannot hover |
|
|
106
|
+
| `needsReview` | `pauses-on-focus` | A stylesheet rule pauses the CSS animation on `:focus` or `:focus-within` |
|
|
107
|
+
| `needsReview` | `small-region` | The region is under `largeRegionArea` and may be decoration |
|
|
108
|
+
| `needsReview` | `subtle-animation` | The animation changes only colour, shadow or filter |
|
|
109
|
+
| `needsReview` | `changed-once` | The region changed in one burst late in the window, such as one slide of a carousel on a four-second timer |
|
|
110
|
+
| `needsReview` | `pseudo-element` | Only a pseudo-element is animated and its size could not be read (an inline `::after` cursor, for example). A pseudo-element of at least `largeRegionArea` is treated as the region itself |
|
|
111
|
+
| `needsReview` | `finite-loop` | A `<marquee>` with a `loop` count |
|
|
112
|
+
| `needsReview` | `uncertain-playback` | A video that started during the window, or whose length is unknown |
|
|
113
|
+
|
|
114
|
+
`reducedMotion` records whether a `prefers-reduced-motion` rule applies to the region's CSS animation. It is supporting evidence and never changes the verdict: the criterion asks for a mechanism on the page.
|
|
115
|
+
|
|
116
|
+
## Browser support
|
|
117
|
+
|
|
118
|
+
The audit uses `document.getAnimations()`, `MutationObserver` and `Element.checkVisibility()`, all available in current Chromium, Firefox and WebKit. Its integration suite runs on every engine the repository's CI covers; at the time of writing it has been run against Chromium through Puppeteer and Playwright. How `<marquee>` and stream-backed videos report themselves varies between engines, so treat Firefox and WebKit results for those two as less certain.
|
|
119
|
+
|
|
120
|
+
The adaptor must provide `evaluate`, `evaluateHandle`, `disposeRef` and `screenshotClip`. The bundled `PuppeteerAdaptor` and `PlaywrightAdaptor` do.
|
|
121
|
+
|
|
122
|
+
## Options
|
|
123
|
+
|
|
124
|
+
| Option | Default | Description |
|
|
125
|
+
| --- | --- | --- |
|
|
126
|
+
| `observationWindow` | `5000` | How long to watch the page, in ms. Content still moving at the end is reported. Five seconds is the limit in the criterion; a shorter window makes script-driven findings less certain, a longer one catches slower carousels. |
|
|
127
|
+
| `minRegionArea` | `5000` | Smallest visible area, in CSS px², of a moving region worth reporting. |
|
|
128
|
+
| `largeRegionArea` | `20000` | Smallest visible area, in CSS px², of a region that can fail. Smaller regions are reported for review. |
|
|
129
|
+
| `regionLimit` | `20` | Max moving regions to examine, largest first. |
|
|
130
|
+
| `controlNamePattern` | see `DEFAULT_CONTROL_NAME_PATTERN` | Regular expression source, matched case-insensitively (with the `u` flag) against the label of controls near a moving region. |
|
|
131
|
+
| `screenshotLimit` | `5` | Max failed and needs-review regions to screenshot, failed first. `0` takes none. |
|
|
132
|
+
| `screenshotInterval` | `1000` | Time between a region's two screenshots, in ms. |
|
|
133
|
+
|
|
134
|
+
## Result shape
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
type MovingContentRegion = {
|
|
138
|
+
/** Selector for the moving region. */
|
|
139
|
+
selector: string;
|
|
140
|
+
/** Truncated opening tag. */
|
|
141
|
+
html: string;
|
|
142
|
+
/** The visible part of the region, in document coordinates. */
|
|
143
|
+
rect: { x: number; y: number; width: number; height: number };
|
|
144
|
+
motion: "video" | "marquee" | "css-animation" | "web-animation" | "script";
|
|
145
|
+
detectedBy: "media-element" | "element" | "animation-api" | "dom-observation";
|
|
146
|
+
/** Why the region is in the list it is in. See the verdicts table. */
|
|
147
|
+
finding: MovingContentFinding;
|
|
148
|
+
/** How long into the observation window the region was last seen moving. */
|
|
149
|
+
observedMs: number;
|
|
150
|
+
/** The long-running animations on the region. */
|
|
151
|
+
animations: {
|
|
152
|
+
name: string | null;
|
|
153
|
+
infinite: boolean;
|
|
154
|
+
activeDurationMs: number | null;
|
|
155
|
+
/** The CSS properties whose value changes over the animation. */
|
|
156
|
+
properties: string[];
|
|
157
|
+
/** The pseudo-element the animation runs on, such as "::after", or null. */
|
|
158
|
+
pseudoElement: string | null;
|
|
159
|
+
}[];
|
|
160
|
+
pauseControl: {
|
|
161
|
+
selector: string;
|
|
162
|
+
html: string;
|
|
163
|
+
name: string;
|
|
164
|
+
foundBy: "name" | "attribute" | "page-control";
|
|
165
|
+
} | null;
|
|
166
|
+
/** States in which a stylesheet rule pauses the region's CSS animation. */
|
|
167
|
+
pausesOn: ("hover" | "focus")[];
|
|
168
|
+
/** Whether a prefers-reduced-motion rule applies. Null when it is not a CSS animation. */
|
|
169
|
+
reducedMotion: boolean | null;
|
|
170
|
+
/** PNG bytes of the region at the end of the window, for failed and needs-review regions. */
|
|
171
|
+
screenshot?: Uint8Array;
|
|
172
|
+
/** PNG bytes of the region `screenshotInterval` later. */
|
|
173
|
+
laterScreenshot?: Uint8Array;
|
|
174
|
+
};
|
|
175
|
+
|
|
176
|
+
type MovingContentResult = {
|
|
177
|
+
failed: MovingContentRegion[];
|
|
178
|
+
needsReview: MovingContentRegion[];
|
|
179
|
+
passed: MovingContentRegion[];
|
|
180
|
+
/** How long the page was observed for. */
|
|
181
|
+
observedMs: number;
|
|
182
|
+
summary: {
|
|
183
|
+
checked: number;
|
|
184
|
+
failed: number;
|
|
185
|
+
needsReview: number;
|
|
186
|
+
passed: number;
|
|
187
|
+
/** Moving regions past `regionLimit`. */
|
|
188
|
+
unchecked: number;
|
|
189
|
+
ignored: { essential: number; tooSmall: number };
|
|
190
|
+
};
|
|
191
|
+
};
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The two screenshots are evidence for a person, and the audit does not compare them: a carousel can look the same in both if they fall between slides. Each region is scrolled into view for its captures and the page is scrolled back afterwards. The audit removes its observers and everything it left on `window` before it returns.
|
|
195
|
+
|
|
196
|
+
## Limitations
|
|
197
|
+
|
|
198
|
+
- **Slow carousels.** A carousel that advances less often than about every two and a half seconds changes once in the window and is reported for review; one on a timer longer than the window is not seen at all. Raise `observationWindow` to catch them.
|
|
199
|
+
- **Content that arrives and then moves slowly.** A carousel that is itself inserted during the window has its first changes read as its entrance, so it needs two further turns in the window to be reported.
|
|
200
|
+
- **Canvas, WebGL and animated images.** Movement drawn inside a `<canvas>`, an animated GIF, APNG or WebP, and an animated SVG using SMIL are not detected.
|
|
201
|
+
- **Only what a script touches is watched.** Script-driven movement is found through changes to `style`, `class`, `hidden`, `src`, `open` and SVG geometry attributes (`transform`, `d`, `points`, `x`, `y`, `cx`, `cy`, `r`, `width`, `height`, `viewBox` and the like), child changes and scroll events. Movement driven through any other attribute or through a CSS custom property set on a distant ancestor is not seen. Movement inside closed shadow roots, cross-origin iframes, or shadow roots attached after the audit starts is not seen.
|
|
202
|
+
- **Auto-updating content.** The second half of the criterion, content that updates on its own such as a live score, is out of scope.
|
|
203
|
+
- **The control is not operated.** A button labelled "Pause" that does nothing passes. So does a region whose only nearby match is an unrelated "Close" button. A pause control that is a plain link (`<a href="#">Pause</a>` with no `role="button"`) is not recognised.
|
|
204
|
+
- **Hover and focus pausing is read from stylesheets only.** A script that pauses a carousel on `mouseenter` or `focusin` is not recognised, and cross-origin stylesheets cannot be read.
|
|
205
|
+
- **Listed languages only.** A pause control labelled in another language is not recognised unless `controlNamePattern` covers it.
|
|
206
|
+
- **Parallax and scroll-linked effects** do not start on their own and are not reported, since nothing scrolls during the window.
|
|
207
|
+
|
|
208
|
+
## Known false positives
|
|
209
|
+
|
|
210
|
+
- **Decorative background animation.** A large hero with a slowly drifting gradient or floating shapes fails when it moves, resizes or fades. Whether that is "presented in parallel with other content" in a way that matters is a judgement call; a page-wide "Pause animations" control passes it.
|
|
211
|
+
- **Large loading placeholders with no semantics.** A skeleton screen that never resolves and has no `aria-busy`, status role or recognisable class is reported.
|
|
212
|
+
- **Live video feeds.** A webcam or stream preview with custom controls labelled in an unlisted language fails.
|
|
213
|
+
|
|
214
|
+
## License
|
|
215
|
+
|
|
216
|
+
Released under the [PolyForm Shield License 1.0.0](./LICENSE.md), in plain language:
|
|
217
|
+
|
|
218
|
+
- **Source-available.** The source is public and you can read, fork, and modify it.
|
|
219
|
+
- **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.
|
|
220
|
+
- **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.
|
|
221
|
+
|
|
222
|
+
See [LICENSE.md](./LICENSE.md) for the full, binding terms.
|
package/dist/audit.d.ts
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { type BrowserAdaptor } from "@a11y-pulse/browser-adaptor";
|
|
2
|
+
import type { MovingContentResult } from "./result";
|
|
3
|
+
/** WCAG 2.2.2 allows movement that stops within five seconds. */
|
|
4
|
+
export declare const DURATION_LIMIT_MS = 5000;
|
|
5
|
+
export declare const DEFAULT_OBSERVATION_WINDOW = 5000;
|
|
6
|
+
export declare const DEFAULT_MIN_REGION_AREA = 5000;
|
|
7
|
+
export declare const DEFAULT_LARGE_REGION_AREA = 20000;
|
|
8
|
+
export declare const DEFAULT_REGION_LIMIT = 20;
|
|
9
|
+
export declare const DEFAULT_SCREENSHOT_LIMIT = 5;
|
|
10
|
+
export declare const DEFAULT_SCREENSHOT_INTERVAL = 1000;
|
|
11
|
+
/**
|
|
12
|
+
* Labels of a control that pauses, stops or hides moving content. "Play" only counts as the whole
|
|
13
|
+
* label, paired with "pause", or followed by what is moving ("Play slideshow"): "Play trailer"
|
|
14
|
+
* starts something else.
|
|
15
|
+
*/
|
|
16
|
+
export declare const DEFAULT_CONTROL_NAME_PATTERN = "(^|[^\\p{L}])(pause|paused|unpause|stop|halt|freeze|hide|close|dismiss|pausar|pausa|detener|parar|pausieren|anhalten|stopp|stoppen|arr\u00EAter|pauzeren|fermare|pausera|stoppa|play\\s*(/|\\||&|and|or)\\s*pause|play(ing)?\\s+(the\\s+)?(slideshow|slide\\s?show|slides|carousel|animations?|rotation|ticker|marquee|background\\s+video))($|[^\\p{L}])|^\\s*(play|playing)\\s*$";
|
|
17
|
+
export type MovingContentOptions = {
|
|
18
|
+
/**
|
|
19
|
+
* How long to watch the page for, in ms. Content still moving at the end is reported. Defaults
|
|
20
|
+
* to 5000, the limit in WCAG 2.2.2; the audit takes at least this long.
|
|
21
|
+
*/
|
|
22
|
+
observationWindow?: number;
|
|
23
|
+
/** Smallest visible area, in CSS px², of a moving region worth reporting. Defaults to 5000. */
|
|
24
|
+
minRegionArea?: number;
|
|
25
|
+
/**
|
|
26
|
+
* Smallest visible area, in CSS px², of a region that can fail. Smaller regions are reported
|
|
27
|
+
* for review. Defaults to 20000.
|
|
28
|
+
*/
|
|
29
|
+
largeRegionArea?: number;
|
|
30
|
+
/** Max moving regions to examine, largest first. Defaults to 20. */
|
|
31
|
+
regionLimit?: number;
|
|
32
|
+
/**
|
|
33
|
+
* Regular expression source, matched case-insensitively against the label of controls near a
|
|
34
|
+
* moving region to find one that pauses, stops or hides it.
|
|
35
|
+
*/
|
|
36
|
+
controlNamePattern?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Max failed and needs-review regions to screenshot, failed first. Each gets two captures,
|
|
39
|
+
* `screenshotInterval` apart. Defaults to 5; 0 takes none.
|
|
40
|
+
*/
|
|
41
|
+
screenshotLimit?: number;
|
|
42
|
+
/** Time between a region's two screenshots, in ms. Defaults to 1000. */
|
|
43
|
+
screenshotInterval?: number;
|
|
44
|
+
};
|
|
45
|
+
/** How often, in ms, the page is sampled over an observation window of `observationWindow` ms. */
|
|
46
|
+
export declare function pollInterval(observationWindow: number): number;
|
|
47
|
+
/**
|
|
48
|
+
* How long, in ms, an element has to hold still for its next change to count as a separate burst
|
|
49
|
+
* of movement.
|
|
50
|
+
*/
|
|
51
|
+
export declare function quietGap(observationWindow: number): number;
|
|
52
|
+
/**
|
|
53
|
+
* Watch the page for content that keeps moving on its own and look for a way to pause it. Nothing
|
|
54
|
+
* is pressed or hovered, and the page is left as it was found. Takes `observationWindow` ms, 5
|
|
55
|
+
* seconds by default, plus the time for screenshots.
|
|
56
|
+
*/
|
|
57
|
+
export declare function runMovingContentAudit(adaptor: BrowserAdaptor, options?: MovingContentOptions): Promise<MovingContentResult>;
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IMPORTANT: The `*Script` functions in this file are serialized and injected into the audited
|
|
3
|
+
* page, so they must not reference any symbols outside their own scope.
|
|
4
|
+
*/
|
|
5
|
+
import type { Rect } from "@a11y-pulse/browser-adaptor";
|
|
6
|
+
export type CollectedAnimation = {
|
|
7
|
+
name: string | null;
|
|
8
|
+
/** A CSS animation, as opposed to one a script started through the Web Animations API. */
|
|
9
|
+
css: boolean;
|
|
10
|
+
infinite: boolean;
|
|
11
|
+
activeDurationMs: number | null;
|
|
12
|
+
/** Properties whose value changes over the animation. Empty when they could not be read. */
|
|
13
|
+
properties: string[];
|
|
14
|
+
/** The pseudo-element the animation runs on, such as `::after`. Null for the element itself. */
|
|
15
|
+
pseudoElement: string | null;
|
|
16
|
+
/** The pseudo-element's own area in CSS px², or null when its size could not be read. */
|
|
17
|
+
pseudoArea: number | null;
|
|
18
|
+
};
|
|
19
|
+
export type CollectedVideo = {
|
|
20
|
+
controls: boolean;
|
|
21
|
+
/** The video loops, or is a live stream with no end. */
|
|
22
|
+
endless: boolean;
|
|
23
|
+
/** Null for a live stream or a video whose length is not known yet. */
|
|
24
|
+
durationS: number | null;
|
|
25
|
+
/** The video was already playing when observation started. */
|
|
26
|
+
playingAtStart: boolean;
|
|
27
|
+
/** Its playback position moved during observation. */
|
|
28
|
+
advanced: boolean;
|
|
29
|
+
};
|
|
30
|
+
export type CollectedControl = {
|
|
31
|
+
/** Index of the control in the stash. */
|
|
32
|
+
elementIndex: number;
|
|
33
|
+
html: string;
|
|
34
|
+
name: string;
|
|
35
|
+
foundBy: "name" | "attribute" | "page-control";
|
|
36
|
+
};
|
|
37
|
+
export type CollectedRegion = {
|
|
38
|
+
/** Index of the region's element in the stash. */
|
|
39
|
+
elementIndex: number;
|
|
40
|
+
/** Shallow outerHTML. */
|
|
41
|
+
html: string;
|
|
42
|
+
/** The visible part of the region, in document coordinates. */
|
|
43
|
+
rect: Rect;
|
|
44
|
+
/**
|
|
45
|
+
* When, in ms since observation started, an element in the region was seen to change position,
|
|
46
|
+
* size, visibility or scroll offset, or a short animation was seen to start on it. The changes
|
|
47
|
+
* that first brought an element into view are left out.
|
|
48
|
+
*/
|
|
49
|
+
times: number[];
|
|
50
|
+
/** Every element seen changing only came into view, or was only inserted, during the watch. */
|
|
51
|
+
appeared: boolean;
|
|
52
|
+
/** Animations still running that last longer than the limit. */
|
|
53
|
+
animations: CollectedAnimation[];
|
|
54
|
+
/** Set for a `<marquee>`: its `loop` count, -1 for endless. */
|
|
55
|
+
marquee: {
|
|
56
|
+
loop: number;
|
|
57
|
+
} | null;
|
|
58
|
+
video: CollectedVideo | null;
|
|
59
|
+
control: CollectedControl | null;
|
|
60
|
+
pausesOn: ("hover" | "focus")[];
|
|
61
|
+
reducedMotion: boolean | null;
|
|
62
|
+
};
|
|
63
|
+
export type RegionCollection = {
|
|
64
|
+
/** How long the page was observed for. */
|
|
65
|
+
elapsedMs: number;
|
|
66
|
+
regions: CollectedRegion[];
|
|
67
|
+
/** Every moving region, including those past the region limit. */
|
|
68
|
+
total: number;
|
|
69
|
+
/** Moving regions under the size threshold. */
|
|
70
|
+
tooSmall: number;
|
|
71
|
+
/** Moving progress indicators, status messages and busy regions. */
|
|
72
|
+
essential: number;
|
|
73
|
+
};
|
|
74
|
+
export type CollectOptions = {
|
|
75
|
+
/** Animations no longer than this are allowed to run to their end. */
|
|
76
|
+
durationLimitMs: number;
|
|
77
|
+
minRegionArea: number;
|
|
78
|
+
regionLimit: number;
|
|
79
|
+
/** Regular expression source matched against a nearby control's label. */
|
|
80
|
+
controlNamePattern: string;
|
|
81
|
+
/** Regular expression source matched against an unlabelled nearby control's class and id. */
|
|
82
|
+
controlAttributePattern: string;
|
|
83
|
+
/** Regular expression source matched against the label of any control on the page. */
|
|
84
|
+
pageControlPattern: string;
|
|
85
|
+
/** Regular expression source matched against the class and id of loading indicators. */
|
|
86
|
+
essentialPattern: string;
|
|
87
|
+
};
|
|
88
|
+
/**
|
|
89
|
+
* Start watching the page for movement nothing asked for. Records, on `window[stateKey]`, when
|
|
90
|
+
* elements a script touches change position, size, visibility or scroll offset, and when short
|
|
91
|
+
* animations start. Changes that bring an element into view (a banner sliding in, a slot being
|
|
92
|
+
* filled) are its entrance, not movement, and are left out: a run of changes ends once
|
|
93
|
+
* `quietGapMs` passes without one. collectRegionsScript reads the record and stops the watch.
|
|
94
|
+
*/
|
|
95
|
+
export declare function startObservationScript(stateKey: string, pollMs: number, durationLimitMs: number, trackLimit: number, quietGapMs: number): void;
|
|
96
|
+
/**
|
|
97
|
+
* Stop the watch started by startObservationScript, if it is still running.
|
|
98
|
+
*/
|
|
99
|
+
export declare function stopObservationScript(stateKey: string): void;
|
|
100
|
+
/**
|
|
101
|
+
* Stop the watch started by startObservationScript and gather what moved into regions, each with
|
|
102
|
+
* the facts needed to judge it. The region elements and any pause controls found are left on
|
|
103
|
+
* `window[stashKey]`.
|
|
104
|
+
*/
|
|
105
|
+
export declare function collectRegionsScript(stateKey: string, stashKey: string, options: CollectOptions): RegionCollection;
|
|
106
|
+
export declare function scrollPositionScript(): {
|
|
107
|
+
x: number;
|
|
108
|
+
y: number;
|
|
109
|
+
};
|
|
110
|
+
export declare function restoreScrollScript(position: {
|
|
111
|
+
x: number;
|
|
112
|
+
y: number;
|
|
113
|
+
}): void;
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { CollectedRegion } from "./browser-scripts";
|
|
2
|
+
export type MotionKind = "video" | "marquee" | "css-animation" | "web-animation" | "script";
|
|
3
|
+
export type DetectedBy = "media-element" | "element" | "animation-api" | "dom-observation";
|
|
4
|
+
export type MovingContentFinding =
|
|
5
|
+
/** Failed: a large region kept moving and nothing pauses it. */
|
|
6
|
+
"no-pause-control"
|
|
7
|
+
/** Passed: a control that pauses, stops or hides the movement was found. */
|
|
8
|
+
| "pause-control"
|
|
9
|
+
/** Passed: the video has the browser's own controls. */
|
|
10
|
+
| "native-controls"
|
|
11
|
+
/** Review: the movement only pauses while hovered, which a keyboard user cannot do. */
|
|
12
|
+
| "pauses-on-hover"
|
|
13
|
+
/** Review: the movement pauses while focus is inside it. */
|
|
14
|
+
| "pauses-on-focus"
|
|
15
|
+
/** Review: the region is small enough that it may be decoration. */
|
|
16
|
+
| "small-region"
|
|
17
|
+
/** Review: the animation changes colour or shading, not position, size or visibility. */
|
|
18
|
+
| "subtle-animation"
|
|
19
|
+
/** Review: the region changed late in the window but was not seen to keep changing. */
|
|
20
|
+
| "changed-once"
|
|
21
|
+
/** Review: only a pseudo-element is animated, and its size could not be read. */
|
|
22
|
+
| "pseudo-element"
|
|
23
|
+
/** Review: the `<marquee>` stops by itself after a set number of loops. */
|
|
24
|
+
| "finite-loop"
|
|
25
|
+
/** Review: the video started during the window, or its length is unknown. */
|
|
26
|
+
| "uncertain-playback";
|
|
27
|
+
export type Verdict = "failed" | "needsReview" | "passed";
|
|
28
|
+
export type Classification = {
|
|
29
|
+
verdict: Verdict;
|
|
30
|
+
finding: MovingContentFinding;
|
|
31
|
+
motion: MotionKind;
|
|
32
|
+
detectedBy: DetectedBy;
|
|
33
|
+
observedMs: number;
|
|
34
|
+
};
|
|
35
|
+
export type ClassifyOptions = {
|
|
36
|
+
/** How long the page was observed for. */
|
|
37
|
+
observedMs: number;
|
|
38
|
+
/** WCAG's limit: movement that stops within this long is allowed. */
|
|
39
|
+
durationLimitMs: number;
|
|
40
|
+
/** Regions at least this large can fail. */
|
|
41
|
+
largeRegionArea: number;
|
|
42
|
+
/**
|
|
43
|
+
* Changes further apart than this belong to separate bursts of movement. Defaults to a tenth of
|
|
44
|
+
* the window.
|
|
45
|
+
*/
|
|
46
|
+
quietGapMs?: number;
|
|
47
|
+
};
|
|
48
|
+
/** The quiet gap used when none is given, as a fraction of the observation window. */
|
|
49
|
+
export declare const QUIET_GAP_FRACTION = 0.1;
|
|
50
|
+
/**
|
|
51
|
+
* Decide which list a moving region belongs in, or return null when the page facts do not show it
|
|
52
|
+
* moving past the observation window.
|
|
53
|
+
*/
|
|
54
|
+
export declare function classifyRegion(region: CollectedRegion, options: ClassifyOptions): Classification | null;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export type { BrowserAdaptor, ElementRef, Rect } from "@a11y-pulse/browser-adaptor";
|
|
2
|
+
export type { MovingContentOptions } from "./audit";
|
|
3
|
+
export { DEFAULT_CONTROL_NAME_PATTERN, DEFAULT_LARGE_REGION_AREA, DEFAULT_MIN_REGION_AREA, DEFAULT_OBSERVATION_WINDOW, DEFAULT_REGION_LIMIT, DEFAULT_SCREENSHOT_INTERVAL, DEFAULT_SCREENSHOT_LIMIT, DURATION_LIMIT_MS, runMovingContentAudit, } from "./audit";
|
|
4
|
+
export type { DetectedBy, MotionKind, MovingContentFinding } from "./classify";
|
|
5
|
+
export type { MovingContentAnimation, MovingContentPauseControl, MovingContentRegion, MovingContentResult, } from "./result";
|