@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
@@ -0,0 +1,211 @@
1
+ /**
2
+ * A collection made of the items that RENDER, for a widget written as JSX
3
+ * children rather than as `items` plus a render function.
4
+ *
5
+ * ```tsx
6
+ * <Menu>
7
+ * <MenuItem>Rename</MenuItem>
8
+ * <MenuItem isDisabled>Duplicate</MenuItem>
9
+ * </Menu>
10
+ * ```
11
+ *
12
+ * Every collection widget here is driven by a `ListState`, which wants data.
13
+ * This turns rendered items INTO that data, so the keyboard delegate, the
14
+ * typeahead and the selection manager are the same ones the data-driven form
15
+ * uses and nothing about them is written twice.
16
+ *
17
+ * The decisions:
18
+ *
19
+ * - **An item registers when its component is created and leaves when its
20
+ * scope is disposed.** A row behind a `<Show>` is in the collection exactly
21
+ * while it is in the document, so an arrow key never lands on a hidden one.
22
+ * - **The order is the document's.** Registration order is creation order,
23
+ * which is document order for a first render and wrong for a row a `<Show>`
24
+ * inserts later, so the entries are sorted by position once their elements
25
+ * exist.
26
+ * - **The text is the element's own unless the item says otherwise.** That is
27
+ * what a typeahead matches against, and it is read after the row has been
28
+ * built: an item's label is usually its children.
29
+ * - **A key is generated unless the item gives one.** A menu item has nothing
30
+ * to be identified by; an option's `value` is its key.
31
+ */
32
+
33
+ import {
34
+ type Accessor,
35
+ createContext,
36
+ createMemo,
37
+ createSignal,
38
+ createUniqueId,
39
+ getContext,
40
+ onCleanup,
41
+ onSettled,
42
+ provide,
43
+ } from "@barqjs/core";
44
+
45
+ import type { ItemAccessors, Key } from "./collections.ts";
46
+ import { access, type MaybeAccessor } from "./utils.ts";
47
+
48
+ /** One rendered item, as the data a `ListState` is built from. */
49
+ export interface StaticEntry {
50
+ key: Key;
51
+ type: "item" | "section";
52
+ textValue: string;
53
+ /** `isDisabled`, `href`, and whatever the widget adds. */
54
+ props: Record<string, unknown>;
55
+ children?: StaticEntry[];
56
+ }
57
+
58
+ export interface StaticItemOptions {
59
+ /** @default a generated id */
60
+ key?: Key | undefined;
61
+ /** @default "item" */
62
+ type?: "item" | "section";
63
+ /** @default the element's text */
64
+ textValue?: MaybeAccessor<string | undefined>;
65
+ /** Per-item options, read whenever the collection is rebuilt. */
66
+ props?: () => Record<string, unknown>;
67
+ /** Leave the item out without unmounting it: a row a filter has hidden. */
68
+ isHidden?: MaybeAccessor<boolean | undefined>;
69
+ }
70
+
71
+ export interface StaticItem {
72
+ key: Key;
73
+ /** Goes on the item's element, which is where its text and position are read. */
74
+ ref: (element: Element | null) => void;
75
+ /** The element, once it exists. */
76
+ element: Accessor<Element | null>;
77
+ }
78
+
79
+ export interface StaticCollection {
80
+ /** The registered items in document order, sections holding their children. */
81
+ entries: Accessor<StaticEntry[]>;
82
+ /** Every registered key in document order, hidden ones included. */
83
+ keys: Accessor<Key[]>;
84
+ /** The element a key rendered, if it is still registered. */
85
+ elementOf: (key: Key) => Element | null;
86
+ register: (options: StaticItemOptions, parentKey: Key | undefined) => StaticItem;
87
+ }
88
+
89
+ interface Registration {
90
+ key: Key;
91
+ type: "item" | "section";
92
+ parentKey: Key | undefined;
93
+ options: StaticItemOptions;
94
+ element: Accessor<Element | null>;
95
+ order: number;
96
+ }
97
+
98
+ /** How a `ListState` reads a {@link StaticEntry}. */
99
+ export const staticAccessors: ItemAccessors<StaticEntry> = {
100
+ getKey: (entry) => entry.key,
101
+ getTextValue: (entry) => entry.textValue,
102
+ getChildren: (entry) => entry.children,
103
+ getType: (entry) => entry.type,
104
+ getProps: (entry) => entry.props,
105
+ };
106
+
107
+ function byDocument(a: Registration, b: Registration): number {
108
+ const first = a.element();
109
+ const second = b.element();
110
+ if (first === null || second === null) return a.order - b.order;
111
+ const relation = first.compareDocumentPosition(second);
112
+ if ((relation & Node.DOCUMENT_POSITION_DISCONNECTED) !== 0) return a.order - b.order;
113
+ if ((relation & Node.DOCUMENT_POSITION_FOLLOWING) !== 0) return -1;
114
+ if ((relation & Node.DOCUMENT_POSITION_PRECEDING) !== 0) return 1;
115
+ return a.order - b.order;
116
+ }
117
+
118
+ export function staticCollection(): StaticCollection {
119
+ const registered = new Map<Key, Registration>();
120
+ let created = 0;
121
+ // The map is the state; the signal only says it changed. Items register from
122
+ // component bodies, which is an owned scope, hence `ownedWrite`.
123
+ const [version, setVersion] = createSignal(0, { ownedWrite: true });
124
+ const changed = (): void => {
125
+ setVersion((current) => current + 1);
126
+ };
127
+
128
+ const ordered = createMemo((): Registration[] => {
129
+ version();
130
+ return [...registered.values()].toSorted(byDocument);
131
+ });
132
+
133
+ const entryOf = (registration: Registration, all: Registration[]): StaticEntry => {
134
+ const entry: StaticEntry = {
135
+ key: registration.key,
136
+ type: registration.type,
137
+ textValue:
138
+ access(registration.options.textValue) ?? registration.element()?.textContent?.trim() ?? "",
139
+ props: registration.options.props?.() ?? {},
140
+ };
141
+ if (registration.type === "section") {
142
+ entry.children = all
143
+ .filter((child) => child.parentKey === registration.key && isShown(child))
144
+ .map((child) => entryOf(child, all));
145
+ }
146
+ return entry;
147
+ };
148
+
149
+ const isShown = (registration: Registration): boolean =>
150
+ access(registration.options.isHidden) !== true;
151
+
152
+ const entries = createMemo((): StaticEntry[] => {
153
+ const all = ordered();
154
+ return all
155
+ .filter((registration) => registration.parentKey === undefined && isShown(registration))
156
+ .map((registration) => entryOf(registration, all));
157
+ });
158
+
159
+ return {
160
+ entries,
161
+ keys: () => ordered().map((registration) => registration.key),
162
+ elementOf: (key) => registered.get(key)?.element() ?? null,
163
+ register: (options, parentKey) => {
164
+ const key = options.key ?? createUniqueId();
165
+ const [element, setElement] = createSignal<Element | null>(null, { ownedWrite: true });
166
+ const registration: Registration = {
167
+ key,
168
+ type: options.type ?? "item",
169
+ parentKey,
170
+ options,
171
+ element,
172
+ order: created++,
173
+ };
174
+ registered.set(key, registration);
175
+ changed();
176
+
177
+ // By the time the tree has settled the row is attached and its children
178
+ // are built, so the position and the text are both the real ones.
179
+ onSettled(changed);
180
+ onCleanup(() => {
181
+ // Only its own entry: the same key rendered a second time has replaced
182
+ // this one, and that copy is still there.
183
+ if (registered.get(key) === registration) registered.delete(key);
184
+ changed();
185
+ });
186
+
187
+ return { key, ref: (node) => setElement(node), element };
188
+ },
189
+ };
190
+ }
191
+
192
+ const StaticSectionContext = createContext<Key | null>(null);
193
+
194
+ /**
195
+ * Register one rendered item with `collection`, under the section it is
196
+ * rendered inside, if any.
197
+ */
198
+ export function staticItem(collection: StaticCollection, options: StaticItemOptions): StaticItem {
199
+ return collection.register(options, getContext(StaticSectionContext) ?? undefined);
200
+ }
201
+
202
+ /**
203
+ * Build `children` as the contents of the section `key`.
204
+ *
205
+ * A call rather than something installed on the ambient owner: a component has
206
+ * no scope of its own, so an install would put every later sibling of the
207
+ * section inside it too.
208
+ */
209
+ export function provideStaticSection(key: Key, children: () => unknown): unknown {
210
+ return provide(StaticSectionContext, () => key, children);
211
+ }
package/src/switch.tsx ADDED
@@ -0,0 +1,212 @@
1
+ /**
2
+ * A switch: on or off, taking effect immediately.
3
+ *
4
+ * The same machinery as a checkbox with one attribute changed, and the
5
+ * difference is not cosmetic. `role="switch"` is announced as "on"/"off"
6
+ * rather than "checked"/"unchecked", which is what tells the user the setting
7
+ * has already been applied rather than waiting for a Save.
8
+ */
9
+
10
+ import {
11
+ type Accessor,
12
+ type Child,
13
+ createContext,
14
+ getContext,
15
+ getOwner,
16
+ type Incoming,
17
+ install,
18
+ } from "@barqjs/core";
19
+ import { ref as makeRef, type RefTarget } from "@barqjs/primitives/refs";
20
+ import { focusRing } from "./focus.ts";
21
+ import { hover } from "./interactions/hover.ts";
22
+ import type { PressEvent } from "./interactions/press.ts";
23
+ import type { ElementRef } from "./interactions/press.ts";
24
+ import type { ToggleState } from "./button.tsx";
25
+ import {
26
+ toggle,
27
+ toggleState,
28
+ toggleElementType,
29
+ type ToggleElementType,
30
+ type ToggleOptions,
31
+ type ToggleResult,
32
+ } from "./toggle.ts";
33
+ import { toggleInput, withHelpText } from "./toggle-input.tsx";
34
+ import type { ValidateFunction, ValidationBehavior } from "./validation.ts";
35
+ import {
36
+ callback,
37
+ filterDOMProps,
38
+ fromProps,
39
+ mergeProps,
40
+ styleProps,
41
+ type StyleProps,
42
+ } from "./utils.ts";
43
+
44
+ export interface SwitchOptions extends ToggleOptions {}
45
+
46
+ export type SwitchResult = ToggleResult;
47
+
48
+ export function switchToggle(
49
+ options: SwitchOptions,
50
+ state: ToggleState,
51
+ ref: ElementRef<HTMLInputElement>,
52
+ ): SwitchResult {
53
+ const result = toggle(options, state, ref);
54
+ return {
55
+ ...result,
56
+ inputProps: mergeProps(result.inputProps, { role: "switch" }),
57
+ };
58
+ }
59
+
60
+ export interface SwitchComponentProps extends StyleProps {
61
+ children?: Child;
62
+ /**
63
+ * `"label"` when the children are the switch's name, `"span"` when they are
64
+ * its drawing and the name comes from somewhere else. Defaults to a label
65
+ * with children and a span without.
66
+ */
67
+ elementType?: ToggleElementType;
68
+ isSelected?: boolean;
69
+ defaultSelected?: boolean;
70
+ isDisabled?: boolean;
71
+ isReadOnly?: boolean;
72
+ isRequired?: boolean;
73
+ isInvalid?: boolean;
74
+ /** What the page thinks of the value, checked as it changes. */
75
+ validate?: ValidateFunction<boolean>;
76
+ /** @default "aria" */
77
+ validationBehavior?: ValidationBehavior;
78
+ /** Help text, rendered after the switch and announced with it. */
79
+ description?: Child;
80
+ /**
81
+ * What is wrong, rendered after the switch while it is invalid. Without one,
82
+ * whatever validation found is shown.
83
+ */
84
+ errorMessage?: Child;
85
+ value?: string;
86
+ name?: string;
87
+ form?: string;
88
+ autoFocus?: boolean;
89
+ "aria-label"?: string;
90
+ "aria-labelledby"?: string;
91
+ "aria-describedby"?: string;
92
+ ref?: RefTarget<HTMLInputElement>;
93
+ onChange?: (isSelected: boolean) => void;
94
+ onFocus?: (event: FocusEvent) => void;
95
+ onBlur?: (event: FocusEvent) => void;
96
+ onPress?: (event: PressEvent) => void;
97
+ }
98
+
99
+ /** What a part drawn inside a switch reads. */
100
+ export interface SwitchContextValue {
101
+ isSelected: Accessor<boolean>;
102
+ isDisabled: Accessor<boolean>;
103
+ }
104
+
105
+ const SwitchContext = createContext<SwitchContextValue | null>(null);
106
+
107
+ /**
108
+ * The switch a part is drawn inside: the thumb of a design system's track,
109
+ * which has to move and recolour with a state it does not own.
110
+ */
111
+ export function useSwitch(): SwitchContextValue {
112
+ const value = getContext(SwitchContext);
113
+ if (value === null || value === undefined) {
114
+ throw new Error("This must be rendered inside a Switch.");
115
+ }
116
+ return value;
117
+ }
118
+
119
+ /**
120
+ * ```tsx
121
+ * <Switch defaultSelected onChange={(on) => wifi.set(on)}>Wi-Fi</Switch>
122
+ * ```
123
+ *
124
+ * With children it is a `<label>` around them, and they name it. With none it
125
+ * is a `<span>`: an empty label names nothing, and a label may not contain
126
+ * another, so it could not be put inside the `<label>` that does carry the
127
+ * text. `elementType="span"` says the same for children that are a drawing (a
128
+ * track's thumb) rather than a name.
129
+ *
130
+ * ```tsx
131
+ * <label>
132
+ * Wi-Fi <Switch />
133
+ * </label>
134
+ * ```
135
+ */
136
+ export function Switch(props: Incoming<SwitchComponentProps>) {
137
+ const inputRef = makeRef<HTMLInputElement>();
138
+ const options = fromProps(props);
139
+
140
+ const state = toggleState(options);
141
+ const {
142
+ labelProps,
143
+ inputProps,
144
+ descriptionProps,
145
+ errorMessageProps,
146
+ isSelected,
147
+ isPressed,
148
+ isDisabled,
149
+ isReadOnly,
150
+ isInvalid,
151
+ errorMessage,
152
+ } = switchToggle(
153
+ {
154
+ ...(options as SwitchOptions),
155
+ validate: callback(props.validate),
156
+ validationBehavior: () => props.validationBehavior?.(),
157
+ },
158
+ state,
159
+ inputRef,
160
+ );
161
+ const { hoverProps, isHovered } = hover({ isDisabled: options.isDisabled });
162
+ const { focusProps, isFocused, isFocusVisible } = focusRing();
163
+
164
+ const owner = getOwner();
165
+ if (owner !== null) {
166
+ const value: SwitchContextValue = { isSelected, isDisabled };
167
+ install(owner, SwitchContext, () => value);
168
+ }
169
+
170
+ const outerProps = mergeProps(
171
+ labelProps,
172
+ hoverProps,
173
+ // NOT `id`: this is a `<label>`, and `id` belongs on the input it wraps.
174
+ // A `<label for>` elsewhere on the page can only reach a LABELABLE element,
175
+ // so an `id` here answered `getElementById` first — the label came earlier
176
+ // in the document — and clicking the text toggled nothing. Measured on the
177
+ // site's checkbox page.
178
+ filterDOMProps(options, { global: true, id: false }),
179
+ styleProps(props),
180
+ {
181
+ "data-selected": isSelected,
182
+ "data-state": () => (isSelected() ? "checked" : "unchecked"),
183
+ "data-pressed": isPressed,
184
+ "data-hovered": isHovered,
185
+ "data-focused": isFocused,
186
+ "data-focus-visible": isFocusVisible,
187
+ "data-disabled": isDisabled,
188
+ "data-readonly": isReadOnly,
189
+ "data-invalid": isInvalid,
190
+ "data-required": () => props.isRequired?.() === true,
191
+ },
192
+ );
193
+
194
+ return withHelpText(
195
+ toggleInput({
196
+ elementType: toggleElementType(props.elementType?.(), props.children),
197
+ outerProps,
198
+ inputProps,
199
+ focusProps,
200
+ inputRef,
201
+ ref: props.ref?.(),
202
+ children: props.children,
203
+ isDisabled,
204
+ }),
205
+ {
206
+ descriptionProps,
207
+ errorMessageProps,
208
+ description: () => props.description?.(),
209
+ errorMessage: () => (isInvalid() ? errorMessage() : undefined),
210
+ },
211
+ );
212
+ }