@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.
Files changed (76) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +293 -2
  3. package/package.json +347 -4
  4. package/src/breadcrumbs.tsx +296 -0
  5. package/src/button.tsx +342 -0
  6. package/src/calendar.tsx +1389 -0
  7. package/src/checkbox.tsx +570 -0
  8. package/src/collections.ts +976 -0
  9. package/src/color.ts +562 -0
  10. package/src/colorpicker.tsx +1478 -0
  11. package/src/combobox.tsx +2481 -0
  12. package/src/command.tsx +1184 -0
  13. package/src/date.ts +652 -0
  14. package/src/datefield.tsx +951 -0
  15. package/src/datepicker.tsx +556 -0
  16. package/src/dialog.tsx +890 -0
  17. package/src/disclosure.tsx +659 -0
  18. package/src/dom.ts +706 -0
  19. package/src/drawer.ts +674 -0
  20. package/src/focus.ts +1370 -0
  21. package/src/form.tsx +94 -0
  22. package/src/gridlist.tsx +563 -0
  23. package/src/i18n.ts +823 -0
  24. package/src/index.ts +1270 -0
  25. package/src/interactions/description.ts +73 -0
  26. package/src/interactions/flags.ts +35 -0
  27. package/src/interactions/focus-events.ts +218 -0
  28. package/src/interactions/focusable.ts +86 -0
  29. package/src/interactions/hover.ts +213 -0
  30. package/src/interactions/interact-outside.ts +123 -0
  31. package/src/interactions/keyboard.ts +105 -0
  32. package/src/interactions/listeners.ts +78 -0
  33. package/src/interactions/long-press.ts +160 -0
  34. package/src/interactions/modality.ts +416 -0
  35. package/src/interactions/move.ts +257 -0
  36. package/src/interactions/open-link.ts +193 -0
  37. package/src/interactions/press.ts +898 -0
  38. package/src/interactions/prevent-focus.ts +102 -0
  39. package/src/interactions/scroll-wheel.ts +43 -0
  40. package/src/interactions/text-selection.ts +77 -0
  41. package/src/interactions.ts +81 -0
  42. package/src/label.ts +128 -0
  43. package/src/link.tsx +381 -0
  44. package/src/listbox.tsx +721 -0
  45. package/src/live.ts +204 -0
  46. package/src/menu.tsx +2290 -0
  47. package/src/menubar.tsx +575 -0
  48. package/src/navigation.ts +735 -0
  49. package/src/numberfield.tsx +838 -0
  50. package/src/otp.ts +430 -0
  51. package/src/overlays.ts +1247 -0
  52. package/src/platform.ts +74 -0
  53. package/src/presence.ts +164 -0
  54. package/src/questionnaire.tsx +1712 -0
  55. package/src/radio.tsx +567 -0
  56. package/src/register-dom.ts +12 -0
  57. package/src/scroller.ts +1165 -0
  58. package/src/select.tsx +1665 -0
  59. package/src/selection.ts +1415 -0
  60. package/src/slider.tsx +1042 -0
  61. package/src/splitter.ts +1152 -0
  62. package/src/static-collection.ts +211 -0
  63. package/src/switch.tsx +186 -0
  64. package/src/table.tsx +0 -0
  65. package/src/tabs.tsx +1018 -0
  66. package/src/tag.tsx +452 -0
  67. package/src/textfield.tsx +417 -0
  68. package/src/toast.ts +658 -0
  69. package/src/toggle-input.tsx +48 -0
  70. package/src/toggle.ts +321 -0
  71. package/src/togglegroup.ts +365 -0
  72. package/src/toolbar.tsx +179 -0
  73. package/src/tooltip.tsx +657 -0
  74. package/src/utils.ts +758 -0
  75. package/src/validation.ts +447 -0
  76. package/src/virtualizer.tsx +674 -0
