@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
@@ -0,0 +1,102 @@
1
+ /**
2
+ * Stopping a press from moving focus, without `preventDefault()`.
3
+ *
4
+ * `preventDefault()` on `mousedown` would do it, but it also cancels the
5
+ * browser's text selection and drag start, which a component that only wants
6
+ * to keep focus where it is has no business cancelling. So focus is allowed to
7
+ * move and then put back inside the same frame, with the intervening events
8
+ * swallowed by capturing listeners so nothing else observes the round trip.
9
+ *
10
+ * Used by a combobox button and a menu trigger: pressing one must not take
11
+ * focus off the input.
12
+ */
13
+
14
+ import {
15
+ activeElement,
16
+ contains,
17
+ focusWithoutScrolling,
18
+ isFocusable,
19
+ isShadowRoot,
20
+ ownerWindow,
21
+ targetElement,
22
+ } from "../dom.ts";
23
+ import { setIgnoringFocus } from "./flags.ts";
24
+
25
+ /**
26
+ * Swallow the next focus that lands on `target`, restoring the element that
27
+ * had it. Returns the teardown, or `undefined` when there was nothing to do.
28
+ */
29
+ export function preventFocus(target: Element | null): (() => void) | undefined {
30
+ // The browser focuses the nearest focusable ancestor, which is where the
31
+ // events will actually land.
32
+ let element: Element | null = target;
33
+ while (element !== null && !isFocusable(element, { skipVisibilityCheck: true })) {
34
+ element = element.parentElement;
35
+ }
36
+
37
+ const view = ownerWindow(element);
38
+ const previous = activeElement(view.document) as HTMLElement | SVGElement | null;
39
+ if (previous === null || (previous as Element) === element) return undefined;
40
+
41
+ // Listen on the target's own root: a focus event inside a shadow root never
42
+ // reaches the window.
43
+ const targetRoot = element?.getRootNode();
44
+ const root: EventTarget =
45
+ targetRoot !== undefined && targetRoot !== null && isShadowRoot(targetRoot) ? targetRoot : view;
46
+
47
+ const movingToTarget = (node: Element | null): boolean =>
48
+ node === element || (node !== null && contains(element, node));
49
+ const leavingPrevious = (node: Element | null): boolean =>
50
+ node === (previous as Element) || (node !== null && contains(previous, node));
51
+
52
+ setIgnoringFocus(true);
53
+ let restoring = false;
54
+
55
+ const onBlur = (event: Event): void => {
56
+ if (leavingPrevious(targetElement(event)) || restoring) event.stopImmediatePropagation();
57
+ };
58
+
59
+ const onFocusOut = (event: Event): void => {
60
+ if (!leavingPrevious(targetElement(event)) && !restoring) return;
61
+ event.stopImmediatePropagation();
62
+ // With no focusable ancestor there will be no focus event to react to, so
63
+ // the restore has to happen here.
64
+ if (element === null && !restoring) {
65
+ restoring = true;
66
+ focusWithoutScrolling(previous);
67
+ cleanup();
68
+ }
69
+ };
70
+
71
+ const onFocus = (event: Event): void => {
72
+ if (movingToTarget(targetElement(event)) || restoring) event.stopImmediatePropagation();
73
+ };
74
+
75
+ const onFocusIn = (event: Event): void => {
76
+ if (!movingToTarget(targetElement(event)) && !restoring) return;
77
+ event.stopImmediatePropagation();
78
+ if (restoring) return;
79
+ restoring = true;
80
+ focusWithoutScrolling(previous);
81
+ cleanup();
82
+ };
83
+
84
+ root.addEventListener("blur", onBlur, true);
85
+ root.addEventListener("focusout", onFocusOut, true);
86
+ root.addEventListener("focusin", onFocusIn, true);
87
+ root.addEventListener("focus", onFocus, true);
88
+
89
+ const cleanup = (): void => {
90
+ cancelAnimationFrame(frame);
91
+ root.removeEventListener("blur", onBlur, true);
92
+ root.removeEventListener("focusout", onFocusOut, true);
93
+ root.removeEventListener("focusin", onFocusIn, true);
94
+ root.removeEventListener("focus", onFocus, true);
95
+ setIgnoringFocus(false);
96
+ restoring = false;
97
+ };
98
+
99
+ // One frame is the ceiling: the focus either moved by then or is not coming.
100
+ const frame = requestAnimationFrame(cleanup);
101
+ return cleanup;
102
+ }
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The wheel, for a control that consumes it rather than scrolling: a number
3
+ * field, a slider, a colour area.
4
+ *
5
+ * Bound non-passively, which is the whole point — a passive `wheel` listener
6
+ * cannot call `preventDefault()`, so the page scrolls underneath. Modern
7
+ * engines default `wheel` on the document to passive, and a listener added
8
+ * through a framework's prop system usually inherits that default, which is
9
+ * why this binds the element directly.
10
+ */
11
+
12
+ import { createEffect } from "@barqjs/core";
13
+ import { access, type MaybeAccessor } from "../utils.ts";
14
+ import type { ElementRef } from "./press.ts";
15
+
16
+ export interface ScrollWheelOptions {
17
+ ref: ElementRef;
18
+ isDisabled?: MaybeAccessor<boolean | undefined>;
19
+ onScroll?: (delta: { deltaX: number; deltaY: number }) => void;
20
+ }
21
+
22
+ export function scrollWheel(options: ScrollWheelOptions): void {
23
+ createEffect(
24
+ () =>
25
+ access(options.isDisabled) === true || options.onScroll === undefined
26
+ ? null
27
+ : access(options.ref),
28
+ (element) => {
29
+ if (element === null || element === undefined) return undefined;
30
+
31
+ const onWheel = (event: WheelEvent): void => {
32
+ // Control held is a zoom gesture, which belongs to the browser.
33
+ if (event.ctrlKey) return;
34
+ event.preventDefault();
35
+ event.stopPropagation();
36
+ options.onScroll?.({ deltaX: event.deltaX, deltaY: event.deltaY });
37
+ };
38
+
39
+ element.addEventListener("wheel", onWheel as EventListener, { passive: false });
40
+ return () => element.removeEventListener("wheel", onWheel as EventListener);
41
+ },
42
+ );
43
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Keeping a long press from selecting text.
3
+ *
4
+ * iOS WebKit begins a text selection on long press, and the only thing that
5
+ * stops it is `user-select: none` on the document element: setting it on the
6
+ * pressed element alone still lets the selection start on a neighbour. So on
7
+ * iOS this is page-wide and reference-counted through three states, because
8
+ * two elements pressed in sequence must not have the second's restore undo the
9
+ * first's disable.
10
+ *
11
+ * Everywhere else the property goes on the element itself. Applying and
12
+ * removing it document-wide forces a style recalculation for the whole page on
13
+ * every press, which is measurable on a large document.
14
+ */
15
+
16
+ import { isStyledElement, ownerDocument } from "../dom.ts";
17
+ import { isIOS, isWebKit } from "../platform.ts";
18
+ import { runAfterTransition } from "../dom.ts";
19
+
20
+ type State = "default" | "disabled" | "restoring";
21
+
22
+ let state: State = "default";
23
+ let savedUserSelect = "";
24
+ const modified = new WeakMap<Element, string>();
25
+
26
+ function userSelectProperty(element: HTMLElement | SVGElement): "userSelect" | "webkitUserSelect" {
27
+ return "userSelect" in element.style ? "userSelect" : "webkitUserSelect";
28
+ }
29
+
30
+ export function disableTextSelection(target?: Element | null): void {
31
+ if (isIOS() && isWebKit()) {
32
+ if (state === "default") {
33
+ const doc = ownerDocument(target);
34
+ savedUserSelect = doc.documentElement.style.webkitUserSelect;
35
+ doc.documentElement.style.webkitUserSelect = "none";
36
+ }
37
+ state = "disabled";
38
+ return;
39
+ }
40
+
41
+ if (isStyledElement(target)) {
42
+ const property = userSelectProperty(target);
43
+ modified.set(target, target.style[property]);
44
+ target.style[property] = "none";
45
+ }
46
+ }
47
+
48
+ export function restoreTextSelection(target?: Element | null): void {
49
+ if (isIOS() && isWebKit()) {
50
+ if (state !== "disabled") return;
51
+ state = "restoring";
52
+
53
+ // iOS can still begin a selection just after pointer up, so the restore
54
+ // waits; and it waits again for any transition, so the page-wide style
55
+ // recalculation does not land in the middle of an animation.
56
+ setTimeout(() => {
57
+ runAfterTransition(() => {
58
+ if (state !== "restoring") return;
59
+ const doc = ownerDocument(target);
60
+ if (doc.documentElement.style.webkitUserSelect === "none") {
61
+ doc.documentElement.style.webkitUserSelect = savedUserSelect || "";
62
+ }
63
+ savedUserSelect = "";
64
+ state = "default";
65
+ });
66
+ }, 300);
67
+ return;
68
+ }
69
+
70
+ if (isStyledElement(target) && modified.has(target)) {
71
+ const previous = modified.get(target) as string;
72
+ const property = userSelectProperty(target);
73
+ if (target.style[property] === "none") target.style[property] = previous;
74
+ if (target.getAttribute("style") === "") target.removeAttribute("style");
75
+ modified.delete(target);
76
+ }
77
+ }
@@ -0,0 +1,81 @@
1
+ /**
2
+ * The interaction layer: what the user did, normalised across every device and
3
+ * assistive technology that can do it.
4
+ */
5
+
6
+ export { description } from "./interactions/description.ts";
7
+
8
+ export { focused, focusWithin } from "./interactions/focus-events.ts";
9
+ export type {
10
+ FocusOptions,
11
+ FocusResult,
12
+ FocusWithinOptions,
13
+ FocusWithinResult,
14
+ } from "./interactions/focus-events.ts";
15
+
16
+ export { focusable, focusSafely } from "./interactions/focusable.ts";
17
+ export type { FocusableOptions, FocusableResult } from "./interactions/focusable.ts";
18
+
19
+ export { hover } from "./interactions/hover.ts";
20
+ export type { HoverEvent, HoverOptions, HoverResult } from "./interactions/hover.ts";
21
+
22
+ export { interactOutside } from "./interactions/interact-outside.ts";
23
+ export type { InteractOutsideOptions } from "./interactions/interact-outside.ts";
24
+
25
+ export { createEventHandler, keyboard } from "./interactions/keyboard.ts";
26
+ export type { BaseEvent, KeyboardOptions, KeyboardResult } from "./interactions/keyboard.ts";
27
+
28
+ export { globalListeners } from "./interactions/listeners.ts";
29
+ export type { GlobalListeners } from "./interactions/listeners.ts";
30
+
31
+ export { longPress } from "./interactions/long-press.ts";
32
+ export type {
33
+ LongPressEvent,
34
+ LongPressOptions,
35
+ LongPressResult,
36
+ } from "./interactions/long-press.ts";
37
+
38
+ export {
39
+ focusVisible,
40
+ getInteractionModality,
41
+ getPointerType,
42
+ isFocusVisible,
43
+ isVirtualClick,
44
+ isVirtualPointerEvent,
45
+ modality,
46
+ onModalityChange,
47
+ resetInteractionModality,
48
+ setInteractionModality,
49
+ trackModality,
50
+ untrackModality,
51
+ } from "./interactions/modality.ts";
52
+ export type { Modality, ModalityHandler, PointerType } from "./interactions/modality.ts";
53
+
54
+ export { move } from "./interactions/move.ts";
55
+ export type {
56
+ MoveEndEvent,
57
+ MoveMoveEvent,
58
+ MoveOptions,
59
+ MoveResult,
60
+ MoveStartEvent,
61
+ } from "./interactions/move.ts";
62
+
63
+ export {
64
+ handleLinkClick,
65
+ openLink,
66
+ router,
67
+ RouterContext,
68
+ shouldClientNavigate,
69
+ syntheticLinkProps,
70
+ } from "./interactions/open-link.ts";
71
+ export type { LinkModifiers, Router } from "./interactions/open-link.ts";
72
+
73
+ export { press } from "./interactions/press.ts";
74
+ export type { ElementRef, PressEvent, PressOptions, PressResult } from "./interactions/press.ts";
75
+
76
+ export { preventFocus } from "./interactions/prevent-focus.ts";
77
+
78
+ export { scrollWheel } from "./interactions/scroll-wheel.ts";
79
+ export type { ScrollWheelOptions } from "./interactions/scroll-wheel.ts";
80
+
81
+ export { disableTextSelection, restoreTextSelection } from "./interactions/text-selection.ts";
package/src/label.ts ADDED
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Labels, descriptions and error messages, wired to the field they belong to.
3
+ *
4
+ * A visible label must be associated with its control, or a screen reader
5
+ * announces "edit text, blank" and the user has to guess. `<label for>` does
6
+ * that for a native input and nothing else: a listbox, a slider or a group of
7
+ * checkboxes is not a labelable element, and needs `aria-labelledby` instead.
8
+ *
9
+ * The description and the error message go in `aria-describedby` rather than
10
+ * `aria-errormessage`, which VoiceOver and NVDA still do not announce.
11
+ */
12
+
13
+ import { type Accessor } from "@barqjs/core";
14
+ import { access, id, mergeProps, type DOMProps, type MaybeAccessor } from "./utils.ts";
15
+
16
+ export interface LabelOptions {
17
+ id?: MaybeAccessor<string | undefined>;
18
+ /** Whether there is a visible label element at all. */
19
+ label?: MaybeAccessor<unknown>;
20
+ "aria-label"?: MaybeAccessor<string | undefined>;
21
+ "aria-labelledby"?: MaybeAccessor<string | undefined>;
22
+ /**
23
+ * What renders the label. `span` when the field is not a labelable element,
24
+ * because `<label for>` on a `<div role="listbox">` does nothing.
25
+ *
26
+ * @default "label"
27
+ */
28
+ labelElementType?: MaybeAccessor<string | undefined>;
29
+ }
30
+
31
+ export interface LabelResult {
32
+ labelProps: DOMProps;
33
+ fieldProps: DOMProps;
34
+ }
35
+
36
+ /**
37
+ * ```tsx
38
+ * const { labelProps, fieldProps } = label({ label: () => props.label?.() });
39
+ * <label {...labelProps}>{props.label}</label>
40
+ * <input {...fieldProps} />
41
+ * ```
42
+ */
43
+ export function label(options: LabelOptions): LabelResult {
44
+ const fieldId = id(options.id);
45
+ const labelId = id();
46
+
47
+ const hasLabel = (): boolean => {
48
+ const value = access(options.label);
49
+ return value !== undefined && value !== null && value !== false && value !== "";
50
+ };
51
+
52
+ const labelledBy = (): string | undefined => {
53
+ const given = access(options["aria-labelledby"]);
54
+ if (!hasLabel()) return given;
55
+ // Both: the visible label first, then whatever else was named, which is
56
+ // the order a screen reader reads them in.
57
+ return given === undefined ? labelId() : `${labelId()} ${given}`;
58
+ };
59
+
60
+ return {
61
+ labelProps: {
62
+ id: () => (hasLabel() ? labelId() : undefined),
63
+ // `for` only when the field can actually be labelled by one.
64
+ for: () =>
65
+ hasLabel() && (access(options.labelElementType) ?? "label") === "label"
66
+ ? fieldId()
67
+ : undefined,
68
+ },
69
+ fieldProps: {
70
+ id: fieldId,
71
+ "aria-label": () => access(options["aria-label"]),
72
+ "aria-labelledby": labelledBy,
73
+ },
74
+ };
75
+ }
76
+
77
+ export interface FieldOptions extends LabelOptions {
78
+ /** Help text shown under the field. */
79
+ description?: MaybeAccessor<unknown>;
80
+ /** What is wrong, shown when the field is invalid. */
81
+ errorMessage?: MaybeAccessor<unknown>;
82
+ isInvalid?: MaybeAccessor<boolean | undefined>;
83
+ "aria-describedby"?: MaybeAccessor<string | undefined>;
84
+ }
85
+
86
+ export interface FieldResult extends LabelResult {
87
+ descriptionProps: DOMProps;
88
+ errorMessageProps: DOMProps;
89
+ }
90
+
91
+ /**
92
+ * A field, its label, and the help text or error under it.
93
+ *
94
+ * `aria-describedby` names only the elements that are actually rendered: an id
95
+ * pointing at nothing is announced as nothing, and hides the description that
96
+ * would have been read instead.
97
+ */
98
+ export function field(options: FieldOptions): FieldResult {
99
+ const { labelProps, fieldProps } = label(options);
100
+ const descriptionId = id();
101
+ const errorMessageId = id();
102
+
103
+ const present = (value: MaybeAccessor<unknown>): boolean => {
104
+ const resolved = access(value);
105
+ return resolved !== undefined && resolved !== null && resolved !== false && resolved !== "";
106
+ };
107
+
108
+ const describedBy = (): string | undefined => {
109
+ const parts = [
110
+ present(options.description) ? descriptionId() : undefined,
111
+ present(options.errorMessage) && access(options.isInvalid) === true
112
+ ? errorMessageId()
113
+ : undefined,
114
+ access(options["aria-describedby"]),
115
+ ].filter((part): part is string => part !== undefined);
116
+ return parts.length === 0 ? undefined : parts.join(" ");
117
+ };
118
+
119
+ return {
120
+ labelProps,
121
+ fieldProps: mergeProps(fieldProps, { "aria-describedby": describedBy }),
122
+ descriptionProps: { id: descriptionId },
123
+ errorMessageProps: { id: errorMessageId },
124
+ };
125
+ }
126
+
127
+ /** The id an element was given, for a component that needs to reference it. */
128
+ export type FieldId = Accessor<string>;