@barqjs/aria 0.0.0-stage → 0.2.0-next.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 +21 -0
- package/README.md +293 -2
- package/package.json +347 -4
- package/src/breadcrumbs.tsx +296 -0
- package/src/button.tsx +342 -0
- package/src/calendar.tsx +1389 -0
- package/src/checkbox.tsx +570 -0
- package/src/collections.ts +976 -0
- package/src/color.ts +562 -0
- package/src/colorpicker.tsx +1478 -0
- package/src/combobox.tsx +2481 -0
- package/src/command.tsx +1184 -0
- package/src/date.ts +652 -0
- package/src/datefield.tsx +951 -0
- package/src/datepicker.tsx +556 -0
- package/src/dialog.tsx +890 -0
- package/src/disclosure.tsx +659 -0
- package/src/dom.ts +706 -0
- package/src/drawer.ts +674 -0
- package/src/focus.ts +1370 -0
- package/src/form.tsx +94 -0
- package/src/gridlist.tsx +563 -0
- package/src/i18n.ts +823 -0
- package/src/index.ts +1270 -0
- package/src/interactions/description.ts +73 -0
- package/src/interactions/flags.ts +35 -0
- package/src/interactions/focus-events.ts +218 -0
- package/src/interactions/focusable.ts +86 -0
- package/src/interactions/hover.ts +213 -0
- package/src/interactions/interact-outside.ts +123 -0
- package/src/interactions/keyboard.ts +105 -0
- package/src/interactions/listeners.ts +78 -0
- package/src/interactions/long-press.ts +160 -0
- package/src/interactions/modality.ts +416 -0
- package/src/interactions/move.ts +257 -0
- package/src/interactions/open-link.ts +193 -0
- package/src/interactions/press.ts +898 -0
- package/src/interactions/prevent-focus.ts +102 -0
- package/src/interactions/scroll-wheel.ts +43 -0
- package/src/interactions/text-selection.ts +77 -0
- package/src/interactions.ts +81 -0
- package/src/label.ts +128 -0
- package/src/link.tsx +381 -0
- package/src/listbox.tsx +721 -0
- package/src/live.ts +204 -0
- package/src/menu.tsx +2290 -0
- package/src/menubar.tsx +575 -0
- package/src/navigation.ts +735 -0
- package/src/numberfield.tsx +838 -0
- package/src/otp.ts +430 -0
- package/src/overlays.ts +1247 -0
- package/src/platform.ts +74 -0
- package/src/presence.ts +164 -0
- package/src/questionnaire.tsx +1712 -0
- package/src/radio.tsx +567 -0
- package/src/register-dom.ts +12 -0
- package/src/scroller.ts +1165 -0
- package/src/select.tsx +1665 -0
- package/src/selection.ts +1415 -0
- package/src/slider.tsx +1042 -0
- package/src/splitter.ts +1152 -0
- package/src/static-collection.ts +211 -0
- package/src/switch.tsx +186 -0
- package/src/table.tsx +0 -0
- package/src/tabs.tsx +1018 -0
- package/src/tag.tsx +452 -0
- package/src/textfield.tsx +417 -0
- package/src/toast.ts +658 -0
- package/src/toggle-input.tsx +48 -0
- package/src/toggle.ts +321 -0
- package/src/togglegroup.ts +365 -0
- package/src/toolbar.tsx +179 -0
- package/src/tooltip.tsx +657 -0
- package/src/utils.ts +758 -0
- package/src/validation.ts +447 -0
- package/src/virtualizer.tsx +674 -0
package/src/live.ts
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Telling a screen reader something that is not in the document.
|
|
3
|
+
*
|
|
4
|
+
* "3 results", "Copied", "Removed from cart": a change a sighted user sees in
|
|
5
|
+
* a corner of the screen and a screen reader user learns nothing about unless
|
|
6
|
+
* it is announced. A live region is the mechanism, and it has to exist before
|
|
7
|
+
* the text lands in it — a region added and filled in the same task is read by
|
|
8
|
+
* nothing, because the announcement is diffed against what was there when the
|
|
9
|
+
* region was first observed.
|
|
10
|
+
*
|
|
11
|
+
* One pair of regions for the page, created on the first announcement and
|
|
12
|
+
* reused. Two, not one: `assertive` interrupts what the user is listening to
|
|
13
|
+
* and `polite` waits, and a widget that gets that choice wrong is either
|
|
14
|
+
* ignored or infuriating.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { focusWithin } from "./interactions/focus-events.ts";
|
|
18
|
+
|
|
19
|
+
export type Assertiveness = "assertive" | "polite";
|
|
20
|
+
|
|
21
|
+
/** Text, or a reference to an element that already holds the text. */
|
|
22
|
+
export type Announcement = string | { "aria-labelledby": string };
|
|
23
|
+
|
|
24
|
+
const DEFAULT_TIMEOUT = 7000;
|
|
25
|
+
|
|
26
|
+
const HIDDEN_STYLE = {
|
|
27
|
+
border: "0",
|
|
28
|
+
clip: "rect(0 0 0 0)",
|
|
29
|
+
clipPath: "inset(50%)",
|
|
30
|
+
height: "1px",
|
|
31
|
+
margin: "-1px",
|
|
32
|
+
overflow: "hidden",
|
|
33
|
+
padding: "0",
|
|
34
|
+
position: "absolute",
|
|
35
|
+
width: "1px",
|
|
36
|
+
whiteSpace: "nowrap",
|
|
37
|
+
} as const;
|
|
38
|
+
|
|
39
|
+
class Announcer {
|
|
40
|
+
node: HTMLElement | null = null;
|
|
41
|
+
#assertive: HTMLElement | null = null;
|
|
42
|
+
#polite: HTMLElement | null = null;
|
|
43
|
+
|
|
44
|
+
constructor() {
|
|
45
|
+
if (typeof document === "undefined") return;
|
|
46
|
+
|
|
47
|
+
this.node = document.createElement("div");
|
|
48
|
+
this.node.dataset.barqLiveAnnouncer = "true";
|
|
49
|
+
Object.assign(this.node.style, HIDDEN_STYLE);
|
|
50
|
+
|
|
51
|
+
this.#assertive = this.#createLog("assertive");
|
|
52
|
+
this.#polite = this.#createLog("polite");
|
|
53
|
+
this.node.append(this.#assertive, this.#polite);
|
|
54
|
+
|
|
55
|
+
// Prepended rather than appended: a region at the end of the body is
|
|
56
|
+
// inside whatever overlay was portalled there last, and an `aria-hidden`
|
|
57
|
+
// on that overlay would hide the announcements with it.
|
|
58
|
+
document.body.prepend(this.node);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
#createLog(live: Assertiveness): HTMLElement {
|
|
62
|
+
const log = document.createElement("div");
|
|
63
|
+
log.setAttribute("role", "log");
|
|
64
|
+
log.setAttribute("aria-live", live);
|
|
65
|
+
// Only additions are announced; the removal below must be silent.
|
|
66
|
+
log.setAttribute("aria-relevant", "additions");
|
|
67
|
+
return log;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
isAttached(): boolean {
|
|
71
|
+
return this.node?.isConnected === true;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
announce(message: Announcement, assertiveness: Assertiveness, timeout: number): void {
|
|
75
|
+
if (this.node === null) return;
|
|
76
|
+
|
|
77
|
+
const entry = document.createElement("div");
|
|
78
|
+
if (typeof message === "object") {
|
|
79
|
+
// An `aria-labelledby` is only read on an element with a role that takes
|
|
80
|
+
// a name from one.
|
|
81
|
+
entry.setAttribute("role", "img");
|
|
82
|
+
entry.setAttribute("aria-labelledby", message["aria-labelledby"]);
|
|
83
|
+
} else {
|
|
84
|
+
entry.textContent = message;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
(assertiveness === "assertive" ? this.#assertive : this.#polite)?.appendChild(entry);
|
|
88
|
+
|
|
89
|
+
// Removed once it has certainly been read, so the region does not grow
|
|
90
|
+
// without bound over a long session.
|
|
91
|
+
if (message !== "") {
|
|
92
|
+
setTimeout(() => entry.remove(), timeout);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
clear(assertiveness?: Assertiveness): void {
|
|
97
|
+
if (this.node === null) return;
|
|
98
|
+
if (assertiveness === undefined || assertiveness === "assertive") {
|
|
99
|
+
if (this.#assertive !== null) this.#assertive.innerHTML = "";
|
|
100
|
+
}
|
|
101
|
+
if (assertiveness === undefined || assertiveness === "polite") {
|
|
102
|
+
if (this.#polite !== null) this.#polite.innerHTML = "";
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
destroy(): void {
|
|
107
|
+
this.node?.remove();
|
|
108
|
+
this.node = null;
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
let announcer: Announcer | null = null;
|
|
113
|
+
|
|
114
|
+
/** Whether the first announcement should wait for the region to settle. */
|
|
115
|
+
const isTest = typeof process !== "undefined" && process.env.NODE_ENV === "test";
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Say something to assistive technology.
|
|
119
|
+
*
|
|
120
|
+
* ```ts
|
|
121
|
+
* announce(`${count} results`, "polite");
|
|
122
|
+
* ```
|
|
123
|
+
*
|
|
124
|
+
* The first call creates the region and waits a moment before filling it:
|
|
125
|
+
* WebKit reads nothing from a region that gained its content in the same frame
|
|
126
|
+
* it was inserted. Subsequent calls are immediate.
|
|
127
|
+
*/
|
|
128
|
+
export function announce(
|
|
129
|
+
message: Announcement,
|
|
130
|
+
assertiveness: Assertiveness = "assertive",
|
|
131
|
+
timeout: number = DEFAULT_TIMEOUT,
|
|
132
|
+
): void {
|
|
133
|
+
if (announcer !== null) {
|
|
134
|
+
announcer.announce(message, assertiveness, timeout);
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
announcer = new Announcer();
|
|
139
|
+
|
|
140
|
+
if (isTest) {
|
|
141
|
+
announcer.announce(message, assertiveness, timeout);
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
setTimeout(() => {
|
|
146
|
+
if (announcer?.isAttached() === true) announcer.announce(message, assertiveness, timeout);
|
|
147
|
+
}, 100);
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Drop everything queued, for one politeness level or both. */
|
|
151
|
+
export function clearAnnouncer(assertiveness?: Assertiveness): void {
|
|
152
|
+
announcer?.clear(assertiveness);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Remove the live regions entirely. */
|
|
156
|
+
export function destroyAnnouncer(): void {
|
|
157
|
+
announcer?.destroy();
|
|
158
|
+
announcer = null;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
// ---------------------------------------------------------------------------
|
|
162
|
+
// Visually hidden
|
|
163
|
+
// ---------------------------------------------------------------------------
|
|
164
|
+
|
|
165
|
+
export interface VisuallyHiddenOptions {
|
|
166
|
+
/**
|
|
167
|
+
* Let the element appear when it takes focus.
|
|
168
|
+
*
|
|
169
|
+
* For a skip link: hidden until the user tabs to it, then visible so a
|
|
170
|
+
* sighted keyboard user can see where focus went.
|
|
171
|
+
*/
|
|
172
|
+
isFocusable?: boolean;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
export interface VisuallyHiddenResult {
|
|
176
|
+
visuallyHiddenProps: Record<string, unknown>;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Hidden from sight, present for assistive technology.
|
|
181
|
+
*
|
|
182
|
+
* Not `display: none` and not `visibility: hidden`: both remove the element
|
|
183
|
+
* from the accessibility tree, which is the opposite of the point. The clip
|
|
184
|
+
* rectangle is what leaves it in the tree while occupying no visible space.
|
|
185
|
+
*
|
|
186
|
+
* ```tsx
|
|
187
|
+
* const { visuallyHiddenProps } = visuallyHidden();
|
|
188
|
+
* <span {...visuallyHiddenProps}>Loading</span>
|
|
189
|
+
* ```
|
|
190
|
+
*/
|
|
191
|
+
export function visuallyHidden(options: VisuallyHiddenOptions = {}): VisuallyHiddenResult {
|
|
192
|
+
if (options.isFocusable !== true) {
|
|
193
|
+
return { visuallyHiddenProps: { style: { ...HIDDEN_STYLE } } };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
const { isFocusWithin, focusWithinProps } = focusWithin({});
|
|
197
|
+
|
|
198
|
+
return {
|
|
199
|
+
visuallyHiddenProps: {
|
|
200
|
+
...focusWithinProps,
|
|
201
|
+
style: () => (isFocusWithin() ? {} : { ...HIDDEN_STYLE }),
|
|
202
|
+
},
|
|
203
|
+
};
|
|
204
|
+
}
|