@barqjs/aria 0.0.0-stage → 0.2.0-next.1

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.
Files changed (103) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +304 -2
  3. package/package.json +437 -4
  4. package/src/autocomplete.tsx +581 -0
  5. package/src/breadcrumbs.tsx +297 -0
  6. package/src/button.tsx +468 -0
  7. package/src/calendar.tsx +2316 -0
  8. package/src/checkbox.tsx +732 -0
  9. package/src/collections.ts +1059 -0
  10. package/src/color.ts +2119 -0
  11. package/src/colorpicker.tsx +2023 -0
  12. package/src/colorswatchpicker.tsx +240 -0
  13. package/src/combobox.tsx +3003 -0
  14. package/src/command.tsx +1203 -0
  15. package/src/date.ts +674 -0
  16. package/src/datefield.tsx +2066 -0
  17. package/src/datepicker.tsx +907 -0
  18. package/src/dialog.tsx +1077 -0
  19. package/src/disclosure.tsx +711 -0
  20. package/src/dnd/clipboard.ts +125 -0
  21. package/src/dnd/collection.ts +1265 -0
  22. package/src/dnd/data.ts +409 -0
  23. package/src/dnd/drag-drop.ts +801 -0
  24. package/src/dnd/index.ts +133 -0
  25. package/src/dnd/manager.ts +639 -0
  26. package/src/dnd/strings.ts +1279 -0
  27. package/src/dnd/targets.ts +726 -0
  28. package/src/dnd/types.ts +212 -0
  29. package/src/dom.ts +703 -0
  30. package/src/drag-and-drop.tsx +669 -0
  31. package/src/drawer.ts +674 -0
  32. package/src/dropzone.tsx +208 -0
  33. package/src/file-trigger.tsx +103 -0
  34. package/src/focus.ts +1370 -0
  35. package/src/form.tsx +94 -0
  36. package/src/gridlist.tsx +1354 -0
  37. package/src/group.tsx +146 -0
  38. package/src/i18n.ts +823 -0
  39. package/src/index.ts +1672 -0
  40. package/src/interactions/description.ts +73 -0
  41. package/src/interactions/flags.ts +35 -0
  42. package/src/interactions/focus-events.ts +226 -0
  43. package/src/interactions/focusable.ts +86 -0
  44. package/src/interactions/hover.ts +213 -0
  45. package/src/interactions/interact-outside.ts +123 -0
  46. package/src/interactions/keyboard.ts +298 -0
  47. package/src/interactions/listeners.ts +78 -0
  48. package/src/interactions/long-press.ts +160 -0
  49. package/src/interactions/modality.ts +428 -0
  50. package/src/interactions/move.ts +257 -0
  51. package/src/interactions/open-link.ts +226 -0
  52. package/src/interactions/press.ts +915 -0
  53. package/src/interactions/prevent-focus.ts +102 -0
  54. package/src/interactions/scroll-wheel.ts +43 -0
  55. package/src/interactions/text-selection.ts +77 -0
  56. package/src/interactions.ts +81 -0
  57. package/src/label.ts +140 -0
  58. package/src/link.tsx +477 -0
  59. package/src/listbox.tsx +1247 -0
  60. package/src/live.ts +208 -0
  61. package/src/menu.tsx +2383 -0
  62. package/src/menubar.tsx +579 -0
  63. package/src/navigation-tree.tsx +357 -0
  64. package/src/navigation.ts +735 -0
  65. package/src/numberfield.tsx +942 -0
  66. package/src/otp.ts +430 -0
  67. package/src/overlay-arrow.tsx +157 -0
  68. package/src/overlays.ts +1549 -0
  69. package/src/platform.ts +75 -0
  70. package/src/presence.ts +164 -0
  71. package/src/preview-trigger.tsx +582 -0
  72. package/src/progress-bar-context.ts +15 -0
  73. package/src/questionnaire.tsx +1717 -0
  74. package/src/radio.tsx +641 -0
  75. package/src/register-dom.ts +12 -0
  76. package/src/scroller.ts +1165 -0
  77. package/src/select.tsx +1745 -0
  78. package/src/selection-indicator.tsx +74 -0
  79. package/src/selection.ts +1472 -0
  80. package/src/shared-element-transition.tsx +316 -0
  81. package/src/sheet.tsx +1461 -0
  82. package/src/slider.tsx +1137 -0
  83. package/src/splitter.ts +1152 -0
  84. package/src/static-collection.ts +211 -0
  85. package/src/switch.tsx +212 -0
  86. package/src/table.tsx +2218 -0
  87. package/src/tabs.tsx +1127 -0
  88. package/src/tag.tsx +637 -0
  89. package/src/textarea.tsx +186 -0
  90. package/src/textfield.tsx +483 -0
  91. package/src/toast-components.tsx +589 -0
  92. package/src/toast.ts +658 -0
  93. package/src/toggle-button-group.tsx +175 -0
  94. package/src/toggle-input.tsx +86 -0
  95. package/src/toggle.ts +384 -0
  96. package/src/togglegroup.ts +365 -0
  97. package/src/tokenfield.tsx +1673 -0
  98. package/src/toolbar.tsx +184 -0
  99. package/src/tooltip.tsx +674 -0
  100. package/src/tree.tsx +2075 -0
  101. package/src/utils.ts +787 -0
  102. package/src/validation.ts +504 -0
  103. package/src/virtualizer.tsx +837 -0