package/src/link.tsx ADDED
@@ -0,0 +1,381 @@
1
+ /**
2
+ * Links, and the separators, progress bars and meters that need no state.
3
+ *
4
+ * A link is a press away from a button, and the difference is what the two
5
+ * mean: a link goes somewhere, a button does something. Assistive technology
6
+ * reports them differently, and Enter activates a link where Enter and Space
7
+ * both activate a button — which is why the press hook has to know which it is
8
+ * looking at rather than treating every activation the same.
9
+ */
10
+
11
+ import { type Accessor, type Child, type Incoming } from "@barqjs/core";
12
+ import { ref as makeRef, mergeRefs, type RefTarget } from "@barqjs/primitives/refs";
13
+ import { focusRing } from "./focus.ts";
14
+ import { focusable, type FocusableOptions } from "./interactions/focusable.ts";
15
+ import { hover } from "./interactions/hover.ts";
16
+ import { handleLinkClick, router, syntheticLinkProps } from "./interactions/open-link.ts";
17
+ import { press, type ElementRef, type PressEvent } from "./interactions/press.ts";
18
+ import { label as labelHook } from "./label.ts";
19
+ import { numberFormatter } from "./i18n.ts";
20
+ import {
21
+ access,
22
+ clamp,
23
+ type DOMProps,
24
+ filterDOMProps,
25
+ fromProps,
26
+ type MaybeAccessor,
27
+ mergeProps,
28
+ type StyleProps,
29
+ styleProps,
30
+ } from "./utils.ts";
31
+
32
+ export interface LinkOptions extends FocusableOptions {
33
+ isDisabled?: MaybeAccessor<boolean | undefined>;
34
+ /** @default "a" */
35
+ elementType?: MaybeAccessor<string | undefined>;
36
+ href?: MaybeAccessor<string | undefined>;
37
+ target?: MaybeAccessor<string | undefined>;
38
+ rel?: MaybeAccessor<string | undefined>;
39
+ download?: MaybeAccessor<boolean | string | undefined>;
40
+ ping?: MaybeAccessor<string | undefined>;
41
+ referrerPolicy?: MaybeAccessor<string | undefined>;
42
+ "aria-current"?: MaybeAccessor<boolean | string | undefined>;
43
+ "aria-label"?: MaybeAccessor<string | undefined>;
44
+ "aria-labelledby"?: MaybeAccessor<string | undefined>;
45
+ "aria-describedby"?: MaybeAccessor<string | undefined>;
46
+ onPress?: (event: PressEvent) => void;
47
+ onPressStart?: (event: PressEvent) => void;
48
+ onPressEnd?: (event: PressEvent) => void;
49
+ onPressChange?: (isPressed: boolean) => void;
50
+ onClick?: (event: MouseEvent) => void;
51
+ }
52
+
53
+ export interface LinkResult {
54
+ linkProps: DOMProps;
55
+ isPressed: Accessor<boolean>;
56
+ }
57
+
58
+ export function link(options: LinkOptions, ref?: ElementRef): LinkResult {
59
+ const elementType = (): string => access(options.elementType) ?? "a";
60
+ const isDisabled = (): boolean => access(options.isDisabled) === true;
61
+
62
+ const { pressProps, isPressed } = press({ ...options, ref });
63
+ const { focusableProps } = focusable(options, ref);
64
+ const navigate = router();
65
+
66
+ const roleProps: DOMProps = {
67
+ // Anything that is not an `<a href>` has to say what it is, and be
68
+ // reachable by Tab, which a `<span>` is not.
69
+ role: () => (elementType() === "a" ? undefined : "link"),
70
+ tabIndex: () => (elementType() === "a" || isDisabled() ? undefined : 0),
71
+ };
72
+
73
+ return {
74
+ isPressed,
75
+ linkProps: mergeProps(
76
+ filterDOMProps(options, { labelable: true, isLink: true }),
77
+ // The `data-href` shape, so a non-anchor element can still be opened by
78
+ // the router or by a middle click.
79
+ elementType() === "a" ? {} : syntheticLinkProps(options as never),
80
+ focusableProps,
81
+ pressProps,
82
+ roleProps,
83
+ {
84
+ // A disabled link must not navigate, and `<a>` has no `disabled`.
85
+ href: () => (isDisabled() ? undefined : access(options.href)),
86
+ "aria-disabled": () => isDisabled() || undefined,
87
+ "aria-current": () => access(options["aria-current"]),
88
+ onClick: (event: MouseEvent) => {
89
+ handleLinkClick(event, access(options.href), navigate);
90
+ },
91
+ },
92
+ ),
93
+ };
94
+ }
95
+
96
+ // ---------------------------------------------------------------------------
97
+ // Separator
98
+ // ---------------------------------------------------------------------------
99
+
100
+ export interface SeparatorOptions {
101
+ /** @default "horizontal" */
102
+ orientation?: MaybeAccessor<"horizontal" | "vertical" | undefined>;
103
+ /** @default "hr" */
104
+ elementType?: MaybeAccessor<string | undefined>;
105
+ "aria-label"?: MaybeAccessor<string | undefined>;
106
+ "aria-labelledby"?: MaybeAccessor<string | undefined>;
107
+ }
108
+
109
+ /**
110
+ * A divider between groups of content.
111
+ *
112
+ * `<hr>` already has the role and a horizontal orientation, so nothing is
113
+ * written for it. Anything else needs both — and `aria-orientation` only when
114
+ * it is vertical, since horizontal is the role's default.
115
+ */
116
+ export function separator(options: SeparatorOptions): { separatorProps: DOMProps } {
117
+ const domProps = filterDOMProps(options, { labelable: true });
118
+
119
+ if ((access(options.elementType) ?? "hr") === "hr") return { separatorProps: domProps };
120
+
121
+ return {
122
+ separatorProps: mergeProps(domProps, {
123
+ role: "separator",
124
+ "aria-orientation": () =>
125
+ access(options.orientation) === "vertical" ? "vertical" : undefined,
126
+ }),
127
+ };
128
+ }
129
+
130
+ // ---------------------------------------------------------------------------
131
+ // Progress and meter
132
+ // ---------------------------------------------------------------------------
133
+
134
+ export interface ProgressBarOptions {
135
+ /** @default 0 */
136
+ value?: MaybeAccessor<number | undefined>;
137
+ /** @default 0 */
138
+ minValue?: MaybeAccessor<number | undefined>;
139
+ /** @default 100 */
140
+ maxValue?: MaybeAccessor<number | undefined>;
141
+ /** Progress that is happening but cannot be measured. */
142
+ isIndeterminate?: MaybeAccessor<boolean | undefined>;
143
+ /** What to say instead of the formatted percentage, e.g. "1 of 4". */
144
+ valueLabel?: MaybeAccessor<string | undefined>;
145
+ /** @default { style: "percent" } */
146
+ formatOptions?: Intl.NumberFormatOptions;
147
+ label?: MaybeAccessor<unknown>;
148
+ id?: MaybeAccessor<string | undefined>;
149
+ "aria-label"?: MaybeAccessor<string | undefined>;
150
+ "aria-labelledby"?: MaybeAccessor<string | undefined>;
151
+ }
152
+
153
+ export interface ProgressBarResult {
154
+ progressBarProps: DOMProps;
155
+ labelProps: DOMProps;
156
+ /** What a screen reader will read for the value. */
157
+ valueText: Accessor<string | undefined>;
158
+ percentage: Accessor<number>;
159
+ }
160
+
161
+ /**
162
+ * A progress bar.
163
+ *
164
+ * `aria-valuetext` is what a screen reader actually reads; `aria-valuenow`
165
+ * alone is announced as a bare number with no unit, which for a percentage is
166
+ * wrong in most locales. An indeterminate bar has neither: a value it does not
167
+ * know is worse than no value.
168
+ */
169
+ export function progressBar(options: ProgressBarOptions): ProgressBarResult {
170
+ const formatOptions = options.formatOptions ?? { style: "percent" as const };
171
+ const format = numberFormatter(formatOptions);
172
+
173
+ const { labelProps, fieldProps } = labelHook({
174
+ ...options,
175
+ // A progressbar is not a labelable element.
176
+ labelElementType: "span",
177
+ });
178
+
179
+ const min = (): number => access(options.minValue) ?? 0;
180
+ const max = (): number => access(options.maxValue) ?? 100;
181
+ const value = (): number => clamp(access(options.value) ?? 0, min(), max());
182
+ const isIndeterminate = (): boolean => access(options.isIndeterminate) === true;
183
+
184
+ const percentage = (): number => {
185
+ const range = max() - min();
186
+ return range === 0 ? 0 : (value() - min()) / range;
187
+ };
188
+
189
+ const valueText = (): string | undefined => {
190
+ if (isIndeterminate()) return undefined;
191
+ const given = access(options.valueLabel);
192
+ if (given !== undefined) return given;
193
+ return format().format(formatOptions.style === "percent" ? percentage() : value());
194
+ };
195
+
196
+ return {
197
+ percentage,
198
+ valueText,
199
+ labelProps,
200
+ progressBarProps: mergeProps(filterDOMProps(options, { labelable: true }), fieldProps, {
201
+ role: "progressbar",
202
+ "aria-valuenow": () => (isIndeterminate() ? undefined : value()),
203
+ "aria-valuemin": min,
204
+ "aria-valuemax": max,
205
+ "aria-valuetext": valueText,
206
+ }),
207
+ };
208
+ }
209
+
210
+ /**
211
+ * A meter: a quantity within a known range, not progress towards completion.
212
+ *
213
+ * `role="meter progressbar"` is a fallback list, and the reason is browser
214
+ * support: Chrome degrades from `meter` on its own, Firefox does not implement
215
+ * it at all, and `progressbar` is what those two announce instead.
216
+ */
217
+ export function meter(options: Omit<ProgressBarOptions, "isIndeterminate">): ProgressBarResult {
218
+ const result = progressBar(options);
219
+ return {
220
+ ...result,
221
+ progressBarProps: mergeProps(result.progressBarProps, { role: "meter progressbar" }),
222
+ };
223
+ }
224
+
225
+ // ---------------------------------------------------------------------------
226
+ // Components
227
+ // ---------------------------------------------------------------------------
228
+
229
+ export interface LinkComponentProps extends StyleProps {
230
+ children?: Child;
231
+ href?: string;
232
+ target?: string;
233
+ rel?: string;
234
+ download?: boolean | string;
235
+ isDisabled?: boolean;
236
+ autoFocus?: boolean;
237
+ "aria-label"?: string;
238
+ "aria-labelledby"?: string;
239
+ "aria-current"?: boolean | string;
240
+ ref?: RefTarget<HTMLAnchorElement>;
241
+ onPress?: (event: PressEvent) => void;
242
+ onClick?: (event: MouseEvent) => void;
243
+ }
244
+
245
+ /**
246
+ * ```tsx
247
+ * <Link href="/about">About</Link>
248
+ * ```
249
+ */
250
+ export function Link(props: Incoming<LinkComponentProps>) {
251
+ const domRef = makeRef<HTMLAnchorElement>();
252
+ const options = fromProps(props);
253
+
254
+ const { linkProps, isPressed } = link(options, domRef);
255
+ const { hoverProps, isHovered } = hover({ isDisabled: options.isDisabled });
256
+ const { focusProps, isFocused, isFocusVisible } = focusRing();
257
+ // `link()` delivers `onClick` itself; bound on the element as well, a
258
+ // caller's handler runs twice for every mouse click.
259
+ const { onClick: _, ...forwarded } = filterDOMProps(options, { global: true });
260
+
261
+ const elementProps = mergeProps(linkProps, hoverProps, focusProps, forwarded, styleProps(props), {
262
+ "data-pressed": isPressed,
263
+ "data-hovered": isHovered,
264
+ "data-focused": isFocused,
265
+ "data-focus-visible": isFocusVisible,
266
+ "data-disabled": () => props.isDisabled?.() === true,
267
+ "data-testid": () => props["data-testid"]?.(),
268
+ });
269
+
270
+ return (
271
+ <a {...elementProps} ref={mergeRefs(domRef.set, props.ref?.())}>
272
+ {props.children}
273
+ </a>
274
+ );
275
+ }
276
+
277
+ export interface SeparatorComponentProps extends StyleProps {
278
+ orientation?: "horizontal" | "vertical";
279
+ /**
280
+ * Drawn and not announced: a rule that divides nothing a screen reader
281
+ * needs told about, such as the line between two toolbar buttons.
282
+ */
283
+ decorative?: boolean;
284
+ "aria-label"?: string;
285
+ }
286
+
287
+ export function Separator(props: Incoming<SeparatorComponentProps>) {
288
+ const options = fromProps(props);
289
+ const { separatorProps } = separator({ ...(options as SeparatorOptions), elementType: "hr" });
290
+
291
+ const elementProps = mergeProps(
292
+ separatorProps,
293
+ filterDOMProps(options, { global: true }),
294
+ styleProps(props),
295
+ {
296
+ role: () => (props.decorative?.() === true ? "none" : undefined),
297
+ "data-orientation": () => props.orientation?.() ?? "horizontal",
298
+ "aria-orientation": () =>
299
+ props.orientation?.() === "vertical" && props.decorative?.() !== true
300
+ ? "vertical"
301
+ : undefined,
302
+ "data-testid": () => props["data-testid"]?.(),
303
+ },
304
+ );
305
+
306
+ return <hr {...elementProps} />;
307
+ }
308
+
309
+ export interface ProgressBarComponentProps extends StyleProps {
310
+ children?: Child;
311
+ label?: Child;
312
+ value?: number;
313
+ minValue?: number;
314
+ maxValue?: number;
315
+ isIndeterminate?: boolean;
316
+ valueLabel?: string;
317
+ formatOptions?: Intl.NumberFormatOptions;
318
+ "aria-label"?: string;
319
+ "aria-labelledby"?: string;
320
+ }
321
+
322
+ /**
323
+ * ```tsx
324
+ * <ProgressBar label="Uploading" value={progress()} />
325
+ * ```
326
+ *
327
+ * The bar itself is the caller's: `data-percentage` carries the fraction so a
328
+ * stylesheet can size a child without a `style` attribute.
329
+ */
330
+ export function ProgressBar(props: Incoming<ProgressBarComponentProps>) {
331
+ const options = fromProps(props);
332
+ const { progressBarProps, labelProps, percentage, valueText } = progressBar(
333
+ options as ProgressBarOptions,
334
+ );
335
+
336
+ const elementProps = mergeProps(
337
+ progressBarProps,
338
+ filterDOMProps(options, { global: true }),
339
+ styleProps(props),
340
+ {
341
+ "data-indeterminate": () => props.isIndeterminate?.() === true,
342
+ "data-percentage": () => (props.isIndeterminate?.() === true ? undefined : percentage()),
343
+ "data-testid": () => props["data-testid"]?.(),
344
+ },
345
+ );
346
+
347
+ return (
348
+ <div {...elementProps}>
349
+ <span {...labelProps}>{props.label}</span>
350
+ {props.children}
351
+ <span aria-hidden="true">{valueText}</span>
352
+ </div>
353
+ );
354
+ }
355
+
356
+ export interface MeterComponentProps extends Omit<ProgressBarComponentProps, "isIndeterminate"> {}
357
+
358
+ export function Meter(props: Incoming<MeterComponentProps>) {
359
+ const options = fromProps(props);
360
+ const { progressBarProps, labelProps, percentage, valueText } = meter(
361
+ options as ProgressBarOptions,
362
+ );
363
+
364
+ const elementProps = mergeProps(
365
+ progressBarProps,
366
+ filterDOMProps(options, { global: true }),
367
+ styleProps(props),
368
+ {
369
+ "data-percentage": percentage,
370
+ "data-testid": () => props["data-testid"]?.(),
371
+ },
372
+ );
373
+
374
+ return (
375
+ <div {...elementProps}>
376
+ <span {...labelProps}>{props.label}</span>
377
+ {props.children}
378
+ <span aria-hidden="true">{valueText}</span>
379
+ </div>
380
+ );
381
+ }