@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,417 @@
1
+ /**
2
+ * Text fields.
3
+ *
4
+ * The input itself is the platform's, and almost all of the accessibility with
5
+ * it. What is added is the wiring a field needs and the platform has no way to
6
+ * express: the label, the description and the error message all announced with
7
+ * the control, the value controllable without the caret jumping, and a search
8
+ * field's Escape-to-clear.
9
+ *
10
+ * `aria-describedby` rather than `aria-errormessage` for the error, because
11
+ * VoiceOver and NVDA still do not announce the latter.
12
+ */
13
+
14
+ import { type Accessor, type Child, type Incoming } from "@barqjs/core";
15
+ import { ref as makeRef, mergeRefs, type RefTarget } from "@barqjs/primitives/refs";
16
+ import { focusRing } from "./focus.ts";
17
+ import { focusable, type FocusableOptions } from "./interactions/focusable.ts";
18
+ import { hover } from "./interactions/hover.ts";
19
+ import { type ElementRef } from "./interactions/press.ts";
20
+ import { field, type FieldOptions } from "./label.ts";
21
+ import { formReset } from "./toggle.ts";
22
+ import {
23
+ fieldValidation,
24
+ formValidation,
25
+ type FormValidationState,
26
+ type ValidateFunction,
27
+ type ValidationBehavior,
28
+ } from "./validation.ts";
29
+ import { button } from "./button.tsx";
30
+ import {
31
+ access,
32
+ callback,
33
+ chain,
34
+ controllable,
35
+ filterDOMProps,
36
+ fromProps,
37
+ mergeProps,
38
+ styleProps,
39
+ type DOMProps,
40
+ type MaybeAccessor,
41
+ type StyleProps,
42
+ } from "./utils.ts";
43
+
44
+ export type TextFieldType = "text" | "search" | "url" | "tel" | "email" | "password";
45
+
46
+ export interface TextFieldOptions extends FieldOptions, FocusableOptions {
47
+ value?: MaybeAccessor<string | undefined>;
48
+ /** What the page thinks of the value, checked as it changes. */
49
+ validate?: ValidateFunction<string>;
50
+ /** @default "aria" */
51
+ validationBehavior?: MaybeAccessor<ValidationBehavior | undefined>;
52
+ defaultValue?: MaybeAccessor<string | undefined>;
53
+ /** @default "text" */
54
+ type?: MaybeAccessor<TextFieldType | undefined>;
55
+ /** Render a `<textarea>` rather than an `<input>`. */
56
+ isMultiLine?: MaybeAccessor<boolean | undefined>;
57
+ isDisabled?: MaybeAccessor<boolean | undefined>;
58
+ isReadOnly?: MaybeAccessor<boolean | undefined>;
59
+ isRequired?: MaybeAccessor<boolean | undefined>;
60
+ placeholder?: MaybeAccessor<string | undefined>;
61
+ name?: MaybeAccessor<string | undefined>;
62
+ form?: MaybeAccessor<string | undefined>;
63
+ autoComplete?: MaybeAccessor<string | undefined>;
64
+ maxLength?: MaybeAccessor<number | undefined>;
65
+ minLength?: MaybeAccessor<number | undefined>;
66
+ pattern?: MaybeAccessor<string | undefined>;
67
+ inputMode?: MaybeAccessor<string | undefined>;
68
+ onChange?: (value: string) => void;
69
+ onKeyDown?: (event: KeyboardEvent) => void;
70
+ onKeyUp?: (event: KeyboardEvent) => void;
71
+ }
72
+
73
+ export interface TextFieldResult {
74
+ labelProps: DOMProps;
75
+ inputProps: DOMProps;
76
+ descriptionProps: DOMProps;
77
+ errorMessageProps: DOMProps;
78
+ value: Accessor<string>;
79
+ setValue(value: string): void;
80
+ /** What is wrong with the value, and whether the user is being told. */
81
+ validation: FormValidationState;
82
+ /** The messages to show, which may be the browser's own. */
83
+ errors: Accessor<string[]>;
84
+ isInvalid: Accessor<boolean>;
85
+ }
86
+
87
+ export function textField(
88
+ options: TextFieldOptions,
89
+ ref: ElementRef<HTMLInputElement | HTMLTextAreaElement>,
90
+ ): TextFieldResult {
91
+ const [value, setValue] = controllable<string>(
92
+ () => access(options.value),
93
+ () => access(options.defaultValue) ?? "",
94
+ options.onChange,
95
+ );
96
+
97
+ // What the BROWSER makes of it is NOT read back into the state's own view of
98
+ // the value: the page's errors are written onto the element with
99
+ // `setCustomValidity`, so reading the element's validity as an input would
100
+ // be reading back what was just written and calling it a new finding.
101
+ // `formValidation` reads it only once the page has nothing to say.
102
+ const {
103
+ state: validation,
104
+ behavior,
105
+ isInvalid,
106
+ errors,
107
+ errorMessage,
108
+ } = fieldValidation<string>({
109
+ value,
110
+ validate: options.validate,
111
+ validationBehavior: options.validationBehavior,
112
+ isInvalid: options.isInvalid,
113
+ errorMessage: options.errorMessage,
114
+ name: options.name,
115
+ });
116
+
117
+ formValidation(
118
+ {
119
+ validationBehavior: behavior,
120
+ focus: () => (access(ref) as HTMLInputElement | null)?.focus(),
121
+ },
122
+ validation,
123
+ ref,
124
+ );
125
+
126
+ const { labelProps, fieldProps, descriptionProps, errorMessageProps } = field({
127
+ ...options,
128
+ isInvalid,
129
+ errorMessage,
130
+ });
131
+ const { focusableProps } = focusable(options, ref);
132
+
133
+ formReset(ref as ElementRef<HTMLInputElement>, access(options.defaultValue) ?? "", setValue);
134
+
135
+ const isDisabled = (): boolean => access(options.isDisabled) === true;
136
+ const isReadOnly = (): boolean => access(options.isReadOnly) === true;
137
+ const isRequired = (): boolean => access(options.isRequired) === true;
138
+
139
+ const onInput = (event: Event): void => {
140
+ const input = event.target as HTMLInputElement;
141
+ setValue(input.value);
142
+ // The field has already changed itself. When the component is controlled
143
+ // and its owner declined, or it is read-only, nothing re-renders on a
144
+ // value that did not move, so the DOM has to be put back by hand.
145
+ if (input.value !== value()) input.value = value();
146
+ };
147
+
148
+ return {
149
+ value,
150
+ setValue,
151
+ validation,
152
+ errors,
153
+ isInvalid,
154
+ labelProps,
155
+ descriptionProps,
156
+ errorMessageProps,
157
+ inputProps: mergeProps(
158
+ filterDOMProps(options, { labelable: true }),
159
+ fieldProps,
160
+ focusableProps,
161
+ {
162
+ type: () =>
163
+ access(options.isMultiLine) === true ? undefined : (access(options.type) ?? "text"),
164
+ value,
165
+ disabled: isDisabled,
166
+ readOnly: isReadOnly,
167
+ required: isRequired,
168
+ placeholder: () => access(options.placeholder),
169
+ name: () => access(options.name),
170
+ form: () => access(options.form),
171
+ autocomplete: () => access(options.autoComplete),
172
+ maxlength: () => access(options.maxLength),
173
+ minlength: () => access(options.minLength),
174
+ pattern: () => access(options.pattern),
175
+ inputmode: () => access(options.inputMode),
176
+ "aria-invalid": () => isInvalid() || undefined,
177
+ "aria-required": () => isRequired() || undefined,
178
+ "aria-readonly": () => isReadOnly() || undefined,
179
+ onInput,
180
+ onKeyDown: options.onKeyDown,
181
+ onKeyUp: options.onKeyUp,
182
+ onBlur: () => validation.commitValidation(),
183
+ },
184
+ ),
185
+ };
186
+ }
187
+
188
+ // ---------------------------------------------------------------------------
189
+ // Search field
190
+ // ---------------------------------------------------------------------------
191
+
192
+ export interface SearchFieldOptions extends TextFieldOptions {
193
+ /** Fired on Enter, and on the clear button. */
194
+ onSubmit?: (value: string) => void;
195
+ onClear?: () => void;
196
+ }
197
+
198
+ export interface SearchFieldResult extends TextFieldResult {
199
+ clearButtonProps: DOMProps;
200
+ }
201
+
202
+ /**
203
+ * A search field: `type="search"`, Enter submits, Escape clears.
204
+ *
205
+ * The clear button is `tabIndex={-1}` and hidden from assistive technology,
206
+ * which sounds wrong and is not: Escape already clears the field from the
207
+ * keyboard, so a Tab stop that does the same thing is an extra stop between
208
+ * the field and whatever follows it, for no new capability.
209
+ */
210
+ export function searchField(
211
+ options: SearchFieldOptions,
212
+ ref: ElementRef<HTMLInputElement>,
213
+ ): SearchFieldResult {
214
+ const result = textField({ ...options, type: () => access(options.type) ?? "search" }, ref);
215
+
216
+ const clear = (): void => {
217
+ if (access(options.isReadOnly) === true || access(options.isDisabled) === true) return;
218
+ result.setValue("");
219
+ const input = access(ref) as HTMLInputElement | null;
220
+ if (input !== null) input.value = "";
221
+ options.onClear?.();
222
+ };
223
+
224
+ const onKeyDown = (event: KeyboardEvent): void => {
225
+ if (event.key === "Enter") {
226
+ event.preventDefault();
227
+ options.onSubmit?.(result.value());
228
+ return;
229
+ }
230
+ if (event.key === "Escape") {
231
+ if (result.value() === "" && options.onClear === undefined) return;
232
+ event.preventDefault();
233
+ clear();
234
+ }
235
+ };
236
+
237
+ const { buttonProps } = button({
238
+ isDisabled: () => access(options.isDisabled) === true || access(options.isReadOnly) === true,
239
+ // Pressing it must not take focus off the field the user is typing in.
240
+ preventFocusOnPress: true,
241
+ excludeFromTabOrder: true,
242
+ onPress: clear,
243
+ });
244
+
245
+ return {
246
+ ...result,
247
+ inputProps: mergeProps(result.inputProps, {
248
+ onKeyDown: chain(onKeyDown, options.onKeyDown),
249
+ }),
250
+ clearButtonProps: mergeProps(buttonProps, { "aria-hidden": true, tabIndex: -1 }),
251
+ };
252
+ }
253
+
254
+ // ---------------------------------------------------------------------------
255
+ // Components
256
+ // ---------------------------------------------------------------------------
257
+
258
+ export interface TextFieldComponentProps extends StyleProps {
259
+ label?: Child;
260
+ description?: Child;
261
+ errorMessage?: Child;
262
+ value?: string;
263
+ defaultValue?: string;
264
+ type?: TextFieldType;
265
+ isMultiLine?: boolean;
266
+ isDisabled?: boolean;
267
+ isReadOnly?: boolean;
268
+ isRequired?: boolean;
269
+ isInvalid?: boolean;
270
+ /** What the page thinks of the value. Return a message, or nothing. */
271
+ validate?: ValidateFunction<string>;
272
+ /** @default "aria" */
273
+ validationBehavior?: ValidationBehavior;
274
+ placeholder?: string;
275
+ name?: string;
276
+ form?: string;
277
+ autoComplete?: string;
278
+ autoFocus?: boolean;
279
+ maxLength?: number;
280
+ minLength?: number;
281
+ pattern?: string;
282
+ inputMode?: string;
283
+ "aria-label"?: string;
284
+ "aria-labelledby"?: string;
285
+ "aria-describedby"?: string;
286
+ ref?: RefTarget<HTMLInputElement>;
287
+ onChange?: (value: string) => void;
288
+ onFocus?: (event: FocusEvent) => void;
289
+ onBlur?: (event: FocusEvent) => void;
290
+ onKeyDown?: (event: KeyboardEvent) => void;
291
+ }
292
+
293
+ /**
294
+ * ```tsx
295
+ * <TextField label="Name" onChange={(v) => name.set(v)} />
296
+ * ```
297
+ */
298
+ export function TextField(props: Incoming<TextFieldComponentProps>) {
299
+ const inputRef = makeRef<HTMLInputElement>();
300
+ const options = fromProps(props);
301
+
302
+ const { labelProps, inputProps, descriptionProps, errorMessageProps, errors, isInvalid } =
303
+ textField(
304
+ {
305
+ ...(options as TextFieldOptions),
306
+ validate: callback(props.validate),
307
+ validationBehavior: () => props.validationBehavior?.(),
308
+ },
309
+ inputRef,
310
+ );
311
+ const { hoverProps, isHovered } = hover({ isDisabled: options.isDisabled });
312
+ const { focusProps, isFocused, isFocusVisible } = focusRing({ isTextInput: true });
313
+
314
+ const controlProps = mergeProps(inputProps, hoverProps, focusProps, {
315
+ "data-hovered": isHovered,
316
+ "data-focused": isFocused,
317
+ "data-focus-visible": isFocusVisible,
318
+ "data-disabled": () => props.isDisabled?.() === true,
319
+ "data-invalid": isInvalid,
320
+ });
321
+
322
+ return (
323
+ <div
324
+ {...mergeProps(styleProps(props), {
325
+ "data-testid": () => props["data-testid"]?.(),
326
+ })}
327
+ >
328
+ <label {...labelProps}>{props.label}</label>
329
+ {() =>
330
+ props.isMultiLine?.() === true ? (
331
+ <textarea
332
+ {...controlProps}
333
+ ref={
334
+ mergeRefs(inputRef.set, props.ref?.()) as unknown as (el: HTMLTextAreaElement) => void
335
+ }
336
+ />
337
+ ) : (
338
+ <input {...controlProps} ref={mergeRefs(inputRef.set, props.ref?.())} />
339
+ )
340
+ }
341
+ <span {...descriptionProps}>{props.description}</span>
342
+ {/* The caller's message when it gave one, and otherwise whatever found
343
+ the problem — which may be the browser, in its own language. */}
344
+ <span {...errorMessageProps}>
345
+ {() => {
346
+ if (!isInvalid()) return null;
347
+ const given = props.errorMessage?.();
348
+ if (given !== undefined && given !== null) return given;
349
+ return errors().join(" ");
350
+ }}
351
+ </span>
352
+ </div>
353
+ );
354
+ }
355
+
356
+ export interface SearchFieldComponentProps extends TextFieldComponentProps {
357
+ onSubmit?: (value: string) => void;
358
+ onClear?: () => void;
359
+ /** What the clear button says. @default "Clear search" */
360
+ clearLabel?: string;
361
+ }
362
+
363
+ /**
364
+ * ```tsx
365
+ * <SearchField label="Search" onSubmit={(q) => search(q)} />
366
+ * ```
367
+ */
368
+ export function SearchField(props: Incoming<SearchFieldComponentProps>) {
369
+ const inputRef = makeRef<HTMLInputElement>();
370
+ const options = fromProps(props);
371
+
372
+ const {
373
+ labelProps,
374
+ inputProps,
375
+ descriptionProps,
376
+ errorMessageProps,
377
+ clearButtonProps,
378
+ value,
379
+ errors,
380
+ isInvalid,
381
+ } = searchField(options as SearchFieldOptions, inputRef);
382
+ const { hoverProps, isHovered } = hover({ isDisabled: options.isDisabled });
383
+ const { focusProps, isFocused, isFocusVisible } = focusRing({ isTextInput: true });
384
+
385
+ const controlProps = mergeProps(inputProps, hoverProps, focusProps, {
386
+ "data-hovered": isHovered,
387
+ "data-focused": isFocused,
388
+ "data-focus-visible": isFocusVisible,
389
+ "data-disabled": () => props.isDisabled?.() === true,
390
+ });
391
+
392
+ return (
393
+ <div
394
+ {...mergeProps(styleProps(props), {
395
+ "data-testid": () => props["data-testid"]?.(),
396
+ "data-empty": () => value() === "",
397
+ })}
398
+ >
399
+ <label {...labelProps}>{props.label}</label>
400
+ <input {...controlProps} ref={mergeRefs(inputRef.set, props.ref?.())} />
401
+ <button type="button" {...clearButtonProps}>
402
+ {() => props.clearLabel?.() ?? "Clear search"}
403
+ </button>
404
+ <span {...descriptionProps}>{props.description}</span>
405
+ {/* The caller's message when it gave one, and otherwise whatever found
406
+ the problem — which may be the browser, in its own language. */}
407
+ <span {...errorMessageProps}>
408
+ {() => {
409
+ if (!isInvalid()) return null;
410
+ const given = props.errorMessage?.();
411
+ if (given !== undefined && given !== null) return given;
412
+ return errors().join(" ");
413
+ }}
414
+ </span>
415
+ </div>
416
+ );
417
+ }