package/src/live.ts ADDED
@@ -0,0 +1,208 @@
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
+ // A region the page took out of the document says nothing, and an
134
+ // application that replaces the body's content does take it out.
135
+ if (announcer !== null && !announcer.isAttached()) destroyAnnouncer();
136
+
137
+ if (announcer !== null) {
138
+ announcer.announce(message, assertiveness, timeout);
139
+ return;
140
+ }
141
+
142
+ announcer = new Announcer();
143
+
144
+ if (isTest) {
145
+ announcer.announce(message, assertiveness, timeout);
146
+ return;
147
+ }
148
+
149
+ setTimeout(() => {
150
+ if (announcer?.isAttached() === true) announcer.announce(message, assertiveness, timeout);
151
+ }, 100);
152
+ }
153
+
154
+ /** Drop everything queued, for one politeness level or both. */
155
+ export function clearAnnouncer(assertiveness?: Assertiveness): void {
156
+ announcer?.clear(assertiveness);
157
+ }
158
+
159
+ /** Remove the live regions entirely. */
160
+ export function destroyAnnouncer(): void {
161
+ announcer?.destroy();
162
+ announcer = null;
163
+ }
164
+
165
+ // ---------------------------------------------------------------------------
166
+ // Visually hidden
167
+ // ---------------------------------------------------------------------------
168
+
169
+ export interface VisuallyHiddenOptions {
170
+ /**
171
+ * Let the element appear when it takes focus.
172
+ *
173
+ * For a skip link: hidden until the user tabs to it, then visible so a
174
+ * sighted keyboard user can see where focus went.
175
+ */
176
+ isFocusable?: boolean;
177
+ }
178
+
179
+ export interface VisuallyHiddenResult {
180
+ visuallyHiddenProps: Record<string, unknown>;
181
+ }
182
+
183
+ /**
184
+ * Hidden from sight, present for assistive technology.
185
+ *
186
+ * Not `display: none` and not `visibility: hidden`: both remove the element
187
+ * from the accessibility tree, which is the opposite of the point. The clip
188
+ * rectangle is what leaves it in the tree while occupying no visible space.
189
+ *
190
+ * ```tsx
191
+ * const { visuallyHiddenProps } = visuallyHidden();
192
+ * <span {...visuallyHiddenProps}>Loading</span>
193
+ * ```
194
+ */
195
+ export function visuallyHidden(options: VisuallyHiddenOptions = {}): VisuallyHiddenResult {
196
+ if (options.isFocusable !== true) {
197
+ return { visuallyHiddenProps: { style: { ...HIDDEN_STYLE } } };
198
+ }
199
+
200
+ const { isFocusWithin, focusWithinProps } = focusWithin({});
201
+
202
+ return {
203
+ visuallyHiddenProps: {
204
+ ...focusWithinProps,
205
+ style: () => (isFocusWithin() ? {} : { ...HIDDEN_STYLE }),
206
+ },
207
+ };
208
+ }